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"
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 4.3 (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 1 contains some important elements of Slacker's docbook. It is not a complete list.
Table 1. Common Slacker's Docbook Elements
| Element | Meaning |
|---|
<img src=“pathname”>
|
Includes an image, inserting a <mediaobject><imageobject><imagedata> in its place. The value of the fileref attribute will be an entity reference from the generated DTD if the output format is PS or PDF, but it will be the same given relative URL if HTML is the chosen output format.
In both cases, the referred image is copied into the build directory. Further, when 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=“pathname” mode=“modestr”>
|
src is assumed to be a relative path from this document.
modestr can be:
cpp - included as code example with C++/Java style comments, with some callout processing. (no linewrap) code - included as example python/perl/shellscript comments (no linewrap) txt or text - included as an example text file with linewrap. tex - included as a LaTeX file (? experimental) xml - Replaced with an entity reference to XML file - does not process included document.
If mode is not “xml”, this tag includes a source file 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>.
|
<li>
| Equivalent to <listitem><para>
|
<ol>
| <orderedlist>
|
<p>
| <para>
|
<pb>
| “parabullet” - rendered as an <orderedlist> when “slides” condition is true. Place <li> around each major idea or sentence. When slides is not true, a <pb> is rendered as a single <para>, and all the <li> tags inside the <pb> are removed. |
<ul>
| <itemizedlist>
|
Conditions, and how they are used
Any element can have a condition (sometimes shortened to just a c) attribute. For example:
<pb>
<li> This shows up in in all versions. </li>
<li condition="slides"> This is in the slides </li>
<li c="textbook"> This is a much longer sentence for the textbook. </li>
</pb>
To process a document, you can select multiple conditional values as separate -c options, or as strings separated by commas (no spaces) after a single -c.
python xml2docbook.py -c remark -c slides,html
python xml2docbook.py -c all
The first executes the script with conditions remark, slides, and html switched on, and all other conditons switched off. The second switches “all” conditions on []
Condition attributes are used in a variety of ways. You can add new conditions to suit your particular document. Only some of them have special meaning inside the python scripts, and those meanings are listed here.
Currently used Conditions
html
For HTML output
pdf
pdf output
ps
ps output - converts as needed, all png images to eps and substitutes the extensions of all <img> src attributes.
fromfile
displays the red “fromfile” information at the top of each page.
slides
renders all <pb> tags as <itemizedlist>
textbook
renders all <pb> tags as <para>, and ignores the enclosed <li> tags.
remark
output in red/italic
todo
like remark
solution
solutions guide
instructor
instructor's notes
