9.2. Technicalities

9.2.1. DocBook

sci-BOT is written in xml-DocBook. Any aspiring author should get a copy of Norman Walsh and Leonard Muellner's, "DocBook: The Definitive Guide". See, [Walsh:1999] for full bibliographical details. An online version of the book is available at DocBook-Online, and an archive of DocBook-Online is provided, too.

Furthermore, we recommend Nik Clayton's "FreeBSD Documentation Project Primer for New Contributors". It gives a gentle introduction to the whole business of using DocBook, and moreover, elaborates on semantical and stylistic issues.

9.2.1.1. Guidelines

  • The preferred text width is 79 characters.

  • Tabulator characters are forbidden; always use spaces.

  • CDATA sections are forbidden.

  • The use of double quotes in para or similar elements is deprecated; use quote or blockquote instead.

  • All id attributes are made of the characters a-z (lowercase only), 0-9, and the dash -.

  • For the following elements identifiers are mandatory: chapter, sect1, sect2, ... sect6, indexterm, example, figure, biblioentry, and co.

  • Identifiers are made up of lowercase alphanumeric characters and dashes. If an element carries an identifier, the identifier must have a prefix. The prefix is separated from the rest of the identifier with a dash.

    tag prefix
    <chapter> chap
    <sect1>, <sect2>, ..., <sect6> sect
    <titleabbrev> chsh or sesh for <chapter> or <sect>N. In general: the first two letters from the prefix plus "sh".
    <indexterm> idx
    <biblioentry> bib
    <equation>, <informalequation> eq
    <table>, <informaltable> tab
    <figure>, <informalfigure> fig
    <example> ex
    <co> co
    <listitem> item

9.2.1.2. Indentation style

Our indentation style mostly follows the common SGML/XML DocBook indentation, with few exceptions:

  • The principal indentation is 4 characters, not 2.

  • Sectioning tags like <chapter>, <sect1>, <sect2>, ..., or <sect6>, do not increase the indentation level; they always start at column 1;

  • <para> is never formatted inline, but as block with the appropriate indentation.

  • <title>, <entry>, and <term> change their inlining character depending on the length of the contained text. As long as the tag and the contained text fit in one line, the tags are formatted inline, otherwise they go on lines by themselves and the contents is indented.

9.2.2. Tables

We prefer tables to be formatted according to DIN 55301. Some formatting systems might not be able to produce a fully compliant output, as well as some output formats are incapable of representing a correctly formatted table. Therefore, we do not only show the SGML-source code, Example 9-1, to mark up a table, followed by the rendered table, Table 9-1, but also a correctly rendered one, Figure 9-1, which was produced by LaTeX.

The DIN 55301 takes about ten pages, explaining the construction of a table in detail; most important for sci-BOT are the following rules:

Example 9-1. SGML-code for a DIN compliant table


<table id = "tab-table-din55301" frame = "top">
    <title>DocBook approximation of a DIN conforming table</title>

    <tgroup cols = "12">
        <colspec colname = "col-pid" align = "right"></colspec>
        <colspec colname = "col-usr" align = "left"></colspec>
        ...
        <colspec colname = "col-cmd" align = "left"></colspec>

        <spanspec spanname = "sp-id" namest = "col-pid" nameend = "col-usr"
                  align = "center" colsep = "1"></spanspec>
        <spanspec spanname = "sp-sched" namest = "col-pri" nameend = "col-ni"
                  align = "center" colsep = "1"></spanspec>
        ...

        <thead>
            <row>
                <entry spanname = "sp-id">Identification</entry>
                <entry spanname = "sp-sched">Scheduling</entry>
                <entry spanname = "sp-mem">Memory</entry>
                <entry align = "center" colsep = "1"
                       morerows = "1" valign = "middle">Stat</entry>
                <entry spanname = "sp-res">Resources</entry>
                <entry align = "center" colsep = "1"
                       morerows = "1" valign = "middle">Command</entry>
            </row>

            <row>
                <entry align = "center" colsep = "1">PID</entry>
                <entry align = "center" colsep = "1">User</entry>
                ...
                <entry align = "center" colsep = "1">Share</entry>
                <!-- space occupied by "Stat" -->
                <entry align = "center" colsep = "1">%CPU</entry>
                <entry align = "center" colsep = "1">%Mem</entry>
                <entry align = "center" colsep = "1">Time</entry>
                <!-- space occupied by "Command" -->
            </row>
        </thead>

        <tbody>
            <row>
                <entry>737</entry>
                <entry>root</entry>
                ...
                <entry>X</entry>
            </row>
            ...
        </tbody>
    </tgroup>
</table>
   

Table 9-1. DocBook approximation of a DIN conforming table

Identification Scheduling Memory Stat Resources Command
PID User Pri Ni Size RSS Share %CPU %Mem Time
737 root 15 0 56644 55M 1556 S 0.9 22.1 0:07 X
1675 cspiel 13 0 1752 1752 1424 S 0.5 0.6 0:00 xisdnload
1973 lvandijk 14 0 1176 1176 988 R 0.5 0.4 0:00 top
2 root 10 0 0 0 0 SW 0.1 0.0 0:00 kswapd
1656 cspiel 10 0 1356 1356 1108 S 0.1 0.5 0:00 bbsload
1764 lvandijk 18 0 6380 6380 3112 S 0.1 2.4 0:09 emacs

Figure 9-1. Table formatted according to DIN 55301

 Example table formatted according to DIN 55301

The output of the top(1) command formatted according to DIN 55301.



9.2.3. Examples

Examples within the main text, should be as short as possible, retaining their completeness. If an author likes to give the complete version of an example, she is encouraged to do so by including it in the Appendix. <xref>s should be added in the main text and in the Appendix to allow for easy moving between the example's abridged and the full version.

Particularly interesting code can go into the Appendix, without having a short equivalent in the running text. No cross-references are necessary in this case.

If the Scilab source of an example is to be included in the file scibot-examples, its listing must be marked up in a special way.

Hints for preparing examples. Our policy forbids the use of CDATA marked sections in sci-BOT. Therefore, all examples are contained in <programlisting> elements, where the usual DocBook formatting rules are active.

9.2.4. Graphics

The inclusion of graphics is a relatively labor intensive job, despite the use of a publishing system that does well support graphics. (The future is so bright, we've gotta wear shades.) So, use it sparingly.

Graphics are wrapped in <mediaobject>s. Graphics must always be supplied in at least Encapsulated PostScript® and in Portable Network Graphics (png) formats. Providing additional formats is up to the author, however gif-encoded images are excluded from sci-BOT because of copyright issues. A <textobject> holding the textual description of the image is as mandatory as an image caption. A complete definition looks like this:

Example 9-2. Inclusion of graphics


<mediaobject>
    <imageobject>
        <imagedata fileref = "graphic.eps" format = "EPS"></imagedata>
    </imageobject>

    <imageobject>
        <imagedata fileref = "graphic.png" format = "PNG"></imagedata>
    </imageobject>

    <textobject>
        <!-- textual description of the image -->
        <phrase>...</phrase>
    </textobject>

    <caption>
        <para>
            ...
        </para>
    </caption>
</mediaobject>
   

In the example we have assumed that there are two graphics files named graphic.eps, and graphic.png. If the author wants an image or set of images go into the List of Figures, the whole <mediaobject> can be wrapped in <figure>.

9.2.5. Mathematics

In the current version of sci-BOT, the use of MathML is not allowed, but as soon as a wider variety of browsers will support MathML, it will be recommended. At present, the only mathematical notation which can be encoded directly in DocBook are superscripts (<superscript>), and subscripts (<subscript>). All "higher" mathematics is encoded with LaTeX as described below.

Equations are treated as graphics (see Section 9.2.4), where the filenames of the graphics files have a special meaning, the textobject has a special format, and the caption is missing.

The textobject must contain exactly one phrase element with attribute role having the value "formula", and the attribute id being the LaTeX-filename of the formula.

Example 9-3. Inclusion of mathematics


<informalequation id = "eq-diff">
    <mediaobject>
        <imageobject>
            <imagedata fileref = "eq-diff.eps" format = "EPS"></imagedata>
        </imageobject>

        <imageobject>
            <imagedata fileref = "eq-diff.png" format = "PNG"></imagedata>
        </imageobject>

        <textobject>
            <phrase role = "formula" id = "eq-diff.tex">
                \[
                    \frac{df}{dx}(x_0) :=
                    \lim_{x \rightarrow x_0} \frac{f(x) - f(x_0)}{x - x_0},
                \]
            </phrase>
        </textobject>
    </mediaobject>
</informalequation>
   

Whenever a formula is set up like this, the build system automatically converts the LaTeX formula in the phrase to the required eps and png files.

9.2.6. Index terms

Index term start tags <indexterm> can carry a role attribute that further specifies which kind of term gets indexed. Marking up <indexterm>'s this way is not required. Currently only Texinfo can handle these role attributes.

Attribute Value Index Class Candidate Elements
c A concept index listing concepts that are discussed. various
f A function index listing functions. funcsynopsis, function
v A variables index listing variables. classname, constant, structfield, structname, symbol, token, type, varname
k A keystroke index listing keyboard and mouse commands. accel, action, guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu, keycap, keycode, keycombo, keysym, menuchoice, mousebutton, shortcut
p A program index listing names of programs. application, command