Changeset 964 for html


Ignore:
Timestamp:
Sep 20, 2004 10:34:35 AM (15 years ago)
Author:
ddelanu
Message:

Minor changes, but also noticed multi-page format was not up to date anyway

Location:
html/trunk/Clp/userguide/howto
Files:
2 added
6 edited

Legend:

Unmodified
Added
Removed
  • html/trunk/Clp/userguide/howto/ar01s02.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook?</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="next" href="ar01s03.html" title="Getting Ready for DocBook"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DocBook?</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695857"></a>DocBook?</h2></div></div><div></div></div><p>
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook?</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="next" href="ar01s03.html" title="Getting Ready for DocBook"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DocBook?</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695860"></a>DocBook?</h2></div></div><div></div></div><p>
    22Why DocBook?  Why not HTML or LaTeX?  Here are a few of the reasons:
    33</p><div class="itemizedlist"><ul type="disc"><li><p>
    44DocBook and the tools we use to work with it are Open Source.
    55</p></li><li><p>
    6 LaTeX is nice for mathematical markup, but DocBook exists for marking-up
    7 technical documentation.
     6LaTeX is nice for mathematical markup, but DocBook <span class="emphasis"><em>exists</em></span>
     7for marking-up technical documentation.
    88</p></li><li><p>
    99Basic HTML is easy to learn and use, but it is very clumsy.  DocBook does a
     
    2626of new software is required to use DocBook (editing can be done in any text
    2727editor).
     28</p></li><li><p>
     29Many tedious tasks, such as the creation of a table of contents, are handled
     30automatically by a good DocBook configuration.
    2831</p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DocBook for Writers of CLP Documentation </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Getting Ready for DocBook</td></tr></table></div></body></html>
  • html/trunk/Clp/userguide/howto/ar01s03.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Getting Ready for DocBook</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s02.html" title="DocBook?"><link rel="next" href="ar01s04.html" title="Need to Know"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Getting Ready for DocBook</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695474"></a>Getting Ready for DocBook</h2></div></div><div></div></div><p>
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Getting Ready for DocBook</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s02.html" title="DocBook?"><link rel="next" href="ar01s04.html" title="Need to Know"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Getting Ready for DocBook</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695480"></a>Getting Ready for DocBook</h2></div></div><div></div></div><p>
    22Editing and publishing CLP documentation with DocBook requires that some
    33important tools be installed.  It is likely that all or most of these tools
    44are already in place on a typical *nix (e.g. Linux) system.  Windows users
    55should strongly consider installing
    6 <a href="http://www.cygwin.com/" target="_top">Cygwin</a>, as this document assumes a
     6<a href="http://www.cygwin.com/" target="_top">Cygwin</a>, as this tutorial assumes a
    77*nix environment for DocBook development.  In fact, the following instructions
    8 for installation are for Cygwin and Red Hat Linux, but should not be
    9 altogether different for another *nix system.
     8for installation are for Cygwin and Red Hat Linux, (and should not be
     9altogether different for another *nix system).
    1010</p><p>
    1111The necessary Cygwin packages can all be found in the "Doc" section
    1212of the categorical view of Cygwin's <tt class="filename">setup.exe</tt>.  The user
    13 should be certain that all of them are selected (there may not be adequate
    14 dependency rules to ensure that all the correct packages are installed).  The
    15 packages in question are:
     13should verify that all of them are selected (because there may not be
     14adequate dependency rules to ensure that all the correct packages are installed).
     15The packages in question are:
    1616</p><div class="itemizedlist"><ul type="disc"><li><p>
    1717<tt class="literal">dockbook-xml42</tt>
    18 <sup>[<a name="id4694784" href="#ftn.id4694784">1</a>]</sup>
     18<sup>[<a name="id4694793" href="#ftn.id4694793">1</a>]</sup>
    1919</p></li><li><p>
    2020<tt class="literal">docbook-xsl</tt>
     
    3939</p></li></ul></div><p>
    4040The Selfdocbook also lists a few other packages, but they are not necessary for
    41 HTML output (this document does not (yet) address how to create output in other
    42 formats).
     41HTML output (this tutorial does not (yet) address how to create output in other
     42formats such as PDF).
    4343</p><p>
    44 The last of the packages, xmlto, is a shell script which facilitates the
    45 conversion of DocBook documents to HTML and other formats.  If all the tools
    46 are properly installed, creating an HTML version of this document, for example,
    47 is as trivial as typing <b class="userinput"><tt>xmlto html docbook4clp.xml</tt></b> at
    48 the command line.  But before jumping in to work with DocBook, there are some
    49 important issues which need to be addressed.
    50 </p><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id4694784" href="#id4694784">1</a>] </sup>This is for version 4.2 of DocBook.  Future versions will have a
     44The last of the packages, <tt class="literal">xmlto</tt>, is a shell script which
     45facilitates the conversion of DocBook documents to HTML and other formats.  If
     46all the tools are properly installed, creating an HTML version of this tutorial,
     47for example, is as trivial as typing
     48<b class="userinput"><tt>xmlto html docbook4clp.xml</tt></b> at the command line.  But
     49before jumping in to work with DocBook, there are some important issues which
     50need to be addressed.
     51</p><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id4694793" href="#id4694793">1</a>] </sup>This is for version 4.2 of DocBook.  Future versions will have a
    5152slightly different name.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s02.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">DocBook? </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Need to Know</td></tr></table></div></body></html>
  • html/trunk/Clp/userguide/howto/ar01s04.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Need to Know</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s03.html" title="Getting Ready for DocBook"><link rel="next" href="ar01s05.html" title="Resources"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Need to Know</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="needtoknow"></a>Need to Know</h2></div></div><div></div></div><p>
    2 Knowledge of DocBook is like a security clearance: a user is on a need-to-know
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Need to Know</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s03.html" title="Getting Ready for DocBook"><link rel="next" href="ar01s05.html" title="DocBook and CLP, Perfect Together"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Need to Know</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="needtoknow"></a>Need to Know</h2></div></div><div></div></div><p>
     2Knowledge of DocBook is like a security clearance: the user is on a need-to-know
    33basis.  That is, to start working with DocBook in a properly configured
    4 environment, a user need know very little, but there is always something more
     4environment, a user needs to know very little, but there is always something more
    55out there to learn.  This section addresses a few details of DocBook that the
    6 typical user will address what a user needs to know to get a first DocBook
    7 document up and running.  Details will be left to the reader to fill-in from
    8 other resources (see <a href="ar01s05.html" title="Resources">the section called &#8220;Resources&#8221;</a>).
     6typical user  needs to know to get a first DocBook document up and running.
     7Details will be left to the reader to fill-in from other resources
     8(see <a href="ar01s07.html" title="Resources">the section called &#8220;Resources&#8221;</a>).
    99</p><p>
    1010What makes an XML document a DocBook document?  It is not difficult to write a
     
    2626</pre><p>
    2727This document is not much use, though, without some meaning for the tags in it.
    28 The DocBook DTD is what gives a document meaning.  This example works better,
    29 and is a valid DocBook document:
     28The DocBook DTD is what gives a document meaning.  The following example works
     29better, and constitutes a valid DocBook document:
    3030</p><pre class="programlisting">
    31  
     31
    3232  &lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
    33   &lt;!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd"&gt;
     33  &lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     34                  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    3435  &lt;book&gt;
    3536    &lt;title&gt;How CLP Won the West&lt;/title&gt;
     
    4445</pre><p>
    4546The only difference is the document type declaration which states the document
    46 is meant to adhere to the standard set out in the file
    47 <tt class="filename">/usr/share/docbook-xml42/docbookx.dtd</tt> (see
    48 <a href="ar01s05.html" title="Resources">the section called &#8220;Resources&#8221;</a> for where to read more about the DocBook DTD).
    49 In other words, adding the extra line of code makes this little example a genuine
    50 DocBook document.  In this case, the declaration uses an absolute path for a
    51 particular system (Cygwin).  DocBook has an elaborate system for eliminating
    52 this lack of elegance.  Future versions of this document will address this (see
    53 <a href="ar01s05.html" title="Resources">the section called &#8220;Resources&#8221;</a> for more on this topic).
     47is meant to adhere to the standard described in the file
     48<tt class="filename">http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</tt> (see
     49<a href="ar01s07.html" title="Resources">the section called &#8220;Resources&#8221;</a> for where to read more about document type
     50declarations the DocBook DTD).  In other words, adding the extra line of code
     51makes this little example a genuine DocBook document.  In this case, the
     52declaration uses an Internet address.  However, in a properly configured
     53environment, a network connection would not be necessary to work with the
     54document, thanks to the "catalog" mechanism.  A discussion of catalogs
     55is beyond the scope of this document (see <a href="ar01s07.html" title="Resources">the section called &#8220;Resources&#8221;</a> for more).
     56Should catalogs not be properly configured on a given system, one could instead
     57use a local path to the DTD in the document type declaration (e.g.
     58<tt class="filename">/usr/share/docbook-xml42/docbookx.dtd</tt>).
    5459</p><p>
    5560Suppose the name of the file containing the example above is
    5661<tt class="filename">bookex.xml</tt>.  To create a single HTML
    5762document from this file is as simple as typing one command:
    58 </p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><br>
    59 <tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html-nochunks bookex.xml</tt></b><br>
    60 </p></div></blockquote></div><p>
     63</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html-nochunks bookex.xml</tt></b></p></div></blockquote></div><p>
    6164To create a multi-part HTML version is just as easy:
    62 </p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><br>
    63 <tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html bookex.xml</tt></b><br>
    64 </p></div></blockquote></div><p>
    65 
    66 </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Getting Ready for DocBook </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Resources</td></tr></table></div></body></html>
     65</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html bookex.xml</tt></b></p></div></blockquote></div><p>
     66A final and very  important DocBook topic is that of "entities". For
     67the purposes of writing CLP documentation (i.e. what follows is a gross simplification),
     68entities are a way of "#include-ing" one document into
     69another, and of using certain special characters which would otherwise confuse
     70the tools used to process DocBook documents.
     71The simplest example of the latter is the &lt; symbol, which is used to begin
     72tags in XML.  Rather than putting the character directly into the document text,
     73an entity can be used.  Specifically, one would use the string
     74<tt class="literal">&amp;lt;</tt> instead.
     75The other use of entities, as suggested above, is to split a document into
     76convenient pieces.  This is demonstrated in <a href="ar01s05.html" title="DocBook and CLP, Perfect Together">the section called &#8220;DocBook and CLP, Perfect Together&#8221;</a>.
     77</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Getting Ready for DocBook </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> DocBook and CLP, Perfect Together</td></tr></table></div></body></html>
  • html/trunk/Clp/userguide/howto/ar01s05.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Resources</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s04.html" title="Need to Know"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Resources</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> </td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="resources"></a>Resources</h2></div></div><div></div></div><p>
    2 Below is a list of some online resources for learning more about DocBook and
    3 XML.
    4 </p><div class="itemizedlist"><ul type="disc"><li><p>
    5 <a href="http://www.docbook.org" target="_top">DocBook.org</a>:
    6 The official site for
    7 <i class="citetitle">DocBook: The Definitive Guide</i>
    8 (see below).
    9 </p></li><li><p>
    10 <a href="http://www.docbook.org/tdg/index.html" target="_top">
    11 DocBook:The Definitive Guide</a>: The number one reference for DocBook tags.
    12 The book is very much oriented toward users of the SGML version of DocBook, but
    13 is still the best resource available for CLP documenters.
    14 </p></li><li><p>
    15 <a href="http://cyberelk.net/tim/docbook/selfdocbookx/index.html" target="_top">The
    16 Selfdocbook (XML Edition)</a> is another very useful reference.  It is a
    17 self-documenting introduction to DocBook XML (it includes its own source,
    18 which makes ita great learning tool).
    19 </p></li><li><p>
    20 <a href="http://wiki.docbook.org/" target="_top">DocBook Wiki</a>
    21 Full of useful DocBook links.
    22 </p></li><li><p>
    23 <a href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook" target="_top">
    24 The Official DocBook homepage</a>: Not terribly useful, but it includes
    25 information on the DocBook mailing lists, and a page where one can
    26 <a href="http://www.oasis-open.org/docbook/xml/" target="_top">download DocBook</a>.
    27 </p></li><li><p>
    28 <a href="http://www.dpawson.co.uk/docbook/" target="_top">DocBook FAQ</a>
    29 A very handy list of frequently asked quesions (with answers!) about DocBook.
    30 </p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left" valign="top">Need to Know </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> </td></tr></table></div></body></html>
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook and CLP, Perfect Together</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="up" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="previous" href="ar01s04.html" title="Need to Know"><link rel="next" href="ar01s06.html" title="Tips and Suggestions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DocBook and CLP, Perfect Together</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s06.html">Next</a></td></tr></table><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="clp"></a>DocBook and CLP, Perfect Together</h2></div></div><div></div></div><p>
     2The DocBook XML source of the CLP documentation is available via the COIN CVS
     3repository in the <tt class="filename">COIN/Clp/Docs</tt> directory.  The first file
     4of interest is <tt class="filename">clpuserguide.xml</tt>.  At the time of this
     5tutorial's writing, the file looked like this:
     6</p><pre class="programlisting">
     7
     8&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
     9&lt;!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
     10  &lt;!ENTITY authors SYSTEM "authors.xml"&gt;
     11  &lt;!ENTITY legal SYSTEM "legal.xml"&gt;
     12  &lt;!ENTITY intro SYSTEM "intro.xml"&gt;
     13  &lt;!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml"&gt;
     14  &lt;!ENTITY notsobasic SYSTEM "notsobasic.xml"&gt;
     15  &lt;!ENTITY moresamples SYSTEM "moresamples.xml"&gt;
     16  &lt;!ENTITY clpexe SYSTEM "clpexe.xml"&gt;
     17  &lt;!ENTITY messages SYSTEM "messages.xml"&gt;
     18  &lt;!ENTITY faq SYSTEM "faq.xml"&gt;
     19  &lt;!ENTITY faqcontent SYSTEM "faqcontent.xml"&gt;
     20  &lt;!ENTITY doxygen SYSTEM "doxygen.xml"&gt;
     21  &lt;!ENTITY revhist SYSTEM "revhist.xml"&gt;
     22]&gt;
     23&lt;book id="clpuserguide" lang="en"&gt;
     24&lt;bookinfo&gt;
     25&lt;title&gt;CLP User Manual&lt;/title&gt;
     26  &amp;authors;
     27  &amp;legal;
     28&lt;/bookinfo&gt;
     29  &amp;intro;
     30  &amp;basicmodelclasses;
     31  &amp;notsobasic;
     32  &amp;moresamples;
     33  &amp;clpexe;
     34  &amp;messages;
     35  &amp;faq;
     36  &amp;doxygen;
     37  &amp;revhist;
     38&lt;/book&gt;
     39
     40</pre><p>
     41Essentially <tt class="filename">clpuserguide.xml</tt> contains a series of entity
     42declarations which refer to other XML files (e.g.
     43&lt;!ENTITY authors SYSTEM "authors.xml"&gt;, which are then included into
     44the main file via use of the entities (e.g. &amp;authors;.  This allows
     45a neat separation of chapters in the Guide, resulting in more manageable and
     46readable source than would be possible without the use of entities.  Neither the
     47names nor the order of the declarations of the entities is particularly
     48important, but it is a good practice to follow the informal convention of naming
     49the entity after the chapter filename, and declaring it in a sensible place with
     50respect to the order of the chapters.
     51</p><p>
     52Editing a particular chapter of the Guide is a matter of editing a single,
     53reasonably sized file.  The addition of a new chapter merely entails the
     54declaration of a new entity and the writing of a short additional line in
     55<tt class="filename">clpuserguide.xml</tt>.  Suppose a chapter on the barrier method
     56of CLP was planned (it is, in fact).  The chapter could be written in a file
     57named <tt class="filename">barrier.xml</tt>, while an entity was declared and used in
     58<tt class="filename">clpuserguide.xml</tt>.  If the barrier chapter was to preceed,
     59say, the chapter on the CLP executable, the new
     60<tt class="filename">clpuserguide.xml</tt> would look like this (with changes
     61emphasized):
     62</p><pre class="programlisting">
     63
     64&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
     65&lt;!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
     66  &lt;!ENTITY authors SYSTEM "authors.xml"&gt;
     67  &lt;!ENTITY legal SYSTEM "legal.xml"&gt;
     68  &lt;!ENTITY intro SYSTEM "intro.xml"&gt;
     69  &lt;!ENTITY basicmodelclasses SYSTEM "basicmodelclasses.xml"&gt;
     70  &lt;!ENTITY notsobasic SYSTEM "notsobasic.xml"&gt;
     71  &lt;!ENTITY moresamples SYSTEM "moresamples.xml"&gt;
     72
     73  <span class="emphasis"><em>&lt;!ENTITY barrier SYSTEM "barrier.xml"&gt;</em></span>
     74
     75  &lt;!ENTITY clpexe SYSTEM "clpexe.xml"&gt;
     76  &lt;!ENTITY messages SYSTEM "messages.xml"&gt;
     77  &lt;!ENTITY faq SYSTEM "faq.xml"&gt;
     78  &lt;!ENTITY faqcontent SYSTEM "faqcontent.xml"&gt;
     79  &lt;!ENTITY doxygen SYSTEM "doxygen.xml"&gt;
     80  &lt;!ENTITY revhist SYSTEM "revhist.xml"&gt;
     81]&gt;
     82&lt;book id="clpuserguide" lang="en"&gt;
     83&lt;bookinfo&gt;
     84&lt;title&gt;CLP User Manual&lt;/title&gt;
     85  &amp;authors;
     86  &amp;legal;
     87&lt;/bookinfo&gt;
     88  &amp;intro;
     89  &amp;basicmodelclasses;
     90  &amp;notsobasic;
     91  &amp;moresamples;
     92
     93  <span class="emphasis"><em>&amp;barrier;</em></span>
     94
     95  &amp;clpexe;
     96  &amp;messages;
     97  &amp;faq;
     98  &amp;doxygen;
     99  &amp;revhist;
     100&lt;/book&gt;
     101
     102</pre><p>
     103The barrier chapter source might look something like this:
     104</p><pre class="programlisting">
     105
     106&lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
     107&lt;chapter id="clpexe"&gt;
     108  &lt;title&gt;
     109  The CLP Barrier Method
     110  &lt;/title&gt;
     111  &lt;section&gt;
     112    &lt;para&gt;
     113      The CLP barrier method can be used &#8230;
     114    &lt;/para&gt;
     115  &lt;/section&gt;
     116&lt;/chapter&gt;
     117
     118</pre><p>
     119Note the absence of a document type declaration; it is not necessary (and in
     120fact "illegal") in this context because this file is included in
     121the main file via the entity mechanism (only one document type declaration is
     122allowed).
     123</p><p>
     124With some content in the proposed <tt class="filename">barrier.xml</tt> and the
     125appropriate changes made to <tt class="filename">clpuserguide.xml</tt>, a new HTML
     126version of the Guide could  be created in much the same manner as the
     127small book example above was transformed to HTML:
     128</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html-nochunks clpuserguide.xml</tt></b></p></div></blockquote></div><p>
     129or for a sectioned version:
     130</p><div class="blockquote"><blockquote class="blockquote"><div class="literallayout"><p><tt class="prompt">$</tt> <b class="userinput"><tt>xmlto html clpuserguide.xml</tt></b></p></div></blockquote></div><p>
     131Most of the chapters and appendices in the Guide exist only to be used in the
     132Guide.  There is currently one exception, the FAQ.  The FAQ is constructed in
     133a way that allows its inclusion in the Guide as well as on the CLP
     134website (i.e. we have a single source document for our frequently asked
     135questions).  The file pointed to by the entity <tt class="literal">faq</tt>,
     136<tt class="filename">faq.xml</tt>, is a wrapper for the file
     137<tt class="filename">faqcontent.xml</tt> (with corresponding entity
     138<tt class="literal">faqcontent</tt>).  <tt class="filename">faqcontent.xml</tt> has another
     139wrapper in <tt class="filename">coin-web/Clp</tt> named
     140<tt class="filename">faqwrapper.xml</tt>, which will be addressed elsewhere.
     141</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ar01s04.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ar01s06.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Need to Know </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Tips and Suggestions</td></tr></table></div></body></html>
  • html/trunk/Clp/userguide/howto/docbook4clp.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook for Writers of CLP Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id4673629"></a>DocBook for Writers of CLP Documentation</h1></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">de la Nuez</span></h3></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id4673644">Introduction</a></span></dt><dt><span class="section"><a href="#id4676374">DocBook?</a></span></dt><dt><span class="section"><a href="#id4675980">Getting Ready for DocBook</a></span></dt><dt><span class="section"><a href="#needtoknow">Need to Know</a></span></dt><dt><span class="section"><a href="#clp">DocBook and CLP, Perfect Together</a></span></dt><dt><span class="section"><a href="#id4674923">Tips and Suggestions</a></span></dt><dt><span class="section"><a href="#resources">Resources</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4673644"></a>Introduction</h2></div></div><div></div></div><p>
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook for Writers of CLP Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id4673655"></a>DocBook for Writers of CLP Documentation</h1></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">de la Nuez</span></h3></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#id4673642">Introduction</a></span></dt><dt><span class="section"><a href="#id4676382">DocBook?</a></span></dt><dt><span class="section"><a href="#id4675986">Getting Ready for DocBook</a></span></dt><dt><span class="section"><a href="#needtoknow">Need to Know</a></span></dt><dt><span class="section"><a href="#clp">DocBook and CLP, Perfect Together</a></span></dt><dt><span class="section"><a href="#id4674940">Tips and Suggestions</a></span></dt><dt><span class="section"><a href="#resources">Resources</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4673642"></a>Introduction</h2></div></div><div></div></div><p>
    22The CLP User Guide is written in
    33<a href="http://www.docbook.org/" target="_top">DocBook</a>
     
    88limited in its scope to applying these two technologies to documenting CLP.
    99See <a href="#resources" title="Resources">the section called &#8220;Resources&#8221;</a> to learn more about DocBook and XML.
    10 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4676374"></a>DocBook?</h2></div></div><div></div></div><p>
     10</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4676382"></a>DocBook?</h2></div></div><div></div></div><p>
    1111Why DocBook?  Why not HTML or LaTeX?  Here are a few of the reasons:
    1212</p><div class="itemizedlist"><ul type="disc"><li><p>
     
    3838Many tedious tasks, such as the creation of a table of contents, are handled
    3939automatically by a good DocBook configuration.
    40 </p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4675980"></a>Getting Ready for DocBook</h2></div></div><div></div></div><p>
     40</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4675986"></a>Getting Ready for DocBook</h2></div></div><div></div></div><p>
    4141Editing and publishing CLP documentation with DocBook requires that some
    4242important tools be installed.  It is likely that all or most of these tools
     
    5555</p><div class="itemizedlist"><ul type="disc"><li><p>
    5656<tt class="literal">dockbook-xml42</tt>
    57 <sup>[<a name="id4675264" href="#ftn.id4675264">1</a>]</sup>
     57<sup>[<a name="id4675270" href="#ftn.id4675270">1</a>]</sup>
    5858</p></li><li><p>
    5959<tt class="literal">docbook-xsl</tt>
     
    120120
    121121  &lt;?xml version="1.0" encoding="ISO-8859-1"?&gt;
    122   &lt;!DOCTYPE book SYSTEM "/usr/share/docbook-xml42/docbookx.dtd"&gt;
     122  &lt;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     123                  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
    123124  &lt;book&gt;
    124125    &lt;title&gt;How CLP Won the West&lt;/title&gt;
     
    134135The only difference is the document type declaration which states the document
    135136is meant to adhere to the standard described in the file
    136 <tt class="filename">/usr/share/docbook-xml42/docbookx.dtd</tt> (see
     137<tt class="filename">http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</tt> (see
    137138<a href="#resources" title="Resources">the section called &#8220;Resources&#8221;</a> for where to read more about document type
    138139declarations the DocBook DTD).  In other words, adding the extra line of code
    139140makes this little example a genuine DocBook document.  In this case, the
    140 declaration uses an absolute path for a particular system (Cygwin).  DocBook has
    141 an elaborate system for eliminating this lack of elegance.  Future versions of
    142 this tutorial will address this (see <a href="#resources" title="Resources">the section called &#8220;Resources&#8221;</a> for more on
    143 this topic).
     141declaration uses an Internet address.  However, in a properly configured
     142environment, a network connection would not be necessary to work with the
     143document, thanks to the "catalog" mechanism.  A discussion of catalogs
     144is beyond the scope of this document (see <a href="#resources" title="Resources">the section called &#8220;Resources&#8221;</a> for more).
     145Should catalogs not be properly configured on a given system, one could instead
     146use a local path to the DTD in the document type declaration (e.g.
     147<tt class="filename">/usr/share/docbook-xml42/docbookx.dtd</tt>).
    144148</p><p>
    145149Suppose the name of the file containing the example above is
     
    300304wrapper in <tt class="filename">coin-web/Clp</tt> named
    301305<tt class="filename">faqwrapper.xml</tt>, which will be addressed elsewhere.
    302 </p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4674923"></a>Tips and Suggestions</h2></div></div><div></div></div><p>
     306</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4674940"></a>Tips and Suggestions</h2></div></div><div></div></div><p>
    303307This tutorial, as well as the first DocBook release of the
    304308<i class="citetitle">CLP User Guide</i>, were written using the Emacs editor.
     
    324328<a href="http://cyberelk.net/tim/docbook/selfdocbookx/index.html" target="_top">The
    325329Selfdocbook (XML Edition)</a> is also an excellent example, as it is a
    326 DocBook document which includes its own source.
     330DocBook document which includes its own source.  Note that the source of this
     331tutorial is available from the COIN CVS repository in the
     332<tt class="filename">COIN/Clp/Docs/Howto</tt> directory.
    327333</p><p>
    328334The DocBook community is quite active, so the official mailing lists are highly
     
    358364<a href="http://www.dpawson.co.uk/docbook/" target="_top">DocBook FAQ</a>
    359365A very handy list of frequently asked quesions (with answers!) about DocBook.
    360 </p></li></ul></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id4675264" href="#id4675264">1</a>] </sup>This is for version 4.2 of DocBook.  Future versions will have a
     366</p></li></ul></div></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a name="ftn.id4675270" href="#id4675270">1</a>] </sup>This is for version 4.2 of DocBook.  Future versions will have a
    361367slightly different name.</p></div></div></div></body></html>
  • html/trunk/Clp/userguide/howto/index.html

    r958 r964  
    1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook for Writers of CLP Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="next" href="ar01s02.html" title="DocBook?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DocBook for Writers of CLP Documentation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr></table><hr></div><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id4633525"></a>DocBook for Writers of CLP Documentation</h1></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">de la Nuez</span></h3></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="index.html#id4695394">Introduction</a></span></dt><dt><span class="section"><a href="ar01s02.html">DocBook?</a></span></dt><dt><span class="section"><a href="ar01s03.html">Getting Ready for DocBook</a></span></dt><dt><span class="section"><a href="ar01s04.html">Need to Know</a></span></dt><dt><span class="section"><a href="ar01s05.html">Resources</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695394"></a>Introduction</h2></div></div><div></div></div><p>
     1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>DocBook for Writers of CLP Documentation</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="DocBook for Writers of CLP Documentation"><link rel="next" href="ar01s02.html" title="DocBook?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">DocBook for Writers of CLP Documentation</th></tr><tr><td width="20%" align="left"> </td><th width="60%" align="center"> </th><td width="20%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr></table><hr></div><div class="article" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id4633593"></a>DocBook for Writers of CLP Documentation</h1></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">de la Nuez</span></h3></div></div></div><div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="index.html#id4695388">Introduction</a></span></dt><dt><span class="section"><a href="ar01s02.html">DocBook?</a></span></dt><dt><span class="section"><a href="ar01s03.html">Getting Ready for DocBook</a></span></dt><dt><span class="section"><a href="ar01s04.html">Need to Know</a></span></dt><dt><span class="section"><a href="ar01s05.html">DocBook and CLP, Perfect Together</a></span></dt><dt><span class="section"><a href="ar01s06.html">Tips and Suggestions</a></span></dt><dt><span class="section"><a href="ar01s07.html">Resources</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id4695388"></a>Introduction</h2></div></div><div></div></div><p>
    22The CLP User Guide is written in
    33<a href="http://www.docbook.org/" target="_top">DocBook</a>
    44<a href="http://www.xml.org/" target="_top">XML</a>.
    5 This document serves as an introduction to using DocBook for maintaining
     5This tutorial serves as an introduction to using DocBook for maintaining
    66the Guide, as well as writing new documentation.  There are countless DocBook
    7 and XML resources available both in print and online, so this document will be
     7and XML resources available both in print and online, so this tutorial will be
    88limited in its scope to applying these two technologies to documenting CLP.
    9 See <a href="ar01s05.html" title="Resources">the section called &#8220;Resources&#8221;</a> to learn more about DocBook and XML.
     9See <a href="ar01s07.html" title="Resources">the section called &#8220;Resources&#8221;</a> to learn more about DocBook and XML.
    1010</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"> </td><td width="40%" align="right"> <a accesskey="n" href="ar01s02.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"> </td><td width="20%" align="center"> </td><td width="40%" align="right" valign="top"> DocBook?</td></tr></table></div></body></html>
Note: See TracChangeset for help on using the changeset viewer.