Difference between revisions of "Docbook Conventions"

From GnuCash
Jump to: navigation, search
(Figures, Tables, Examples, Formulas: This lists are currently not displayed by yelp …)
(maint -> stable)
 
Line 4: Line 4:
 
==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/maint/util/xmlformat/README xmlformat] after saving your changes, but if you want to adjust your editors settings:.
+
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:.
 
:;No trailing spaces:
 
:;No trailing spaces:
 
:;Indent: 2 spaces per level, no <code>Tab</code>s
 
:;Indent: 2 spaces per level, no <code>Tab</code>s
Line 11: Line 11:
 
;;Inline elements: should stay on one line.
 
;;Inline elements: should stay on one line.
 
:;Line length: not longer than your display.
 
:;Line length: not longer than your display.
[https://github.com/Gnucash/gnucash-docs/blob/maint/util/xmlformat/xmlformat.conf Full recent configuration]
+
[https://github.com/Gnucash/gnucash-docs/blob/stable/util/xmlformat/xmlformat.conf Full recent configuration]
  
 
==Figures, Tables, Examples, Formulas==
 
==Figures, Tables, Examples, Formulas==
Line 23: Line 23:
  
 
==No Direct Formating==
 
==No Direct Formating==
Like for HTML you can use CSS, Docbook delegates the formating to [{{URL:GH}}Gnucash/gnucash-docs/tree/maint/xsl 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>

Latest revision as of 00:33, 25 October 2023

Conventions to use while writing Documentation in Docbook

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.

Full recent configuration

Figures, Tables, Examples, 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.
      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>
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 and Docbook Processing for some subtile differences.