Testo nei Sorgenti

All'interno dei sorgenti lo sviluppatore utilizza dei tags per comunicare con il sistema di documentazione. Il testo che viene preparato è normalmente in ascii senza particolari markup. E' anche possibile controllare la formattazione delle descrizioni lunghe usando direttamente il markup sgml. La difficoltà è minima. La derivazione del markup adottato da html semplifica ulteriormente l'utilizzo. Normalmente si utilizzano i comandi più immediati e semplici¹:

1. Paragrafi: <P> .
2. Liste: <OL>, <UL> e <LI>.
3. Attributi: <B>, <I>, <SMALL>.

Vi sono alcune regole che vanno rispettate. Innazitutto bisogna identificare il tipo di testo:

1. I paragrafi singoli non richiedono il markup <P>.
2. I paragrafi multipli richiedono il markup. E' possibile omettere l'apertura o la chiusura ma è molto meglio aprire a chiudere ciascun tag.
3. I caratteri speciali (< > " &) vanno inseriti come entità, seguendo le regole sgml e html: (&lt; &gt; &Quot; $anp;). E' anche ammessa la forma #sym(lt), #sym(gt), ...
4. I nomi, ad esempio i nomi delle funzioni, devono essere compilati usando i soli caratteri ascii standard (cioè fino a 128). Non vi è motivo di far diversamente in quanto il compilatore ha i medesimi requisiti.
5. I titoli possono contenere solo testo Latin-1 ed entità.
6. Le descrizioni brevi, ad esempio quelle di un parametro di una funzione, sono nel formato mini-body. Normalmente dovrebbero contenere solo paragrafi e liste.
7. Le descrizioni estese sono nel formato body-nh. Possono socntenere tutto il markup previsto per il body con l'esclusione dei titoli e delle righe orrizontali.

Nell'esempio che segue vediamo:

• Il titolo della funzione.
• La descrizione breve del parametro di input. Decrizione che comprende un link. Il sistema considera tutto il testo un 'unico paragrafo e aggiunge il markup <P>.
• La descrizione lunga di tutta la funzione. Normalmente questa è l'unica zona che può richiedere un markup sgml.

/**
*************************************************************************************
@Fun     Sets the abort handler
@Param   p_abort_ar  IN  A pointer to the abort routine of type #dat(pABORT_AR)
@Descr   
<P>Sets the new abort handler. If the parameter is NULL it calls
#fun(abort_ar_UnSetRoutine).
The abort handler is used by the #fun(AbortAR) routine. This function is usually 
invoked by the library to set up the proper handler.</P>
<OL>
    <LI>If you need to ask <B>Do not use it>/B>!</LI>
    <LI>If you are not a library developer <B>forget alla about it</B>!.</LI>
</OL>
@/Descr                    
*************************************************************************************
**/
...

¹ E' possibile utilizzare tutto il markup previsto. L'area più difficile da preparare a mano --- anche perchè si scosta alquanto da html --- è il markup delle tabelle. La politica deve essere quella di compilare i testi lunghi e complessi usando notes evitando di incorporarli nei sorgenti. In caso i sorgenti possono citare direttamente questi testi.