Login | Register
My pages Projects Community openCollabNet

3.  Stylesheet Test

[ fromfile: styletest.xml id: styletest ]

Abstract

This file is an example that uses all Slacker document elements, and a subset of common/popular elements from the Docbook language. It's also a testcase for the scripts and stylesheets.

[Important] What is Slacker's Docbook?

hi there

Slacker's Docbook is two things.

  1. A language which you can write books in

  2. A set of scripts and files which convert from Slacker's Docbook (the language) into Docbook/XML, and later to other file formats such as HTML, PDF, LaTex.

The motivation for developing this is explained in Section 1.

Most of the non-Docbook tags added to Slacker's Docbook will be familiar to anyone who has edited an HTML page, since they were taken from HTML.

It is much faster and easier to compose Slacker's than to use standard Docbook/XML.

The scripts are organized and deployed by Apache Ant, an open source, cross platform, Java-based build tool.

Output format is controlled by easily customizable stylesheets which we have provided.

The use of several Slacker's Docbook tags and directives is demonstrated below.

This text is in a condition="textbook" element, so it only appears in the textbook version.

ant bookhtml or ant pdf both generate versions that include textbook elements. An alternate way of describing textbook conditionals is with the <textbook> tag. This is equivalent to a <p condition="textbook">

Figure 2.  A title for a figure

A title for a figure

  1. Here is an ordered list. item. It should look familiar since it's tag is borrowed from XHTML.

  2. This ordered list shows you which version(s) you are reading:

  3. You are reading textbook text.

  4. This listitem item appears in every version

An admonition is a Docbook tag with a title and an associated icon.

Here are the available admonitions. The original Docbook admonitions are all supported in Slacker's Docbook; however, we have added two new tags: <prereq> and <question>.

[Warning] Warning

Danger Will Robinson. Things to be careful about.

[Warning] Caution

Cautions can be dangerous to your health. They happen to be mapped to <warning> anyway.

[Note] This is a note

Take note of that. It's important!

[Note] Important

This is actually not so important, since it's mapped to <note>.

[Tip] Tip

This is a tip. It's very good advice. It could save you time.

[Important] Question

The Docbook meaning of <question> remains the same if it appears inside a <qandaset>. However, if it appears where a other admonitions are allowed, <question> is mapped to the docbook important admonition.

[Caution] Prerequisites

This is inside a <prereq>. It's mapped to the <caution> admonition since we are not using it.

The glyphs are taken from Bobco fonts, with copyrights held by the Subgenius Foundation [1].

A formalpara about parabullet (<pb>) .  This is a <formalpara> which is discussing the parabullet that follows. parabullets are very interesting because they are rendered quite differently depending on which version you are generating. In order to simultaneously write bullet-text for the slides version and paragraph text in the book version without repeating yourself, mark each paragraph as a <pb>, marking up each major idea in it as an <li>.

This content is inside <pb>, which is short for parabullet. When a <pb> is encountered, and condition['slides'] is not true, we translate <pb> into <para>, stripping all <li>s. Otherwise, the preprocessor translates each <li> into a <listitem> <para> and the <pb> maps to an <unorderedlist>. They appear as bullets in the slides version and paragraphs in the textbook. This means that unordered lists inside <pb>should be properly punctuated. <li> is much easier to type than <listitem> <para>.

  • This is a regular unordered list.

  • It should appear always as a bullet in all versions.

  1. Add keyword-processing with hyperlinks to the Element Reference Guide. We have it already in the C++ textbook.

About including files

When including C++, you can use //start and //end comments to switch on/off inclusion.

In addition, c-style multiline comments appear as callouts in the program listings, if they do not start on a new line.

Click on filename, or the "link" icon below the included code to see the original file before processing. Notice we only see a small piece of the larger file, bettween the lines marked with //start id="menu" and //end, due to the segid="menu" attribute in the <include> tag.

Example 4. src/dialogs.cpp

[ . . . . ]


    QMenu *menu = new QMenu("&Questions", this);    1
    /* This is not a callout because it starts on a new line */
    QMainWindow::menuBar()->addMenu(menu);


    menu->addAction("&Ask question",                2
                    this, SLOT(askQuestion()), tr("Alt+A"));
    menu->addAction("Ask a &dumb question",
                    this, SLOT(askDumbQuestion()), tr("Alt+D"));
}

1

Insert a menu into the menubar.

2

It's a good idea to line them up beneath each other.


In this next example, there is no link, and in fact, the included file has restricted permissions, so you should not be able to see it even if you guessed at its url.

Example 5. src/sample.cpp

[ . . . . ]

int main() {
    Point p(1,1);
    const Point q(2,2);
    p.set(4,4);  1
    p.print();
    q.set(4,4);  2
    return 0;
}

1

ok to reassign p

2

error! const object cannot call non-const methods




[1] Praise Bob!