Working with DocBook

In any convenient directory, create your document directories with your source documents. You will need to create a site map and an outline for the document set.

Finally, copy build.xml from /home/zeil/usr/local/DocBook/tools/ into that directory. Use a text editor to open up build.xml. If necessary, change the docbook, sitemap, and outline properties near the start of that file.

DocBook actually provides a variety of linking mechanisms, but xxe does not offer all of them as options to insert into your documents. It's when you are doing linking that you are likely to be most aware of the fact that DocBook is, underneath it all, XML. Even more important than the specific tags used to support linking are the attributes:

For consistency, the same attributes are used, without the namespaces, in other linking contexts within this tool set. Both the course outline and the html output format allow the use of href to link outside of the document set and targetdoc/targetptr to link within the document set.

The actual link forms that you can insert into your documents with xxe are links and olinks.

The usual DocBook element for source code is the programlisting. One of the optional attributes for a programlisting is the language. If you set the language attribute to cpp or to java, then the source code will be highlighted accordingly.

Here, for example, is a programlisting with no language value set.

#include <iostream>

using namespace std;
/*  A simple
    program */
int main()
{
  cout << "Hello World!" << endl;
  return 0; // Zero denotes a normal termination
}

and here is the same listing with a language attribute of cpp:

#include <iostream>

using namespace std;
/*  A simple
    program */
int main()
{
  cout << "Hello World!" << endl;
  return 0; // Zero denotes a normal termination
}

DocBook contains elements that serve as "wrappers" for mathematics but does not, itself, provide for formatting and display of mathematical expressions. To actually create mathematical formulae, the tool set has support for ASCIIMath.

To activate this support, your document must have at least one element, anywhere in the document, that has a role attribute of "`text(am)text(ath)`". I usually put this on the DocBook wrapper elements for mathematics such as informalequation or inlineequation.

A typical sequence for creating a line of mathematics, then, is to insert an informalequation just after a paragraph. xxe will automatically insert a mathphrase inside the informalequation. Within the mathphrase you can type text. Type the reverse apostrophe (the one under the ~ key on most keyboards), then one or more spaces, then the equation you want (in the ASCIImath format), then one or more spaces, then close with another reverse apostrophe.

Obviously, as you modify your document set, things can go wrong.

The ant build process generates a steady stream of messages, some pure information and some errors. You can capture these into a file by using the -l option to write all messages to a log file, e.g.:

ant -l build.log

Unfortunately, that hides the messages from you while the build is running. On Unix/Linux system, therefore, I prefer

ant | tee build.log

There are several ways in which to override the default appearances I have set up.

Most documents won't use all of these mechanism. In order to avoid false error messages from link checkers, the actual code to load these files is inserted into web pages only if those files exist at the time that you build the document set. Keep in mind then, that if you decide to add a new .css file for the first time, you will need to rebuild all the affected documents before they start using it.

There's not, at the present, a whole lot of Javascript used in this toolset. It's used

If you need to add new Javascript, then the rules are exactly the same as for the CSS files above. Just replace ".css" by ".js".

The shared directory is also used to hold the graphics for the navigation icons, the callout marks, and a few other things. So, if you decide you don't like the look of the prev/next pointers and want to use something else, just place your own versions in your own shared directory.