Element Reference

The following is a short and incomplete guide to the most commonly used AlcoveBook elements. For further reference, see the AlcoveBook DTD.

Article header elements

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).

Article header

articleinfo: the "arthinfo" element contains all of the other elements that make up the article header.

Article title

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 information

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.

Revision information

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.

Article abstract

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>
	  

Legal and corporate informations

Specify the customer

The contractsponsor element describes the customer for which this document is written.

Corporate informations

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:

Example 7. Exemple of corporate informations

	    
<corpauthor>
  <ulink url="http://www.alcove.com/">Alcôve</ulink>
</corpauthor>
<address>
  153, <street>Boulevard Anatole France</street>
  <postcode>93200</postcode> 
  <city>Saint Denis</city>
  <country>France</country>
    Tel: <phone>+33 1 49 22 68 00</phone>
    Fax: <phone>+33 1 49 22 68 01</phone>
</address>
	    

Copyright

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:

Example 8. Copyright and distribution terms example

	    
<copyright>
  <year>2001</year>
  <holder>Alcôve and Benjamin Drieu</holder>
</copyright>
<legalnotice>
  <para>
    This document can be redistributed under the terms of the
    GNU Free Documentation Licence. ...
  </para>
</legalnotice>
	      

Marking up text

The following elements can be used in a text paragraph in order to mark up in a specific way a part of text:

Marking up code, filenames, commands, and the like

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.

Code samples

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 &lt;stdio.h&gt;
      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.

Filenames and directories

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>
	  

Commands

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

Other elements are available in order to mark computer content:

computeroutput

this element marks a string produced by a computer. Typically an application warning ;

database

this element marks names of databases data, typically names for tables or columns. Its class specifies the type for this data ;

envar

this element marks the name of a environment variable ;

userinput

this element marks a string produced by a user in interaction with a computer program. Typically, it is typed on the standard input ;

varname

this element marks the name of a variable 

Marking up lists, tables, figures

Lists

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).

Example 9. List example

<para>
  Software used in our offer
</para>
<itemizedlist>
  <listitem>
    <para>Apache, a web server&nbsp;;</para>
  </listitem>
  <listitem>
    <para>Mon a monitoring software&nbsp;;</para>
  </listitem>
  <listitem>
    <para>the Linux 2.4.1 kernel.</para>
  </listitem>
</itemizedlist>
	  

Tables

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:

Example 10. Table example

<table>
  <title>Table example</title>
  <tgroup cols="3">
    <thead>
      <row>
        <entry>Name</entry>
        <entry>Age</entry>
        <entry>Sex</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>Benjamin Drieu</entry>
        <entry>23</entry>
        <entry>Male</entry>
      </row>
      <row>
        <entry>Errol the Hamster</entry>
        <entry>34</entry>
        <entry>Brown</entry>
      </row>
    </tbody>
  </tgroup>
</table>
	  

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.

Figures

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:

Example 11. Figure example

<figure>
  <title>A photo of my dog</title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="rex.eps">
    </imageobject>
  </mediaobject>
</figure>
	  

Using external files

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:

External entities

External entities are defined in the document identification element. See Example 12 for the definition and use of external entities:

Example 12. Example of external entities

<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN" [
  <!-- internal entities -->
  <!entity myfirstname "Benjamin">
  <!entity mysurname "Drieu">
  <!-- external entities -->
  <!entity introsection SYSTEM "intro-section.sgml">
  <!entity foosection SYSTEM "foo-section.sgml">
]>
<article lang="fr">
  <articleinfo>
    <title>A gentle introduction to AlcoveBook</title>
    <subtitle></subtitle>
    <author>
      <firstname>&myfirstname;</firstname>
      <surname>&mysurname;</surname>
    </author>
    <date>10/27/2001</date>
  </articleinfo>

  &introsection;
  &foosection;
</article>
	  

Including an image of the text

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.

Example 13. Example of inline textual image

<mediaobject>
  <imageobject>
    <imagedata fileref="/etc/passwd" format="linespecific">
  </imageobject>
</mediaobject>