<?xml version="1.0" encoding="utf-8"?>
<?xml-stylesheet href="urn:x-daps:xslt:profiling:docbook45-profile.xsl"
                 type="text/xml" title="Profiling step"?>
<!DOCTYPE article PUBLIC
 "-//OASIS//DTD DocBook XML V4.5//EN"
 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [


  <!ENTITY % entities SYSTEM "entity-decl.ent">
  %entities;
]>

<article lang="en" id="art.tutorial">
 <title>How to Write an Article with DocBook and &dapsacr;</title>
 <subtitle>Tutorial</subtitle>

 <articleinfo>
  <date><?dbtimestamp format="B d, Y"?></date>
  <authorgroup>
    <author>
      <firstname>Vanessa</firstname>
      <surname>Wallfahrer</surname>
    </author>
   <author>
    <firstname>Tanja</firstname>
    <surname>Roth</surname></author>
  </authorgroup>
 </articleinfo>

 <abstract>
  <para>&dapsacr; is an open source program for transforming DocBook XML into output
   formats such as HTML or PDF. &dapsacr; is command line based and runs on Linux*.</para>

  <para>
    In XML-based publishing, layout and contents are strictly separated: while
    writing, you only focus on the contents and the XML tags to use.  The
    layout for different output formats is defined in so-called stylesheets
    and is automatically applied when converting the XML into output formats.
  </para>
  <para>
    This tutorial is for DocBook and &dapsacr; beginners. Previous knowledge
    of XML is not required, but you need basic knowledge of using the Bash
    Shell. We will write a recipe for a chili sauce in DocBook and convert it
    into HTML. The tutorial explains step-by-step how to set up your document,
    which basic XML tags to use for writing it, and how to produce the output
    shown in <xref linkend="fig.daps.tutorial.goal" xrefstyle="select: label"
    />.
  </para>
</abstract>

 <figure id="fig.daps.tutorial.goal">
  <title>The Goal: Publishing a Recipe for a Chili Sauce in HTML
   Format</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="butcht7.11.png" width="80%"/>
 </imageobject>
</mediaobject>
</figure>
 
 <sect1>
  <title>Why Should I Use DocBook and &dapsacr;?</title>
  <para>
    DocBook is a markup language for technical documentation. Content is
    tagged with XML elements according to its meaning. This is similar to
    sorting objects into drawers according to their function: For example, you
    place scissors and tongs <remark>dpopov 2016-10-10: Tongs? Perhaps
    screwdrivers is better?</remark> into a drawer labeled
    <literal>Tools</literal>, whereas you place teddies and building blocks
    into a drawer labeled <literal>Toys</literal>. Similarly, when writing
    documents with DocBook, you would <quote>sort</quote> the author's name
    into an XML tag called <sgmltag>author</sgmltag>, whereas you would
    <quote>sort</quote> a reference to another document into an XML element
    called <sgmltag>xref</sgmltag>.
  </para>
  <para>
    While this might seem cumbersome at first sight, this approach has the
    advantage that you can generate documents in different formats from the
    same XML sources. Imagine you want anything tagged with an
    <sgmltag>xref</sgmltag> element to appear in <emphasis>blue</emphasis> in
    HTML output, whereas you want it to appear in <emphasis>green</emphasis>
    in the PDF output. Or you decide at one point that you want references to
    other documents (<sgmltag>xref</sgmltag>s) to be displayed in red in all
    output formats from now on. This can be achieved
    <emphasis>without</emphasis> changing anything in the XML files
    themselves. It is only a matter of defining in the stylesheets which color
    to use for <sgmltag>xref</sgmltag> elements in different output formats.
  </para>
  <para>
    With &dapsacr;, you can convert your XML sources into various output
    formats with one command. &dapsacr; takes care of converting any images in
    your documents automatically into the format best suited for the selected
    output format. &dapsacr; also makes writing and editing more efficient by
    providing additional features like editor macros, spell checking or link
    checking. With &daps; you can also control which stylesheets to use for
    generating output.
  </para>
 </sect1>
 
  <sect1>
  <title>What You Need</title>
  <para>
   The first step is to install a few packages, including an editor with XML
   support for more efficient writing. Recommended is Emacs and &dapsacr;
   version 2.0 or higher.  Follow the steps below to install Emacs and
   &dapsacr;:
  </para>
  <procedure>
   <step>
    <para>
     Open your terminal and log in as root by entering
    </para>
    <screen>&prompt.user;su -</screen>
    <para>
     Note that &prompt.user; or (&prompt.root; below) stands for your prompt. 
     Do not type that part.
    </para>
   </step>
   <step>
    <para>
     Enter your root password.
    </para>
   </step>
   <step>
    <para>
     Install Emacs with zypper:
    </para>
    <screen>&prompt.root;zypper in emacs</screen>
   </step>
   <step>
    <para>
     Install &dapsacr; with zypper:
    </para>
    <screen>&prompt.root;zypper in daps</screen>
   </step>
  </procedure>
 </sect1>

 <sect1>
  <title>How to Start</title>
  <para>
   To be able to process the XML files, &dapsacr; requires a specific
   directory structure. Either use <command>daps-init</command> or set it up
   manually. The <command>daps-init</command> command is especially advisable
   for beginners, because it creates an example and the necessary
   structure. File names always end with <filename>.xml</filename>.
  </para>
  <sect2>
    <title>Working with <command>daps-init</command></title>
    <para>
      The <command>daps-init</command> command creates a working environment
      for &dapsacr;. In this case, it creates a directory called
      <filename>tutorial</filename>. It contains a &dapsacr; configuration
      file for your tutorial (<filename>DC-tutorial</filename>), the DocBook
      XML file located in the XML subdirectory and a subdirectory containing
      image files (<filename>images</filename>). The
      <filename>image</filename> directory will be relevant later (see <xref
      linkend="ex.image"/>).
    </para>
    <procedure>
     <step>
    <para>
      The <command>daps-init</command> command creates a working environment
      for &dapsacr;. It builds a directory with the specified
      <filename>filename</filename>. This directory contains a DC-file, a
      <filename>xml</filename> subdirectory and a <filename>image</filename>
      subdirectory. The <filename>image</filename> directory (see <xref
      linkend="ex.image"/>) will be relevant later.
    </para>
    <screen> daps-init --docdir recipe -r article</screen>
     </step>
     <step>
      <para>
       Now you can start working on your text.  To learn about the needed XML
       tags, read the following chapters. If you need help with &dapsacr;,
       open the <filename>daps-init</filename> man page in your terminal:
      </para>
      <screen>&prompt.user;daps-init --help</screen>
     </step>
     <step>
      <para>
       Open the XML file (<filename>recipe/xml/MAIN-daps-example.xml</filename>) in
       your editor and use it as a reference.
      </para>
     </step>
     <step>
      <para>
       Open the Documentation Configuration file (<filename>recipe/DC-daps-example</filename>)
       in an editor and use it as reference.
      </para>
     </step>
     <step>
      <para>
       Proceed with <xref linkend="sec.howto"/>, where we will create another
       XML file and another DC file from scratch (in addition to the files
       created by daps-init) and use them to write the recipe.
      </para>
     </step>
   </procedure>
  </sect2>

<sect2>
    <title>Working without <command>daps-init</command></title>
   <procedure>

    <para>
     This method is suitable for the more experienced writer.
    </para>
    <step>
    <para>
     For working without <command>daps-init</command>, create a directory with
     your project name and two subdirectories, called <filename>xml</filename> and
     <filename>images</filename>. Open a terminal.
    </para>
     </step>
    <step>
    <screen>&prompt.user;mkdir recipe</screen>
    </step>
    <step>
     <screen>&prompt.user;cd recipe</screen>
    </step>
    <step>
    <screen>&prompt.user;mkdir -p images/src/{dia,eps,fig,pdf,png,svg} xml</screen>
     <para>
      Now you have created the required directory structure that is
      needed by &dapsacr;.</para>
     </step>
     <step>
     <para>Create a DC-file, which is a configuration file for your project.
       Open a new file and paste the following lines with your XML
       file name instead of "MAIN-daps-example.xml". See below.
     </para>
     </step>
   </procedure>
</sect2>
<sect2>
 <title>Creating an XML File and a Documentation Configuration
 File</title>
 <para>
  Now we will create an XML file (that we will use in the following for
  writing the recipe) and
  a Documentation Configuration (DC) file (that we will use later on for
  converting the XML file into HTML output).
 </para>
<procedure>
 <step>
  <title>
    To create the XML file:
  </title>
  <substeps>
  <step>
   <para>
    In a terminal, switch to the XML subdirectory.

   </para>
   <screen>&prompt.user;cd xml</screen>
  </step>
  <step>
     <para>
      Open a new file, and paste the following header into it (see <xref
      linkend="ex.header"/>), or copy this from <filename>MAIN-daps-example.xml</filename>.
     </para>

    <example id="ex.header">
     <title>Header of a DocBook File</title>
     <programlisting>&lt;?xml version="1.0" encoding="utf-8"?&gt; <co id="co.header.xml"/>
     &lt;!DOCTYPE article PUBLIC <co id="co.header2.xml"/>
     "-//OASIS//DTD DocBook XML V4.5//EN"
     "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [

     ]&gt;
     </programlisting>
     <calloutlist>
      <callout arearefs="co.header.xml">
       <para>
	XML-Declaration for XML V1.0, encoding UTF-8
       </para>
      </callout>
      <callout arearefs="co.header2.xml">
       <para>
	The general syntax for a document type declaration
       </para>
      </callout>
     </calloutlist>
    </example>
    <para>
     Don't be afraid if you don't understand the header. Just insert it by
     copy and paste into your file.
    </para>
  </step>
  <step>
   <para>
    Save the file as <filename>recipe.xml</filename>.
   </para>
  </step>
  </substeps>
 </step>
 <step>
  <title>To create the DC file:</title>
  <substeps>
   <step>
    <para>
     Switch to the directory above (that should be your <filename>recipe</filename>
     directory):
     <screen>&prompt.user;cd ..</screen>
    </para>
   </step>
   <step>
    <para>
     Open a new file and paste the following line into it:
     MAIN=<quote>recipe.xml</quote>
    </para>
   </step>
   <step>
    <para>
     Save the file, for example as <filename>DC-recipe</filename>.
    </para>
   </step>
  </substeps>
 </step>
</procedure>
</sect2>
</sect1>



 <sect1 id="sec.howto">
  <title>How to Write</title>

  <sect2>
   <title>Identifying Start and End Tags</title>
   <para>
    To categorize content, XML uses tags. XML tags primarily consist of an
    element name (such as <literal>para</literal> for a paragraph in DocBook)
    and enclosing less-than/greater-than characters (<literal>&lt;</literal>,
    <literal>&gt;</literal>). XML tags (<literal>&lt;para&gt;</literal>) must
    be closed. You can do so either with an end tag
    (<literal>&lt;para&gt;&lt;/para&gt;</literal>) or by adding a backslash
    before the final <literal>&gt;</literal> in the tag
    (<command>&lt;para/&gt;</command>). The content between the tags depends on
    which element you want to create. Open the XML file
    <filename>recipe.xml</filename> that you just created, and place the
    cursor below the header. To define
    an article, paste an <command>article</command> start and
    end tag into the XML file. Between these two tags, write your text as
    shown in <xref linkend="ex.tags"/>.
   </para>
   <example id="ex.tags">
    <title>Start and End Tag of an Article</title>
    <programlisting>&lt;article&gt;
Tags and text
&lt;/article&gt;
    </programlisting>
   </example>
  </sect2>
  <sect2>
   <title>Adding Metadata</title>
   <para>
    Each article may contain information about its author, publication
    date, release information, copyright or other <quote>metadata</quote>. To include
    such metadata use an article info element and enter the following data (see <xref linkend="ex.articleinfo"/>):
   </para>
   <example id="ex.articleinfo">
    <title>Article Info Header</title>
    <programlisting>&lt;article lang="en" id="art.template"&gt;<co id="co.article.xml"/>
&lt;title>Little G's Ceylon Bang&lt;/title&gt;<co id="co.article2.xml"/>
&lt;articleinfo&gt;
&lt;releaseinfo&gt;
  2013-10-21<co id="co.article3.xml"/>
&lt;/releaseinfo&gt;
 &lt;author&gt;<co id="co.author.xml"/>
  &lt;firstname&gt;Tux&lt;/firstname&gt;
  &lt;surname&gt;Penguin&lt;/surname&gt;
 &lt;/author&gt;
&lt;/articleinfo&gt;
&lt;abstract&gt;<co id="co.article5.xml"/>
Recipe for a chili sauce.
&lt;/abstract>
&lt;/article><co id="co.article4.xml"/>
    </programlisting>
    <calloutlist>
     <callout arearefs="co.article.xml">
      <para>
       Article start tag.
      </para>
     </callout>
     <callout arearefs="co.article2.xml">
      <para>
       Title for the article.
      </para>
     </callout>
     <callout arearefs="co.article3.xml">
      <para>
       Build date.
      </para>
     </callout>
     <callout  arearefs="co.author.xml">
      <para>
       The author's name.
      </para>
     </callout>
     <callout arearefs="co.article5.xml">
      <para>
       An abstract. What is your article about?
      </para>
     </callout>
     <callout arearefs="co.article4.xml">
      <para>
       Article end tag. It always has to be at the very end of the article.
      </para>
     </callout>
    </calloutlist>
   </example>
   <figure>
    <title>HTML Output (Article Title and Article Info)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="articleinfo2.png" width="70%"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect2>


  <sect2>
   <title>Structuring Your Document With Sections</title>
   <para>
    Each article consists of sections and subsections. <xref xreflabel="Example
    4" linkend="ex.sections"/> contains a
    section and a subsection.
   </para>
   <example id="ex.sections">
    <title>Example: Structure With Sections</title>
    <programlisting>&lt;sect1&gt;<co id="co.section.xml"/>
 &lt;title&gt;What do you need?&lt;/title&gt;
  &lt;sect2&gt;<co id="co.section2.xml"/>
   &lt;title&gt;Ingredients&lt;/title&gt;
    &lt;para/&gt;
   &lt;/sect2&gt;<co id="co.section3.xml"/>
   &lt;sect2&gt;
    &lt;title&gt;Equipment&lt;/title&gt;
     &lt;para/&gt;
  &lt;/sect2&gt;
 &lt;/sect1&gt;<co id="co.section4.xml"/>
&lt;sect1 id="sec.preparation"&gt;
 &lt;title&gt;Preparation&lt;/title&gt;
&lt;/sect1&gt;
    </programlisting>
    <calloutlist>
     <callout arearefs="co.section.xml">
      <para>
       Start tag of section level one. Section1 is the parent element of every
       element that comes below. Always needs a title. Recommended is a para
       tag in every section.
      </para>
     </callout>
     <callout arearefs="co.section2.xml">
      <para>
       Start tag section of level two.
      </para>
     </callout>
     <callout arearefs="co.section3.xml">
      <para>
       End tag section of level two.
      </para>
     </callout>
     <callout arearefs="co.section4.xml">
      <para>
       End tag of the section level one parent element.
      </para>
     </callout>
    </calloutlist>
   </example>
   <para>
    Place the cursor after the abstract end tag and before the article
    end tag and paste the content of <quote>Example 4</quote> into your XML file.
   </para>

   <figure>
    <title>HTML Output (Article With Sections)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="ohnealles.png" width="70%"/>
     </imageobject>
    </mediaobject>
   </figure>
   <para>
    The image above shows the given XML file example as an HTML
    page. As you can see in the picture, the section level two is a child
    element of section level one. It is possible to nest sections.
   </para>
  </sect2>


  <sect2>
   <title>Creating Itemized Lists</title>
   <para>
    To create a list, use the <command>&lt;itemizedlist> </command> tag.
   </para>

   <example>
    <title>Itemized List</title>
    <programlisting>&lt;itemizedlist&gt;
 &lt;listitem&gt;
  &lt;para&gt;
   60g Habanero Chilis
  &lt;/para&gt;
  &lt;/listitem&gt;
 &lt;listitem&gt;
  &lt;para&gt;
   30g Cayenne Chilis
  &lt;/para&gt;
 &lt;/listitem&gt;
 &lt;listitem&gt;
  &lt;para&gt;
   1,5 Butch T Chilis
  &lt;/para&gt;
 &lt;/listitem&gt;
 &lt;listitem&gt;
  &lt;para&gt;
   75g Kidney Beans
  &lt;/para&gt;
 &lt;/listitem&gt;
&lt;/itemizedlist&gt;
    </programlisting>
   </example>
   <para>
    Place the cursor behind the following line:
    <screen>&lt;title>Preparation&lt;/title></screen>
    and paste the contents of <quote>Example 5</quote> into your XML file.
   </para>

   <figure>
    <title>HTML Output (Article With an Itemized List)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="ohnestep.png" width="70%"/>
      </imageobject>
     </mediaobject>
   </figure>

  </sect2>

  <sect2>
   <title>Providing Step-by-Step Instructions</title>

   <para>
    For writing instructions, it is recommended to do it step-by-step, as you can
    see in the following <xref xreflabel="example"
    linkend="ex.listing"/>. That way, instructions are easier to understand
    and browse for the reader.
   </para>
   <example id="ex.listing">
    <title>Example of Step-by-Step Instructions</title>

    <programlisting>&lt;procedure><co id="co.textstructure.xml"/>
 &lt;step&gt;<co id="co.textstructure2.xml"/>
  &lt;para&gt;<co id="co.textstructure3.xml"/>
   Rinse, than drain the kidney beans for about 10 minutes.
  &lt;/para&gt;
 &lt;/step&gt;
 &lt;step&gt;
  &lt;para&gt;
   Fry kidney beans with some oil.
  &lt;/para&gt;
 &lt;/step&gt;
 &lt;step&gt;
  &lt;para&gt;
   Puree all ingredients.
  &lt;/para&gt;
 &lt;/step&gt;
 &lt;step&gt;
  &lt;para&gt;
   Cook for about 5 minutes.
  &lt;/para&gt;
 &lt;/step&gt;
&lt;/procedure&gt;
    </programlisting>
    <calloutlist>
     <callout arearefs="co.textstructure.xml">
      <para>
       Procedure start tag.
      </para>
     </callout>
     <callout arearefs="co.textstructure2.xml">
      <para>
       If you use <command>&lt;step></command> elements you can create numeric listed paragraphs. Every
       further <command> &lt;step></command> you add automatically counts
       up.
      </para>
     </callout>
     <callout arearefs="co.textstructure3.xml">
      <para>
       Within <command>&lt;para>&lt;/para></command> you can write down your text.
      </para>
     </callout>
    </calloutlist>
   </example>

   <figure>
    <title>HTML Output (Article with Step-by-Step-Instructions)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="ohnelink.png" width="80%"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect2>


<sect2>
 <title>Inserting Remote Links and Cross References</title>

 <sect3>
  <title>Remote Links</title>
  <para>
  To refer to an external HTML page, integrate an internet link in your tutorial.
  </para>
 <example>
  <title>Integrating Remote Link</title>
  <programlisting>&lt;para&gt;
 Before you start to cook:
 &lt;ulink url="http://www.crazyhotseeds.com/top-10-worlds-hottest-peppers/"/&gt;
&lt;/para&gt;
  </programlisting>
 </example>
 <para>
  To get the output shown in Figure 6, place the cursor behind the
  <command>&lt;/para></command> end tag within the
  <command>&lt;abstract></command> element and paste the content of
  <quote>Example 7</quote> into your XML file.
 </para>

<figure>
 <title>HTML Output (Article with Remote Link)</title>
 <mediaobject>
  <imageobject>
   <imagedata fileref="chilirezeptlink3.png" width="100%"/>
  </imageobject>
 </mediaobject>
</figure>
 </sect3>
 <sect3>
  <title>Cross References</title>
  <para>
   With cross references (xref elements) you link to paragraphs or examples within your document.
  </para>
  <example>
   <title>Integrating Cross References</title>
   <programlisting>&lt;para>
 How to prepare see &lt;xref linkend="sec.preparation"/&gt;<co id="co.references.xml"/>
&lt;/para&gt;

...


&lt;sect1 id="sec.preparation"&gt;<co id="co.references2.xml"/>

   </programlisting>
   <calloutlist>
    <callout arearefs="co.references.xml">
     <para>
      With <command>&lt;xref linkend="ex.preparation"/&gt;</command> you set a link to the
      following <quote>Preparation</quote> title.
     </para>
    </callout>
    <callout arearefs="co.references2.xml">
     <para>
      Set <command>id=sec.preparation</command> at the section, that you want to refer to.
      Set <command>id=ex.preparation</command> at the paragraph, you want to refer to.
     </para>
    </callout>
   </calloutlist>
  </example>
<para>
 To get the output shown in <quote>Figure 7</quote>, place the cursor below the
 <command>&lt;title>Preparation&lt;/title></command> element and paste the
 contents of <quote>Example 8</quote> into your XML file.
</para>

<figure>
 <title>HTML Output (Article with Cross-Reference)</title>
<mediaobject>
 <imageobject>
  <imagedata fileref="ohnebild.png" width="100%"/>
 </imageobject>
</mediaobject>
</figure>
<para>
 As you can see in the screenshot, the underlined part is a link to the section<quote>Preparation</quote>.
</para>
 </sect3>
</sect2>


  <sect2>
   <title>Embedding Images</title>

   <procedure>
    <step>
     <para id="ex.image">
      To add an image to your document, save the image you want (for example,
      <filename>butcht.png</filename>) into the directory
      <filename>image/png</filename>. If you save it to different directory,
      DAPS will not be able to locate it.
     </para>
    </step>
    <step>
     <para>
      Add an image reference into your XML file.
     </para>
    </step>
   </procedure>
   <example>
    <title>Integrating Images</title>
    <programlisting>&lt;figure&gt;
    &lt;title&gt;Butch T Chili&lt;/title&gt;<co id="co.image.xml"/>
    &lt;mediaobject&gt;
    &lt;imageobject&gt;
    &lt;imagedata fileref="butcht.png"/&gt;<co id="co.image2.xml"/>
    &lt;/imageobject&gt;
    &lt;/mediaobject&gt;
    &lt;/figure&gt;
    </programlisting>
   </example>
   <calloutlist>
    <callout arearefs="co.image.xml">
     <para>
      Image title. In the output formats, the title will appear
      together with the image.
     </para>
    </callout>
    <callout arearefs="co.image2.xml">
     <para>
      The image reference.
     </para>
    </callout>
   </calloutlist>
   <figure>
    <title>HTML Output (Article with Integrated Image)</title>
    <mediaobject>
     <imageobject>
      <imagedata fileref="butcht7.11.png" width="80%"/>
     </imageobject>
    </mediaobject>
   </figure>
  </sect2>
</sect1>


 <sect1>
  <title>Convert Your XML Files</title>
  <para>
    You can convert the XML file at any time, no matter if it is finished or
   you only want to see the temporary result. Convert as often as you like.
   <important>
    <para>
     The XML file must be valid, otherwise the conversion will fail.
     Check if it is
     valid: <screen>daps -d DC-tutorial validate</screen>
    </para>
   </important>
  </para>
  <sect2>
   <title>Convert Your XML File Into PDF</title>
  <procedure>
   <step>
     <para>
      Open a terminal and enter run the following command:
     </para>
     <screen>&prompt.user;daps -d <filename>DC-tutorial</filename> pdf</screen>
   </step>
   <step>
     <para>
     &dapsacr; automatically creates a directory called
     <filename>build</filename>. &dapsacr; saves the resulting PDF file in the
     build directory.
     </para>
   </step>
  </procedure>
  </sect2>
   <sect2>
    <title>Convert Your XML File Into HTML</title>
    <procedure>
     <step>
     <para>
      To build an HTML page, open a terminal and enter the following command:
     </para>
     <screen>&prompt.user;daps -d <filename>DC-tutorial</filename> html --single</screen>
     </step>
     <step>
     <para>
      You get a green colored link, which you can open in a browser, such as
      Firefox.
     </para>
     </step>
    </procedure>
  </sect2>
 </sect1>
  <sect1>
   <title>Further Information</title>
   <para>
    If you still have questions or need additional information, read the
    &dapsacr; man page. To open the &dapsacr; man page using the following
    command:
   </para>
   <screen>&prompt.user;daps --help</screen>
   <para>
    Alternatively, visit the following links:
   </para>
   <itemizedlist>
    <listitem>
     <para>
     <ulink url="http://www.docbook.org/tdg/en/html/docbook.html"/>
     </para>
    </listitem>
   <listitem>
     <para>
     <ulink url="http://opensuse.github.io/daps/doc/index.html"/>
     </para>
    </listitem>
   </itemizedlist>
 </sect1>

</article>