Author Reference

Patterns to avoid

The following patterns tend to occur again and again in writing documentation. Please try to avoid them…

The examples exaggerated, but that's for illustration purposes, not to offend anyone.

(some skimpy example of a complicated configuration file that is supposed to speak for itself
but does not because its too simple)

Collection (directory) structure

• A single article must be stored in a collection on its own, the article-collection. Related assets or other files will be stored in sub-collections of this. This setup ensures that everything belonging to a single article stays together.

• In the eXist documentation app, the article-collection will become a sub-collection of the data collection. So an article-collection called new-cool-feature will become /db/apps/doc/data/new-cool-feature.

• The name of the article-collection should be the same as the document-name of the article itself. So if your article is called new-cool-feature.xml, store it as new-cool-feature/new-cool-feature.xml.

• Any binary assets (images, etc.) referenced by your article must be stored in a sub-collection assets. So in our example in new-cool-feature/assets.

• Any non-binary assets (usually included program/text listings) referenced by your article must be stored in a sub-collection listings. So in our example in new-cool-feature/listings.

Overall XML structure

Here is an example how an article for this documentation set looks like:

<?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" schematypens="http://relaxng.org/ns/structure/1.0"?><?xml-model href="http://docbook.org/xml/5.0/rng/docbook.rng" type="application/xml" schematypens="http://purl.oclc.org/dsdl/schematron"?>
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  <info>
    <title>
      Document title
    </title>
    <date>
      1Q18
    </date>
    <keywordset>
      <keyword>
        blah
      </keyword>
    </keywordset>
  </info>
  <para>
    Introductory paragraph(s)
  </para>
  <sect1 xml:id="main-id">
    <title>
      Title of first main section
    </title>
    <para>
      Lorem ipsum...
    </para>
    <sect2 xml:id="sub-id">
      <title>
        Title of first sub-section
      </title>
      <para>
        Lorem ipsum...
      </para>
    </sect2>
  </sect1>
  <sect1 xml:id="next-id">
    <title>
      Title of second main section
    </title>
    <para>
      Lorem ipsum...
    </para>
  </sect1>
</article>

Both the processing instructions at the top are optional but strongly recommended. They're present to guide tools like oXygen in validating the document and provide authoring hints.

Article information

Here is an example the article's mandatory information section:

<info>
  <title>
    Author Reference
  </title>
  <date>
    January 2018
  </date>
  <keywordset>
    <keyword>
      authoring
    </keyword>
  </keywordset>
</info>

The following rules and guidelines apply:

• There must be a title present in a <title> element. This is the main title of the document. It will be displayed at the top of the page.

• Optional but strongly recommended is a date in the <date> element. This will be displayed below the title and provide the reader with some clue on how old this information is. We all know that sometimes articles get outdated but are not removed... You don't have to provide an exact date. Just month and year will do, or some indication like 1Q18.

• We use keywords to mark an article for certain subject areas. See Keyword usage.

• You can add more information in <info> to your heart's desire but the renderer won't use nor display it.

Supported block elements

The following DocBook 5 block level elements are supported for the eXist-db documentation set. Unsupported elements will be flagged when the content is rendered (you'll see a bold red error message in the middle of your story).

Paragraphs

Use <para> to tag text as a paragraph.

Section levels

You can use <sect1> up to <sect3> as section levels. Only <sect1> and <sect2> will appear in the table of contents. Markup in titles is ignored.

Lists

You can use either <itemizedlist> (with bullets) or <orderedlist> (with numbers).

Variable list

A <variablelist> is a bit of a misnomer. It creates lists like this one (the list of block elements you're looking at now), so it's useful for much more than variables.

Notes

Note: About notes

The <note> element creates a noticeable layout like this. The title is optional.

Warnings

Warning:

Both the <warning> and <important> element produce a layout like this. The only difference is the text of the header. You can optionally add a title.

Examples

The <example> element produces an example in a layout like this. It must have a <title> element, which is displayed at the bottom:

Listings

Anything you want to present as a program listing or other fixed text (e.g. a sequence of commands) must be enclosed in a <programlisting> element. There are two ways to provide the actual contents of the listing:

• Simply enclose the text in the <programlisting> element. Use CDATA if necessary. Any markup will be ignored.

• Add an xlink:href attribute (xmlns:xlink="http://www.w3.org/1999/xlink") with a reference to a file containing the text. This must be a relative reference (e.g. xlink:href="listings/mylisting.txt"). The contents of the element will be ignored.

  Using the xlink:href attribute is definitely not the proper way to do this. It should be done by using an <xi:include> element inside <programlisting>. However, current XInclude limitations in eXist prevent this from working properly (it can only include XML, not text). So therefore this workaround.

Listings have two display modes:

• If it's a listing in some language (like XML), add a language attribute with the name of the language. The render will try to add some color coding (if it recognizes it). Here is a listing with language="xml":

  <example-xml example="true">
    <!-- Comment -->
    <p>
      Some text...
    </p>
  </example-xml>

• For a straight listing, don't add a language attribute. Here is the same listing as above without:

  <example-xml example="true">
    <!-- Comment -->
    <p>
      Some text...
    </p>
  </example-xml>

Figures

Use <figure> or <informalfigure> to add an asset. The effect of both elements is almost the same, the only difference is that an informal figure has no title. DocBook prescribes an elaborate XML construction, here is an example:

<figure>
  <title>
    Figure title here
  </title>
  <mediaobject>
    <imageobject>
      <imagedata fileref="assets/powered-by-exist.gif" width="50%"/>
    </imageobject>
  </mediaobject>
</figure>

This produces:

The width attribute is the only size-related attribute used. It sets the width relative to the available horizontal space. If you don't specify a width a default of 75% is used.

Tables

Use <table> or <informaltable> to add a table. The effect of both elements is almost the same, the only difference is that an informal table has no title. Table layout is kept simple and straight. Here is how a simple table looks like:

<table>
  <title>
    Table title
  </title>
  <tgroup cols="2">
    <colspec colwidth="30%"/>
    <colspec/>
    <thead>
      <row>
        <entry>
          Col 1
        </entry>
        <entry>
          Col 2
        </entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>
          <para>
            Bla
          </para>
        </entry>
        <entry>
          <para>
            More bla
          </para>
        </entry>
      </row>
      <row>
        <entry>
          <para>
            Blegh
          </para>
        </entry>
        <entry>
          <para>
            More blegh
          </para>
        </entry>
      </row>
    </tbody>
  </tgroup>
</table>

And this is the result:

Col 1	Col 2
Bla	More bla
Blegh	More blegh

Supported inline elements

The following inline elements are supported:

Emphasis

Use <emphasis> for emphasizing.

Although discouraged, you can request a specific emphasis type:

• Use role="bold" for bold emphasis.

• Use role="underline" for underlined emphasis.

• Use role="italic" for italic emphasis. This looks the same as no role attribute but produces an <i> instead of an <em>.

GUI Items

Use <guimenuitem> around anything referring to choices in a GUI, for instance menu choices. The effect is now simple italic but that might change later.

Code

Use <code> or <literal> for literals, pieces of code, commands, etc. The result will be mono-spaced.

The general guideline is to use this for everything that lists pieces of code, attributes, variable names, etc. For elements use <tag>.

Tags

A <tag> element surrounds its content with < and > and formats it like code. Meant to make life easier: <tag>xxx</tag> is the shorter version of <code><xxx></code>.

Figures

Use the <inlinemediaobject> to add an asset inline in the text. DocBook prescribes an elaborate XML construction, here is an example of a paragraph with an inline figure:

<para>
  There is an asset
  <inlinemediaobject>
    <imageobject>
      <imagedata fileref="assets/webstart.small.jpg"/>
    </imageobject>
  </inlinemediaobject>
  here.
</para>

This produces:

There is an asset here.

The width attribute is the only size-related attribute recognized and used.

Internal links

You can create a link to any block level element with the <xref> element. To do so, give the target an identifier by using xml:id="..." and mention this identifier in the linkend attribute of the <xref>.

You can generate a specific link text by adding an xreflabel attribute to the target element, like here: directory structure list. If this attribute is not present on the target its title is used, like this: General guidelines. If there is no title, the name of the element is presented.

External links

Links to external sources are done with the <link> element. Place the target's full URI in the xlink:href attribute. For instance, <link xlink:href="https://exist-db.org/exist/apps/homepage/index.html"> links to the eXist home page.

To open the link on a new page, add condition="_blank".

Article links

To create a link to another article in this documentation set, also use the <link> element. However, use the target's document name (without the .xml extension) as the link address. For instance, <link xlink:href="documentation"> links to the documentation home page.

Generating indexes

Indexes can be automagicly generated. For examples have a look at the documentation home page. There are three variations:

Alphabetical index on title

Add a role="indexontitle" attribute to a <para> element. An index on title will be generated after it.

Index on keyword, all

Add a role="indexonkeyword" attribute to a <para> element. An index on keywords (as specified in the <info> element, see Keyword usage) will be generated after it.

Index on keyword, single

Add a role="indexonkeyword:somekeyword" attribute to a <para> element to generate a list of articles with this specific keyword (as specified in the <info> element, see Keyword usage).