<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<article>
<articleinfo>
<title>DocBook for Writers of CLP Documentation</title>
<author><firstname>David</firstname><surname>de la Nuez</surname></author>
</articleinfo>

<section>
<title>Introduction</title>
<para>
The CLP User Guide is written in
<ulink url="http://www.docbook.org/">DocBook</ulink>
<ulink url="http://www.xml.org/">XML</ulink>.
This tutorial serves as an introduction to using DocBook for maintaining
the Guide, as well as writing new documentation.  There are countless DocBook
and XML resources available both in print and online, so this tutorial will be
limited in its scope to applying these two technologies to documenting CLP.
See <xref linkend="resources"/> to learn more about DocBook and XML.
</para>
</section>

<section>
<title>DocBook?</title>
<para>
Why DocBook?  Why not HTML or LaTeX?  Here are a few of the reasons:
</para>
<itemizedlist>
<listitem>
<para>
DocBook and the tools we use to work with it are Open Source.
</para>
</listitem>
<listitem>
<para>
LaTeX is nice for mathematical markup, but DocBook <emphasis>exists</emphasis>
for marking-up technical documentation.
</para>
</listitem>
<listitem>
<para>
Basic HTML is easy to learn and use, but it is very clumsy.  DocBook does a
good job of separating content from presentation (HTML does not do this
particularly well, even with the use of CSS), allowing the writer to focus on
what really matters, the content.
</para>
</listitem>
<listitem>
<para>
DocBook can transformed into high-quality online and printed output (e.g.
HTML and PDF, respectively), while working from a single source.
</para>
</listitem>
<listitem>
<para>
DocBook is very robust, thoroughly documented, and has a strong community
behind it.
</para>
</listitem>
<listitem>
<para>
DocBook is a modern though mature standard for documentation of software
(or other) projects which is at no risk of obsolescence.
</para>
</listitem>
<listitem>
<para>
The tools needed for creating and manipulating DocBook documents are typically
part of existing *nix installations (including
<ulink url="http://www.cygwin.com/">Cygwin</ulink>) so little or no installation
of new software is required to use DocBook (editing can be done in any text
editor).
</para>
</listitem>
<listitem>
<para>
Many tedious tasks, such as the creation of a table of contents, are handled
automatically by a good DocBook configuration.
</para>
</listitem>
</itemizedlist>
</section>

<section>
<title>Getting Ready for DocBook</title>
<para>
Editing and publishing CLP documentation with DocBook requires that some
important tools be installed.  It is likely that all or most of these tools
are already in place on a typical *nix (e.g. Linux) system.  Windows users
should strongly consider installing
<ulink url="http://www.cygwin.com/">Cygwin</ulink>, as this tutorial assumes a
*nix environment for DocBook development.  In fact, the following instructions
for installation are for Cygwin and Red Hat Linux, (and should not be
altogether different for another *nix system).
</para>
<para>
The necessary Cygwin packages can all be found in the &quot;Doc&quot; section
of the categorical view of Cygwin's <filename>setup.exe</filename>.  The user
should verify that all of them are selected (because there may not be
adequate dependency rules to ensure that all the correct packages are installed).
The packages in question are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>dockbook-xml42</literal>
<footnote><para>This is for version 4.2 of DocBook.  Future versions will have a
slightly different name.</para></footnote>
</para>
</listitem>
<listitem>
<para>
<literal>docbook-xsl</literal>
</para>
</listitem>
<listitem>
<para>
<literal>libxml2</literal>
</para>
</listitem>
<listitem>
<para>
<literal>libxslt</literal>
</para>
</listitem>
<listitem>
<para>
<literal>xmlto</literal>
</para>
</listitem>
</itemizedlist>
<para>
According to <ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">
The Selfdocbook (XML Edition)</ulink>, the Red Hat Linux (7.3) packages needed
are:
</para>
<itemizedlist>
<listitem>
<para>
<literal>sgml-common</literal> and <literal>xml-common</literal>
</para>
</listitem>
<listitem>
<para>
<literal>docbook-style-xsl</literal>
</para>
</listitem>
<listitem>
<para>
<literal>docbook-dtds</literal>
</para>
</listitem>
<listitem>
<para>
<literal>xmlto</literal>
</para>
</listitem>
</itemizedlist>
<para>
The Selfdocbook also lists a few other packages, but they are not necessary for
HTML output (this tutorial does not (yet) address how to create output in other
formats such as PDF).
</para>
<para>
The last of the packages, <literal>xmlto</literal>, is a shell script which
facilitates the conversion of DocBook documents to HTML and other formats.  If
all the tools are properly installed, creating an HTML version of this tutorial,
for example, is as trivial as typing
<userinput>xmlto html docbook4clp.xml</userinput> at the command line.  But
before jumping in to work with DocBook, there are some important issues which
need to be addressed.
</para>
</section>

<section id="needtoknow">
<title>Need to Know</title>
<para>
Knowledge of DocBook is like a security clearance: the user is on a need-to-know
basis.  That is, to start working with DocBook in a properly configured
environment, a user needs to know very little, but there is always something more
out there to learn.  This section addresses a few details of DocBook that the
typical user  needs to know to get a first DocBook document up and running.
Details will be left to the reader to fill-in from other resources
(see <xref linkend="resources"/>).
</para>
<para>
What makes an XML document a DocBook document?  It is not difficult to write a
&quot;valid&quot; XML document.  The following example would constitute a valid
XML document:
</para>
<programlisting>
<![CDATA[  
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <book>
    <title>How CLP Won the West</title>
    <chapter>
      <title>In the Beginning</title>
      <para>
      There once was a large LP...
      </para>
    </chapter>
  </book>
]]>
</programlisting>
<para>
This document is not much use, though, without some meaning for the tags in it.
The DocBook DTD is what gives a document meaning.  The following example works
better, and constitutes a valid DocBook document:
</para>
<programlisting>
<![CDATA[
  <?xml version="1.0" encoding="ISO-8859-1"?>
  <!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd">
  <book>
    <title>How CLP Won the West</title>
    <chapter>
      <title>In the Beginning</title>
      <para>
      There once was a large LP...
      </para>
    </chapter>
  </book>
]]>
</programlisting>
<para>
The only difference is the document type declaration which states the document
is meant to adhere to the standard described in the file 
<filename>/usr/share/docbook-xml42/docbookx.dtd</filename> (see
<xref linkend="resources"/> for where to read more about document type
declarations the DocBook DTD).  In other words, adding the extra line of code
makes this little example a genuine DocBook document.  In this case, the
declaration uses an absolute path for a particular system (Cygwin).  DocBook has
an elaborate system for eliminating this lack of elegance.  Future versions of
this tutorial will address this (see <xref linkend="resources"/> for more on
this topic).
</para>
<para>
Suppose the name of the file containing the example above is
<filename>bookex.xml</filename>.  To create a single HTML
document from this file is as simple as typing one command:
</para>
<blockquote>
<literallayout><prompt>$</prompt> <userinput>xmlto html-nochunks bookex.xml</userinput></literallayout>
</blockquote>
<para>
To create a multi-part HTML version is just as easy:
</para>
<blockquote>
<literallayout><prompt>$</prompt> <userinput>xmlto html bookex.xml</userinput></literallayout>
</blockquote>
<para>
A final and very  important DocBook topic is that of &quot;entities&quot;. For
the purposes of writing CLP documentation (i.e. what follows is a gross simplification),
entities are a way of &quot;#include-ing&quot; one document into
another, and of using certain special characters which would otherwise confuse
the tools used to process DocBook documents.
The simplest example of the latter is the &lt; symbol, which is used to begin
tags in XML.  Rather than putting the character directly into the document text,
an entity can be used.  Specifically, one would use the string
<literal><![CDATA[&lt;]]></literal> instead.
The other use of entities, as suggested above, is to split a document into
convenient pieces.  This is demonstrated in <xref linkend="clp"/>.
</para>
</section>

<section id="clp">
<title>DocBook and CLP, Perfect Together</title>
<para>
The DocBook XML source of the CLP documentation is available via the COIN CVS
repository in the <filename>COIN/Clp/Docs</filename> directory.  The first file
of interest is <filename>clpuserguide.xml</filename>.  At the time of this
tutorial's writing, the file looked like this:
</para>
<programlisting>
<![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
  <!ENTITY authors SYSTEM "authors.xml">
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY intro SYSTEM "intro.xml">
  <!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml">
  <!ENTITY notsobasic SYSTEM "notsobasic.xml">
  <!ENTITY moresamples SYSTEM "moresamples.xml">
  <!ENTITY clpexe SYSTEM "clpexe.xml">
  <!ENTITY messages SYSTEM "messages.xml">
  <!ENTITY faq SYSTEM "faq.xml">
  <!ENTITY faqcontent SYSTEM "faqcontent.xml">
  <!ENTITY doxygen SYSTEM "doxygen.xml">
  <!ENTITY revhist SYSTEM "revhist.xml">
]>
<book id="clpuserguide" lang="en">
<bookinfo>
<title>CLP User Manual</title>
  &authors;
  &legal;
</bookinfo>
  &intro;
  &basicmodelclasses;
  &notsobasic;
  &moresamples;
  &clpexe;
  &messages;
  &faq;
  &doxygen;
  &revhist;
</book>
]]>
</programlisting>
<para>
Essentially <filename>clpuserguide.xml</filename> contains a series of entity
declarations which refer to other XML files (e.g.
<![CDATA[<!ENTITY authors SYSTEM "authors.xml">]]>, which are then included into
the main file via use of the entities (e.g. <![CDATA[&authors;]]>.  This allows
a neat separation of chapters in the Guide, resulting in more manageable and
readable source than would be possible without the use of entities.  Neither the
names nor the order of the declarations of the entities is particularly
important, but it is a good practice to follow the informal convention of naming
the entity after the chapter filename, and declaring it in a sensible place with
respect to the order of the chapters.
</para>
<para>
Editing a particular chapter of the Guide is a matter of editing a single,
reasonably sized file.  The addition of a new chapter merely entails the 
declaration of a new entity and the writing of a short additional line in
<filename>clpuserguide.xml</filename>.  Suppose a chapter on the barrier method
of CLP was planned (it is, in fact).  The chapter could be written in a file
named <filename>barrier.xml</filename>, while an entity was declared and used in
<filename>clpuserguide.xml</filename>.  If the barrier chapter was to preceed,
say, the chapter on the CLP executable, the new
<filename>clpuserguide.xml</filename> would look like this (with changes
emphasized):
</para>
<programlisting>
<![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
  <!ENTITY authors SYSTEM "authors.xml">
  <!ENTITY legal SYSTEM "legal.xml">
  <!ENTITY intro SYSTEM "intro.xml">
  <!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml">
  <!ENTITY notsobasic SYSTEM "notsobasic.xml">
  <!ENTITY moresamples SYSTEM "moresamples.xml">
]]>
  <emphasis>&lt;!ENTITY barrier SYSTEM &quot;barrier.xml&quot;&gt;</emphasis>
<![CDATA[
  <!ENTITY clpexe SYSTEM "clpexe.xml">
  <!ENTITY messages SYSTEM "messages.xml">
  <!ENTITY faq SYSTEM "faq.xml">
  <!ENTITY faqcontent SYSTEM "faqcontent.xml">
  <!ENTITY doxygen SYSTEM "doxygen.xml">
  <!ENTITY revhist SYSTEM "revhist.xml">
]>
<book id="clpuserguide" lang="en">
<bookinfo>
<title>CLP User Manual</title>
  &authors;
  &legal;
</bookinfo>
  &intro;
  &basicmodelclasses;
  &notsobasic;
  &moresamples;
]]>
  <emphasis>&amp;barrier;</emphasis>
<![CDATA[
  &clpexe;
  &messages;
  &faq;
  &doxygen;
  &revhist;
</book>
]]>
</programlisting>
<para>
The barrier chapter source might look something like this:
</para>
<programlisting>
<![CDATA[
<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="clpexe">
  <title>
  The CLP Barrier Method
  </title>
  <section>
    <para>
      The CLP barrier method can be used ]]>&hellip;<![CDATA[
    </para>
  </section>
</chapter>
]]>
</programlisting>
<para>
Note the absence of a document type declaration; it is not necessary (and in
fact &quot;illegal&quot;) in this context because this file is included in
the main file via the entity mechanism (only one document type declaration is
allowed).
</para>
<para>
With some content in the proposed <filename>barrier.xml</filename> and the
appropriate changes made to <filename>clpuserguide.xml</filename>, a new HTML
version of the Guide could  be created in much the same manner as the
small book example above was transformed to HTML:
</para>
<blockquote>
<literallayout><prompt>$</prompt> <userinput>xmlto html-nochunks clpuserguide.xml</userinput></literallayout>
</blockquote>
<para>
or for a sectioned version:
</para>
<blockquote>
<literallayout><prompt>$</prompt> <userinput>xmlto html clpuserguide.xml</userinput></literallayout>
</blockquote>
<para>
Most of the chapters and appendices in the Guide exist only to be used in the
Guide.  There is currently one exception, the FAQ.  The FAQ is constructed in
a way that allows its inclusion in the Guide as well as on the CLP
website (i.e. we have a single source document for our frequently asked
questions).  The file pointed to by the entity <literal>faq</literal>,
<filename>faq.xml</filename>, is a wrapper for the file
<filename>faqcontent.xml</filename> (with corresponding entity
<literal>faqcontent</literal>).  <filename>faqcontent.xml</filename> has another
wrapper in <filename>coin-web/Clp</filename> named
<filename>faqwrapper.xml</filename>, which will be addressed elsewhere.
</para>
</section>

<section>
<title>Tips and Suggestions</title>
<para>
This tutorial, as well as the first DocBook release of the
<citetitle>CLP User Guide</citetitle>, were written using the Emacs editor.
Most any text editor will do as a DocBook editor, but Emacs has its advantages.
First, naturally, Emacs is Open Source.  Second, there are Emacs modes tailored
for editing XML documents which provide features such as syntax highlighting.
One such mode is <literal>PGSML</literal>, which may be part of a system's
default Emacs configuration (this appears to be the case with Cygwin, at the
very least).
</para>
<para>
As the size of a DocBook project grows, so does the time it takes to transform
it to HTML.  If one wishes to simply check the validity of a document rather
than wait for the entire HTML generation process to complete, the validating
parser called by <literal>xmlto</literal> is easy enough to use:
</para>
<blockquote>
<literallayout><prompt>$</prompt> <userinput>xmllint --nout --postvalid --xinclude clpuserguide.xml</userinput></literallayout>
</blockquote>
<para>
If there are no errors in the document, the parser will terminate without
any explicit output.  If there is in fact an error, a (sometimes) helpful
error message will be printed by the parser.
</para>
<para>
With DocBook, as is the case with any other computer language, it is easiest
to learn by example.  The existing examples which are part of CLP are
this tutorial, of course, and the User Guide itself.
<ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">The
Selfdocbook (XML Edition)</ulink> is also an excellent example, as it is a
DocBook document which includes its own source.
</para>
<para>
The DocBook community is quite active, so the official mailing lists are highly
recommended. See <xref linkend="resources"/> for more information on the lists
as well as a number of other helpful resources.
</para>
</section>

<section id="resources">
<title>Resources</title>
<para>
Below is a list of some online resources for learning more about DocBook and
XML.
</para>
<itemizedlist>
<listitem>
<para>
<ulink url="http://www.docbook.org">DocBook.org</ulink>:
The official site for
<citetitle pubwork="book">DocBook: The Definitive Guide</citetitle>
(see below).
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.docbook.org/tdg/index.html">
DocBook:The Definitive Guide</ulink>: The number one reference for DocBook tags.
The book is very much oriented toward users of the SGML version of DocBook, but
is still the best resource available for CLP documenters.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">The
Selfdocbook (XML Edition)</ulink> is another very useful reference.  It is a 
self-documenting introduction to DocBook XML (it includes its own source,
which makes ita great learning tool).
</para>
</listitem>
<listitem>
<para>
<ulink url="http://wiki.docbook.org/">DocBook Wiki</ulink>
Full of useful DocBook links.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
The Official DocBook homepage</ulink>: Not terribly useful, but it includes
information on the DocBook mailing lists, and a page where one can 
<ulink url="http://www.oasis-open.org/docbook/xml/">download DocBook</ulink>.
</para>
</listitem>
<listitem>
<para>
<ulink url="http://www.dpawson.co.uk/docbook/">DocBook FAQ</ulink>
A very handy list of frequently asked quesions (with answers!) about DocBook.
</para>
</listitem>
</itemizedlist>
</section>
</article>