Scilab Bag Of Tricks: The Scilab-2.5.x IAQ (Infrequently Asked Questions) | ||
---|---|---|
Prev | Chapter 9. Notes for Contributers | Next |
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.
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 |
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.
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:
Top and bottom of the table header are framed, but never are the header's left or right sides.
Logical lines in the table header are separated by rules.
In the header different columns within one logical line are separated with vertical rules. The width of a column must be less or equal the width of the column above it.
Entries in the header are centered horizontally and vertically.
The table body lacks any rule.
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 |
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.
<programlisting> must contain the two attributes role, and id.
role must be scilab.
id must end in .sci. The id will be the filename of the example when stored in the archive.
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.
Relational operators containing "<"; or ">"; must be written as <, or > respectively. Note that this also holds for digraph operators like "<=", and ">=", or anything else – think of comments – that contain "<"; or ">".
Logical and, "&", must be written as &.
Additional comments to the code should be wrapped in <lineannotation> elements. These will be stripped off when generating scibot-examples.
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>.
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.
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 |