13.4. Dobre zwyczaje obowiązujące przy pisaniu dokumentacji

Aby zapewnić optymalne działanie skryptu docgen oraz zapewnić generowanie dokumentacji, która jest zgodna ze standardem języka HTML w wersji 4.01, dobrze jest się stosować do następujących zasad:

• Listy (<ol>, <ul>) należy umieszczać w podsekcji jednoparagrafowej docgena, gdyż w przeciwnym wypadku między znacznik otwierający a zamykający wstawiane są znaczniki <p>, co powoduje, że dokument staje się niezgodny ze standardem HTML 4.01 oraz powoduje niepoprawne wyświetlanie np. w przeglądarce Konqueror.

• Zawsze należy zamykać otwierane znaczniki. Co prawda niektóre przeglądarki poprawnie wyświetlają strony z niedomkniętymi znacznikami <li> czy <p>, ale nie jest to zgodne ze standardem i inne przeglądarki mogą mieć z tym problem.

• Należy używać tylko znaczników, co do których mamy pewność, że są opisane w standardzie - niektóre popularne i szeroko w Sieci opisywane znaczniki (jak np. <nobr>) są rozszerzeniami specyficznymi dla konkretnych przeglądarek i inne mogą mieć z nimi problemy.

• Należy dopisywać wszystkie wymagane atrybuty do znaczników (np. dla znacznika <img> jest to atrybut alt).

• Znak % jest znakiem zarezerwowanym dla zmiennych rozpoznawanych przez skrypt docgen i nie należy go używać wprost w komentarzach. Zamiast niego można zastosować jego kod ASCII zapisany jako &#37;, co w przeglądarce spowoduje wyświetlenie znaku %.