Now we'll walk through the process of creating a simple AlcoveBook article. This example includes some of the most commonly used AlcoveBook elements, and is here mostly to show you what a document marked up with DocBook looks like. If you're looking for a more complete list of DocBook elements and their uses, see the Element Reference or the AlcoveBook DTD reference, available at http://debian-docs/alcovebook-sgml-doc/html/DTD-HOME.html.
Assuming that you're marking up an article
,
the first thing you have to have in your document is the
document type declaration:
<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN">
After that, you have to define the "root" element, which will contain
all the other elements in your document. For an article, the root
element is simply article
. So, add this
element and its end tag after the document type declaration:
The article
element has 2 mandatory
attributes, name lang
(with possible values
en, fr, de, es)
and role
(with possible values
proposal, whitepaper,
specification,
documentation, delivery,
other).
lang
is used by the stylesheets for generated
text ("Table of contents", etc.), and role
is
used by the
alcovebook2x
scripts to select a default stylesheet.
<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN"> <article lang="en" role="proposal"> </article>
Everything else you add to your document will be contained within the "article" tags, so when you're done, the last tag in your document should be "</article>".
Next, you'll want to add some "header" information. Header information includes the article's title, the author's name and email address, the revision history of the document, and lots of other stuff. For now, we'll just add the article title and the author name (not that your document is not usable yet).
<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN"> <article lang="en" role="proposal"> <articleinfo> <title>A practical introduction to AlcoveBook</title> <subtitle></subtitle> <author> <firstname>Benjamin</firstname> <surname>Drieu</surname> </author> <date>28 August 2001</date> </articleinfo> </article>
Note: The
subtitle
element is mandatory. For AlcoveBook purposes, you should use it for the type of document (eg. "commercial proposal").
You now have to add a revision history, by using the revhistory
tag.
<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN"> <article lang="en" role="proposal"> <articleinfo> <title>A practical introduction to AlcoveBook</title> <subtitle></subtitle> <author> <firstname>Benjamin</firstname> <surname>Drieu</surname> </author> <date>27 August 2001</date> <revhistory> <revision> <revnumber>0.1</revnumber> <date>27 August 2001</date> <revremark>Initial revision</revremark> </revision> </revhistory> </articleinfo> </article>
Revision history elements are detailed in the Section called Revision information.
So, now that we have some header information added, lets actually add some content in a level 1 section with a title:
<!DOCTYPE article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN"> <article lang="en" role="proposal"> <articleinfo> <title>A practical introduction to AlcoveBook</title> <subtitle></subtitle> <author> <firstname>Benjamin</firstname> <surname>Drieu</surname> </author> <date>August, 27, 2001</date> <revhistory> <revision> <revnumber>0.1</revnumber> <date>27 August 2001</date> <revremark>Initial revision</revremark> </revision> </revhistory> </articleinfo> <section> <title>Introduction</title> <para> It is quite decent to begin a text with an introduction. </para> </section> </article>
Note: Note the
title
element in thesection
element. This element names the section it is in.After this element, there is a
para
element, which contains text. In AlcoveBook, it is mandatory to write text insidepara
or equivalent elements.
I think you're probably getting the hang of it at this point.
Adding subsections and sub-subsections is also simple. There is no separate element for subsections and sub-subsections. A section of level n is simply included in a section of level n-1. So, to write a subsection:
Example 6. Subsection example
<section> <title>Ye old good stories of uncle Benj</title> <section> <title>The story of Paf the dog</title> <para> Once upon a time ... </para> </section> <section> <title>The story of two frogs on a railway</title> <para> Once upon a time ... </para> </section> </section>