Difference between revisions of "Docbook Conventions"

From GnuCash
Jump to: navigation, search
(Source File Format: (draft))
(Source File Format: trailing spaces, <screen>)
Line 3: Line 3:
 
A unique format facilitates updating translations and improves readability.
 
A unique format facilitates updating translations and improves readability.
 
;Note: This is currently a suggestion and can be discussed on gnucash-devel.
 
;Note: This is currently a suggestion and can be discussed on gnucash-devel.
 +
;No trailing spaces:
 
;Indent: 2 spaces per level, no <code>Tab</code>s
 
;Indent: 2 spaces per level, no <code>Tab</code>s
 +
:;Exception: <screen> etc.
 
;Block elements: require a new line, while for
 
;Block elements: require a new line, while for
 
;Inline elements: should stay on one line.
 
;Inline elements: should stay on one line.

Revision as of 11:11, 27 October 2019

Conventions to use while writing Documentation in Docbook

Source File Format

A unique format facilitates updating translations and improves readability.

Note
This is currently a suggestion and can be discussed on gnucash-devel.
No trailing spaces
Indent
2 spaces per level, no Tabs
Exception
<screen> etc.
Block elements
require a new line, while for
Inline elements
should stay on one line.
Line length
not longer than your display.

Figures, Tables, Formulas

  • should have a unique, but short title. This will
    1. be printed bold on top of the element
    2. generate an entry in the respective list of the document content.
  • If an extended description of an MediaObject is required, add a caption.

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:
<para>
  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>.
</para>

<itemizedlist>
  <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>
  </listitem>
<itemizedlist>

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

<para>
  You can exit from GNU Emacs with 
  <menuchoice>
    <shortcut>
      <keycombo><keysym>C-x</keysym><keysym>C-c</keysym></keycombo>
    </shortcut>
    <guimenu>Files</guimenu>
    <guimenuitem>Exit Emacs</guimenuitem>
  </menuchoice>.
</para>
See also
Docbook Links