The DocBook XML source of the CLP documentation is available via the COIN CVS repository in the COIN/Clp/Docs directory. The first file of interest is clpuserguide.xml. At the time of this tutorial's writing, the file looked like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.2/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>

Essentially clpuserguide.xml contains a series of entity declarations which refer to other XML files (e.g. <!ENTITY authors SYSTEM "authors.xml">, which are then included into the main file via use of the entities (e.g. &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.

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 clpuserguide.xml. Suppose a chapter on the barrier method of CLP was planned (it is, in fact). The chapter could be written in a file named barrier.xml, while an entity was declared and used in clpuserguide.xml. If the barrier chapter was to preceed, say, the chapter on the CLP executable, the new clpuserguide.xml would look like this (with changes emphasized):

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                  "http://www.oasis-open.org/docbook/xml/4.2/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 barrier SYSTEM "barrier.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;

  &barrier;

  &clpexe;
  &messages;
  &faq;
  &doxygen;
  &revhist;
</book>

The barrier chapter source might look something like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<chapter id="barrier">
  <title>
  The CLP Barrier Method
  </title>
  <section>
    <para>
      The CLP barrier method can be used …
    </para>
  </section>
</chapter>

Note the absence of a document type declaration; it is not necessary (and in fact "illegal") in this context because this file is included in the main file via the entity mechanism (only one document type declaration is allowed).

With some content in the proposed barrier.xml and the appropriate changes made to clpuserguide.xml, 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:

or for a sectioned version:

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 faq, faq.xml, is a wrapper for the file faqcontent.xml (with corresponding entity faqcontent). faqcontent.xml has another wrapper in coin-web/Clp named faqwrapper.xml, which will be addressed elsewhere.