Compilazione dei Documenti MAN

Lo scopo di un documento man è quello di "pilotare" la produzione di un manuale LaTeX. Il manuale viene creato sulla base di un indice che contiene alternativamente: titoli e documenti. I documenti man stampabili direttamente sono i documenti con dcl man: rappresentano sempre un manuale finito. E' possibile ed utile creare dei documenti con dtd man e classe diversa. In questo caso hanno la funzione di sub-manuali. I primi sono denominati man primari e i secondi man secondari.

Questa struttura è molto articolata ma permette la semplificazione della preparazione dei manuali. Si crea un manuale richiamando dei sub-manuali invece di richiamare direttamente i singoli documenti. Questa possibilità implica che il contenuto del manuale principale si semplifica e viene costruito utilizzando dei blocchi gerarchici. L'alternativa sarebbe un lunghissimo elenco di documenti.

Campo	Notes di compilazione
DCL	Classe del documento (AMM, DSG, DST, RIS, ...). Questo campo viene posizionato automaticamente sulla base della vista di partenza. Ma può essere modificato manualmente. Obbligatorio.
Name	Nome del documento. Identifica un determinato documento. Non va modificato a cuor leggero. L'utente può referenziare un documento tramite un comando #dcl(nome). Cambiare il nome comporta "rompere" questi linki. Ovviamente i riferimenti gestiti tramite link notes non si rompono se si cambia il nome. Il sistema genera un nome "random" se il nome viene lasciato vuoto o se il nome fornito termina con un punto. Obbligatorio.
Titolo	Titolo del documento. Obbligatorio.
Categoria	Categoria a cui appartiene il documento. Può essere assegnata anche direttamente dalla vista agendo su più documenti. Obbligatorio.
Ordinamento	Permette di ordinare i documenti all'interno di una categoria. A parità di ordinamento il sistema ordina per nome.
Body	Nei man primari questo testo diventa la prefazione. Nei man secondari segue il titolo del documento e si frappone tra il titolo e il contenuto del man.
Contenuto	Un elenco di comandi. Ogni comando prevede un livello: H0, H1, H2, H3, H4, H5, H6, H9. Associato al livello vi è un comando: Un Titolo. Un documento. Una lista di documenti. Una lista categorizzata di documenti. Una lista dinamica di documenti.
Indice Generale	Significativo solo sui documenti man primari. Quasi sempre richiesto.
Lista delle Tabelle	Significativo solo sui documenti man primari. Richiesto se sono presenti tabelle con caption e se si ritiene utile censirle.
Lista delle Figure	Significativo solo sui documenti man primari. Va richiesto se sono presenti figure con caption.
Indice Documenti	Significativo solo sui documenti man primari. Quasi sempre richiesto.
Ometti Indice HTML	Sempre significativo. Se richiesto il documento html non conterrà l'indice.

Nella compilazione del contenuto di un manuale valgono le seguenti regole:

1. Un man senza contenuto si comporta esattamente con un dcv. Vi sono comandi che cambiano il dtd da dcv a man e viceversa. Trasformare un man in un dcv comporta la perdita delle informazioni specifiche del man.
2. E' possibile fornire un input parziale e chiedere al sistema di completarlo premendo il tasto sgml. In particolare:
1. Sè è presente un link NOTES, il sistema crea anche un comando #dcl(nome) e un commento che riporta il titolo corrente del documento.
2. Se è presente un comando #dcl(nome) e il documento è gestito in notes il sistema crea un link notes automaticamente.
3. Le opzioni TeX sono significative solo per i man primari.
4. Il livello H0 può essere usato solo nei man primari. Non può essere assegnato ad un documento ma solo ad un titolo.
5. Il livello H9 può essere usato solo nei man primari. Non vuole nè documento nè titolo.
6. Il contenuto deve sempre partire dal livello H1, sia nei man primari che secondari. Nel caso dei MAN secondari il livello effettivo è il risultato della somma dei livelli di inclusione.
7. E' possibile forzare o omettere il titolo di un documento.
8. Il comando "@DocList" include tutti i documenti con un certo schema di nome.
9. Il comando "@CatList" include i documenti categorizzati che appartengono ad una determinata categoria. Le categoria vanno a formare livelli intermedi di titoli.
10. Il comando "@AutList" include tutti i documenti con un certo schema di nome che siano stati citati dai documenti che precedono fisicamente questo comando.

E' frequente adottare uno schema "elenca e includi": si elencano dei documenti per poi includerli uno dopo l'altro. Questo schema quando viene tradotto in HTML comporta una "strana" dupicazione di link. Infatti saranno presenti sia i link dell'elenco che quelli generati dal contenuto. Questa stranezza deriva dal fatto che il "contenuto" si traduce in html come elenco di link, non avendo alcun senso includere i documenti¹. Il parametro "Ometti Indice HTML" ha lo scopo di evitare questa duplicazione nella presentazione html e continuare a gestire lo schema "elenca e includi" in TeX.

I documenti man sono visibili nelle:

• Vista Documenti Categorizzati
• Vista Manuali Categorizzati

---

¹ Se così non fosse un'intero manuale di 300 pagine andare a formare un unico mostruoso documento html. Documento che abuserebbe delle capacità del browser e della pazienza dell'utente!