[docs] xmldocs - jon modified refs/no_default_reparse

Davor Ocelic docelic at mail.inet.hr
Sat Aug 20 15:00:07 EDT 2005


> Expand on pragma no_default_reparse documentation. Davor, let me know if
> any of this is misformatted.

Hoy, glad to see others catching up ;-)

It's generally OK.

The primary "rule" that you broke, however, is putting universally 
applicable style instructions into individual reference pages.

See, users visiting the "no_default_reparse" pragma documentation
will learn that *pragmas are best defined at the top of pages*,
while users visiting all other pragma pages will not be told the same.

Therefore, by nature, such information should be moved to 'pragma'
glossary entry which, by definition, contains all information 
about pragmas.


Second problem is, there are entity files in xmldocs/docbook/*.ent.
It is always advisable to use entities instead of manual markup.

For example, catalog.cfg should always be written as &ccf; ,
this entity will expand to <filename>catalog.cfg</filename>.
Likewise, interchange.cfg should be written as &gcf;.
See docbook/*.ent files for a list of possible entities.

Look up the upcoming diff for other changes.


Enjoy,
-doc



More information about the docs mailing list