Here are some notes about DocBook and general conventions:

(Go to http://docbook.org/ for the full Docbook manual)

-> All chapter and section elements should have 'id' attributes that are the
   same as their ENTITY definitions in manual.xml (this makes it much easier
   to remember them) 

For in-line commands that the user might run, use <userinput>.
For command names use <command>.
For longer or important commands that you want in a new special paragraph, or
for a long interactive session, use <userinput> and <computeroutput>, or <screen>.
For command-line prompts use <prompt>.
For filenames, use <filename>.  
For other code-like things, use <literal> or <constant>.
For variables (environment variables, C++ variables, options in config files, use <envar> or <varname>.
Use <firstterm> around new terminolgy
Use <acronym> around acronyms (this will help us add a glossary of acronyms at
some point in the future if we want).
Use <blockquote> for block quotes.
Use <important> for big flashy warnings, and <note> for set off, but less urgent
notices.
Use these tags for GUI components: (but not all stylesheets render them
specially)
    <mousebutton>
    <guilabel>Field name</guilabel>
    <guimenu>...
    <guisubmenu>...
    <guimenuitem>...
    <guibutton>...
    <guiicon>...
    <menuchoice>
        <shortcut><keycombo><keysym>Ctrl+X</keysym></keycombo>
        <guimenu>Edit</guimenu>
        <guimenuitem>Cut</guimenuitem>
    </menuchoice>       <!-- Usually rendered like: Edit->Cut (Ctrl+X) -->

For command-line parametors, use <option> or <parameter>.

For command synopses use:
<cmdsynopsis>
    <command>command</command>
    <arg>-f <replacable>foo</replacable></arg>  <!-- has [] around it -->
    <arg choice="plain">-b <replatable>bar</replacable></arg>
</cmdsynopsis>

Todo: use <msgset> in the VOP chapter.