Difference between revisions of "Docbook Conventions"
From GnuCash
m (→Figures, Tables, Formulas: typo) |
(→Source File Format: (draft)) |
||
| Line 1: | Line 1: | ||
Conventions to use while writing Documentation in Docbook | 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. | ||
| + | ;Indent: 2 spaces per level, no <code>Tab</code>s | ||
| + | ;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== | ==Figures, Tables, Formulas== | ||
* should have a unique, but short title. This will | * should have a unique, but short title. This will | ||
Revision as of 10: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.
- Indent
- 2 spaces per level, no
Tabs - 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
- be printed bold on top of the element
- 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>
<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
