The following is a short and incomplete guide to the most commonly used AlcoveBook elements. For further reference, see the AlcoveBook DTD.
Any AlcoveBook "article" should include an article header. The article header contains information such as the article title, author, revision history, abstract, and so forth. The order of appearance of elements is not important, but some elements must appear exactly once (title, subtitle, date, revhistory), some must not appear more than once (abstract, invpartnumber), and all others, when appearing more than once, must be grouped together (eg. you can't insert a corpauthor between two author elements).
articleinfo: the "arthinfo" element contains all of the other elements that make up the article header.
title: the "title" element contained in the article header defines the article title. So, if you're writing an article called The Necromicon, your article header would look like this:
<article lang="en" role="proposal">
<articleinfo>
<title>The Necromicon</title>
...
</articleinfo>
</article>
author is the element which contains all of your author-related information, including first name, surname, email address, organizational affiliation, etc. Each of these pieces of information is marked up separately within the "author" element, which might seem like a bit of a pain, but it's worth it. The more comprehensive the markup, the more we can do with the information when processing the document (eg. produce an index of all documents written by each individual in a firm, which would be quite difficult if the information was not structured enough).
All that aside, here's an example of an article header that contains an author's first name, surname, organisational affiliation, and email address. Usually all you need is the name and email address, and there's other stuff you can add. For now, we'll keep it simple:
<articleinfo>
...
<author>
<firstname>Benjamin</firstname>
<surname>Drieu</surname>
<affiliation>
<orgname>Alcôve Worldwide Inc.</orgname>
<address>
<email>Benjamin.Drieu@fr.alcove.com</email>
</address>
</affiliation>
</author>
...
</articleinfo>
Note: It is possible to specify several authors for an article. It is only necessary to put them one after the other in as much author elements as there are authors.
Most technical documentation goes through a series of revisions as the writer improves and updates the document. In order that readers know which version of a document s/he is reading, technical documentation often includes a revision number and other information. In a AlcoveBook article, the revision information is part of the article header, and is contained in the revhistory element. Here's an example:
<articleinfo>
...
<revhistory>
<revision>
<revnumber>0.1</revnumber>
<date>17 August 2001</date>
<revremarks>
Fist draft
</revremarks>
</revision>
<revision>
<revnumber>0.2</revnumber>
<date>23 August 2001</date>
<revremarks>
Updated section 1
</revremarks>
</revision>
</revhistory>
...
</articleinfo>
Valid elements in a revision context:
revnumber, the number of the revision ;
date, the date of the revision ;
revremarks, a short description of modifications added.
| Warning |
Note that order of revisions is increasing, so put the newest revisions at the end of the revision history. |
Many people write abstracts for their articles, which are short summaries, usually no more than a paragraph long, that tell the reader just what the article is about. In a AlcoveBook article, the abstract is part of the article header, contained in an abstract element.
<articleinfo>
...
<abstract>
<para>
This article describes the steps that are performed to boot
the Linux kernel. While this kind of information is not
relevant to the system's functionality, it's interesting to
see how the different architectures bring the system up.
</para>
</abstract>
...
</articleinfo>
The contractsponsor element describes the customer for which this document is written.
The name of the company that produces the document can be described in the corpauthor element. Since there is no markup yet to incude address and such within corpauthor, Alcôve information must be put just after the corpauthor element, in an address element. Here is an exemple of what the French branch of Alcôve uses:
All of Alcôve documents must have a copyright, which is normaly a double copyright: Alcôve's copyright as well as the author's copyright (ask for confirmation to your project manager, exceptions may exist).
Copyright is described in the copyright element and licencing conditions are described in the legalnotice element. Thus, a document which is under the GNU FDL license would use:
The following elements can be used in a text paragraph in order to mark up in a specific way a part of text:
emphasis: emphases text (exemple) ;
subscript: exemple ;
superscript: exemple ;
quote: quote somebody ("exemple").
If you're doing computer-related documentation or writing, chances are that you're going to have to use code samples, filenames, commands, and other computer-centric things in your document. AlcoveBook, being designed for doing technical documentation, provides tags for marking each of these up as a specific type of element.
When you want to include a multiple-line code example in your document, you should use the programlisting tag included in a example element. You may use example since it allows you to name every example of your document, which can be useful to produce a table of examples, or to have a stylesheet render reference to examples using this name.
Tip: The programlisting element has a width attribute that controls the width of the program listing. It specifies the number of caracters by line.
<section>
<title>Your first C program</title>
<para>
You will write a Hello World! program for your first C lesson:
</para>
<example>
<title>Hello.c</title>
<programlisting>
#include <stdio.h>
int
main (int argc, char ** argv)
{
printf("Hello world!\n");
}
</programlisting>
</example>
</section>
If you want not to mess too much with your example's content, because of the presence of characters that are special to SGML (eg. SGML, XML, or HTML examples, or even C programs), you have to use a special bit of markup that tells the parser to ignore any tags it contains. This special bit of markup is a CDATA marker, the beginning of which appears directly after the programlisting start tag, and which ends just before the programlisting end tag:
<para>
<programlisting>
<![CDATA[
<html>
<head>
<title>Web Page Title</title>
</head>
<body bgcolor="#ffffff">
Web Page Content
</body>
</html>
]]>
</programlisting>
</para>
Note that the beginning of the CDATA marker is "<![CDATA[", and the end of the CDATA marker is "]]>". Any markup contained between the beginning and end bits of a CDATA marker will be ignored by the processing tools and treated as if it were just part of the regular text.
The downside of this is that you can't use, say, tags like function, varname, classname, etc., that could have been used to pretty-print your example, or footnotes, or any other things that would have been useful. An automatic pretty-printer for examples will probably be provided in the future, but you'll have to do things by hand if you want to do sophisticated things. You may want to use a callout where you would have used footnotes.
Appropriately enough, in DocBook you markup filenames with a filename tag. You mark up directories with the same tag, only by adding class="directory" as an attribute. For example:
<para> In case of problems while upgrading from Mandrake 7.3 to Mandrake 8.0, we recommend that you delete the content of the <filename class="directory">/usr</filename> directory and that you install a Debian GNU/Linux distribution instead. </para>
When you want to mark up a command or command line, use the intuitively-named command tag. For example:
<para> When you want to generate HTML output from your AlcoveBook instance, use the <command>alcovebook2html</command> command from the command line. </para>
Often, commands include more than one part, some of which, in documentation, are actually "replaceable", meaning that they indicate something that can be replaced or modified by the user who is typing the command. Use the replaceable element to achieve that purpose.
You can also mark up command options or flags separately as well.
<para>
<programlisting>
<command>apt-get <option>-f</option> install</command>
</programlisting>
</para>
Other elements are available in order to mark computer content:
this element marks a string produced by a computer. Typically an application warning ;
this element marks names of databases data, typically names for tables or columns. Its class specifies the type for this data ;
this element marks the name of a environment variable ;
this element marks a string produced by a user in interaction with a computer program. Typically, it is typed on the standard input ;
this element marks the name of a variable
Lists can be obtained by several ways, but the most usual is to use the itemizedlist element for a non ordered list or the orderedlist element for an ordered list. Each of those two elements may contain a sequence of listitem elements, containing in turn a para element (or another element).
Tables are a bit tricky because AlcoveBook is somewhat verbose. The idea is to define a group of cells, included in rows, included in groups of rows. An example may help you:
The following elements are used to describe a table:
entry describes the content of a cell ;
row describes the content of a row. It has to contain as much entry elements as there are columns in the row group ;
tbody describes the content of the table. It contains as much row elements as there are lines in the table ;
thead describes the table header. It has to contain as much entry elements as there are columns in the table ;
tgroup describes the content a group of rows. It must contain at least one tbody or thead element and a cols parameter, set to the number of columns of the table ;
title describes the table title.
Figure are included with the figure element. This element allows to name a figure and to put an imageobject element in it. For example, to include a photo of your dog (EPS format) in a technical proposal, just use:
It is quite handy to insert external files in a SGML document (i.e. to split a document into as many files as chapters or to insert an exemple rather than using pasting it into the document). Two methods can be used:
using SGML external entities ;
using a DocBook textual inline image.
External entities are defined in the document identification element. See Example 12 for the definition and use of external entities:
This is done by defining an imagedata element (the Section called Figures), i.e. in a mediaobject context. Its format attribute must be specified as linespecific. This solution allows to included documents without SGML transformation of the included document (ie. an image of the file, which can be seen as an image encoded in ASCII instead of a bitmap format). But it is a DocBook feature, not an SGML feature like general entities.