Login | Register
My pages Projects Community openCollabNet

A.  The Grammar

[ fromfile: grammar.xml id: grammar ]

To specify that a document uses this grammar, place the following attributes in the root element. For example, here is the root element of this section:

<section id="userguide"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xi="http://www.w3.org/2001/XInclude"
    xsi:noNamespaceSchemaLocation='http://slackerdoc.tigris.org/xsd/slackerdoc.xsd'
>
<title> User's Guide </title>

The formal grammar of Slacker's Docbook is written in W3C XML Schema Description language. It is based on the unofficial Docbook 4.4 xsd.

If you use a modern XML editor such as jEdit (with the XML plugin), you can take advantage of W3C XML Schemas. You can see detailed error messages and completion assistance popups to help you learn the language faster.

If you downloaded Slacker's Docbook to your local machine, you can take advantage of the provided OASIS catalog file. Your editor can use this file and no longer need to grab the schema from the network.

Table A.1 is a table listing the elements of Slacker's docbook. In addition to these, you can use any tag in Docbook 4.4.

Table A.1.  Slacker's Docbook Elements

Element Meaning
<a href="urlref"> <ulink url="urlref">
<b> <emphasis role="bold">
<i> <emphasis>
<img src="fileref">

Includes an image, inserting a <mediaobject><imageobject><imagedata> in its place. The value of the fileref attribute is unchanged, and if a relative path, the referenced file is copied into the destination directory, relative to the generated file. Further, if the output format is PS, any PNG files are automatically converted into EPS using the convert program, which comes with imagemagick.

Other attributes, such as width, height, scale, and scalefit are passed to the <imagedata>.

<include src="srcFile" [mode="modestr"] [segid="segIdRef"] [allfiles="1"]>

srcFile is assumed to be a relative path from this document to a source code example. The example can be trimmed through the use of //start and //end comments.

segIdRef, an optional attribute, is a reference to a named //start id=segId snippet in the included file. This way, you can have different-named snippets included from different examples.

modestr, an optional attribute, can be:

  • cpp - included as code example with C++/QML/Java style comments, with some callout processing. (no linewrap). Equivalent to js and qml mode.

  • code - included as example Python/Perl/Shellscript comments (no linewrap)

  • txt or text - included as an example text file with linewrap.

This tag includes srcFile at preprocess time, and inserts its contents inside an <example><programlisting>. Since each <example> should have an id attribute, it is recommended you also supply an id="idAttr" to the <include>, which will get passed onto the generated <example>.

Each srcFile is linked from the generated HTML example, and is also copied into the build directory so that the relative URL still works, and the generated files can be more easily packaged for distribution.

If the optional allfiles attribute is specified, then all of the sibling files of the included src file will also be copied (non-recursively) into the build directory, to provide a "complete" programming example.

<li> Expanded to <listitem><para> except when inside a <pb> element.
<ol> <orderedlist>
<p> <para>
<pb> "parabullet" - mapped to <orderedlist> when "slides" condition is true. Add child <li> elements around each major idea or sentence. When slides condition is not true, a <pb> is rendered as a single <para>, and all the <li> tags inside the <pb> are removed.
<pre> <programlisting>
<tt> <literal>
<ul> <itemizedlist>