
                  MAILPGN: ESTRATTORE DI PARTITE DALLE EMAIL
                  ------------------------------------------

Autore: Paolo Buratti - TRENTO
MailPgn e' un programma di pubblico dominio, liberamente distribuibile.


PREMESSA
--------

Io gioco frequentemente su alcuni siti con server FICS come chess.net e ICC.
Avendo abilitato le variabili AUTOMAIL e PGN, ricevo ogni settimana molte partite in formato PGN da questi server.
Prima di usare MailPgn, ero costretto ogni giorno ad estrarre le partite PGN dalla posta in arrivo con lunghe e ripetitive operazione di "copia" e "incolla".
Un bel giorno ho avuto un idea: far svolgere questo fastidioso lavoro ad un programma.
Questo programma si chiama MailPgn.

A COSA SERVE
------------

MailPgn estrae partite scacchistiche in formato PGN o ASCII dal file della posta in arrivo.
Questo programma funziona con Windows3.1 (+Win32s che comunque e' quasi sempre gia' installata) oppure Windows95. 
MailPgn legge direttamente dal file della posta in arrivo tutti i messaggi e riconosce quelli di natura scacchistica, dopo di che li registra in un unico file ascii. 
In questo modo le operazioni di import in programmi di scacchi o database risultano notevolemente semplificate.


INDICE DEL FILE LEGGIMI.TXT
-------------------------------

In questo help vengono trattati i seguenti argomenti:


		A) INSTALLAZIONE
		B) LOCALIZZAZIONE DEL FILE DELLA POSTA IN ARRIVO
		C) COMANDI DEL MENU
		D) IMPOSTARE LE PREFERENZE
		E) NOTE TECNICHE
		F) PAGAMENTI IN NATURA :-)

A) INSTALLAZIONE *********************************************************

MailPgn e' un programma molto piccolo per questa ragione io non lo ho affiancato ad un enorme (e faticoso per me :-) programma di installazione.

Per installare MailPgn eseguire le seguenti operazioni:

	1) Crea una nuova directory e chiamala "MAILPGN". 
           (In MS-DOS si usa il comando:  MD c:\MAILPGN )
	2) Copia nella directory appena creata i file: MailPgn.exe e leggimi.txt
	3) Sorridi: sei gia' a buon punto!  :-)

       *4) Se hai Windows3.1:

           A) Apri il gruppo di programmi (finestra) dove vuoi inserire MailPgn
	   B) Seleziona il menu File-> Nuovo -> Singolo programma
	   C) Scrivi nel campo descrizione: "Mail Pgn Games Extractor" 
	   D) Premi il pulsante Sfoglia (Browse in inglese) per cercare il file MailPgn.exe
           E) Seleziona MailPgn.exe e premi OK o LOAD o CARICA  
	   F) Imposta la directory di lavoro a quella dove 
              e' contenuto mailpgn.exe (es: c:\mailpgn)
           G) Clicka su OK
	   H) D'ora in poi ti chiameremo Einstein :-]

        *4) Se hai Windows 95 :

	   A) Apri il gruppo di programmi (finestra) dove vuoi inserire MailPgn
	   B) Clicka col pulsante sinistro del mouse all'interno di 
              questo gruppo senza pero' colpire alcuna icona
	   C) Clicka col pulsante destro del mouse e seleziona dal menu che 
              appare la voce "Nuovo->Collegamento" (o "new -> link file" in inglese)
	   D) Premi il pulsante SFOGLIA (o Browse) per localizzare MailPgn.exe
	   E) Seleziona MailPgn.exe 
	   F) Premi "Avanti" (o "Next") 
	   G) Scrivi nel campo "descrizione": Mail Pgn Games Extractor
	   H) D'ora in poi ti chiameremo Einstein :-]

B) LOCALIZZAZIONE DEL FILE DELLA POSTA IN ARRIVO ***********************************

L'informazione piu' importante (e indispensabile) da impostare nelle preferenze (vedi sotto) e' il percorso completo e il nome del file che contiene la posta in arrivo.
Qui di seguito daro' alcune indicazioni per facilitarti il compito.
Prima di selezionare (dalla finestra preferenze) il pulsante BROWSE (che significa "sfoglia") devi selezionare il programma email di cui intendi localizzare il file posta in arrivo.
Ovviamente se anche intendi usare piu' programmi di posta diversi ogni file di preferenze dovra essere impostato singolarmente.

Dov'e dunque questo file?
Incominciamo col dire che a seconda del programma email usato cambiera' (spesso) anche il nome del file.
Anche se ognuno ha nel suo disco rigide directory diverse, ti fornisco le directory dove si trovano i file della posta in arrivo sul mio sistema, come semplice indicazione.
Ho inserito le directory di tutti e tre i programmi email in mio possesso: Eudora, Outlook Express (o Internet Mail, non cambia quasi niente) e Netscape.

--- PROGRAMMA EUDORA  ----

C:\EUDORA					<- DIRECTORY

IN       MBX        37.521  07/05/98  13.49 IN.MBX      <- QUESTO E' IL FILE DA SELEZIONARE
IN       TOC         8.234  07/05/98  13.48 IN.TOC      <- NON QUEESTO !!
OUT      MBX         1.783  06/04/98  22.25 OUT.MBX
TRASH    MBX         4.055  10/01/98  21.06 TRASH.MBX
         3 file         45.789 byte
         0 dir       157.626.368 byte disponibili

--- MICROSOFT OUTLOOK EXPRESS

C:\Programmi\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  <- QUESTO E' IL FILE
POSTAI~1 IDX        17.660  07/05/98  15.59 Posta in arrivo.idx  <- NON QUESTO !!
        14 file      3.643.161 byte
         2 dir     1.438.515.200 byte disponibili


---- NETSCAPE MESSANGER

C:\Programmi\Netscape\Users\md6283\Mail    <- DIRECTORY (NOTA: md6283 e' il mio identificativo
                                              EMAIL)

INBOX               37.265  07/05/98  14.44 Inbox	<- QUESTO E' IL FILE DA SELEZIONARE
INBOX    SNM         7.856  07/05/98  14.45 Inbox.snm   <- NON QUESTO !!
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
        11 file         63.393 byte
         2 dir     1.438.515.200 byte disponibili

C) COMANDI DEL MENU *********************************************************

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

Ti permette di impostare le preferenze del programma senza (necessariamente) eseguire subito la scansione. In effetti quando dai il via alla scansione ti verra' mostrata proprio questa finestra  ma come semplice verifica. Col comando set prefences puoi impostare distinte preferenze per tutti i programmi email in tuo possesso, oppure diversi criteri di ricerca per uno stesso programma email.
Per una descrizione completa delle impostazioni della finestra preferenze vedi in questo stesso file la sezione D) Impostare le preferenze.

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

Questi comandi non sono strettamente necessari se tu intendi usare MailPgn con un solo programma email e sempre con le stesse impostazioni di ricerca. MailPgn difatti registra automaticamente le ultime preferenze impostate nel file mailpgn.prf, e le ricarica (sempre in modo automatico) ogni volta che viene riavviato in futuro.
Questi comandi saranno invece molto utili se vuoi creare diversi file di preferenze da poter caricare rapidamente a seconda delle circostanze.

Nota: ricordati che MailPgn all'avvio e' sempre impostato con le preferenze stabilite nel file mailpgn.prf. Se tu l'ultima volta che hai usato MailPgn hai creato un nuovo profilo di preferenze e l'hai registrato nel file (supponiamo) eudora.prf. Quando eseguirai la volta successiva mailpgn, le preferenze caricate automaticamente NON saranno quelle di eudora.prf ma quelle di mailpgn.prf.
Questo significa che ti conviene sovrascrivere il file mailpgn.prf con le preferenze che pensi userai piu' frequentemente (oltre a registrarle in un altro file con nome distinto). In questo modo non avrai bisogno di selezionare il comando LOAD PREFERENCES ogni volta che vuoi usare Eduroa (nel nostro esempio).



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

Questo e' il comando che da il via alla scansione del file della posta in arrivo.
Quando selezioni questo comando ti verra' mostrata la finestra con le preferenze attuali. Se lo desideri puoi modificarle oppure premere ABORT per caricare un file di preferenze diverso.
Le partite trovate verranno scritte (o aggiunte) nel file di destinazione che avrai stabilito nelle preferenze.
Oltre alle partite MailPgn creera' anche un indice riassuntivo di tutte le partite scandite e lo scrivera' (o aggiungera') in un file con lo stesso nome di quello delle partite ma con estensione ".LST".
L'indice riassuntivo (definito "game report list") contiene informazioni di questo genere:


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


In fondo all'indice ci sara' anche un quadro riassuntivo numerico sulle partite giocate, vinte, perse e sul tipo di partite giocate: standard, blitz, lightining ecc.
NOTA: Perche' il quadro riassuntivo numerico sia corretto e' necessario che nelle preferenze tu abbia impostato il tuo alias (soprannome o handle) che usi in queste partite. Altrimenti mailpgn non potra' distinguere chi sei tu e chi l'avversario.

D) IMPOSTARE LE PREFERENZE ****************************************************

La finestra delle preferenze e' divista in cinque riquadri.
Analizziamo distintamente le funzioni di ognuna di queste cinque aree. 

1)  Riquadro: "In-box source" ---------------------------------------------------

In quest'area si impostano le informazioni relative al file sorgente. Ossia al file che contiene la posta del tuo programma email.

Vedi la sezione B) LOCALIZZARE IL FILE DELLA POSTA IN ARRIVO

NOTA: I file della posta di Microsoft ed Eudora hanno un estensione ".MBX" mentre quello di Netscape non ha alcuna estensione.
Per questa ragione e' opportuno PRIMA di premere il pulsante BROWSE, selezionare il nome del programma email usato. 

NOTA: Se utilizzi un programma email diverso dai tre previsti puoi provare ad utilizzare l'impostazione "Microsoft" e poi cercare il file *.mbx nelle directory dove e' installato il tuo programma.

ATTENZIONE: Il file della posta di Microsoft spesso continua a contenere un messaggio email anche dopo che questo e' stato "virtualmente" cancellato dall'elenco visibile nel tuo programma email. Questo significa che se anche cancelli un'email con soggetto "chess game report: Paolone vs Dijrv", in relata' MailPgn la trovera' comunque, perche' Outlook express non l'ha cancellata fisicamente ma solo a livello logico. (Tra parentesi: Bill Gates e' un genio. Di questo passo, dopo qualche anno il file .mbx di Outlook potra' arrivare a centinaia di megabyte).
Per evitare il problema di dover scandire ogni volta anche i messaggi gia' cancellati puoi impostare (nel riquadro "SCAN ONLY EMAIL MESSAGES") le voci: [X] WITH RECEIVED DATE e  (*) FOLLOWING LAST SCANNING DATE.
In questo modo non verranno estratti messaggi gia' scanditi in date precedenti all'ultima scansione. 


2) Riquadro: "PGN Destination File" -----------------------------------------------

In quest'area dovrai impostare il nome del file dove verranno scritte le partite estratte dalla posta.
Dovrai anche scegliere se le partite dovranno essere "aggiunte" (append) al file di destinazione o scritte cancellando il precedente contenuto del file destinazione (create).
Il file contenente l'indice riassuntivo delle partite avra' lo stesso nome e lo stesso modo d'accesso (create o append) del file contenente le partite PGN ma con un estensione .LST.

Se tu imposti la voce "Remove too new PGN token", MailPgn eliminera' dalle partite estratte tutti i token piu' recenti prima di scriverle nel file destinazione.
L'utilita' di questa funzione e' di permettere anche a programmi di gestione di file PGN, piuttosto vecchiotti di importare queste partite senza "impazzire" o seppellirti di messaggi d'errore.
Ad esempio la notissima utility cbascii (per tradurre da pgn a cbf e viceversa) non riconosce molti nuovi token come [TimeControl] o [Mode] (usati da chess.net) e quando si tenta di fargli convertire una partita con questi tag, cbascii si inchioda col messaggio d'errore: " '[' spurios character founded in game xxxx' ".
Se attivi la voce "Remove too recent PGN token" MailPgn eliminera' tutti i token "misteriosi" lasciando solo quelli fondamentali.
Questi sono i token fondamentali che MailPgn manterra' in ogni caso:

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


3) Riquadro: "Scan only email messages" -----------------------------------------------------

[Subject field]

Se inserisci una stringa in questo campo, MailPgn considerera' solo i messaggi che hanno nel campo oggetto (subject) questa stringa. 
Ovviamente la stringa inserita verra' interpetata da MailPgn come una sotto-stringa del campo oggetto. Se ad esempio inserisci la stringa "Fischer", tutti i messaggi in cui e' presente la parola Fischer verrano presi in considerazione. ("Fischer-spasskij", "Io gioco come Fischer", "Ho comprato un orologio con sistema Fischer". Devo continuare? :-((
Se questo campo viene lasciato vuoto, MailPgn non dara' alcun peso al contenuto del campo "subject" dei messaggi.

CONSIGLI: Se tu vuoi estrarre solo le partite aggiornate usa la stringa "adjourned".
Se vuoi scandire solo le partite che hai giocato contro Babaloo, inserisci la stringa "Babaloo". Eccetera.


[Chess game in PGN format]

Se attivi questa voce verranno caricati solo partite in formato PGN. Tutte le partite in formato ASCII lineare (senza token PGN) verranno ignorate.

Attenzione: Se usi una stringa nulla (il campo vuoto) come maschera di ricerca del soggetto e disattivi il formato pgn, potrebbe accadere che MailPgn inserisca nel file di destinazione parecchia robaccia. Se un messaggio email contiene stringhe come "1/2-1/2", "wild" ect. MailPgn credera' che si tratti di una partita di scacchi. Questo avviene solo quando "only PGN games e' disattivato".


[With received date]

Per evitare di dover cancellare manualmente dalla tua posta i messaggi scacchistici gia' scanditi (e inseriti in un file destinazione) puoi attivare la voce "With received date".

Se attivi la voce "Current date", MailPgn importera' solo i messaggi con la data di ricevimento del giorno attuale.
Se attivi la voce "Last scanning date" (scelta consigliata) MailPgn importera' solo i messaggi con data di ricezione posteriore a quella della data dell'ultima scansione effettuata. (MailPgn registra sempre nel file di preferenze utilizzato la data in cui effettua la scansione)

Note: [Current date] lavora in giorni. [Last scanning date] = discrimina anche i secondi delle due date (di ricezione e ultima di scansione)

Nota: La data dell'ultima scansione verra' registrata solo se la scansione avra' avuto esito positivo (almeno una partita trovata).

[With my opponent's rate >=] 

Se tu hai specificato il nome o alias che usi nelle tue partite (vedi sotto) puoi anche attivare questa voce per chiedere a MailPgn di ignorare le partite in cui il tuo avversario ha un punteggio elo inferiore a quello da te stabilito.
Ad esempio se il tuo nickname e' "Zorro" e il valore inserito in "With my opponent's rate" fosse "1600". MailPgn ignorera' partite come "Zorro(1820) vs Baluba(1580)".

Nota: Se tu NON hai fornito il tuo nickname, oppure MailPgn trova una partita che non e' stata giocata da te, MailPgn effettuera' il controllo sull'elo del giocatore col valore minore.
Esempio: con elo richiesto "1600"  la partita "Tizio(1710) vs Caio(1540)" non verra' importata, perche' Caio ha un elo inferiore a quello richiesto (1600).

Nota: Se NON desideri che venga effettuata una selezione sulla base dell'elo dei giocatori devi lasciare questo campo vuoto oppure scrivere 0 (zero).
Ricorda che i giocatori unrated (inclassificati NC) spesso hanno un elo = 0 nel tag PGN relativo. Se quindi inserisci un punteggio elo minimo richiesto diverso da zero tutte le partite in cui l'avversario non ha un punteggio elo verranno ignorate.


[With Result different from Abort]

Se tu attivi questa voce MailPgn ignorera' le partite con risultato "aborted". (Ovviamente perche' possa riusciri e' necessario che nella partita sia inserita la stringa "aborted". Nelle partite inviate dai server FICS questa stringa e' sempre presente per descrivere una partita abortita.

4) Riquadro: "My Nickname (handle)" --------------------------------------------------

Se desideri avere l'indice riassuntivo dei tuoi risultati (nelle partite scandite) devi inserire in questo campo il nome che usi, altrimeni MailPgn non sara' in grado di fornirti un quadro riassuntivo delle TUE vittorie, sconfitte ecc.
Se le partite che ricevi via email non sono state giocate da te (o non tutte) puoi lasciare questo campo vuoto. L'import delle partite funzionera' comunque, solo che il file *.LST non conterra' un quadro riassuntivo numerico in fondo, ma solo l'indice delle partite scandite e il loro risultato.

5) Riquadro: "Execute Program" ----------------------------------------------------------

[Execute program (after scanning)]

Se desideri che dopo la scansione delle partite MailPgn "attivi" per te un programma specifico, puoi inserire il suo percorso completo e nome in questo campo.
Ad esempio se vuoi analizzare subito dopo la scansione le partite importate con il programma Fritz, potrai inserire il nome dell'eseguibile fritz.exe in questo campo e attivare la voce "Execute program (after scanning)". In questo modo MailPgn, prima effettuera' la scansione delle partite, le registrera' nel file destinazione stabilito e dopo chiamera' Fritz e terminera' la sua esecuzione (sua di MailPgn). In questo modo ti ritroverai subito in grado di visulizzare le partite appena importate.

NOTA: Se desideri eseguire piu' di un programma ad esempio con l'obiettivo di tradurre il file PGN in formato CBF (con CBASCII o PGN2CBF) per poi usare il file CBF come import in un programma di database scacchistico, la soluzione puo' essere quella di usare un piccolo programma *.bat contenente le chiamate a tutti i programmi che desideri.
A questo proposito ricorda che per fornire al file *.bat o al programma *.exe specificato il nome del file destinazione puoi (oltre che inserire il suo nome completo, se intendi usare sempre lo stesso file) usare la coppia di caratteri %s  (percentuale ed esse minuscola). MailPgn prima di attivare il programma sostituira' questi caratteri col nome completo del file destinazione. 
Esempio: Campo eseguibile "c:\fritz5\fritz.exe" linea comandi "-p%s", nome file destinazione "c:\temp\mygames.pgn".
MailPgn eseguira' il comando completo "c:\fritz5\fritz.exe -pc:\temp\mygames.pgn".

ATTENZIONE: Se intendi usare un file *.bat e utilizzi Windows95, l'ultima riga del file *.bat dovra' essere EXIT. In caso contrario Windows95 rimarra' in attesa che tu chiuda "manualmente" la finestra DOS aperta dal file BAT.

ATTENZIONE: Se tu vuoi attivare questa funzione devi ricordarti di attivare il quadratino (checkbox) alla sinistra della scritta "Execute program...". Non e' sufficiente inserire un valido nome di eseguibile nel campo a fianco. Se il checkbox non e' impostato il nome dell'eseguibile verra' ignorato.

[...and exit from mailpgn]

Se attivi la voce "Execute after scanning" puoi decidere di attivare anche questa voce per far terminare l'esecuzione di mailpgn dopo che questo ha scandito le partite e lanciato il programma da te stabilito. Se la voce "execute after scanning" e' disattiva anche l'impostazione di " and exit from mailpgn" verra' ignorata.


E) NOTE TECNICHE *******************************************************

I) MailPgn non effettuera' la scansione di messaggi email con content-type diverso da
   text/plai. In pratica ignorera' i messaggi in formato HTML o multipart/form-data.


II) Inizialmente io pensavo di permettere a MailPgn di estrarre e rimuovere (o etichettare 
    con un messaggio come "SCANNED GAME" i messaggi email una volta scanditi. In seguito
    pero' mi sono reso conto che questo comportava il rischio di danneggiare il file della posta
    in arrivo.
    Per questa ragione MailPgn NON rimuove realmente i messaggi importati, e neppure li
    modifica in alcun modo.

Questo comporta due fatti: uno positivo e l'altro negativo :-(

1) Il fatto positivo e' che usando MailPgn non esiste alcun pericolo per la propria posta. Anche se il programma email usato (e conseguentemente il formato del file della posta in arrivo) fosse del tutto incompatibile con MailPgn, nessun danno potra' essere arrecato. Nella peggiore delle ipotesi MailPgn potrebbe andare in crash ma senza che questo comporti problemi per il programma email o i suoi file.

2) Il fatto negativo e' che dovrai essere tu (se lo desideri) ad eliminare manualmente i messaggi email gia' scanditi.


III) MailPgn e' anche in grado di scandire messaggi NON PGN. Tuttavia in questo caso
     potrebbe avere difficolta' ad ottenere i dati informativi sulla partita
     (nomi dei giocatori, elo ecc.)
     Attualmente MailPgn tenta di ottenere i nomi dei giocatori cercando la 
     stringa "vs.". Se la trova assume che a sinistra di questa stringa vi sara' 
     il nome del bianco e a destra del nero.


IV) Se dopo aver effettuato una scansione il numero a fianco della scritta
    (nella finestra principale del programma) "not recognized email headers"
    fosse molto alto, rispetto al totale dei messaggi, e' molto probabile 
    che hai scelto il tipo di programma email sbagliato. In questo caso 
    ti conviene provare a fare un altro tentativo modificando solo 
    (nelle preferenze) la selezione di "kind email program"


F) PAGAMENTI IN NATURA *******************************************************

Io gioco spesso su chess.net (e ancora piu' spesso, ultimamente) su ICC col nome "Paolone".
Se hai apprezzato il mio programma, ricordati di questo quando giocherai contro di me... 
A buon intenditore poche parole...  ;-)

NOTA: Se tu sei una splendida signorina potresti trovare un altro modo per "sdebitarti" :-)))

     
   Ciao


   Paolo

