

                  MAIL PGN GAMES EXTRACTOR
                  -------------------------

Hello, 

I'm Paolo Buratti (ITALY-TN).  

I've done this program for all friends of chess.net and ICC (and
other chess sites too).

(MailPgn is a full free pubblic domain program, freely distributable.)

I enabled my AUTOMAIL and PGN variables; this means that everyday I
receive many chess games by email.

Before MailPgn, every day I had to extract my chess games from email
messages with long and irritating copy and paste operations.  On one
fine day I had an idea: to create a program to do that irritating job
for me!

MailPgn is a chess game extractor for Windows 3.x + win32s or
Windows95.  It reads messages directly from the email in-box file,
recognizes those of chess nature, and writes them to a plain ASCII text
file.  This is useful to simplify and speed up the import operations in
chess programs like chess-base or task-base.



               MARK REMARKS AND NOTES ABOUT MAILPGN
              ---------------------------------------

Using MailPgn is very simple.  However here are some remarks and notes about:

		A) INSTALLATION
		B) LOCATE IN-BOX FILE
		C) MENU COMMANDS
		D) PREFERENCES SETTINGS
		E) TECHNICAL NOTES
		F) IN KIND PAYMENTS

A) INSTALLATION *********************************************************

Because MailPgn is so small, I haven't included a huge or complicated
installation program.

To install MailPgn:

	1) Create a new directory named: "MailPgn" 
	2) Copy in the files: MailPgn.exe and MailPgn.txt
	3) Smile: you are already in good shape :-) 
	*4) From Windows 3.1 environment:
	   A) Open program group where you wish to place MailPgn
	   B) Select File Menu -> New -> Single program
	   C) Write in description box: Mail Pgn Games Extractor
	   D) Browse to locate MailPgn directory
	   E) Select MailPgn.exe file
	   F) Set work directory "MailPgn"
	   G) Click on OK
	   H) Now, we'll name you Einstein :-]
	*4) From Windows 95 environment
	   A) Open program group where you wish to place MailPgn
	   B) Click left mouse button in window program group
              (without hitting any icon)
	   C) Press right mouse button and select new-> link file
	   D) Browse to locate MailPgn directory
	   E) Select MailPgn.exe file
	   F) Select Next (or OK) 
	   G) Write in description box: Mail Pgn Games Extractor
	   H) Now, we'll name you Einstein :-]


B) LOCATE IN-BOX FILE ******************************************************

You could have trouble in finding your email program's in-box file :-(

In MailPgn's Setup Preferences window, before pressing the Browse
button, select the correct email program.

I'm Italian and my version of Windows 95 is Italian too.  So I can't
show you exactly what this would look like in other versions of Windows
95.  However I believe these are the directories where you should find
the in-box file for specific email programs:

--- EUDORA MAIL PROGRAM ----

C:\EUDORA					<- DIRECTORY

IN       MBX        37.521  07/05/98  13.49 IN.MBX      <- THIS IS IT
IN       TOC         8.234  07/05/98  13.48 IN.TOC      <- NOT THIS
OUT      MBX         1.783  06/04/98  22.25 OUT.MBX
TRASH    MBX         4.055  10/01/98  21.06 TRASH.MBX


--- MICROSOFT OUTLOOK EXPRESS

C:\Program Files\Outlook Express\Default User\Mail    <- DIRECTORY

POSTAI~2 IDX         1.200  02/05/98  22.37 Posta in uscita.idx
POSTAI~2 MBX         5.060  02/05/98  22.37 Posta in uscita.mbx
POSTAI~3 IDX         1.200  02/05/98  22.37 Posta inviata.idx
POSTAI~3 MBX         5.060  02/05/98  22.37 Posta inviata.mbx
POSTAE~1 IDX        13.900  07/05/98  15.27 Posta eliminata.idx
POSTAE~1 MBX     3.039.020  07/05/98  15.27 Posta eliminata.mbx
BOZZE    MBX       270.080  05/05/98  19.31 Bozze.mbx
BOZZE    IDX        19.168  07/05/98  15.44 Bozze.idx
POSTAI~1 MBX       264.948  07/05/98  15.59 Posta in arrivo.mbx  <- THIS IS IT
POSTAI~1 IDX        17.660  07/05/98  15.59 Posta in arrivo.idx  <- NOT THIS

NOTE: "Posta in arrivo" means: "In box mail"


---- NETSCAPE MESSENGER

C:\Program Files\Netscape\Users\Default\Mail	<- DIRECTORY
						(You may have a user id
						rather than Default)

INBOX               37.265  07/05/98  14.44 Inbox	<- THIS IS IT
INBOX    SNM         7.856  07/05/98  14.45 Inbox.snm   <- NOT THIS
DRAFTS                   0  05/04/98  23.45 Drafts
DRAFTS   SNM         2.568  05/04/98  23.45 Drafts.snm
TRASH                    0  05/04/98  23.45 Trash
TRASH    SNM         2.568  05/04/98  23.45 Trash.snm
SENT                 4.343  08/04/98  21.54 Sent
SENT     SNM         6.048  19/04/98  23.23 Sent.snm
UNSENT~1                 0  05/04/98  23.45 Unsent Messages
UNSENT~1 SNM         2.576  05/04/98  23.45 Unsent Messages.snm
POPSTATE DAT           169  07/05/98  14.44 popstate.dat



C) MENU COMMANDS *********************************************************

Set Preferences
-----------------

This permits you to set any value such as the full path of the in-box
file, destination PGN file name, flag PGN only, mask search for subject
field, etc.  (See below.)


Load & Save Preferences
-------------------------

These are not necessary if you use only one email program.  A default
preferences file (MailPgn.prf) will be loaded and saved automatically
every time MailPgn starts and ends a job session.

You could use Load & Save Preferences if you use different email
programs or different settings for scanning your in-box file.


Start Game Extraction
------------------------

This command starts the scanning of your in-box email file.  You will
be prompted for set/change scanning preferences.

The chess games found will be written in the destination file you set
in preferences.

MailPgn will write a game report list also.  This game report list
doesn't include chess games; it holds only statistical references of
every game played.  For example:

"PaulaJones(4646) - Clinton(6969)  lightning  0-1"

(Very high rate...)

At the bottom there will also be a summary of your won/drawn/lost/adjourned/
aborted games and the kind of games played (Blitz, Wild, etc.).

The Game report list file will have the same name as the destination
chess games file, but will have a ".lst" extension.


D) PREFERENCES SETTINGS ****************************************************

The Preferences window is divided into five frames. 

1)  "In-box source" frame

Directions on how to select your in-box mail file are earlier in this file.

Note: Microsoft and Eudora in-box file have an ".MBX" extension, while
Netscape has NO extension.  Before browsing, be sure to set the correct
email program type.

Warning:  The Microsoft in-box file will often also contain "erased"
messages.  Many versions of Microsoft email programs don't actually
remove erased messages from the in-box file after a user delete
command.  They simply erase the message's title from the folder.  If
you have this problem, use the setting:

   [X] With Received date
+  (*) Following last scanning date.

This will avoid importing the same message twice.


2) "PGN Destination File" frame

The chess games extracted from MailPgn will be written in the
ascii-pgn-file chosen by you.

If you set "Create" open mode, the games from this scanning will
overwrite any old games in the PGN Destination File.  If you set
"Append", the new games will be added to listing at the bottom, and the
old games will be preserved.  The Games report list file will use the
same open mode that you've set here for the PGN Destination file:  Create
will overwrite any old reports, and Append will add to any old reports.

If you set "Remove too new PGN token", MailPgn will remove any too recent
pgn tokens from the chess games before writing to the ASCII PGN
Destination file.  The PGN format has had many changes and improvements
in the past years.  Many chess programs like the file chess program or
the PGN reader, or converter utilities (like CBASCII) could not recognize
the newests PGN tokens, and would break their run with a syntax error.

For example chess.net uses [TimeControl] and [Mode] tokens that CBASCII
for MSDOS doesn't accept!  (It stops with the message "'[' spurious
character found in game ...")

Ifyou have these troubles, switch on the "Remove too new PGN Token" and
MailPGN will remove all latest tokens, leaving only standard PGN tokens like:

[Event	[Site	[Date	[Round
[White	[Black	[Result	[Eco	
[WhiteElo	[BlackElo
[Annotator	[FEN


3) "Scan only email messages" frame

[Subject field]

MailPgn will scan only those email messages whose Subject field holds the
string specified by you.  If this editor box is empty, MailPgn will scan
every email message.

Tip:  If you would like MailPgn to extract only adjourned games, you
could set the Subject field string to "adjourned".  If you wish only to
extract your game vs. Babaloo (a handle name), set the Subject field
string to "Babaloo", etc.


[Chess game in PGN format]

If you flag "Only pgn format", the chess games not in PGN format will be
ignored.

Warning:  If you have nothing in the Subject field search box, and then
if you don't switch on "Only pgn format", MailPgn may insert a little
trash in the destination file.  MailPgn is recognizing chess game strings
like "1/2-1/2", "wild", etc. in a regular email message, and tries to
write them out as a chess game.  This happens only when "Only pgn format"
is disabled.


[With received date]

To avoid manually erasing email messages already scanned, you can set
check on received message date.

If you switch on [Current date], MailPgn will import only messages
received today.

If you switch on [Last scanning date], MailPgn will import only those
messages received after the last scanning date of that specific in-box
file name.

Note:  [Current date] accuracy = days.  [Last scanning date] accuracy =
seconds.

Note:  Last scanning date will be saved by MailPgn only if that scanning
was successful, e.g., some chess game has been saved to the PGN
Destination File.


[With my opponent's rate >=] 

If you think it's not meaningful to import chess games played vs.
opponents with a very low rate, you can enter in this edit box a
minimum rate acceptable for imported games.  MailPgn will then import
only those games where your opponent's rate is equal to or greater than
the value set.

Note:  If you have not written your nickname-handle, or if MailPgn
finds a game without your nickname, it will verify if the lower rate of
_any_ player is lower than the set rate.  For example:  Your nickname =
Paolone, and the Minimum rated = 1600.  If MailPgn finds a chess game
message with following players:  Pinco(1610) vs. Pallino(1590).  It
will not import the game because Pallino has a rate lower than 1600.

Warning:  If you don't wish to use this criteria, you should leave this
field empty or write a '0'.


[With Result different from Abort]

If you switch on this box, MailPgn will ignore chess report of aborted
games.


4) "My Nickname (handle)" frame

If you wish to have a statistical game report list (to save in an ASCII
file), you must write your battle-name, i.e., the handle (nickname,
alias, etc.).  If MailPgn knows your handle, it could calculate your
total score in the last scanned games (Win/Lose/Draw, etc.).


5) "Execute Program" frame

If you wish to immediately analyse the chess games just scanned, you
can set the execution of a convert/import program after scanning.  For
example you could convert PGN chess games in Chess Base format with
CBASCII, or you could start a PGN reader program to watch the chess games.

Tips:  If your translate procedure is complex enough, you could create
a batch file with the extension .BAT to execute more than just one program.

Note:  If you work in the Windows 95 environment, the last line of the
BAT file should be "EXIT".  (Otherwise it'll wait until you close the
window.)

If you insert in the command line editor the characters "%s", MailPgn
will substitute "%s" with the active PGN destination file name before
running the executable program.

If you switch on "and exit from MailPgn" box, MailPgn will terminate
after launching the application.

Note:  If the application is an MS-DOS program and you are in the
Windows 95 environment, you may need to select the right icon on the
menu row (at the desktop's bottom) to watch the newest program.

Note:  If the checkbox "Execute program (after scanning)" is not
flagged, MailPgn will ignore the Execute name and command line fields.


E) TECHNICAL NOTES *******************************************************

I)   MailPgn will not parse email messages with content-type different
     than text/plain. It will ignore messages in HTML format and/or
     multipart/form-data.

II)  At first I thought to allow MailPgn to extract and remove scanned
     games from the mail in-box.  But I've had many problems with
     Microsoft Outlook Express.  Now MailPgn doesn't write or modify
     anything in the in-box file.  This means good news and bad news:

     Good News:  You will have no fear that MailPgn might damage your email
                 messages, because it's only going to read them.
     Bad News:   You must manually erase the email messages just scanned.

III) MailPGn is able to scan chess games that are not in PGN format as
     well.  However it could have problems in recognizing player names.
     If the message is not PGN format, it will search for the "vs."
     string.  If it finds that string, MailPgn will extract the White
     player at the left, and the Black player at the right.


IV)  If, after scanning, the "not recognized mail headers" number is
     high enough (compared with total email messages), it's probable
     that you chose the wrong kind of email program.  You should change
     it and try again.


F) IN KIND PAYMENTS *******************************************************

I play chess every day on chess.net or ICC with the handle "Paolone".
If you appreciate my program, please let me win some games in the future.

If you are a beautiful girl, no doubt there are other ways to repay me :-}

P.S.

Last News: My mother language is not english. 
I suppose you are very surprised about this news. However if a true WASP 
 mom-english language person wishes rewrite this document in a good english 
I'll be happy, but please: don't erase my important name :-(

      Bye Bye, nice things

          Paolo


Note from the editor:

Paolo's first English version was very good indeed; far better than I
could have done in Italian!  But, per his request (in his original
dialect up there in the "Last News" paragraph), I went through the text
file, editing slightly make it read better.  My sincerest apologies if
I've somehow distorted the information.  The problem is undoubtedly my
fault and not Paolo's :-)

Regards,

David Kirschbaum, Windows Archivist for Simtel(tm)
Internet: kirschd@Simtel.Net        http://www.simtel.net/simtel.net/
Uucp:  uunet!simtel.net!kirschd      ftp://ftp.simtel.net/pub/simtelnet