source: branches/autotools-update/Clp/doc/Howto/docbook4clp.xml @ 2339

Last change on this file since 2339 was 421, checked in by ddelanu, 16 years ago

Added a lot of content and edited -- now ready for posting

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 17.7 KB
Line 
1<?xml version="1.0" encoding="ISO-8859-1"?>
2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<article>
5<articleinfo>
6<title>DocBook for Writers of CLP Documentation</title>
7<author><firstname>David</firstname><surname>de la Nuez</surname></author>
8</articleinfo>
9
10<section>
11<title>Introduction</title>
12<para>
13The CLP User Guide is written in
14<ulink url="http://www.docbook.org/">DocBook</ulink>
15<ulink url="http://www.xml.org/">XML</ulink>.
16This tutorial serves as an introduction to using DocBook for maintaining
17the Guide, as well as writing new documentation.  There are countless DocBook
18and XML resources available both in print and online, so this tutorial will be
19limited in its scope to applying these two technologies to documenting CLP.
20See <xref linkend="resources"/> to learn more about DocBook and XML.
21</para>
22</section>
23
24<section>
25<title>DocBook?</title>
26<para>
27Why DocBook?  Why not HTML or LaTeX?  Here are a few of the reasons:
28</para>
29<itemizedlist>
30<listitem>
31<para>
32DocBook and the tools we use to work with it are Open Source.
33</para>
34</listitem>
35<listitem>
36<para>
37LaTeX is nice for mathematical markup, but DocBook <emphasis>exists</emphasis>
38for marking-up technical documentation.
39</para>
40</listitem>
41<listitem>
42<para>
43Basic HTML is easy to learn and use, but it is very clumsy.  DocBook does a
44good job of separating content from presentation (HTML does not do this
45particularly well, even with the use of CSS), allowing the writer to focus on
46what really matters, the content.
47</para>
48</listitem>
49<listitem>
50<para>
51DocBook can transformed into high-quality online and printed output (e.g.
52HTML and PDF, respectively), while working from a single source.
53</para>
54</listitem>
55<listitem>
56<para>
57DocBook is very robust, thoroughly documented, and has a strong community
58behind it.
59</para>
60</listitem>
61<listitem>
62<para>
63DocBook is a modern though mature standard for documentation of software
64(or other) projects which is at no risk of obsolescence.
65</para>
66</listitem>
67<listitem>
68<para>
69The tools needed for creating and manipulating DocBook documents are typically
70part of existing *nix installations (including
71<ulink url="http://www.cygwin.com/">Cygwin</ulink>) so little or no installation
72of new software is required to use DocBook (editing can be done in any text
73editor).
74</para>
75</listitem>
76<listitem>
77<para>
78Many tedious tasks, such as the creation of a table of contents, are handled
79automatically by a good DocBook configuration.
80</para>
81</listitem>
82</itemizedlist>
83</section>
84
85<section>
86<title>Getting Ready for DocBook</title>
87<para>
88Editing and publishing CLP documentation with DocBook requires that some
89important tools be installed.  It is likely that all or most of these tools
90are already in place on a typical *nix (e.g. Linux) system.  Windows users
91should strongly consider installing
92<ulink url="http://www.cygwin.com/">Cygwin</ulink>, as this tutorial assumes a
93*nix environment for DocBook development.  In fact, the following instructions
94for installation are for Cygwin and Red Hat Linux, (and should not be
95altogether different for another *nix system).
96</para>
97<para>
98The necessary Cygwin packages can all be found in the &quot;Doc&quot; section
99of the categorical view of Cygwin's <filename>setup.exe</filename>.  The user
100should verify that all of them are selected (because there may not be
101adequate dependency rules to ensure that all the correct packages are installed).
102The packages in question are:
103</para>
104<itemizedlist>
105<listitem>
106<para>
107<literal>dockbook-xml42</literal>
108<footnote><para>This is for version 4.2 of DocBook.  Future versions will have a
109slightly different name.</para></footnote>
110</para>
111</listitem>
112<listitem>
113<para>
114<literal>docbook-xsl</literal>
115</para>
116</listitem>
117<listitem>
118<para>
119<literal>libxml2</literal>
120</para>
121</listitem>
122<listitem>
123<para>
124<literal>libxslt</literal>
125</para>
126</listitem>
127<listitem>
128<para>
129<literal>xmlto</literal>
130</para>
131</listitem>
132</itemizedlist>
133<para>
134According to <ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">
135The Selfdocbook (XML Edition)</ulink>, the Red Hat Linux (7.3) packages needed
136are:
137</para>
138<itemizedlist>
139<listitem>
140<para>
141<literal>sgml-common</literal> and <literal>xml-common</literal>
142</para>
143</listitem>
144<listitem>
145<para>
146<literal>docbook-style-xsl</literal>
147</para>
148</listitem>
149<listitem>
150<para>
151<literal>docbook-dtds</literal>
152</para>
153</listitem>
154<listitem>
155<para>
156<literal>xmlto</literal>
157</para>
158</listitem>
159</itemizedlist>
160<para>
161The Selfdocbook also lists a few other packages, but they are not necessary for
162HTML output (this tutorial does not (yet) address how to create output in other
163formats such as PDF).
164</para>
165<para>
166The last of the packages, <literal>xmlto</literal>, is a shell script which
167facilitates the conversion of DocBook documents to HTML and other formats.  If
168all the tools are properly installed, creating an HTML version of this tutorial,
169for example, is as trivial as typing
170<userinput>xmlto html docbook4clp.xml</userinput> at the command line.  But
171before jumping in to work with DocBook, there are some important issues which
172need to be addressed.
173</para>
174</section>
175
176<section id="needtoknow">
177<title>Need to Know</title>
178<para>
179Knowledge of DocBook is like a security clearance: the user is on a need-to-know
180basis.  That is, to start working with DocBook in a properly configured
181environment, a user needs to know very little, but there is always something more
182out there to learn.  This section addresses a few details of DocBook that the
183typical user  needs to know to get a first DocBook document up and running.
184Details will be left to the reader to fill-in from other resources
185(see <xref linkend="resources"/>).
186</para>
187<para>
188What makes an XML document a DocBook document?  It is not difficult to write a
189&quot;valid&quot; XML document.  The following example would constitute a valid
190XML document:
191</para>
192<programlisting>
193<![CDATA[ 
194  <?xml version="1.0" encoding="ISO-8859-1"?>
195  <book>
196    <title>How CLP Won the West</title>
197    <chapter>
198      <title>In the Beginning</title>
199      <para>
200      There once was a large LP...
201      </para>
202    </chapter>
203  </book>
204]]>
205</programlisting>
206<para>
207This document is not much use, though, without some meaning for the tags in it.
208The DocBook DTD is what gives a document meaning.  The following example works
209better, and constitutes a valid DocBook document:
210</para>
211<programlisting>
212<![CDATA[
213  <?xml version="1.0" encoding="ISO-8859-1"?>
214  <!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd">
215  <book>
216    <title>How CLP Won the West</title>
217    <chapter>
218      <title>In the Beginning</title>
219      <para>
220      There once was a large LP...
221      </para>
222    </chapter>
223  </book>
224]]>
225</programlisting>
226<para>
227The only difference is the document type declaration which states the document
228is meant to adhere to the standard described in the file
229<filename>/usr/share/docbook-xml42/docbookx.dtd</filename> (see
230<xref linkend="resources"/> for where to read more about document type
231declarations the DocBook DTD).  In other words, adding the extra line of code
232makes this little example a genuine DocBook document.  In this case, the
233declaration uses an absolute path for a particular system (Cygwin).  DocBook has
234an elaborate system for eliminating this lack of elegance.  Future versions of
235this tutorial will address this (see <xref linkend="resources"/> for more on
236this topic).
237</para>
238<para>
239Suppose the name of the file containing the example above is
240<filename>bookex.xml</filename>.  To create a single HTML
241document from this file is as simple as typing one command:
242</para>
243<blockquote>
244<literallayout><prompt>$</prompt> <userinput>xmlto html-nochunks bookex.xml</userinput></literallayout>
245</blockquote>
246<para>
247To create a multi-part HTML version is just as easy:
248</para>
249<blockquote>
250<literallayout><prompt>$</prompt> <userinput>xmlto html bookex.xml</userinput></literallayout>
251</blockquote>
252<para>
253A final and very  important DocBook topic is that of &quot;entities&quot;. For
254the purposes of writing CLP documentation (i.e. what follows is a gross simplification),
255entities are a way of &quot;#include-ing&quot; one document into
256another, and of using certain special characters which would otherwise confuse
257the tools used to process DocBook documents.
258The simplest example of the latter is the &lt; symbol, which is used to begin
259tags in XML.  Rather than putting the character directly into the document text,
260an entity can be used.  Specifically, one would use the string
261<literal><![CDATA[&lt;]]></literal> instead.
262The other use of entities, as suggested above, is to split a document into
263convenient pieces.  This is demonstrated in <xref linkend="clp"/>.
264</para>
265</section>
266
267<section id="clp">
268<title>DocBook and CLP, Perfect Together</title>
269<para>
270The DocBook XML source of the CLP documentation is available via the COIN CVS
271repository in the <filename>COIN/Clp/Docs</filename> directory.  The first file
272of interest is <filename>clpuserguide.xml</filename>.  At the time of this
273tutorial's writing, the file looked like this:
274</para>
275<programlisting>
276<![CDATA[
277<?xml version="1.0" encoding="ISO-8859-1"?>
278<!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
279  <!ENTITY authors SYSTEM "authors.xml">
280  <!ENTITY legal SYSTEM "legal.xml">
281  <!ENTITY intro SYSTEM "intro.xml">
282  <!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml">
283  <!ENTITY notsobasic SYSTEM "notsobasic.xml">
284  <!ENTITY moresamples SYSTEM "moresamples.xml">
285  <!ENTITY clpexe SYSTEM "clpexe.xml">
286  <!ENTITY messages SYSTEM "messages.xml">
287  <!ENTITY faq SYSTEM "faq.xml">
288  <!ENTITY faqcontent SYSTEM "faqcontent.xml">
289  <!ENTITY doxygen SYSTEM "doxygen.xml">
290  <!ENTITY revhist SYSTEM "revhist.xml">
291]>
292<book id="clpuserguide" lang="en">
293<bookinfo>
294<title>CLP User Manual</title>
295  &authors;
296  &legal;
297</bookinfo>
298  &intro;
299  &basicmodelclasses;
300  &notsobasic;
301  &moresamples;
302  &clpexe;
303  &messages;
304  &faq;
305  &doxygen;
306  &revhist;
307</book>
308]]>
309</programlisting>
310<para>
311Essentially <filename>clpuserguide.xml</filename> contains a series of entity
312declarations which refer to other XML files (e.g.
313<![CDATA[<!ENTITY authors SYSTEM "authors.xml">]]>, which are then included into
314the main file via use of the entities (e.g. <![CDATA[&authors;]]>.  This allows
315a neat separation of chapters in the Guide, resulting in more manageable and
316readable source than would be possible without the use of entities.  Neither the
317names nor the order of the declarations of the entities is particularly
318important, but it is a good practice to follow the informal convention of naming
319the entity after the chapter filename, and declaring it in a sensible place with
320respect to the order of the chapters.
321</para>
322<para>
323Editing a particular chapter of the Guide is a matter of editing a single,
324reasonably sized file.  The addition of a new chapter merely entails the
325declaration of a new entity and the writing of a short additional line in
326<filename>clpuserguide.xml</filename>.  Suppose a chapter on the barrier method
327of CLP was planned (it is, in fact).  The chapter could be written in a file
328named <filename>barrier.xml</filename>, while an entity was declared and used in
329<filename>clpuserguide.xml</filename>.  If the barrier chapter was to preceed,
330say, the chapter on the CLP executable, the new
331<filename>clpuserguide.xml</filename> would look like this (with changes
332emphasized):
333</para>
334<programlisting>
335<![CDATA[
336<?xml version="1.0" encoding="ISO-8859-1"?>
337<!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
338  <!ENTITY authors SYSTEM "authors.xml">
339  <!ENTITY legal SYSTEM "legal.xml">
340  <!ENTITY intro SYSTEM "intro.xml">
341  <!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml">
342  <!ENTITY notsobasic SYSTEM "notsobasic.xml">
343  <!ENTITY moresamples SYSTEM "moresamples.xml">
344]]>
345  <emphasis>&lt;!ENTITY barrier SYSTEM &quot;barrier.xml&quot;&gt;</emphasis>
346<![CDATA[
347  <!ENTITY clpexe SYSTEM "clpexe.xml">
348  <!ENTITY messages SYSTEM "messages.xml">
349  <!ENTITY faq SYSTEM "faq.xml">
350  <!ENTITY faqcontent SYSTEM "faqcontent.xml">
351  <!ENTITY doxygen SYSTEM "doxygen.xml">
352  <!ENTITY revhist SYSTEM "revhist.xml">
353]>
354<book id="clpuserguide" lang="en">
355<bookinfo>
356<title>CLP User Manual</title>
357  &authors;
358  &legal;
359</bookinfo>
360  &intro;
361  &basicmodelclasses;
362  &notsobasic;
363  &moresamples;
364]]>
365  <emphasis>&amp;barrier;</emphasis>
366<![CDATA[
367  &clpexe;
368  &messages;
369  &faq;
370  &doxygen;
371  &revhist;
372</book>
373]]>
374</programlisting>
375<para>
376The barrier chapter source might look something like this:
377</para>
378<programlisting>
379<![CDATA[
380<?xml version="1.0" encoding="ISO-8859-1"?>
381<chapter id="clpexe">
382  <title>
383  The CLP Barrier Method
384  </title>
385  <section>
386    <para>
387      The CLP barrier method can be used ]]>&hellip;<![CDATA[
388    </para>
389  </section>
390</chapter>
391]]>
392</programlisting>
393<para>
394Note the absence of a document type declaration; it is not necessary (and in
395fact &quot;illegal&quot;) in this context because this file is included in
396the main file via the entity mechanism (only one document type declaration is
397allowed).
398</para>
399<para>
400With some content in the proposed <filename>barrier.xml</filename> and the
401appropriate changes made to <filename>clpuserguide.xml</filename>, a new HTML
402version of the Guide could  be created in much the same manner as the
403small book example above was transformed to HTML:
404</para>
405<blockquote>
406<literallayout><prompt>$</prompt> <userinput>xmlto html-nochunks clpuserguide.xml</userinput></literallayout>
407</blockquote>
408<para>
409or for a sectioned version:
410</para>
411<blockquote>
412<literallayout><prompt>$</prompt> <userinput>xmlto html clpuserguide.xml</userinput></literallayout>
413</blockquote>
414<para>
415Most of the chapters and appendices in the Guide exist only to be used in the
416Guide.  There is currently one exception, the FAQ.  The FAQ is constructed in
417a way that allows its inclusion in the Guide as well as on the CLP
418website (i.e. we have a single source document for our frequently asked
419questions).  The file pointed to by the entity <literal>faq</literal>,
420<filename>faq.xml</filename>, is a wrapper for the file
421<filename>faqcontent.xml</filename> (with corresponding entity
422<literal>faqcontent</literal>).  <filename>faqcontent.xml</filename> has another
423wrapper in <filename>coin-web/Clp</filename> named
424<filename>faqwrapper.xml</filename>, which will be addressed elsewhere.
425</para>
426</section>
427
428<section>
429<title>Tips and Suggestions</title>
430<para>
431This tutorial, as well as the first DocBook release of the
432<citetitle>CLP User Guide</citetitle>, were written using the Emacs editor.
433Most any text editor will do as a DocBook editor, but Emacs has its advantages.
434First, naturally, Emacs is Open Source.  Second, there are Emacs modes tailored
435for editing XML documents which provide features such as syntax highlighting.
436One such mode is <literal>PGSML</literal>, which may be part of a system's
437default Emacs configuration (this appears to be the case with Cygwin, at the
438very least).
439</para>
440<para>
441As the size of a DocBook project grows, so does the time it takes to transform
442it to HTML.  If one wishes to simply check the validity of a document rather
443than wait for the entire HTML generation process to complete, the validating
444parser called by <literal>xmlto</literal> is easy enough to use:
445</para>
446<blockquote>
447<literallayout><prompt>$</prompt> <userinput>xmllint --nout --postvalid --xinclude clpuserguide.xml</userinput></literallayout>
448</blockquote>
449<para>
450If there are no errors in the document, the parser will terminate without
451any explicit output.  If there is in fact an error, a (sometimes) helpful
452error message will be printed by the parser.
453</para>
454<para>
455With DocBook, as is the case with any other computer language, it is easiest
456to learn by example.  The existing examples which are part of CLP are
457this tutorial, of course, and the User Guide itself.
458<ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">The
459Selfdocbook (XML Edition)</ulink> is also an excellent example, as it is a
460DocBook document which includes its own source.
461</para>
462<para>
463The DocBook community is quite active, so the official mailing lists are highly
464recommended. See <xref linkend="resources"/> for more information on the lists
465as well as a number of other helpful resources.
466</para>
467</section>
468
469<section id="resources">
470<title>Resources</title>
471<para>
472Below is a list of some online resources for learning more about DocBook and
473XML.
474</para>
475<itemizedlist>
476<listitem>
477<para>
478<ulink url="http://www.docbook.org">DocBook.org</ulink>:
479The official site for
480<citetitle pubwork="book">DocBook: The Definitive Guide</citetitle>
481(see below).
482</para>
483</listitem>
484<listitem>
485<para>
486<ulink url="http://www.docbook.org/tdg/index.html">
487DocBook:The Definitive Guide</ulink>: The number one reference for DocBook tags.
488The book is very much oriented toward users of the SGML version of DocBook, but
489is still the best resource available for CLP documenters.
490</para>
491</listitem>
492<listitem>
493<para>
494<ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">The
495Selfdocbook (XML Edition)</ulink> is another very useful reference.  It is a
496self-documenting introduction to DocBook XML (it includes its own source,
497which makes ita great learning tool).
498</para>
499</listitem>
500<listitem>
501<para>
502<ulink url="http://wiki.docbook.org/">DocBook Wiki</ulink>
503Full of useful DocBook links.
504</para>
505</listitem>
506<listitem>
507<para>
508<ulink url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
509The Official DocBook homepage</ulink>: Not terribly useful, but it includes
510information on the DocBook mailing lists, and a page where one can
511<ulink url="http://www.oasis-open.org/docbook/xml/">download DocBook</ulink>.
512</para>
513</listitem>
514<listitem>
515<para>
516<ulink url="http://www.dpawson.co.uk/docbook/">DocBook FAQ</ulink>
517A very handy list of frequently asked quesions (with answers!) about DocBook.
518</para>
519</listitem>
520</itemizedlist>
521</section>
522</article>
Note: See TracBrowser for help on using the repository browser.