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:
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>
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 awidth
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:
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.
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:
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>
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.