Difference between revisions of "Docbook Conventions"
From GnuCash
(→Source File Format: (draft)) |
(maint -> stable) |
||
| (8 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
Conventions to use while writing Documentation in Docbook | Conventions to use while writing Documentation in Docbook | ||
| + | [[Category:Documentation Development]] | ||
| + | |||
==Source File Format== | ==Source File Format== | ||
| − | A unique format facilitates updating translations and improves readability. | + | A unique format facilitates ''updating translations'' and ''improves readability''. |
| − | + | You can get this now by using [{{URL:GH}}Gnucash/gnucash-docs/blob/stable/util/xmlformat/README xmlformat] after saving your changes, but if you want to adjust your editors settings:. | |
| − | ;Indent: 2 spaces per level, no <code>Tab</code>s | + | :;No trailing spaces: |
| − | ;Block elements: require a new line, while for | + | :;Indent: 2 spaces per level, no <code>Tab</code>s |
| − | ;Inline elements: should stay on one line. | + | ::;Exception: <screen> and other verbatim elements |
| − | ;Line length: not longer than your display. | + | :;Block elements: require a new line, while for |
| + | ;;Inline elements: should stay on one line. | ||
| + | :;Line length: not longer than your display. | ||
| + | [https://github.com/Gnucash/gnucash-docs/blob/stable/util/xmlformat/xmlformat.conf Full recent configuration] | ||
| − | ==Figures, Tables, Formulas== | + | ==Figures, Tables, Examples, Formulas== |
* should have a unique, but short title. This will | * should have a unique, but short title. This will | ||
*# be printed bold on top of the element | *# be printed bold on top of the element | ||
*# generate an entry in the respective list of the document content. | *# generate an entry in the respective list of the document content. | ||
| + | *#;Note: This lists are currently not displayed by yelp, but in all other formats. | ||
* If an extended description of an MediaObject is required, add a caption. | * If an extended description of an MediaObject is required, add a caption. | ||
| + | ===Tables=== | ||
| + | ''Yelp'' dislikes missing table entries and aborts the rendering after the last defined entry, while ''HTML'' completes the rest. | ||
==No Direct Formating== | ==No Direct Formating== | ||
| − | Like for HTML you can use CSS, Docbook delegates the formating to xsl stylesheets. | + | Like for HTML you can use CSS, Docbook delegates the formating to [{{URL:GH}}Gnucash/gnucash-docs/tree/stable/xsl xsl stylesheets]. |
Markups like <Syntaxhighlight lang="xml"> | Markups like <Syntaxhighlight lang="xml"> | ||
<emphasis role="bold">Fat text</emphasis> | <emphasis role="bold">Fat text</emphasis> | ||
| Line 50: | Line 58: | ||
</para> | </para> | ||
</Syntaxhighlight> | </Syntaxhighlight> | ||
| − | ;See also: [[Docbook Links]] | + | ;See also: [[Docbook Links]] and [[Docbook Processing]] for some subtile differences. |
| − | [[ | ||
| − | |||
Latest revision as of 00:33, 25 October 2023
Conventions to use while writing Documentation in Docbook
Contents
Source File Format
A unique format facilitates updating translations and improves readability. You can get this now by using xmlformat after saving your changes, but if you want to adjust your editors settings:.
- No trailing spaces
- Indent
- 2 spaces per level, no
Tabs- Exception
- <screen> and other verbatim elements
- Block elements
- require a new line, while for
- Inline elements
- should stay on one line.
- Line length
- not longer than your display.
Figures, Tables, Examples, 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.
- Note
- This lists are currently not displayed by yelp, but in all other formats.
- If an extended description of an MediaObject is required, add a caption.
Tables
Yelp dislikes missing table entries and aborts the rendering after the last defined entry, while HTML completes the rest.
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 and Docbook Processing for some subtile differences.
