Changeset 421


Ignore:
Timestamp:
Sep 1, 2004 4:11:57 PM (15 years ago)
Author:
ddelanu
Message:

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

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/Docs/Howto/docbook4clp.xml

    r415 r421  
    11<?xml version="1.0" encoding="ISO-8859-1"?>
    2 <!DOCTYPE article SYSTEM "/usr/share/docbook-xml42/docbookx.dtd" [
    3 ]>
     2<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
     3                  "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
    44<article>
    55<articleinfo>
     
    9292<ulink url="http://www.cygwin.com/">Cygwin</ulink>, as this tutorial assumes a
    9393*nix environment for DocBook development.  In fact, the following instructions
    94 for installation are for Cygwin and Red Hat Linux, but should not be
    95 altogether different for another *nix system.
     94for installation are for Cygwin and Red Hat Linux, (and should not be
     95altogether different for another *nix system).
    9696</para>
    9797<para>
    9898The necessary Cygwin packages can all be found in the &quot;Doc&quot; section
    9999of the categorical view of Cygwin's <filename>setup.exe</filename>.  The user
    100 should be certain that all of them are selected (because there may not be
     100should verify that all of them are selected (because there may not be
    101101adequate dependency rules to ensure that all the correct packages are installed).
    102102The packages in question are:
     
    164164</para>
    165165<para>
    166 The last of the packages, xmlto, is a shell script which facilitates the
    167 conversion of DocBook documents to HTML and other formats.  If all the tools
    168 are properly installed, creating an HTML version of this tutorial, for example,
    169 is as trivial as typing <userinput>xmlto html docbook4clp.xml</userinput> at
    170 the command line.  But before jumping in to work with DocBook, there are some
    171 important issues which need to be addressed.
     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.
    172173</para>
    173174</section>
     
    176177<title>Need to Know</title>
    177178<para>
    178 Knowledge of DocBook is like a security clearance: a user is on a need-to-know
     179Knowledge of DocBook is like a security clearance: the user is on a need-to-know
    179180basis.  That is, to start working with DocBook in a properly configured
    180181environment, a user needs to know very little, but there is always something more
     
    205206<para>
    206207This document is not much use, though, without some meaning for the tags in it.
    207 The DocBook DTD is what gives a document meaning.  This example works better,
    208 and is a valid DocBook document:
     208The DocBook DTD is what gives a document meaning.  The following example works
     209better, and constitutes a valid DocBook document:
    209210</para>
    210211<programlisting>
     
    225226<para>
    226227The only difference is the document type declaration which states the document
    227 is meant to adhere to the standard set out in the file
     228is meant to adhere to the standard described in the file
    228229<filename>/usr/share/docbook-xml42/docbookx.dtd</filename> (see
    229 <xref linkend="resources"/> for where to read more about the DocBook DTD).
    230 In other words, adding the extra line of code makes this little example a genuine
    231 DocBook document.  In this case, the declaration uses an absolute path for a
    232 particular system (Cygwin).  DocBook has an elaborate system for eliminating
    233 this lack of elegance.  Future versions of this tutorial will address this (see
    234 <xref linkend="resources"/> for more on this topic).
     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).
    235237</para>
    236238<para>
     
    254256another, and of using certain special characters which would otherwise confuse
    255257the tools used to process DocBook documents.
    256 </para>
    257 <para>
    258258The simplest example of the latter is the &lt; symbol, which is used to begin
    259259tags in XML.  Rather than putting the character directly into the document text,
    260260an entity can be used.  Specifically, one would use the string
    261261<literal><![CDATA[&lt;]]></literal> instead.
    262 </para>
    263 <para>
    264262The other use of entities, as suggested above, is to split a document into
    265263convenient pieces.  This is demonstrated in <xref linkend="clp"/>.
     
    312310<para>
    313311Essentially <filename>clpuserguide.xml</filename> contains a series of entity
    314 declarations which refer to other XML files, which are then included into the
    315 main file via use of the entities.  This makes more a neat separation of
    316 chapters in the Guide, resulting in more manageable and readable source than
    317 would be possible without the use of entities.  Neither the names nor the order
    318 of the declarations of the entities is particularly important, but it is a good
    319 practice to follow the informal convention of naming the entity after the chapter
    320 filename, and declaring it in a sensible place with respect to the order of the
    321 chapters.
     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.
    322321</para>
    323322<para>
     
    375374</programlisting>
    376375<para>
    377 The barrier chapeter source might look something like this:
     376The barrier chapter source might look something like this:
    378377</para>
    379378<programlisting>
     
    394393<para>
    395394Note the absence of a document type declaration; it is not necessary (and in
    396 fact &quot;illegal&quot;) in this context because this this file is included in
    397 the main file via the entity mechanism.
     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).
    398398</para>
    399399<para>
    400400With some content in the proposed <filename>barrier.xml</filename> and the
    401401appropriate changes made to <filename>clpuserguide.xml</filename>, a new HTML
    402 version of the Guide could then be created in much the same manner as the
     402version of the Guide could be created in much the same manner as the
    403403small book example above was transformed to HTML:
    404404</para>
     
    415415Most of the chapters and appendices in the Guide exist only to be used in the
    416416Guide.  There is currently one exception, the FAQ.  The FAQ is constructed in
    417 a way that allows its inclusion in the Guide as well as directly on the CLP
    418 website.  The file pointed to by the entity <literal>faq</literal>,
     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>,
    419420<filename>faq.xml</filename>, is a wrapper for the file
    420421<filename>faqcontent.xml</filename> (with corresponding entity
     
    452453</para>
    453454<para>
    454 With DocBook, as is the case with any other computer language, it is often
    455 easiest to learn by example.  The existing examples which are part of CLP are
     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
    456457this tutorial, of course, and the User Guide itself.
    457458<ulink url="http://cyberelk.net/tim/docbook/selfdocbookx/index.html">The
Note: See TracChangeset for help on using the changeset viewer.