Step by Step Example

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.

Step 1: Including the Document Type Declaration

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">
	  
	

Step 2: Adding a "root" element

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

Step 3: Adding an article header

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

Step 4: Adding revision history

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.

Step 5: Adding a first level section

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 the section 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 inside para or equivalent elements.

I think you're probably getting the hang of it at this point.

Step 6: Adding subsections and sub-subsections

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>