Getting started

You don't need any specific tool or editor to write a documentation using AlcoveBook. However, we recommend that you use the Emacs editor and its psgml mode, which offers a lot of interesting features (see the Section called Psgml in Appendix A).

Let's begin with a short example of a basic AlcoveBook document. Please note that this example, although a valid DocBook document, is not a complete AlcoveBook one, and will be gradually completed in the further sections to make it a valid document.

<!doctype article PUBLIC "-//Alcove//DTD DocBook V4.1-Based Subset AlcoveBook V0.1 Draft//EN">
<article>
  <articleinfo>
    <title>Principia Discordia</title>
    <subtitle>or, How I Found the Goddess and 
              What I Did To Her When I Found Her</subtitle>
    <author>
      <firstname>Malaclypse</firstname>
      <surname>The Younger</surname>
      <affiliation>
        <jobtitle>CTO</jobtitle>
        <orgname>Erisian Liberation Front</orgname>
        <address><email>malaclypse@eris.com</email></address>
      </affiliation>
    </author>
    <date>May, 17th, 1723</date>
  </articleinfo>
  <section>
    <title>Introduction</title>
    <para>
      ...
    </para>
  </section>
</article>
      

The "article" tags tell us that the document is an article. All other elements in the document are contained within this "root" element. The first pair of "title" tags indicate the article title, which is contained in the articleinfo element. The second set of "title" tags, contained by the section element, indicate the title of that section (generally speaking, all elements contained in the articleinfo element describe meta informations about the article: author, date, ...).

So, what's that "DOCTYPE" tag at the very beginning? That's the "document type declaration" which is how we define what type of SGML document this is and which DTD we're using for the markup. You don't have to understand the document type declaration, you just have to make sure that it's at the top of all the documents you markup using AlcoveBook. You might have to change the word after "DOCTYPE", depending on what sort of document you're creating: the example is an "article", but you might want to create a "book", a "chapter", a "refentry", or something else.

You will find at the very end of this example a section element, that we will describer later. This element contains content from the first section of the document.