Docbook Conventions

From GnuCash
Jump to: navigation, search

Conventions to use while writing Documentation in Docbook

No Direct Formating

Like for HTML you can use CSS, Docbook delegates the formating to xsl stylesheets.

Markups like
<emphasis role="bold">Fat text</emphasis>
are a bad idea. How should a screenreader interpret this? Do other elements exist which tell about the semantic of your string? A few examples:
  The <keycap>F1</keycap> key on an IBM PC keyboard generates the
  scan code <keycode>0x3B</keycode> when pressed.  This value
  is defined as <keysym>KEY_F1</keysym> in 
  <filename class="headerfile">keyboard.h</filename>.

  <title>Fields in the xyz Dialog</title>
  <listitem><para><guilabel>Encoding</guilabel>: This is usually the UTF-8 variant.</para</listitem>
  <listitem><para><guilabel>Magic</guilabel>: Mages will know.</para>
    <warning><para>Do not use it!</para></warning>

  Typing <userinput>Ex</userinput> will match the <computeroutput>Expenses</computeroutput> section of the account list.

  You can exit from GNU Emacs with 
    <guimenuitem>Exit Emacs</guimenuitem>
See also
Docbook Links