Comments on Docs

[Ali Abdin <aliabdin aucegypt edu>]

Hmmm - it seems that a number of authors don't seem to read the GDP Handbook
:) It explicitly states that all tags should be lowercase (but not things like
entities!) yet people have entities in lowercase :)

Also - according to the GDP. Each sect must have its own unique id (not a
DocBook requirement though). I quote the relevant section of the GDP:

"Regardless of which elements you use, give each structural element a unique
id, so that you can link to it. For usage example, see the template."



Also - in the gnome-app-template file you have a <sect1 id="license"> that
states the license of the documentation - Is this the GDP way of adding
licenses to docs, or are we supposed to just have legalnotice (if the former,
I don't really need to change gnome-db2html2, but if the latter then I need to
modify gnome-db2html2 and somebody needs to modify the gnome-app-template
file)

I also encountered a bad run-in with a file that did not put a closing bracket
on a sect2 tag! ick. It's been fixed now though - but I also remember seeing a
doc that had &hellip (no semicolon) - Of course when we switch to DocBook XML
everyone can just use xmllint to verify their docs :)

Regards,
Ali