Realizzare help files

Ogni applicazione, anche la più semplice, dispone di un file della guida di supporto, che ne documenta le funzioni e l'utilizzo. Questi file della guida, in formato Help di Windows (.hlp), sono veri e propri file compilati. Ogni file help è costituito da più pagine al suo interno (denominate Topics -argomenti-). Ad ogni pagina viene attribuito un nome univoco (paragonabile alla proprietà Name in Visual Basic) e un titolo (paragonabile alla proprietà Caption in Visual Basic). Addizionalmente, la pagina può contenere una serie di parole chiave (keywords, paragonabile al meta tag in HTML) che ne descrivono il contenuto; queste parole chiave verranno utilizzate per la funzione di 'Trova' della Guida. Il sorgente di una guida si divide solitamente in due file: un file RTF standard (Rich Text Format) e un file ASCII con estensione HPJ. Analizzeremo questi due file separatamente.

Il file RTF è un file Rich Text Format normale: nel nostro caso lo stiamo realizzando con Word 97, ma qualsiasi word processor compatibile potrà essere impiegato. Il file RTF deve rispettare alcune convenzioni:

• Ogni argomento (topic) deve essere separato dall'altro tramite una interruzione di pagina (page break) manuale; non sono valide le interruzioni generate automaticamente da Word;
• I nomi, titoli e keywords dei vari argomenti vengono assegnati tramite commenti a pie' di pagina (footnotes); questi vanno specificati all'inizio di ogni argomento, prima del testo dell'argomento stesso:
  • Per impostare il nome della pagina inserire una footnote contentente al posto di un numero il carattere #; come testo della footnote inserire il nome della pagina (meglio se in maiuscolo);
  • Per impostare il titolo della pagina inserire una footnote contenente al posto di un numero il carattere $; come testo della footnote inserire il titolo della pagina;
  • Per impostare le keywords della pagina inserire una footnote contenente al posto di un numero il carattere K; come testo della footnote inserire tutte le parole chiave separate tra di loro da un punto e virgola;
• I collegamenti verso altre pagine sono strutturati nel modo seguente:
  Testo del linkTOPICDIDESTINAZIONE
  Il TOPIC DI DESTINAZIONE deve essere scritto in caratteri nascosti e si deve riferire al nome dell'argomento verso il quale link deve dirigersi.
  Il testo del link deve essere sottolineato seguendo queste nozioni:
  • Per i link POPUP, la sottolineatura dev'essere 'a puntini';
  • Per i link normali, la sottolineatura dev'essere 'normale';
• Le immagini vanno inserite normalmente

Il file HPJ, come specificato prima, è un file ASCII contenente tutte le informazioni sul file della guida. Può essere paragonato al file .VBP di un progetto in Visual Basic. Il file HPJ è strutturato in un modo simile ai file INI. Si suddivide in più sezioni, racchiuse da parentesi quadre. Ogni sezione riguarda una parte specifica dalla compilazione. Le sezioni sono:

[OPTIONS]
ROOT=Directory contenente tutti i files della guida (.rtf, .bmp, ...)
CONTENTS=Nome (footnote #) del sommario della guida
WARNING=Il livello di visualizzazione errori durante la compilazione (max=3)

[FILES]
Elenco dei file RTF da includere nella guida; esempio:
file1.rtf
file2.rtf

[MAP]
Assegna ad ogni topic name un numero (ContextID) per poter richiamare l'argomento da Visual Basic. Per esempio:
MIO_ARGOMENTO_UNO 001

[WINDOWS]
Funzione facoltativa avanzata: definisce la posizione della finestra dell'help, utile per impostare la posizione iniziale della finestra (la finestra Main). Si imposta così:
MAIN="Guida della mia applicazione",(100,100,600,300)

Per effettuare la compilazione (il cui risultato sarà il nostro file .hlp!) è necessario aprire una finestra MS-DOS e portarsi nella directory \HC di Visual Basic. Da qui digitare:
HC c:\percorso\completo\file.hpj
Se la compilazione ha esito positivo, nella directory \HC verrà realizzato il file .hlp. Per utilizzare il file .hlp appena creato con la nostra applicazione VB, è sufficiente assegnare ad ogni componente dei nostri form un valore ContextID (definito nella sezione MAP del file .HPJ) e assegnare il file .hlp come help file per tutto il progetto. Così facendo ad ogni pressione del tasto F1 verrà automaticamente aperta la guida sull'argomento specificato.

TORNA INDIETRO