LDP
/
old-www
1
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity
old-www/LDP/LDP-Author-Guide/html/LDP-Author-Guide.html

18621 lines
337 KiB
HTML
Raw Permalink Blame History

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML
><HEAD
><TITLE
>LDP Author Guide</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
><BODY
CLASS="book"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="BOOK"
><A
NAME="index"
></A
><DIV
CLASS="TITLEPAGE"
><H1
CLASS="title"
><A
NAME="AEN2"
></A
>LDP Author Guide</H1
><H3
CLASS="author"
><A
NAME="AEN5"
></A
>Jorge Godoy</H3
><DIV
CLASS="affiliation"
><SPAN
CLASS="orgname"
><A
HREF="http://www.conectiva.com"
TARGET="_top"
>Conectiva S.A.</A
><BR></SPAN
><SPAN
CLASS="orgdiv"
>Publishing Department<BR></SPAN
><DIV
CLASS="address"
><P
CLASS="address"
><TT
CLASS="email"
>&#60;<A
HREF="mailto:godoy@metalab.unc.edu"
>godoy@metalab.unc.edu</A
>&#62;</TT
></P
></DIV
></DIV
><H3
CLASS="author"
><A
NAME="AEN14"
></A
>Emma Jane Hogbin</H3
><DIV
CLASS="affiliation"
><DIV
CLASS="address"
><P
CLASS="address"
><TT
CLASS="email"
>&#60;<A
HREF="mailto:emmajane@xtrinsic.com"
>emmajane@xtrinsic.com</A
>&#62;</TT
></P
></DIV
></DIV
><H3
CLASS="author"
><A
NAME="AEN20"
></A
>Mark F. Komarinski</H3
><DIV
CLASS="affiliation"
><DIV
CLASS="address"
><P
CLASS="address"
><TT
CLASS="email"
>&#60;<A
HREF="mailto:mkomarinski@wayga.org"
>mkomarinski@wayga.org</A
>&#62;</TT
></P
></DIV
></DIV
><H3
CLASS="author"
><A
NAME="AEN27"
></A
>David C. Merrill</H3
><DIV
CLASS="affiliation"
><DIV
CLASS="address"
><P
CLASS="address"
>david&nbsp;-AT-&nbsp;lupercalia.net</P
></DIV
></DIV
><P
CLASS="pubdate"
>2005-03-04<BR></P
><DIV
CLASS="revhistory"
><TABLE
WIDTH="100%"
BORDER="0"
><TR
><TH
ALIGN="LEFT"
VALIGN="TOP"
COLSPAN="3"
><B
>Revision History</B
></TH
></TR
><TR
><TD
ALIGN="LEFT"
>Revision 4.84.74.64.54.44.34.24.1</TD
><TD
ALIGN="LEFT"
>2006-04-202005-03-042005-01-232004-07-142004-04-192004-04-042004-04-022004-01-27</TD
><TD
ALIGN="LEFT"
>Revised by: MGejhejhejhejhejhejhejh</TD
></TR
><TR
><TD
ALIGN="LEFT"
COLSPAN="3"
>Added notes about prefered submission formats,
corrected links, packaged templates.Typo fixed in sample DocBook markup. Added new web-based authoring tool and information on LaTeX to DocBook conversions.Typos fixed in xmlto notes and book template. Copied information about
DocBook-capable word processing tools into the "Converting Documents
to DocBook XML" Appendix; added new XML editors; and information about tools to convert other formats to DocBook XML.Updated information regarding CVS accounts and connecting to the CVS server.Added editor credit requirements to the Using DocBook
section. Updated the submission procedure. New documents can now only
be added by one of the Review Coordinators after the successful
completion of each of the required reviews.Removed the section Contributing to The
LDP (replaced by Summary of The LDP Process).Added references for LyX to DocBook conversions in the
bibliography.Updated the license requirements and added them to the
table of contents (moved them out of the sub-section).</TD
></TR
></TABLE
></DIV
><DIV
><DIV
CLASS="abstract"
><A
NAME="AEN33"
></A
><P
></P
><P
>&#13; This guide describes the process of submitting and publishing a
document with The Linux Documentation Project (TLDP). It includes
information about the tools, toolchains and formats used by TLDP.
The document's primary audience is new TLDP authors, but it also
contains information for seasoned documentation authors.
</P
><P
></P
></DIV
></DIV
><HR></DIV
><DIV
CLASS="TOC"
><DL
><DT
><B
>Table of Contents</B
></DT
><DT
>1. <A
HREF="#aboutthisguide"
>About this Guide</A
></DT
><DD
><DL
><DT
>1.1. <A
HREF="#purpose"
>About this Guide</A
></DT
><DT
>1.2. <A
HREF="#theldp"
>About The LDP</A
></DT
><DT
>1.3. <A
HREF="#feedback"
>Feedback</A
></DT
><DT
>1.4. <A
HREF="#copyrights"
>Copyrights and Trademarks</A
></DT
><DT
>1.5. <A
HREF="#acknowledgements"
>Acknowledgments and Thanks</A
></DT
><DT
>1.6. <A
HREF="#conventions"
>Document Conventions</A
></DT
></DL
></DD
><DT
>2. <A
HREF="#introduction"
>Authoring TLDP Documents: An Introduction</A
></DT
><DD
><DL
><DT
>2.1. <A
HREF="#process"
>Summary of The LDP Process</A
></DT
><DT
>2.2. <A
HREF="#mailinglists"
>Mailing Lists</A
></DT
></DL
></DD
><DT
>3. <A
HREF="#propose"
>Writing Your Proposal</A
></DT
><DD
><DL
><DT
>3.1. <A
HREF="#sg-subject"
>Choosing a Subject</A
></DT
><DT
>3.2. <A
HREF="#scope"
>Scope of Your Document</A
></DT
><DT
>3.3. <A
HREF="#unmaintained"
>Unmaintained and Out-of-date Documents</A
></DT
><DT
>3.4. <A
HREF="#sg-outline"
>Developing an Outline</A
></DT
><DT
>3.5. <A
HREF="#research"
>Research</A
></DT
></DL
></DD
><DT
>4. <A
HREF="#write"
>Write</A
></DT
><DD
><DL
><DT
>4.1. <A
HREF="#sg-writingstyle"
>Writing the Text</A
></DT
><DT
>4.2. <A
HREF="#sg-editing"
>Edit and Proofread the Text</A
></DT
><DT
>4.3. <A
HREF="#tools-writing"
>Tools for Writing, Editing and Maintaining your Document</A
></DT
></DL
></DD
><DT
>5. <A
HREF="#ag-markup"
>Markup</A
></DT
><DD
><DL
><DT
>5.1. <A
HREF="#markup"
>Markup: A General Overview</A
></DT
><DT
>5.2. <A
HREF="#docbook-why"
>DocBook: What it is and why we use it</A
></DT
><DT
>5.3. <A
HREF="#docbookxml"
>XML and SGML: Why we use XML</A
></DT
><DT
>5.4. <A
HREF="#acceptedversions"
>Markup Languages Accepted by TLDP</A
></DT
></DL
></DD
><DT
>6. <A
HREF="#distribute"
>Distributing Your Documentation</A
></DT
><DD
><DL
><DT
>6.1. <A
HREF="#pre-distribute"
>Before Distributing Your Documentation</A
></DT
><DT
>6.2. <A
HREF="#doc-licensing"
>Licensing and Copyright</A
></DT
><DT
>6.3. <A
HREF="#crediting-ack"
>Acknowledgments</A
></DT
><DT
>6.4. <A
HREF="#ag-review"
>TLDP Review Process</A
></DT
><DT
>6.5. <A
HREF="#submission"
>Submission to LDP for publication</A
></DT
></DL
></DD
><DT
>7. <A
HREF="#sg-maintaining"
>Maintenance</A
></DT
><DD
><DL
><DT
>7.1. <A
HREF="#sg-maintaining-support"
>Maintaining Your Document</A
></DT
><DT
>7.2. <A
HREF="#fixingerrors"
>Fixing Errors</A
></DT
></DL
></DD
><DT
><A
HREF="#bibliography"
>References</A
></DT
><DT
>A. <A
HREF="#templates"
>Templates</A
></DT
><DD
><DL
><DT
>A.1. <A
HREF="#templates-book"
>Document Templates</A
></DT
><DT
>A.2. <A
HREF="#templates-style"
>Style Sheets</A
></DT
><DT
>A.3. <A
HREF="#templates-gdfl"
>GNU Free Documentation License</A
></DT
></DL
></DD
><DT
>B. <A
HREF="#tools"
>System Setup: Editors, Validation and
Transformations</A
></DT
><DD
><DL
><DT
>B.1. <A
HREF="#tools-distro"
>Tools for your operating
system</A
></DT
><DT
>B.2. <A
HREF="#tools-edit"
>Editing tools</A
></DT
><DT
>B.3. <A
HREF="#tools-validate"
>Validation</A
></DT
><DT
>B.4. <A
HREF="#transformations"
>Transformations</A
></DT
><DT
>B.5. <A
HREF="#dtd"
>DocBook DTD</A
></DT
><DT
>B.6. <A
HREF="#doc-components"
>Formatting Documents</A
></DT
></DL
></DD
><DT
>C. <A
HREF="#cvs"
>Concurrent Version System (CVS)</A
></DT
><DD
><DL
><DT
>C.1. <A
HREF="#getaccount"
>Getting a CVS account</A
></DT
><DT
>C.2. <A
HREF="#usingcvs"
>Using CVS</A
></DT
><DT
>C.3. <A
HREF="#cvs-resources"
>CVS Resources</A
></DT
></DL
></DD
><DT
>D. <A
HREF="#using-docbook"
>DocBook: Sample Markup</A
></DT
><DD
><DL
><DT
>D.1. <A
HREF="#writing-docbook"
>General Tips and Tricks</A
></DT
><DT
>D.2. <A
HREF="#section"
><TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> and <TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
>: what's the difference?</A
></DT
><DT
>D.3. <A
HREF="#commandprompt"
>Command Prompts</A
></DT
><DT
>D.4. <A
HREF="#encoding-index"
>Encoding Indexes</A
></DT
><DT
>D.5. <A
HREF="#inserting-pictures"
>Inserting Pictures</A
></DT
><DT
>D.6. <A
HREF="#metadata-markup"
>Markup for Metadata</A
></DT
><DT
>D.7. <A
HREF="#doc-bib"
>Bibliographies</A
></DT
><DT
>D.8. <A
HREF="#tools-entities"
>Entities (shortcuts,
text macros and re-usable text)</A
></DT
><DT
>D.9. <A
HREF="#namedfiles"
>Customizing your HTML files</A
></DT
></DL
></DD
><DT
>E. <A
HREF="#x2docbook"
>Converting Documents to DocBook XML</A
></DT
><DD
><DL
><DT
>E.1. <A
HREF="#txt2docbook"
>Text to DocBook</A
></DT
><DT
>E.2. <A
HREF="#oo2docbook"
>OpenOffice.org to DocBook</A
></DT
><DT
>E.3. <A
HREF="#word2docbook"
>Microsoft Word to DocBook</A
></DT
><DT
>E.4. <A
HREF="#tex4ht"
>LaTeX to DocBook</A
></DT
><DT
>E.5. <A
HREF="#lyx2docbook"
>LyX to DocBook</A
></DT
><DT
>E.6. <A
HREF="#docbook2docbook"
>DocBook to DocBook Transformations</A
></DT
></DL
></DD
><DT
><A
HREF="#glossary"
>Glossary</A
></DT
><DT
>F. <A
HREF="#fdl"
>GNU Free Documentation License</A
></DT
><DD
><DL
><DT
>F.1. <A
HREF="#fdl-preamble"
>0. PREAMBLE</A
></DT
><DT
>F.2. <A
HREF="#fdl-section1"
>1. APPLICABILITY AND DEFINITIONS</A
></DT
><DT
>F.3. <A
HREF="#fdl-section2"
>2. VERBATIM COPYING</A
></DT
><DT
>F.4. <A
HREF="#fdl-section3"
>3. COPYING IN QUANTITY</A
></DT
><DT
>F.5. <A
HREF="#fdl-section4"
>4. MODIFICATIONS</A
></DT
><DT
>F.6. <A
HREF="#fdl-section5"
>5. COMBINING DOCUMENTS</A
></DT
><DT
>F.7. <A
HREF="#fdl-section6"
>6. COLLECTIONS OF DOCUMENTS</A
></DT
><DT
>F.8. <A
HREF="#fdl-section7"
>7. AGGREGATION WITH INDEPENDENT WORKS</A
></DT
><DT
>F.9. <A
HREF="#fdl-section8"
>8. TRANSLATION</A
></DT
><DT
>F.10. <A
HREF="#fdl-section9"
>9. TERMINATION</A
></DT
><DT
>F.11. <A
HREF="#fdl-section10"
>10. FUTURE REVISIONS OF THIS LICENSE</A
></DT
><DT
>F.12. <A
HREF="#fdl-using"
>Addendum</A
></DT
></DL
></DD
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Tables</B
></DT
><DT
>D-1. <A
HREF="#table-useful-markup"
>Useful markup</A
></DT
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Figures</B
></DT
><DT
>B-1. <A
HREF="#AEN1567"
>epcEdit screen shot</A
></DT
><DT
>B-2. <A
HREF="#AEN1598"
>nedit screen shot</A
></DT
><DT
>B-3. <A
HREF="#AEN1659"
>Adding shell commands to nedit</A
></DT
><DT
>B-4. <A
HREF="#AEN1682"
><SPAN
CLASS="application"
>nsgmls</SPAN
> output on success</A
></DT
></DL
></DIV
><DIV
CLASS="LOT"
><DL
CLASS="LOT"
><DT
><B
>List of Examples</B
></DT
><DT
>B-1. <A
HREF="#ex-catalog-files"
>Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES
Environmental Variables</A
></DT
><DT
>B-2. <A
HREF="#example-catalog-sgml"
>Example of an SGML catalog</A
></DT
><DT
>B-3. <A
HREF="#ex-catalog-xml"
>Sample XML Catalog file</A
></DT
><DT
>B-4. <A
HREF="#xmllint-example"
>Debugging example using xmllint</A
></DT
><DT
>B-5. <A
HREF="#ex-dsssl"
><SPAN
CLASS="QUOTE"
>"Installing"</SPAN
> DSSSL style sheets</A
></DT
><DT
>B-6. <A
HREF="#ex-htmloutput"
>Example creating HTML output</A
></DT
><DT
>B-7. <A
HREF="#ex-dtd"
><SPAN
CLASS="QUOTE"
>"Installing"</SPAN
> DocBook Document Type Definitions</A
></DT
><DT
>B-8. <A
HREF="#AEN2358"
>Style sheet to insert summaries in articles</A
></DT
><DT
>B-9. <A
HREF="#ex-entity-external-index"
>Configuring an external entity to include the
index</A
></DT
><DT
>D-1. <A
HREF="#ex-programlisting"
>Command Prompt with <TT
CLASS="sgmltag"
>programlisting</TT
></A
></DT
><DT
>D-2. <A
HREF="#ex-screen"
>Command Prompt with <TT
CLASS="sgmltag"
>screen</TT
></A
></DT
><DT
>D-3. <A
HREF="#example-code-index"
>Code for the generation of an index</A
></DT
><DT
>D-4. <A
HREF="#index-zone"
>Use of the attribute <TT
CLASS="sgmltag"
>zone</TT
></A
></DT
><DT
>D-5. <A
HREF="#ex-index"
>Usage of values <TT
CLASS="sgmltag"
>startofrange</TT
> and <TT
CLASS="sgmltag"
>endofrange</TT
> on the attribute<TT
CLASS="sgmltag"
>class</TT
></A
></DT
><DT
>D-6. <A
HREF="#ex-picture-fileref"
>Inserting a picture</A
></DT
><DT
>D-7. <A
HREF="#former-figure-imageobject"
>Using <TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
></A
></DT
><DT
>D-8. <A
HREF="#ex-othercredit"
>Other Credit</A
></DT
><DT
>D-9. <A
HREF="#ex-editor"
>Editor</A
></DT
><DT
>D-10. <A
HREF="#sample-metadata"
>Sample Meta Data</A
></DT
><DT
>D-11. <A
HREF="#ex-bib"
>A Bibliography</A
></DT
><DT
>D-12. <A
HREF="#ex-entities"
>Adding
Entities</A
></DT
><DT
>D-13. <A
HREF="#ex-entity-parameters"
>Use of parameter entities</A
></DT
></DL
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="aboutthisguide"
></A
>Chapter 1. About this Guide</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="purpose"
></A
>1.1. About this Guide</H1
><P
>This document was started on Aug 26, 1999 by Mark
F. Komarinski after two day's worth of frustration getting tools
to work. If even one LDP author is helped by this, then I did my
job.</P
><P
>&#13; Version 4 of this document was released in early 2004 by Emma Jane
Hogbin. A complete overhaul of the document was done to separate
the authoring HOWTOs from the technical HOWTOs. The review took
approximately eight months.
</P
><P
>&#13; The newest version of this document can be found at the LDP
homepage
<A
HREF="http://www.tldp.org/"
TARGET="_top"
>http://www.tldp.org</A
>.
The original DocBook, HTML, and other formats can be found there.
</P
><P
>&#13; There are many ways to contribute to the Linux movement
that do not require the ability to produce software. One such way is
to write documentation. The availability of
easy-to-understand, technically accurate documentation can make a
world of difference to someone who is struggling with Linux
software. This Guide is designed to help you research and write a
HOWTO which can be submitted to the LDP. The appendices also include
sample templates, markup tips and information on how to transform
your document from DocBook to another format (such as HTML) for
easier proofreading.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="theldp"
></A
>1.2. About The LDP</H1
><P
>The Linux Documentation Project (LDP) was started to
provide new users a way of quickly getting information about a
particular subject. It not only contains a series of books on
administration, networking, and programming, but also has a large
number of smaller works on individual subjects, written by those
who have used it. If you want to find out about printing, you
get the <A
HREF="http://www.tldp.org/HOWTO/Printing-HOWTO.html"
TARGET="_top"
>Printing
HOWTO</A
>. If you want to do find out if your Ethernet card
works with Linux, grab the <A
HREF="http://www.tldp.org/HOWTO/Ethernet-HOWTO.html"
TARGET="_top"
>Ethernet
HOWTO</A
>, and so on.
</P
><P
>&#13; The LDP provides documents to the world in a variety of
convenient formats and also accepts submissions in a
number of formats. The current standard for storing
the source documentation is a format known as DocBook, see <A
HREF="#docbook-why"
>Section 5.2</A
>.
</P
><A
NAME="AEN92"
></A
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="BLOCKQUOTE"
><TR
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
><TD
WIDTH="80%"
VALIGN="TOP"
><P
>The Linux Documentation Project (LDP) is working on
developing free, high-quality documentation for the GNU/Linux
operating system. The overall goal of the LDP is to
collaborate in all of the issues of Linux documentation. This
includes the creation of <SPAN
CLASS="QUOTE"
>"HOWTOs"</SPAN
> and <SPAN
CLASS="QUOTE"
>"Guides"</SPAN
>. We hope to
establish a system of documentation for Linux that will be
easy to use and search. This includes the integration of the
manual pages, info docs, HOWTOs, and other documents.</P
></TD
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="RIGHT"
VALIGN="TOP"
>--<SPAN
CLASS="attribution"
>LDP Manifesto located at <A
HREF="http://www.tldp.org/manifesto.html"
TARGET="_top"
>http://www.tldp.org/manifesto.html</A
></SPAN
></TD
><TD
WIDTH="10%"
>&nbsp;</TD
></TR
></TABLE
><P
>&#13; The human readable version goes more like this: The LDP consists
of a large group of volunteers who are working on documentation
about Linux and the programs which run on the Linux kernel.
These documents exist primarily as shorter HOWTOs and longer
Guides. Both are available from <A
HREF="http://www.tldp.org/"
TARGET="_top"
>http://www.tldp.org/</A
>.
This Guide focuses primarily on how to write your own HOWTOs for
submission to the LDP.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="feedback"
></A
>1.3. Feedback</H1
><P
>&#13; Send feedback to <TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
>. Please reference the title
of this document in your email. Please note: you must <A
HREF="http://tldp.org/mailinfo.html#maillists"
TARGET="_top"
>be subscribed</A
>
in order to send email to the list.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="copyrights"
></A
>1.4. Copyrights and Trademarks</H1
><P
>Copyright 1999-2002 Mark F. Komarinski, David C. Merrill, Jorge Godoy</P
><P
>&#13; Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts. A copy of the license is included in the appendix entitled
<SPAN
CLASS="QUOTE"
>"GNU Free Documentation License."</SPAN
>
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="acknowledgements"
></A
>1.5. Acknowledgments and Thanks</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="ack1-3"
></A
>1.5.1. Version 1 - Version 3</H2
><P
> Thanks
to everyone that gave comments as I was writing this. This includes David
Lawyer, Deb Richardson, Daniel Barlow, Greg Ferguson, Mark Craig and other
members of the <TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
> list. Some sections I
got from the <A
HREF="http://www.tldp.org/HOWTO/"
TARGET="_top"
>HOWTO Index</A
>
and the sgmltools documentation. The sections on network access to CVS was
partially written by Sergiusz Pawlowicz
(<TT
CLASS="email"
>&#60;<A
HREF="mailto:ser@metalab.unc.edu"
>ser@metalab.unc.edu</A
>&#62;</TT
>). Sections on DocBook were written by
Jorge Godoy (<TT
CLASS="email"
>&#60;<A
HREF="mailto:godoy@conectiva.com"
>godoy@conectiva.com</A
>&#62;</TT
>). A great deal of thanks
to both of them for their help. </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="ack4"
></A
>1.5.2. Version 4</H2
><P
>
Thanks to Tabatha Marshall and Machtelt Garrels (Tille) for making sure I actually
finished the document. Thanks to my reviewers: Charles Curley, Martin
Brown and Tille; and to Saqib Ali for his on-line transformation and
validation tools. I have also incorporated a number of useful emails from the
LDP mailing lists. The original authors are credited within the document.
Special personal thank yous are extended to Steve Champeon for getting me
interested in markup languages and for being a wonderful mentor; and to my
partner, Graig Kent, for being outrageously supportive. [EJH]
</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="conventions"
></A
>1.6. Document Conventions</H1
><P
>This document uses the following conventions<A
NAME="AEN127"
HREF="#FTN.AEN127"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
>:</P
><DIV
CLASS="informaltable"
><A
NAME="AEN130"
></A
><P
></P
><TABLE
BORDER="0"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Descriptions</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Appearance</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Information requiring special attention</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This is a warning.</P
></TD
></TR
></TABLE
></DIV
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Caution</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This cautions the reader.</P
></TD
></TR
></TABLE
></DIV
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Hint</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This is a hint.</P
></TD
></TR
></TABLE
></DIV
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Notes</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This is a note.</P
></TD
></TR
></TABLE
></DIV
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>File Names</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="filename"
>file.extension</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Directory Names</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="filename"
>directory</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Commands to be typed</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
CLASS="command"
>command</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Applications Names</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="application"
>application</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><I
CLASS="foreignphrase"
>Prompt</I
> of users command under bash shell</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>bash$</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><I
CLASS="foreignphrase"
>Prompt</I
> of root users command under bash shell</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>bash#</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><I
CLASS="foreignphrase"
>Prompt</I
> of user command under tcsh shell</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>tcsh$</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Environment Variables</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="envar"
>VARIABLE</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Emphasized word</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><EM
>word</EM
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Quoted text</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="QUOTE"
>"quote"</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Code Example</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
><TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Beginning and end of paragraph<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="introduction"
></A
>Chapter 2. Authoring TLDP Documents: An Introduction</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="process"
></A
>2.1. Summary of The LDP Process</H1
><P
>&#13; The following section outlines the process of creating and/or
maintaining a document for the Linux Documentation Project. This
section includes all steps--some of which may not be relevant to your
specific document.
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>&#13; Join the discuss mailing list. Authors who are interested in taking over
the maintenance of someone else's document should also join this list.
This is to make sure the LDP knows who is working on what documentation.
</P
><P
>&#13; If you have not yet written your documentation, please review our
documents (<A
HREF="http://tldp.org/HOWTO/HOWTO-INDEX/howtos.html"
TARGET="_top"
>current</A
>,
<A
HREF="http://tldp.org/authors/unmaint.html"
TARGET="_top"
>unmaintained</A
>
and <A
HREF=""
TARGET="_top"
>in progress</A
>) and submit a proposal to the
list. Your proposal should include reasons why your document will be
different than those already in the collection; or identify a subject
that is currently missing from our documentation. For more information
about writing proposals, please read <A
HREF="#propose"
>Chapter 3</A
>.
</P
><P
>&#13; For more information about the mailing lists, please read <A
HREF="#mailinglists"
>Section 2.2</A
> or visit <A
HREF="http://lists.tldp.org"
TARGET="_top"
>lists.tldp.org</A
> to subscribe.
If your document has already been written, please submit a copy to the
discuss list (or include the URL of where it can be found).
</P
></LI
><LI
><P
>&#13; Write your document. If your document has not yet been written, please
be sure to email the discuss list before you start writing.
<EM
>You may choose whatever format you feel most comfortable
in to write your document.</EM
> If it is not one of the formats
accepted by the LDP a volunteer will convert it for you. For more
information on writing technical documentation, please read
<A
HREF="#write"
>Chapter 4</A
>.
</P
></LI
><LI
><P
>&#13; If you are adding your own markup, you may also want to join the
docbook mailing list.
For more information about the LDP DocBook list please read
<A
HREF="#mailinglists"
>Section 2.2</A
>.
If you would like to start with a template, you may find the templates in
<A
HREF="#templates"
>Appendix A</A
> useful. There is also a general
introduction to markup in <A
HREF="#ag-markup"
>Chapter 5</A
> and a section
full of examples at <A
HREF="#using-docbook"
>Appendix D</A
>.
</P
></LI
><LI
><P
>&#13; Submit your document for technical, language and metadata reviews. Do this by
emailing your document to <TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
>. In the
subject line be sure give the title of the document. In the body of the
email say that you are ready for the review process. Outline any
additional reviews your document may have already received. You should
be assigned a reviewer within the week. The reviews may take an
additional week each. For more information about this process, please
read <A
HREF="#distribute"
>Chapter 6</A
>.
</P
><P
>&#13; If your document is not already in DocBook or LinuxDoc format, a
reviewer will convert it for you.
</P
></LI
><LI
><P
>&#13; Once your document has been through each of the reviews a Review
Coordinator will add it to the CVS, update the version number to 1.0
and have the document published on the public Web site.
For more information about your final submission to the LDP, please
read <A
HREF="#submission"
>Section 6.5</A
>.
</P
></LI
></OL
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>If you don't submit your document in DocBook format</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; The volunteer adding markup to your document may choose any
accepted markup language. The Author Guide, however,
will refer only to DocBook. If you are submitting plain text or
some other format, please let the LDP know if you prefer to
maintain your document in either LinuxDoc or DocBook, which are the accepted formats for end-results.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="mailinglists"
></A
>2.2. Mailing Lists</H1
><P
>You can subscribe to the following mailing lists:</P
><P
></P
><UL
><LI
><P
>First is <TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
>, which is the main
discussion group of the LDP.</P
></LI
><LI
><P
>Another is the <TT
CLASS="email"
>&#60;<A
HREF="mailto:docbook@en.tldp.org"
>docbook@en.tldp.org</A
>&#62;</TT
> list, which is for
questions about DocBook use including markup and transformations. If you run into
trouble with a particular markup tag, you can send your question
here for answers.</P
></LI
></UL
><P
>You can subscribe to either list by sending a request
message to either <TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss-subscribe@en.tldp.org"
>discuss-subscribe@en.tldp.org</A
>&#62;</TT
> or
<TT
CLASS="email"
>&#60;<A
HREF="mailto:docbook-subscribe@en.tldp.org"
>docbook-subscribe@en.tldp.org</A
>&#62;</TT
>. The subject of your message should read
<SPAN
CLASS="QUOTE"
>"subscribe"</SPAN
> (no quotes). To
remove yourself from the list, send an E-mail with the subject of
<SPAN
CLASS="QUOTE"
>"unsubscribe"</SPAN
> to
<TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss-unsubscribe@en.tldp.org"
>discuss-unsubscribe@en.tldp.org</A
>&#62;</TT
> or
<TT
CLASS="email"
>&#60;<A
HREF="mailto:docbook-unsubscribe@en.tldp.org"
>docbook-unsubscribe@en.tldp.org</A
>&#62;</TT
>.</P
><P
>&#13; If you are interested in DocBook beyond the simple markup of your
LDP document, you may want to consider joining one of the <A
HREF="http://www.oasis-open.org/"
TARGET="_top"
>OASIS</A
> DocBook mailing
lists. Please see <A
HREF="http://docbook.org/mailinglist/index.html"
TARGET="_top"
>http://docbook.org/mailinglist/index.html</A
>
for more information.
</P
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="propose"
></A
>Chapter 3. Writing Your Proposal</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="sg-subject"
></A
>3.1. Choosing a Subject</H1
><P
>&#13; It is likely that if you are reading the Author Guide, you already have a
subject in mind. The idea may have come from your own frustrations in
trying to get something to work; or maybe you are already writing or
have written documentation for other purposes and you want to submit
it to the LDP.
For example, if you posted a question to a mailing list
and it took many posts to resolve the problem -- that might be an incentive to write documentation.
</P
><P
>&#13; Regardless of how you picked your subject, it is important that the LDP
community understand why your documentation should be included in its
collection. If someone has requested documentation, or you worked
with a mailing list to resolve a problem you should include the details in
your proposal to the LDP discuss mailing list. It may help others to
understand the need for your specific document.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="scope"
></A
>3.2. Scope of Your Document</H1
><P
>&#13; Now that you've got a subject, you will need to decide the
<EM
>scope</EM
> of the document. The scope or subject area
should be:
</P
><P
></P
><OL
TYPE="1"
><LI
><DIV
CLASS="formalpara"
><P
><B
>Clearly defined. </B
>
Define the boundaries of your
subject area before you begin. Do not repeat information that is in
another HOWTO and do not leave gaps of information between
your HOWTO and someone else's HOWTO.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Not too broad, and not too narrow. </B
>
If you try to cover too much information you may sacrifice depth.
It is better to cover a small subject area in detail than to cover a large subject
area poorly. Linux tools are known for doing exactly one
thing and doing that one thing <EM
>well</EM
>.
Similarly, your HOWTO should cover one subject and cover it
<EM
>well</EM
>.
</P
></DIV
><P
>&#13; If the scope of your proposed document is very narrow, it might be better to
include your information as part of another HOWTO.
This makes it easier for readers to find the HOWTO they need.
Search the LDP repository for topics which relate to your
document. If you find a document which is a good match, email the author
and ask them if they would like to include your contribution.
</P
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Undocumented. </B
>
Before documenting a particular subject, always do a web
search (and specifically a search within the LDP documents)
to see if your topic is already covered in another
document. If it is, refer to the other document instead of
duplicating the information within your own document. You
may wish to include a brief summary of information that
can be found in other documents.
</P
></DIV
><P
>&#13; If the HOWTO already in place is insufficient or needs updating,
contact the author and offer to help. See also <A
HREF="#unmaintained"
>Section 3.3</A
> for taking over old or unmaintained documents.</P
><P
>&#13; Most authors appreciate any help offered. Additionally, sending
comments and remarks to the author is usually regarded both as a
reassurance and a reward: to the author, feedback is the ultimate proof that writing the documentation was not a pointless effort.</P
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Pre-approved by the LDP. </B
>
Before you proceed with your HOWTO, post to the discuss list
and get some feedback from other LDP volunteers. Checking with the
list <EM
>before</EM
> you begin can save you headaches
<EM
>later</EM
>.
</P
></DIV
></LI
></OL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Stay in touch!</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; Joining the discuss list and following
it regularly, even if you never post, is a good way to stay current
on the activities, needs and policies of the LDP.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="typesofdocs"
></A
>3.2.1. Documentation Templates</H2
><P
>&#13; After you've decided the scope of your document you
should start to consider the type of document that you will write. There are
a number of different LDP documentation templates:
Guides, HOWTOs, man pages and FAQs. Rahul Sundaram
describes their scope in the <A
HREF="http://tldp.org/FAQ/LDP-FAQ/index.html"
TARGET="_top"
>Linux Documentation
Project (LDP) FAQ</A
>. Here is a brief overview of what they are
with pointers on how you can get started writing your own:
</P
><P
></P
><UL
><LI
><DIV
CLASS="formalpara"
><P
><B
>Guides. </B
>A guide covers a broad subject and is quite long. The Author
Guide (this document) is a guide. Other guides include:
<A
HREF="http://tldp.org/LDP/intro-linux/html/index.html"
TARGET="_top"
>Introduction to Linux: A hands on
guide</A
>,
<A
HREF="http://tldp.org/LDP/lkmpg/index.html"
TARGET="_top"
>The Linux Kernel
Module Programming Guide</A
>, etc. A full list of guides is
available from: <A
HREF="http://tldp.org/guides.html"
TARGET="_top"
>Linux Project
Documentation Guides</A
>. Guides use the <SPAN
CLASS="QUOTE"
>"book"</SPAN
>
templates located in <A
HREF="#templates"
>Appendix A</A
>.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>HOWTOs. </B
>A HOWTO is typically a set of instructions that outlines,
step-by-step, how a specific task is accomplished. Examples of
HOWTOs are:
<A
HREF="http://tldp.org/HOWTO/CDROM-HOWTO/index.html"
TARGET="_top"
>CDROM-HOWTO</A
>
<A
HREF="http://tldp.org/HOWTO/Module-HOWTO/index.html"
TARGET="_top"
>Module-HOWTO</A
>.
A full list of HOWTOs is available from: <A
HREF="http://tldp.org/HOWTO/HOWTO-INDEX/howtos.html"
TARGET="_top"
>Single List of
HOWTOs</A
> (warning: it's a BIG page). HOWTOs typically use the
<SPAN
CLASS="QUOTE"
>"article"</SPAN
> template and are output to multiple HTML
pages by default.
Templates are available in <A
HREF="#templates"
>Appendix A</A
>.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>man pages. </B
>man (Manual) pages are the standard form of help available for many
linux applications and utilities. They can be viewed by typing
<B
CLASS="command"
>man applicationname</B
> at a prompt. A full list of man
pages is available from:
<A
HREF="http://tldp.org/docs.html#man"
TARGET="_top"
>Linux Man Pages</A
>.
Since man pages are bundled with software there is no LDP template
at this time.</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>FAQs. </B
>FAQs (Frequently Asked Questions) are a list of questions and
answers to help prevent new users from asking the same questions
over and over again.
A full list of FAQs is available from: <A
HREF="http://tldp.org/FAQ/"
TARGET="_top"
>Linux Documentation Project
FAQs</A
>. FAQs typically use the <SPAN
CLASS="QUOTE"
>"article"</SPAN
>
template with some specific DocBook elements to form the
Question/Answer structure.
You can find a template for writing a FAQ in <A
HREF="#templates"
>Appendix A</A
>.
</P
></DIV
></LI
></UL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>mini-HOWTOs and HOWTOs</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; The LDP no longer distinguishes between HOWTOs and mini-HOWTOs. All
previously written mini-HOWTOs have been included in longer HOWTOs.
All new documents must be at least HOWTO in length. This means the
documents should cover a bigger subject area rather than a small one. If
your document is very small you may wish to submit it for inclusion
in another, larger HOWTO that already exists. If you're not sure
what size your document is, email the discuss list and ask for
feedback.
</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="unmaintained"
></A
>3.3. Unmaintained and Out-of-date Documents</H1
><P
>&#13; If you wish to become the <SPAN
CLASS="QUOTE"
>"owner"</SPAN
> for an unmaintained document there are
several steps you must go through.
</P
><P
></P
><UL
><LI
><P
>&#13; Contact the author. Make sure the author no longer
wishes to maintain the document in question. Note that the E-mail address
shown may no longer be valid. In that case, try a <A
HREF="http://google.com"
TARGET="_top"
>search</A
> for the
author. If the original author of a document cannot be found after a <SPAN
CLASS="QUOTE"
>"good-faith"</SPAN
> effort,
let us know (<TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
>--<A
HREF="http://tldp.org/mailinfo.html#maillists"
TARGET="_top"
>subscription
required</A
>).
</P
></LI
><LI
><P
>&#13; Determine if a more up-to-date copy of the document exists, outside
of what is available on the LDP. If so, try to secure a copy for yourself
to work on.
</P
></LI
><LI
><P
>&#13; Inform the LDP which document you would like to maintain, so that we can
track who is working on what and prevent duplication of effort. We also
suggest that you join the LDP general discussion list
(<TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
>). This step is also required for new
documents.
</P
></LI
><LI
><P
>
Submit the document to the LDP with any intended modifications. Make
sure to continue to reference the original author somewhere within the
document (Credits, Revision History, etc.). Once the document is
re-submitted, we will remove the entry from the list of unmaintained
documents.
</P
></LI
></UL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Feedback wanted</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Some of unmaintained documents may be outdated, or the content may be
covered in another (actively maintained) HOWTO. If that is the situation,
contact us (preferably on the discuss mailing list) and let us know.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="sg-outline"
></A
>3.4. Developing an Outline</H1
><P
>&#13; Before you actually begin writing, prepare an outline.
An outline will help you to get a clear picture of the subject matter
and allow you to concentrate on one small part of the HOWTO
at a time.
</P
><P
>&#13; Unless your HOWTO is exceptionally small, your outline will probably
be multilevel.
When developing a multilevel outline, the top level should contain general
subject areas, and sub-headings should be more detailed and specific.
Look at each level of your outline independently,
and make sure it covers all key areas of the subject matter. Sub-headings
should cover all key areas of the heading under which they fall.
</P
><P
>&#13; Each item in your outline should follow the item before it,
and lead into the item that comes next. For example, a HOWTO about a particular
program shouldn't have a section on <EM
>configuration</EM
>
before one on <EM
>installation</EM
>.</P
><P
>You may choose to use the following outline for a HOWTO about
using a specific program:</P
><P
></P
><UL
><LI
><P
>development history</P
></LI
><LI
><P
>where to download the software from</P
></LI
><LI
><P
>how to install the software</P
></LI
><LI
><P
>how to configure the software</P
></LI
><LI
><P
>how to use the software</P
></LI
></UL
><P
>You may find it helpful to try a little <SPAN
CLASS="QUOTE"
>"card
sorting"</SPAN
> at this stage of the writing process. Write all of your mini
subject areas onto pieces of paper. Now sort these pieces of paper into
main headings and their sub-sections. It may help to shuffle the slips of
paper before you start. This will help to give you a fresh set of eyes
while working.
</P
><P
>&#13; When you are comfortable with your outline, look it over once more,
with a critical eye. Have you covered every relevant topic in
sufficient detail? Have you not wandered beyond the scope of the document?
It is a good idea to show your outline to others (including The LDP
discuss list) to get some feedback.
Remember: it is much easier to reorganize your document at the outline stage
than doing this after writing it.
</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Writing a HOWTO made easy</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; For help writing your HOWTO outline, and getting a head start on
the markup of your document, check out <A
HREF="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html"
TARGET="_top"
>The LDP HOWTO
Generator</A
>. Note that this is for generating HOWTOs. Templates for FAQs and Guides are available in <A
HREF="#templates"
>Appendix A</A
>.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>You're not alone</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; You might have noticed a theme developing here.
Just like Free software, Free documentation is best when you
<SPAN
CLASS="QUOTE"
>"release early, release often."</SPAN
> The discuss list includes
many experienced LDP authors, and you would be wise to seek their
advice when making decisions about your contribution.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="research"
></A
>3.5. Research</H1
><P
>&#13; While you are working on your outline you will most likely research
your topic--especially to confirm the document you are about to
write does not yet exist! Here are a few pointers that will keep
you from pulling out your hair later:
</P
><P
></P
><UL
><LI
><DIV
CLASS="formalpara"
><P
><B
>Compile your resources as you research. </B
>It is almost guaranteed you will not remember where to
find a critical piece of information when you need it most. It
will help to bookmark important (and even not so important)
pages as you go. Make sure the bookmark's title reflects why the
page is important to you.
If there are multiple key ideas in one page, you may want to bookmark the
same page with different titles.</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Assume your most important resource will disappear. </B
>The dreaded <SPAN
CLASS="QUOTE"
>"Error 404: Page not found"</SPAN
>. Even if you have
bookmarked a page it may not be there when you return to it. If
a page contains a really critical piece of information: make a
copy. You may do this by creating a text file with the title of
the document, the author's name, the page's URL and the text of
the page into a text file on your computer. You might also
choose to <SPAN
CLASS="QUOTE"
>"print"</SPAN
> the file to a PDF (save as or convert to PDF format will
capture the original URL on the page if you're using a smart
browser).</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Start your <SPAN
CLASS="QUOTE"
>"Resources"</SPAN
> page now. </B
>As you find pages of interest add them to a Resources
document. You may do this by exporting your bookmarks or by
keeping a separate text file with the Resources sorted by
sub-category. A little effort now will save you a lot of time
later.</P
></DIV
><P
>&#13; There is more information about the DocBook markup of
bibliographies in <A
HREF="#doc-bib"
>Section D.7</A
>.
</P
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Write down subject areas as you go. </B
>If you are card sorting you may find it particularly
useful to write topic cards as you find pages that cover that
specific topic. At the top of the card write the subject area.
In the main area of the card write a few notes about what you
might cover under this topic--include the titles of pages that
contain important information. If a sub-topic gets too big you
may want to divide it into multiple cards.</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Separate generic information from version-specific
information. </B
>A new version of the software that you describe might be released the day after you release your document.
Other things, like where to download
the software, won't change. Alternatively, you may
choose to document old problems with specific software as a way
of encouraging readers to upgrade to the latest version available:
<SPAN
CLASS="QUOTE"
>"Version X of the software is known for a specific bug.
The bug was fixed as of Version Y."</SPAN
>
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Save all related emails. </B
>People will often have interesting insight into the
problem that you are writing about. Any questions that are asked
about your topic should be addressed in the final document. If
you are writing about software make sure to ask people what
system they are using. Add information in your document about
which system configurations your instructions have been tested
on. (Having lots of friends with moderately different
configurations can be very beneficial!)
All of these personal experiences can add
greatly to your final documentation.</P
></DIV
></LI
></UL
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="write"
></A
>Chapter 4. Write</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="sg-writingstyle"
></A
>4.1. Writing the Text</H1
><P
>&#13; By now you should have organized your document; you collected bits of raw information
and inserted them into the outline.
Your next challenge is to massage all of the raw data you've collected
into a readable, entertaining and understandable whole. If you are
working from an existing document make sure any new pieces of
information are in the best possible places.
</P
><P
>&#13; It has taken quite a bit of work to get to the point where you can
actually start writing, hasn't it? Well, the hard work begins to pay
off for you now. At this stage, you can begin to really use your
imagination and creativity to communicate this heap of information.
Don't be too clever though! Your readers are already struggling with
new concepts--do not make them struggle to understand your language
as well.
</P
><P
>&#13; There are a number of classic guides to writing--many
of which are available on-line.
Their language will
seem old, but the messages are still valuable to authors today.
These are listed in . Also listed in the
resources section are a variety of sites that have
information specific to technical writing.
</P
><P
>&#13; The Author Guide wouldn't be complete without
mentioning the Plain Language movement. Although
directed at simplifying government documents, <A
HREF="http://www.blm.gov/nhp/NPR/pe_toc.html"
TARGET="_top"
>Writing user-friendly
documents</A
> is quite useful. It includes before and after
writing samples. There's also a
<A
HREF="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html"
TARGET="_top"
>PlainTrain
writing tutorial</A
>.
</P
><P
>&#13; And any document that discusses writing for the web wouldn't be complete without
a nod toward <A
HREF="http://www.useit.com"
TARGET="_top"
>useit.com</A
>.
The following articles may be of specific interest:
<P
></P
><UL
><LI
><P
><A
HREF="http://www.useit.com/papers/webwriting/"
TARGET="_top"
>Writing for the Web</A
></P
></LI
><LI
><P
><A
HREF="http://useit.com/alertbox/20030811.html"
TARGET="_top"
>Information pollution</A
></P
></LI
><LI
><P
><A
HREF="http://useit.com/alertbox/9703b.html"
TARGET="_top"
>Be Succinct! (Writing for the Web)</A
></P
></LI
></UL
>
There are many, many resources for writing web
documents--a quick web search for <SPAN
CLASS="QUOTE"
>"web
writing"</SPAN
> will find lots of resources.
Don't get too distracted, though: the ultimate goal is to
write, not to read about writing!
</P
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="writing-style"
></A
>4.1.1. Writing Style and Style Guides</H2
><P
>&#13; There are a number of industry style guides which define how language
should be used in documents. A common example for American English is
the <A
HREF="http://www.chicagomanualofstyle.org/"
TARGET="_top"
>Chicago Manual
of Style</A
>. It defines things like: whether a period (.) should be inside or
outside of <SPAN
CLASS="QUOTE"
>"quotes"</SPAN
>; and the format for citing
another document. A style guide helps to keep documents
consistent--most corporations will follow a style guide to
format media releases and other promotional material.
Style guides mays also define how words should be spelled
(is it color or colour?).
</P
><P
>&#13; The LDP does not require a specific style
guide; however, you should use a consistent style throughout your
document. Your document should be spell checked for a single
language (e.g. American English vs. British English).
The <A
HREF="http://tldp.org/HOWTO/LDP-Reviewer-HOWTO/"
TARGET="_top"
>Reviewer's HOWTO</A
> currently lists a number of
conventions for LDP documents and it is as close as it
gets to an official LDP Style Guide.
</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>A personal glossary</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>It helps to make a list of terms that you were new to you when you
first started researching and writing your document. You can refer to this
list while writing the text. You may also want to include it as a glossary in
your final document.
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; You can save yourself a lot of time in the editing phase if you
decide how you will write your document ahead of time. If you are
taking over someone else's document you may need to either: modify
your own style to fit the current document; or edit the
document so that it melds with the style you would like to
use from now on.
</P
><P
>&#13; From a writing style perspective, use of the
first-person in a HOWTO adds to its charm--an attribute most
other documentation sorely lacks. Don't be afraid
to speak for yourself--use the word <SPAN
CLASS="QUOTE"
>"I"</SPAN
> to
describe your personal experiences and opinions.
</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="writing-resources"
></A
>4.1.2. On-line Writing Resources</H2
><P
>&#13; In the
section, you will find a list of resources that cover the subject
better than this guide could hope to. Consult them, and follow their
advice.
</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="sg-editing"
></A
>4.2. Edit and Proofread the Text</H1
><P
>&#13; Once you've written the text of your HOWTO, it is time
to polish and refine it. Good editing can make the
difference between a good HOWTO and a great one.
</P
><P
>&#13; One of the goals of editing is to remove <EM
>[extraneous]</EM
> material that
has crept its way into your document.
You should go through your HOWTO carefully, and ruthlessly
delete anything that does not contribute to the reader's understanding
of the subject matter. It is natural for writers to go off on tangents
while in the process of writing. Now is the time to correct that. It
often helps to leave a bit of time between when you write a document
and when you edit it.
</P
><P
>&#13; Make sure that the content of every section matches the title
precisely. It's possible that your original subject heading
is no longer relevant. If you've strayed from your original heading
it could mean one of the following: the original title was poorly
worded, the new material should actually go in a different section,
or the new material is not really necessary for your document. If you
need to change a title, check to see if the original subject heading
is still important. If it is, make sure that topic is covered somewhere
else in the document.
</P
><P
>&#13; When editing and proofing your work, check for obvious mistakes,
such as spelling errors and typos. You should also check for deeper, but
less obvious errors as well, such as <SPAN
CLASS="QUOTE"
>"holes"</SPAN
> in the
information. If you are creating a set of instructions it may
help to test them on a new machine. Sometimes there
are packages that need to be installed which you've forgotten to
mention in your documentation, for instance.
</P
><P
>&#13; When you are completely satisfied with the quality and accuracy of
your work, forward it to someone else for third-party proofing.
You will be too close to the work to see fundamental flaws.
Have others test the instructions as
well. Make sure they follow exactly what you have written. Ask anyone
who tests your documentation to make specific notes in any places
where they didn't follow your instructions (and the reason why they
didn't follow them). For example: <SPAN
CLASS="QUOTE"
>"I skipped step 2 because I
already have the required packages installed."</SPAN
>
</P
><P
>&#13; In a sense, editing is like code review in software development.
Having a programmer review their own code doesn't make much sense,
and neither does having a writer edit their own document.
Recruit a friend, or write the discuss list
to find a volunteer to proofread before submitting your document. You
may also want to submit your document to a mailing list that is
relevant to your document's topic. List members should be able to
help check the facts, clarity of your instructions and language of
the document.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Native speaker?</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; If you are writing in a language in which you are not fluent,
find an editor who is. Technical
documentation, more than any other type of writing, must use
extremely precise grammar and vocabulary. Misuse of language
makes your document less valuable.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tools-writing"
></A
>4.3. Tools for Writing, Editing and Maintaining your Document</H1
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Reminder</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; You do <EM
>not</EM
> need to submit your
initial document to the LDP in anything more than plain text! Other open
submission formats are accepted as well, for instance OpenOffice documents,
RTF files or HTML. The LDP volunteers will convert your document to DocBook
for you. Once it has been converted you will need to maintain your document
in DocBook format, but that should be obvious.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="ag-edittools"
></A
>4.3.1. Editing Tools</H2
><P
>&#13; You may use any word processing or text editing tool to write your
initial document. When you get to the markup stage you may want to use
a text editor which recognizes DocBook files. At a minimum a program
which adds syntax highlighting to your markup will make life a lot
easier. For a description of editors which can handle DocBook files
please skip to <A
HREF="#tools-edit"
>Section B.2</A
>.
</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="cvs-brief"
></A
>4.3.2. Concurrent Versions System (CVS)</H2
><P
>&#13; The LDP provides optional CVS access to its authors. This enables
collaborative writing and has the following positive effects:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
> CVS will keep an off-site backup of your documents. In
the event that you hand over a document to another author,
they can just retrieve the document from CVS and continue
on. In the event you need to go back to a previous version of
a document, you can retrieve it as well. </P
></LI
><LI
><P
>However difficult from an organizational point of view, it's great to have multiple people working on the same
document. CVS enables you to do this. You can have CVS tell you what changes were made by another author
while you were editing your copy, and
integrate those changes.</P
></LI
><LI
><P
>CVS keeps a log of what changes were made. These logs (and
a date stamp) can be placed automatically inside your documents
when they are published.
</P
></LI
><LI
><P
> CVS can be combined with scripts to automatically
update the LDP web site with new documentation as it's written
and submitted. This is not in place yet, but it is a goal.
Currently, CVS updates signal the HOWTO coordinator to
update the LDP web page, meaning that if you use CVS, you're not
required to e-mail your XML code. (Although you do
still need to send the submit list an email when you
are ready for your document to be published, because the whole publishing process has not been fully automated yet.) </P
></LI
></OL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Access to our CVS repository</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Only authors with at least three submissions get access to our CVS, see <A
HREF="#cvs"
>Appendix C</A
>.</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; For more information on how to use CVS to maintain your LDP
documents, please read <A
HREF="#cvs"
>Appendix C</A
>.
</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="ag-spellcheck"
></A
>4.3.3. Spell Check</H2
><P
>&#13; Some writing tools will come with their own built-in spell
check tools. This list is only if your application does not
have a spell check option.
</P
><P
></P
><DIV
CLASS="variablelist"
><P
><B
>Spell Check Software</B
></P
><DL
><DT
><SPAN
CLASS="application"
>aspell</SPAN
>
<A
HREF="http://aspell.sourceforge.net"
TARGET="_top"
>http://aspell.sourceforge.net</A
></DT
><DD
><P
>&#13; This spell check application can work around XML tags. By
distinguishing between content and markup aspell is able to check
your content and ignore the bits it shouldn't be looking at. If you
are getting spelling errors in your markup tags you may be using an
old version and should upgrade.
</P
><P
>The <B
CLASS="command"
>aspell</B
> command comes with the <SPAN
CLASS="application"
>aspell</SPAN
> package, included on most Linux distributions. Use the command as follows:</P
><P
><B
CLASS="command"
>aspell <TT
CLASS="option"
>-c</TT
> <TT
CLASS="filename"
>file</TT
></B
> </P
><P
>An interactive user interface allows for fast and easy correction of errors. Use the <TT
CLASS="option"
>--help</TT
> to read more about <B
CLASS="command"
>aspell</B
> features.</P
></DD
><DT
><SPAN
CLASS="application"
>ispell</SPAN
>
<A
HREF="http://www.cs.hmc.edu/~geoff/ispell.html"
TARGET="_top"
>http://www.cs.hmc.edu/~geoff/ispell.html</A
></DT
><DD
><P
>&#13; Similar to <SPAN
CLASS="application"
>aspell</SPAN
>, but tries to spell
check your markup tags. If you have a choice, use
<SPAN
CLASS="application"
>aspell</SPAN
>, if not,
<SPAN
CLASS="application"
>ispell</SPAN
> is a very acceptable substitute.
</P
></DD
></DL
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="ag-markup"
></A
>Chapter 5. Markup</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="markup"
></A
>5.1. Markup: A General Overview</H1
><P
>&#13; A markup language is a system for marking or tagging a document to
define the structure of the document. You may add tags to your document
to define which parts of your document are paragraphs, titles,
sections, glossary items (the list goes on!).
There are many markup languages in use today. XHTML and HTML will be
familiar to those who author web documents. The LDP uses a markup
language known as DocBook. Each of these markup languages uses its own
<SPAN
CLASS="QUOTE"
>"controlled vocabulary"</SPAN
> to describe documents. For
example: in XHTML a paragraph would be marked up with the tagset
&#60;p&#62;&#60;/p&#62; while in DocBook a paragraph would be marked up
with <TT
CLASS="sgmltag"
>&#60;para&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>. The tagsets are defined in a quasi
dictionary known as a Document Type Definition (DTD).
</P
><P
>&#13; Markup languages also follow a set of rules on how a document
can be assembled. The rules are either SGML (Standard Generalized
Markup Language) or XML (eXtensible Markup Language). These rules are
essentially the <SPAN
CLASS="QUOTE"
>"grammar"</SPAN
> of a document's markup. SGML and
XML are very similiar. XML is a sub-set of SGML, but XML requires more
precise use of the tags when marking up a document.
The LDP accepts both SGML and XML documents, but prefers XML.
</P
><P
>There are three components to an XML/SGML document which is read by a
person.</P
><P
></P
><UL
><LI
><DIV
CLASS="formalpara"
><P
><B
>Content. </B
>
As a TLDP author it is good to remember
that this is the most important piece. Many authors will
write the content first and add their markup later. Content
may include both plain text and graphics. This is the only part that
is required of LDP authors!
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Markup. </B
>
To describe the structure of a document a controlled
vocabulary is added on top of the content. It is used to
distinguish different kinds of content: paragraphs,
lists, tables, warnings (and so on). The markup must also conform to
either SGML or XML rules. If you are not comfortable
adding markup to your document, a TLDP volunteer will do it for you.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Transformation. </B
>
Finally the document is transformed from DocBook to PDF, HTML,
PostScript for display in digital or paper form. This transformation is controlled
through the Document Style Semantics and Specification
Language (DSSSL).
The DSSSL tells the program doing the transformation how to
convert the raw markup into something that a human can read.
The LDP uses a series of scripts to automate these transformations.
You are not required to transform your own documents.
</P
></DIV
></LI
></UL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Content, markup and transformations</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Steve Champeon does a great job of
explaining how content, markup languages, and transformations all fit
together in his article <A
HREF="http://hotwired.lycos.com/webmonkey/02/42/index4a.html"
TARGET="_top"
>The
Secret Life of Markup</A
>. Although he is writing from an HTML
perspective, the ideas are relevant and there is an example of DocBook markup.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="docbook-why"
></A
>5.2. DocBook: What it is and why we use it</H1
><P
>&#13; According to the official DocBook web site,
<A
NAME="AEN567"
></A
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="BLOCKQUOTE"
><TR
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
><TD
WIDTH="80%"
VALIGN="TOP"
><P
>&#13; DocBook is a general purpose XML and SGML document type particularly well
suited to books and papers about computer hardware and software (though
it is by no means limited to these applications).
</P
></TD
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="RIGHT"
VALIGN="TOP"
>--<SPAN
CLASS="attribution"
>DocBook.org</SPAN
></TD
><TD
WIDTH="10%"
>&nbsp;</TD
></TR
></TABLE
>
</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>For the impatient</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; In the next sections we will be explaining about the theoretical side of DocBook, its origins, development, advantages and disadvantages. If you just want the practical side, check out these sections for an overview of HOWTO DocBook:
,
<A
HREF="#using-docbook"
>Appendix D</A
>,
and <A
HREF="#x2docbook"
>Appendix E</A
>
from this guide.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>For the beginner</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>We wish to stress again the fact that any open document format will
be accepted. If you feel more comfortable with plain text, OpenOffice or
HTML, that is fine with us. If you do not look forward to learning
DocBook, LDP volunteerd will convert your document to DocBook XML. To us, the most important task for our authors is the actual writing, not the formatting, keep that in mind!</P
><P
>From the point of submission onwards, however, you will have to maintain
your document in this XML format, but that's a piece of cake. Promised.</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; Although there are other DTDs used to write documentation,
there are a few reasons not to use them.
</P
><P
></P
><UL
><LI
><P
> DocBook is the most
popular DTD, being
used by more than a dozen major open source projects from
GNOME to Python to FreeBSD.
</P
></LI
><LI
><P
> The tools for DocBook
are more developed than others. DocBook support is
included in most Linux distributions, allowing you to
send raw files to be processed at the receiver's end.
</P
></LI
><LI
><P
> And finally, DocBook
has an extensive set of tags (over 300 in all) which is
very useful when you are trying to describe the content
of a document. Fortunately for new authors the majority
of them do not need to be used for simple documentation.
</P
></LI
></UL
><P
>Still not convinced? Eric
Raymond has written a <A
HREF="http://en.tldp.org/HOWTO/DocBook-Demystification-HOWTO/"
TARGET="_top"
>DocBook
Demystification HOWTO</A
> which may help. </P
><P
>&#13; Convinced, but still not comfortable with the thought of
working with DocBook? Give David Lawyer's <A
HREF="http://tldp.org/HOWTO/Howtos-with-LinuxDoc.html"
TARGET="_top"
>Howtos-with-LinuxDoc-mini-HOWTO</A
>
a try.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="docbookxml"
></A
>5.3. XML and SGML: Why we use XML</H1
><P
>&#13; DocBook comes in a couple of different flavors--including both
XML and SGML formats. This means that you may use either the SGML
grammar/rules when adding markup, or you may use the XML grammar/rules.
Either way you may only use one set of rules throughout your document,
and you must define which one you are using at the top of your document.
</P
><P
>&#13; The LDP prefers the XML flavor of DocBook. There are a number of
reasons for this including the following:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>&#13; Libraries for handling XML files are developing at a
rapid pace. These utilities may make it easier for new
authoring tools to become available.
</P
></LI
><LI
><P
>&#13; Many popular word processing programs are now creating
XML output. While it may not be DocBook XML, this does
make it easier for application writers to either add
DocBook XML support, or provide some method of translating
between their format and DocBook XML.
</P
></LI
><LI
><P
>&#13; Everyone else is doing it. While this might not be a
real reason, it allows the LDP to keep up-to-date with
similar projects. Tools, procedures, and issues can be
worked out in a common framework.
</P
></LI
></OL
><P
>&#13; Still not convinced? Fortunately the LDP does
accept a number of other file formats for input. The list of accepted markup
languages can be found in <A
HREF="#acceptedversions"
>Section 5.4</A
>
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="acceptedversions"
></A
>5.4. Markup Languages Accepted by TLDP</H1
><P
>&#13; The LDP stores its documents in the following markup languages:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>&#13; DocBook XML version 4.2 (preferred), 4.1.2
</P
></LI
><LI
><P
>&#13; DocBook SGML version 4.2, 4.1, or 3.x
</P
></LI
><LI
><P
>&#13; LinuxDoc SGML
</P
></LI
></OL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>New Documents</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; A new document may be submitted to the LDP in any format. Documents
which are not in DocBook or LinuxDoc will be converted by a volunteer.
The author is responsible for adding markup to any revisions which are
made.
</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="distribute"
></A
>Chapter 6. Distributing Your Documentation</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="pre-distribute"
></A
>6.1. Before Distributing Your Documentation</H1
><P
>&#13; Before you distribute your documentation, there are a few more
things that you will need to check and possibly add to your document.
</P
><P
></P
><DIV
CLASS="variablelist"
><DL
><DT
>Spelling and Grammar Check</DT
><DD
><P
>&#13; You can read more about helper applications in <A
HREF="#ag-spellcheck"
>Section 4.3.3</A
>. You should also check your document for
its overall flow and clarity.
</P
></DD
><DT
>Abstract and Other Meta Data</DT
><DD
><P
>&#13; Add a short paragraph which clearly defines the scope of your
document.
For more information on how to add this information using DocBook
please read <A
HREF="#metadata-markup"
>Section D.6</A
>
</P
></DD
><DT
>Acknowledgments</DT
><DD
><P
>&#13; Give credit where credit is due. For more information about when to
give credit, read <A
HREF="#crediting-ack"
>Section 6.3</A
>.
</P
></DD
><DT
>License and Copyright</DT
><DD
><P
>&#13; The LDP distributes documents, however, the author maintains the
copyright on the document. All documents accepted by the LDP must
contain a license and copyright notice. You can read more about this
in <A
HREF="#doc-copyright"
>Section 6.2.1</A
>.
You may also want to add a Disclaimer, but this is optional. More
about this in <A
HREF="#doc-disclaimer"
>Section 6.2.2</A
>.
</P
></DD
><DT
>Validate the Markup</DT
><DD
><P
>&#13; If you are submitting a DocBook or LinuxDoc document, make sure the
markup is valid. Read why in <A
HREF="#why-validate"
>Section B.3.1</A
>.
</P
></DD
><DT
>Obtain Peer Reviews</DT
><DD
><P
>&#13; You may want to have others review your document before
submitting it to the LDP. Ask people for a <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/peerreview.html"
TARGET="_top"
>Peer
Review</A
> and/or a <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html"
TARGET="_top"
>Technical
Accuracy Review</A
>. Since not all mailing lists will respond favorably
to attachments, you may wish to set up a temporary web site which houses your
document. Note: this is absolutely <EM
>not</EM
> required.
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="doc-licensing"
></A
>6.2. Licensing and Copyright</H1
><P
> In order for a document to be accepted by the LDP,
it must be licensed and conform to the <SPAN
CLASS="QUOTE"
>"LICENSE
REQUIREMENTS"</SPAN
> section of the LDP Manifesto located at <A
HREF="http://www.tldp.org/manifesto.html"
TARGET="_top"
>http://www.tldp.org/manifesto.html</A
>.
</P
><P
> We recommend using the <A
HREF="http://www.gnu.org/copyleft/fdl.html"
TARGET="_top"
>GNU Free Documentation
License (GFDL)</A
>, one of the <A
HREF="http://www.creativecommons.org/license"
TARGET="_top"
>Creative Commons
Licenses</A
> (<A
HREF="http://creativecommons.org/licenses/sa/1.0/"
TARGET="_top"
>Share-Alike</A
>, or <A
HREF="http://creativecommons.org/licenses/by-sa/2.0/"
TARGET="_top"
>Attribution-Share-Alike</A
>), or the LDP license (currently under review). The full text of the license must be included in your document, including the title and version of the license you are using. The LDP will not accept new documents that do not meet licensing requirements.</P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Debian-compatible licenses</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>The Debian package maintainer for LDP documents has divided the LDP documents into those with a <SPAN
CLASS="QUOTE"
>"free"</SPAN
> license and those with a <SPAN
CLASS="QUOTE"
>"non-free"</SPAN
> license. For a summary of this list, please read <A
HREF="http://www.debian.org/legal/licenses/byname"
TARGET="_top"
>Debian License Summaries</A
>. Currently the Artistic License, BSD License and the GNU General Public License are listed as <SPAN
CLASS="QUOTE"
>"free"</SPAN
>. These licenses will also be accepted by the LDP. The definition of <SPAN
CLASS="QUOTE"
>"non-free"</SPAN
> has not been made transparent. By choosing another license that has any kind of restriction on redistribution or whether or not the document may be modified, your document <EM
>may</EM
> be put into the <SPAN
CLASS="QUOTE"
>"non-free"</SPAN
> package instead of the <SPAN
CLASS="QUOTE"
>"free"</SPAN
> package. We are working with Debian to clarify how these decisions are made.</P
></TD
></TR
></TABLE
></DIV
><P
>You can get DocBook markups of both the GNU GPL and the GNU FDL from <A
HREF="http://developer.gnome.org/projects/gdp/licenses.html"
TARGET="_top"
> the GNOME Documentation Project</A
>. You can then merely include the license in its entirety in your document. A DocBook-formatted copy of the license is available in <A
HREF="#templates"
>Appendix A</A
>.
</P
><P
>&#13; For more information about open source documentation and
licensing, please check .
</P
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="doc-copyright"
></A
>6.2.1. Copyright</H2
><P
>As an author, you may retain the copyright and add other
restrictions (for example: require approval for any translations or
derivative works). If you are a new
maintainer of an already-existing HOWTO, you must include the
previous copyright statements of the previous author(s) and the
dates they maintained that document. </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="doc-disclaimer"
></A
>6.2.2. Disclaimer</H2
><P
>If you would like to include a disclaimer, you may choose
to use the following:</P
><A
NAME="AEN689"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
>
No liability for the contents of this document can be accepted.
Use the concepts, examples and information at your own risk.
There may be errors and inaccuracies, that could be damaging
to your system. Proceed with caution, and although it is highly
unlikely that accidents will happen because of following advice
or procedures described in this document, the author(s) do not
take any responsibility for any damage claimed to be caused by
doing so.
</P
><P
>&#13;All copyrights are held by their by their respective owners,
unless specifically noted otherwise. Use of a term in this
document should not be regarded as affecting the validity of
any trademark or service mark. Naming of particular products or
brands should not be seen as endorsements.
</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="doc-sourcecode"
></A
>6.2.3. Licensing source code</H2
><P
>If your HOWTO includes bits of source code that you want others to use,
you may choose to release the source code under GPL.</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="crediting-ack"
></A
>6.3. Acknowledgments</H1
><P
>Your document should have an <SPAN
CLASS="QUOTE"
>"Acknowledgments"</SPAN
> section,
in which you mention everyone who has contributed to your document in
any meaningful way. You should include translators and converters, as well as
people who have sent you lots of good feedback, perhaps the person who taught
you the knowledge you are now passing on, and anybody else who was instrumental
in making the document what it is. Most authors put this section at the end
of their document.
</P
><P
>When someone else assists in the production of an
LDP document,
you should give them proper attribution, and there are DocBook tags
designed to do this. This section will show you the tags you should
use, as well as other ways of giving credit where credit is due.
Crediting editors is easy - there is already an
<TT
CLASS="sgmltag"
>&#60;editor&#62;</TT
>tag in DocBook.
But there are two special cases where you need to credit someone,
but DocBook doesn't provide a special tag. These are <EM
>translators</EM
>
and <EM
>converters</EM
>.</P
><P
>A <EM
>converter</EM
> is someone
who performs a source code conversion, for instance from HTML to DocBook XML.
Source code conversions help the LDP achieve long term goals for meta-data,
and allow us to distribute documentation in many different formats.</P
><P
>Translators take your original document and translate it into other
human-readable languages, from English to Japanese for example, or from German
to English. Each translation allows many more people all over the world
to make use of your document and of the Linux operating system!</P
><P
>&#13; We recommend that
you acknowledge converters in the comment for the
initial version released in the new format, and
we recommend that you credit translators in each
version which they have translated.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Acknowledgments translated in DocBook</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>For more information on how to add these credits using DocBook
please read <A
HREF="#metadata-markup"
>Section D.6</A
>
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="ag-review"
></A
>6.4. TLDP Review Process</H1
><P
>&#13; Before your document is accepted to the LDP collection it will undergo
at least three formal reviews. These reviews include a <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html"
TARGET="_top"
>technical accuracy
review</A
>, a <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/languagereview.html"
TARGET="_top"
>language
review</A
> and a <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/metadatareview.html"
TARGET="_top"
>metadata
review</A
>. All new documents must pass these reviews
before being accepted into the collection.
</P
><P
>&#13; When you feel your document is finished, email a copy to the submit
mailing list (<TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
>). Please include the title of your document and
<SPAN
CLASS="QUOTE"
>"Final Review Required"</SPAN
> in the subject line of your email.
A team of volunteers will be assigned to your document for each of the
reviews. It may take up to a week to gather a team who is qualified to review your document.
Typically the technical review happens first, followed by the language
review and finally the metadata review. Your reviewers will read your document give you feedback on
whether or not they think your document is ready for publication in the
LDP collection.
</P
><P
>&#13; Your reviewers may have specific points that must be changed. Once you
have made the changes submit your document back to your review team.
They will review the document again and advise you on whether or not
your document is ready for inclusion in the LDP collection. You may
need to undergo several edits before your document is ready. Or it may
not require any additional work. Be prepared to make at least one round
of changes for both the technical and language reviews. Ideally this
exchange will happen in the LDP's <A
HREF="http://cvs.tldp.org"
TARGET="_top"
>CVS</A
> to better track each of the
changes that are made, and keep track of the most current version of
your document.
</P
><P
>&#13; Once your document has passed both the technical and language reviews,
you may submit it by following the instructions in <A
HREF="#submission"
>Section 6.5</A
>.
</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Comparing Two Source Files</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Your reviewer may make changes directly to your source file, or they may put their suggestions in a separate email. If they are working with the source file directly, and your document is using DocBook XML, you may find <SPAN
CLASS="application"
>XMLdiff</SPAN
> useful to see the changes that your reviewer has made to your source file. It is a python tool that figures out the differences between two similar XML files, in the same way the <SPAN
CLASS="application"
>diff</SPAN
> utility compares text files.</P
><P
>XMLdiff is available from <A
HREF="http://www.logilab.org/projects/xmldiff"
TARGET="_top"
>http://www.logilab.org/projects/xmldiff</A
>.</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; For more information on what the reviewers will be looking for, please
read the <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/index.html"
TARGET="_top"
>Linux Documentation Project Reviewer HOWTO</A
>.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="submission"
></A
>6.5. Submission to LDP for publication</H1
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>The final step</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; This section contains information on what to do after your
document has received both a technical and language review by the
LDP volunteers.
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; As part of the review process a Review Coordinator will add your
document to the CVS (including any associated image files) and
notify the submit mailing list that your document is ready for
publication.
</P
><P
>&#13; If you do not already have a CVS account, please apply for one
when your document is submitted for publication. You can apply
for an account contacting LDP CVS master Sergiusz <A
HREF="mailto:ser@gnu.org"
TARGET="_top"
>mailto:ser@gnu.org</A
>
</P
></DIV
></DIV
><DIV
CLASS="chapter"
><HR><H1
><A
NAME="sg-maintaining"
></A
>Chapter 7. Maintenance</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="sg-maintaining-support"
></A
>7.1. Maintaining Your Document</H1
><P
>Just because your document has now been published does not mean your
job is done. Linux documentation needs regular maintenance to make sure it
is up to date, and to improve it in response to readers' ideas
and suggestions. TLDP is a living, growing body of knowledge,
not just a publish-and-forget-it static entity.</P
><P
>Add relevant mailing lists to your document where people
can get support. If you have the time, follow these
mailing lists yourself to stay up-to-date on the
latest information.</P
><P
>Put your email address in the document, and politely request
feedback from your readers. Once you are officially published,
you will begin to receive notes with suggestions.
Some of these emails will be very valuable. Create a
folder in your mail program for
incoming suggestions--when the time is right review
the folder and make updates to your document. If you
are following a related mailing list you may also
choose to save a copy of important emails from the list to
this folder.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>We are not a free support service, but...</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; Some people who email you will request personal
assistance. You should feel free to decline personal
assistance if you cannot spare the time. Writing a
contribution to the LDP does not commit you to a lifetime
of free support for anyone on the net; however, do try
to reply to all requests and suggest a mailing list that
will (hopefully) be able to provide support to your reader.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="fixingerrors"
></A
>7.2. Fixing Errors</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="fix-own"
></A
>7.2.1. Fixing Your Own Documents</H2
><P
>If you find an error in your own document, please fix it and re-submit the document. You can re-submit your files by emailing them to <TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
>. </P
><P
>If you have been using the CVS, you can submit your changes to the CVS tree and then send a note to the submit mailing list (<TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
>). In your email please give the exact path of your document in the CVS tree.</P
><P
>Remember to update the revision history at the top of the document.</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="fix-other"
></A
>7.2.2. Fixing Other Documents in the Collection</H2
><P
>If you find an error in someone else's document please contact the author of the document with the correction. If you do not hear back from the author within a <SPAN
CLASS="QUOTE"
>"reasonable"</SPAN
> amount of time, please email the LDP coordinator at <TT
CLASS="email"
>&#60;<A
HREF="mailto:discuss@en.tldp.org"
>discuss@en.tldp.org</A
>&#62;</TT
> (<A
HREF="http://tldp.org/mailinfo.html#maillists"
TARGET="_top"
>subscription required</A
>) and describe the problem and how you think it needs to be fixed. If the license permits, you may be asked to make the change directly to the document. If the problems are serious, the document may be removed from the collection, or moved to the <SPAN
CLASS="QUOTE"
>"Unmaintained"</SPAN
> section.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Taking over unmaintained documentation</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>For more information on how to deal with unmaintained documents, please read: <A
HREF="http://www.tldp.org/authors/unmaint.html"
TARGET="_top"
>Unmaintained</A
> (includes a list of steps to take to take over <SPAN
CLASS="QUOTE"
>"ownership"</SPAN
> of unmaintained documents, and a list of unmaintained documents).</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
></DIV
><A
NAME="bibliography"
></A
><HR><H1
><A
NAME="bibliography"
></A
>References</H1
><H2
CLASS="bibliodiv"
><A
NAME="ref-markup"
></A
>Markup and general information</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN776"
></A
><P
><I
>Secret Life of Markup, The</I
>, <A
HREF="http://hotwired.lycos.com/webmonkey/02/42/index4a.html"
TARGET="_top"
>http://hotwired.lycos.com/webmonkey/02/42/index4a.html</A
>, <SPAN
CLASS="AUTHOR"
>Steve Champeon</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN783"
></A
><P
><I
>Progressive Enhancement and the Future of Web Design</I
><I
>: </I
><I
>&#13; Where We Are Now
</I
>, <A
HREF="http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html"
TARGET="_top"
>http://hotwired.lycos.com/webmonkey/03/21/index3a_page2.html</A
>, <SPAN
CLASS="AUTHOR"
>Steve Champeon</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN791"
></A
><P
><I
>SGML</I
>, <A
HREF="http://www.w3.org/MarkUp/SGML/"
TARGET="_top"
>http://www.w3.org/MarkUp/SGML/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-docbook"
></A
>DocBook References</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN797"
></A
><P
><I
>DocBook XML 4.1.2 Quick Start Guide</I
>, <A
HREF="http://www.jimweller.net/jim/dbxmlqs/index.html"
TARGET="_top"
>http://www.jimweller.net/jim/dbxmlqs/index.html</A
>, <SPAN
CLASS="AUTHOR"
>Jim Weller</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>&#13; <A
NAME="AEN806"
></A
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="BLOCKQUOTE"
><TR
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
><TD
WIDTH="80%"
VALIGN="TOP"
><P
>Describes how to install, configure and use the tools and resources for
DocBook XML 4.1.2. The purpose of this quick start guide is to get new
docbook authors, editors, and contributors up and running fast with the
DoocBook tools. These are powerful tool in the hands of an author. It
assumes a fair knowledge of building and installing source packages.
There are probably a million and one ways to accomplish my ultimate
goal of installing and using these tools. This one works well for
me.
</P
></TD
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="RIGHT"
VALIGN="TOP"
>--<SPAN
CLASS="attribution"
>Jim Weller</SPAN
></TD
><TD
WIDTH="10%"
>&nbsp;</TD
></TR
></TABLE
>
</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN809"
></A
><P
><I
>&#13;Installing And Using An XML/SGML DocBook Editing Suite
Setting Up A Free XML/SGML DocBook Editing Suite For Windows And
Unix/Linux/BSD</I
>, <A
HREF="http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksys.html"
TARGET="_top"
>http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/docbooksys/docbooksys.html</A
>
, <SPAN
CLASS="AUTHOR"
>Ashley J.S. Mills</SPAN
>, 2002.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN819"
></A
><P
><I
>&#13;Getting Upto Speed With DocBook</I
>, <A
HREF="http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/UniDocBook/UniDocBook.html"
TARGET="_top"
>http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/UniDocBook/UniDocBook.html</A
>, <SPAN
CLASS="AUTHOR"
>Ashley J.S. Mills</SPAN
>, 2002.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN829"
></A
><P
><I
>DocBook: The Definitive Guide</I
>, <A
HREF="http://www.docbook.org/"
TARGET="_top"
>http://www.docbook.org/</A
>, <SPAN
CLASS="AUTHOR"
>Norman Walsh</SPAN
>, <SPAN
CLASS="AUTHOR"
>Leonard Muellner</SPAN
>, 1999, 1-56592-580-7, O'Reilly &#38; Associates, Inc..</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>This book was released by O'Reilly in October 1999, and
is a great reference to DocBook. I have not found it to be a
great practical book. You can pick it up at the book vendor of
choice, and the entire book is also available online (in HTML and SGML
formats) at the above URL. </P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN847"
></A
><P
><I
>Simplified DocBook: The Definitive Guide</I
>, <A
HREF="http://www.docbook.org/tdg/simple/en/html/sdocbook.html"
TARGET="_top"
>http://www.docbook.org/tdg/simple/en/html/sdocbook.html</A
>, <SPAN
CLASS="AUTHOR"
>Norman Walsh</SPAN
>, <SPAN
CLASS="AUTHOR"
>Leonard Muellner</SPAN
>, 1999.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN860"
></A
><P
><I
>Simplified DocBook</I
>, <A
HREF="http://www.oasis-open.org/docbook/xml/simple/"
TARGET="_top"
>http://www.oasis-open.org/docbook/xml/simple/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN864"
></A
><P
><I
>XML Matters: Getting started with the DocBook XML
dialect</I
>, <A
HREF="http://www-106.ibm.com/developerworks/xml/library/xml-matters3.html"
TARGET="_top"
>http://www-106.ibm.com/developerworks/xml/library/xml-matters3.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN868"
></A
><P
><I
>FAQ for DocBook markup</I
>, <A
HREF="http://www.dpawson.co.uk/docbook/markup.html"
TARGET="_top"
>http://www.dpawson.co.uk/docbook/markup.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN872"
></A
><P
><I
>Single-Source Publishing with DocBook XML</I
>, , <A
HREF=" http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/frames.html"
TARGET="_top"
> http://www.lodestar2.com/people/dyork/talks/2002/ols/docbook-tutorial/frames/frames.html</A
>, <SPAN
CLASS="AUTHOR"
>Dan York</SPAN
>, 2002.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN883"
></A
><P
><I
>&#13; DocBook Install mini-HOWTO</I
>, <A
HREF="http://tldp.org/HOWTO/mini/DocBook-Install/"
TARGET="_top"
>http://tldp.org/HOWTO/mini/DocBook-Install/</A
>, <SPAN
CLASS="AUTHOR"
>Robert Easter</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN890"
></A
><P
><I
>Exploring SGML DocBook</I
>, <A
HREF="http://lwn.net/2000/features/DocBook/"
TARGET="_top"
>http://lwn.net/2000/features/DocBook/</A
>, <SPAN
CLASS="AUTHOR"
>Giorgio Zoppi</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-linuxdoc"
></A
>LinuxDoc</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN899"
></A
><P
><I
>Howtos-with-LinuxDoc-mini-HOWTO</I
>, <A
HREF="http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html"
TARGET="_top"
>http://www.tldp.org/HOWTO/Howtos-with-LinuxDoc.html</A
>, <SPAN
CLASS="AUTHOR"
>David Lawyer</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN906"
></A
><P
><I
>LinuxDoc-SGML User's Guide</I
>, <A
HREF="http://www.nmt.edu/tcc/doc/guide.html"
TARGET="_top"
>http://www.nmt.edu/tcc/doc/guide.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-x2docbook"
></A
>Converting Other Formats to DocBook</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN912"
></A
><P
><I
>&#13;Converting HTML to Docbook SGML/XML Using html2db</I
>, <A
HREF="http://www.cise.ufl.edu/~ppadala/tidy/"
TARGET="_top"
>http://www.cise.ufl.edu/~ppadala/tidy/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN916"
></A
><P
><I
>5-Minute Review: Using LyX for Creating DocBook</I
>, <A
HREF="http://www.teledyn.com/help/XML/lyx2db/t1.html"
TARGET="_top"
>http://www.teledyn.com/help/XML/lyx2db/t1.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN920"
></A
><P
><I
>Document processing with LyX and SGML</I
>, <A
HREF="http://www.karakas-online.de/mySGML/"
TARGET="_top"
>http://www.karakas-online.de/mySGML/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-templates"
></A
>LDP templates, tools &#38; links</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN926"
></A
><P
><I
>LDP Templates</I
>, , <A
HREF="http://www.tldp.org/authors/index.html#resources"
TARGET="_top"
>http://www.tldp.org/authors/index.html#resources</A
>
.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>Contains links to SGML templates and their resulting HTML output
to help you see what your document will look like. Many of the tags
just need to be replaced with information unique to your HOWTO.
Also contains links to tools and other useful information.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN933"
></A
><P
><I
>Linux Documentation Project HOWTO Generator, The</I
>, <A
HREF="http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html"
TARGET="_top"
>http://www.nyx.net/~sgjoen/The_LDP_HOWTO_Generator.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>&#13;This is a standalone web page with a number of fields to fill in
and a few buttons. When ready the compile button starts the
compilation of all the input fields and wraps it all in proper
LinuxDoc SGML, ready to process with the LinuxDoc SGML tools.
</P
><P
>&#13;The compiled output is outputted to a read-only text area near
the bottom of the webpage, so the text has to be copied and
pasted into a file for compilation.
</P
><P
>&#13;DocBook is not currently supported.
</P
></DIV
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-transform"
></A
>DocBook Transformations</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN943"
></A
><P
><I
>DocBook XML/SGML Processing Using OpenJade</I
>, , <A
HREF="http://tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/"
TARGET="_top"
>http://tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/</A
>, <SPAN
CLASS="AUTHOR"
>Saqib Ali</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-techwriting"
></A
>General Writing Links and Style Guides</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN953"
></A
><P
><I
>&#13;Guide to Grammar and Style</I
>, <A
HREF="http://newark.rutgers.edu/~jlynch/Writing/"
TARGET="_top"
>http://newark.rutgers.edu/~jlynch/Writing/</A
>, <SPAN
CLASS="AUTHOR"
>Jack Lynch</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN960"
></A
><P
><I
>Purdue's Online Writing Lab</I
>, <A
HREF="http://owl.english.purdue.edu/"
TARGET="_top"
>http://owl.english.purdue.edu/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN964"
></A
><P
><I
>&#13;Chicago Manual of Style</I
>, <A
HREF="http://www.chicagomanualofstyle.org/"
TARGET="_top"
>http://www.chicagomanualofstyle.org/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN968"
></A
><P
><I
>&#13;Plain Language Resources</I
>, <A
HREF="http://www.plainlanguagenetwork.org/Resources/"
TARGET="_top"
>http://www.plainlanguagenetwork.org/Resources/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN972"
></A
><P
><I
>Writing User-Friendly Documents</I
>, <A
HREF="http://www.blm.gov/nhp/NPR/pe_toc.html"
TARGET="_top"
>http://www.blm.gov/nhp/NPR/pe_toc.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>&#13; This is quite useful. It includes before and after writing samples.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN978"
></A
><P
><I
>PlainTrain Writing Tutorial</I
>, <A
HREF="http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html"
TARGET="_top"
>http://www.web.net/~plain/PlainTrain/IntroducingPlainLanguage.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN982"
></A
><P
><I
>Writing for the Web</I
>, <A
HREF="http://www.useit.com/papers/webwriting/"
TARGET="_top"
>http://www.useit.com/papers/webwriting/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN986"
></A
><P
><I
>Information Pollution</I
>, <A
HREF="http://useit.com/alertbox/20030811.html"
TARGET="_top"
>http://useit.com/alertbox/20030811.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN990"
></A
><P
><I
>Be Succinct! (Writing for the Web)</I
>, <A
HREF="http://useit.com/alertbox/9703b.html"
TARGET="_top"
>http://useit.com/alertbox/9703b.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN994"
></A
><P
><I
>Politics and the English Language</I
>, <A
HREF="http://www.k-1.com/Orwell/index.cgi/work/essays/language.html"
TARGET="_top"
>http://www.k-1.com/Orwell/index.cgi/work/essays/language.html</A
>, <SPAN
CLASS="AUTHOR"
>George Orwell</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>A classic text on writing.</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1003"
></A
><P
><I
>Elements of Style, The</I
>, <A
HREF="http://www.bartleby.com/141/"
TARGET="_top"
>http://www.bartleby.com/141/</A
>, <SPAN
CLASS="AUTHOR"
> Strunk and White</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>A classic text on writing.</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1012"
></A
><P
><I
>A Short Handbook and Style Sheet</I
>, <A
HREF="http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics"
TARGET="_top"
>http://newark.rutgers.edu/~jlynch/Writing/m.html#mechanics</A
>, <SPAN
CLASS="AUTHOR"
>Thomas Pinney</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1019"
></A
><P
><I
>Technical Writing Links</I
>, <A
HREF="http://www.techcomplus.com/tips.htm"
TARGET="_top"
>http://www.techcomplus.com/tips.htm</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1023"
></A
><P
><I
>&#13;Technical Writing Tutorial</I
>, <A
HREF="http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html"
TARGET="_top"
>http://psdam.mit.edu/rise/tutorials/writing/technical-writing.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1027"
></A
><P
><I
>&#13;Strategies to succeed in technical writing</I
>, <A
HREF="http://www.school-for-champions.com/techwriting.htm"
TARGET="_top"
>http://www.school-for-champions.com/techwriting.htm</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1031"
></A
><P
><I
>&#13;User Guides Online Tutorial</I
>, <A
HREF="http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml"
TARGET="_top"
>http://www.klariti.com/technical-writing/User-Guides-Tutorial.shtml</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1035"
></A
><P
><I
>&#13;DMOZ Technical Writing Links</I
>, <A
HREF="http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing/"
TARGET="_top"
>http://dmoz.org/Arts/Writers_Resources/Non-Fiction/Technical_Writing/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1039"
></A
><P
><I
>&#13;techwr-L</I
>, <A
HREF="http://www.raycomm.com/techwhirl/magazine/"
TARGET="_top"
>http://www.raycomm.com/techwhirl/magazine/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1043"
></A
><P
><I
>Technical Writing Links</I
>, <A
HREF="http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html"
TARGET="_top"
>http://academic.middlesex.cc.ma.us/PeterHarbeson/links.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>&#13;An omnibus of links--scrounge for goodies.
</P
></DIV
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-relatedtldp"
></A
>Related TLDP Documents</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN1051"
></A
><P
><I
>&#13;Linux Documentation Project (LDP) FAQ</I
>, <A
HREF="http://tldp.org/FAQ/LDP-FAQ/index.html"
TARGET="_top"
>http://tldp.org/FAQ/LDP-FAQ/index.html</A
>, <SPAN
CLASS="AUTHOR"
>Rahul Sundaram</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1058"
></A
><P
><I
>LDP HOWTO-INDEX</I
>, <A
HREF="http://tldp.org/HOWTO/HOWTO-INDEX/"
TARGET="_top"
>http://tldp.org/HOWTO/HOWTO-INDEX/</A
>, <SPAN
CLASS="AUTHOR"
>Guylhem Aznar</SPAN
>, <SPAN
CLASS="AUTHOR"
>Joshua Drake</SPAN
>, <SPAN
CLASS="AUTHOR"
>Greg Ferguson</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-cvs"
></A
>Software: CVS</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN1073"
></A
><P
><I
>CVS: Project Management</I
>, <A
HREF="http://doc.cs.byu.edu/programming/cvs/"
TARGET="_top"
>http://doc.cs.byu.edu/programming/cvs/</A
>, <SPAN
CLASS="AUTHOR"
>Byron Clark</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1080"
></A
><P
><I
>CVS</I
>, <A
HREF="http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/cvstute/cvstute.html"
TARGET="_top"
>http://supportweb.cs.bham.ac.uk/documentation/tutorials/docsystem/build/tutorials/cvstute/cvstute.html</A
>, <SPAN
CLASS="AUTHOR"
>Ashley J.S. Mills</SPAN
>, <SPAN
CLASS="AUTHOR"
>Alan P. Sexton</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1090"
></A
><P
><I
>CVS--Concurrent Versions System</I
>, <A
HREF="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html"
TARGET="_top"
>http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</A
>, <SPAN
CLASS="AUTHOR"
>Pascal Molli</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1097"
></A
><P
><I
>Learning About CVS </I
>, <A
HREF="http://cvshome.org/docs/"
TARGET="_top"
>http://cvshome.org/docs/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-software-edit"
></A
>Software: Emacs</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN1103"
></A
><P
><I
>Information about PSGML </I
>, <A
HREF="http://www.lysator.liu.se/~lenst/about_psgml/"
TARGET="_top"
>http://www.lysator.liu.se/~lenst/about_psgml/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1107"
></A
><P
><I
>Emacs: The Free Software IDE</I
>, <A
HREF="http://www.linuxjournal.com/article.php?sid=576"
TARGET="_top"
>http://www.linuxjournal.com/article.php?sid=576</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1111"
></A
><P
><I
>Emacs/PSGML Quick Reference</I
>, <A
HREF="http://www.snee.com/bob/sgmlfree/psgmqref.html"
TARGET="_top"
>http://www.snee.com/bob/sgmlfree/psgmqref.html</A
>, <SPAN
CLASS="AUTHOR"
>Bob Ducharme</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1118"
></A
><P
><I
>NT Emacs Installation</I
>, <A
HREF="http://www.charlescurley.com/emacs.html"
TARGET="_top"
>http://www.charlescurley.com/emacs.html</A
>, <SPAN
CLASS="AUTHOR"
>Charles Curley</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1125"
></A
><P
><I
>Cygwin Packages for DocBook Authoring</I
>, <A
HREF="http://www.docbook.org/wiki/moin.cgi/CygwinPackages/"
TARGET="_top"
>http://www.docbook.org/wiki/moin.cgi/CygwinPackages/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1129"
></A
><P
><I
>SGML for Windows NT</I
><I
>: </I
><I
>&#13; Setting up a free SGML/XML editing and publishing system on
Windows/Cygwin
</I
>, <A
HREF="http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.html"
TARGET="_top"
>http://ourworld.compuserve.com/homepages/hoenicka_markus/cygbook1.html</A
>, <SPAN
CLASS="AUTHOR"
>Markus Hoenicka</SPAN
>, 2000.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1140"
></A
><P
><I
>Vim</I
>, <A
HREF="http://www.newriders.com/books/opl/ebooks/0735710015.html"
TARGET="_top"
>http://www.newriders.com/books/opl/ebooks/0735710015.html</A
>, <SPAN
CLASS="AUTHOR"
>Steve Oualline</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-xml"
></A
>XML Authoring Tools</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN1149"
></A
><P
><I
>Saqib's list of XML Authoring Tools</I
>, <A
HREF="http://www.xml-dev.com/xml/editors.html"
TARGET="_top"
>http://www.xml-dev.com/xml/editors.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><HR><H2
CLASS="bibliodiv"
><A
NAME="ref-licenses"
></A
>Documentation Licenses</H2
><DIV
CLASS="biblioentry"
><A
NAME="AEN1155"
></A
><P
><I
>Licensing HOWTO</I
>, <A
HREF="http://www.catb.org/~esr/Licensing-HOWTO.html"
TARGET="_top"
>http://www.catb.org/~esr/Licensing-HOWTO.html</A
>, <SPAN
CLASS="AUTHOR"
>Eric Raymond</SPAN
>, <SPAN
CLASS="AUTHOR"
>Catherine Raymond</SPAN
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
><A
NAME="AEN1167"
></A
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="BLOCKQUOTE"
><TR
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
><TD
WIDTH="80%"
VALIGN="TOP"
><P
>&#13;This document explains how U.S. copyright and licensing law applies to
open-source software projects. It compares the strengths and weaknesses of
the existing open-source licenses, and gives guidance on how to choose a
license for your project. It also explains the legalities of changing a
project's license. It suggests new practice for coping with today's
high-threat legal environment--this part is a must-read for all
project leaders.
</P
></TD
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="RIGHT"
VALIGN="TOP"
>--<SPAN
CLASS="attribution"
>Eric Raymond and Catherine Raymond</SPAN
></TD
><TD
WIDTH="10%"
>&nbsp;</TD
></TR
></TABLE
></P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1170"
></A
><P
><I
>OPL</I
>, <A
HREF="http://www.opencontent.org/openpub/"
TARGET="_top"
>http://www.opencontent.org/openpub/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>OpenContent officially closed June 30, 2003.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1176"
></A
><P
><I
>Creative Commons</I
>, <A
HREF="http://creativecommons.org/licenses/by-sa/1.0/"
TARGET="_top"
>http://creativecommons.org/licenses/by-sa/1.0/</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1180"
></A
><P
><I
>GNU Free Documentation License</I
>, <A
HREF="http://www.gnu.org/copyleft/fdl.html"
TARGET="_top"
>http://www.gnu.org/copyleft/fdl.html</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
></DIV
></DIV
><DIV
CLASS="biblioentry"
><A
NAME="AEN1184"
></A
><P
><I
>GNU General Public License</I
>, <A
HREF="http://www.gnu.org/licenses/licenses.html#GPL"
TARGET="_top"
>http://www.gnu.org/licenses/licenses.html#GPL</A
>.</P
><DIV
CLASS="BIBLIOENTRYBLOCK"
STYLE="margin-left: 0.5in"
><DIV
CLASS="abstract"
><P
>&#13; If you would like your documents to be included in the main Debian
distribution, you should use this license. It is not, however, the
LDP's license of choice.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="templates"
></A
>Appendix A. Templates</H1
><P
>&#13; The LDP stores its documents in the following markup languages:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>&#13; DocBook XML version 4.2 (preferred), 4.1.2
</P
></LI
><LI
><P
>&#13; DocBook SGML version 4.2, 4.1, or 3.x
</P
></LI
><LI
><P
>&#13; LinuxDoc SGML
</P
></LI
></OL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>New Documents</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; A new document may be submitted to the LDP in any format. Documents
which are not in DocBook or LinuxDoc will be converted by a volunteer.
The author is responsible for adding markup to any revisions which are
made.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="templates-book"
></A
>A.1. Document Templates</H1
><P
></P
><OL
TYPE="1"
><LI
><DIV
CLASS="formalpara"
><P
><B
>HOWTO (Article) <A
HREF="templates/ldp-howto.zip"
TARGET="_top"
>templates/ldp-howto.zip</A
>. </B
>
Most HOWTO documents will use this template.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Guide (Book) <A
HREF="templates/ldp-guide.zip"
TARGET="_top"
>templates/ldp-guide.zip</A
>. </B
>
Use this template to create a full book (like this Author Guide,
for instance). Templates provided by Tille Garrels.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>FAQ <A
HREF="templates/ldp-faq.zip"
TARGET="_top"
>templates/ldp-faq.zip</A
>. </B
>A standard article for writing a FAQ (Frequently Asked Questions) list.</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>LinuxDoc<A
HREF="templates/ldp-linuxdoc.zip"
TARGET="_top"
>templates/ldp-linuxdoc.zip</A
>. </B
>A standard template both in HOWTO length and Guide length.</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Disclaimer <A
HREF="disclaimer.xml"
TARGET="_top"
>disclaimer.xml</A
>. </B
>
A standard disclaimer which warns readers that (1) your document may
not be perfect and (2) you are not responsible if things end up
broken because of it.
</P
></DIV
></LI
></OL
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="templates-style"
></A
>A.2. Style Sheets</H1
><P
>&#13; The following style sheets can be used to make your document nicer to
look at. Remember that the LDP will use its own style sheets to
distribute your documentation.
</P
><P
></P
><OL
TYPE="1"
><LI
><DIV
CLASS="formalpara"
><P
><B
>DSL Style Sheet <A
HREF="style.dsl"
TARGET="_top"
>style.dsl</A
>. </B
>
This DSL style sheet was provided by Tille and is to be used with DSSSL
transformations.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>Cascading Style Sheet <A
HREF="style-ob.css"
TARGET="_top"
>style-ob.css</A
>. </B
>
This CSS file was provided by Saqib Ali and Emma Jane Hogbin. The
<SPAN
CLASS="QUOTE"
>"ob"</SPAN
> is for <SPAN
CLASS="QUOTE"
>"orange and blue"</SPAN
>. Use this CSS
file with an HTML file. Instructions are included in the CSS file.
</P
></DIV
></LI
></OL
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="templates-gdfl"
></A
>A.3. GNU Free Documentation License</H1
><P
>&#13; The GFDL (GNU Free Documentation License) is available in XML format
at <A
HREF="http://www.gnu.org/licenses/fdl.xml"
TARGET="_top"
>http://www.gnu.org/licenses/fdl.xml</A
>. For a version in appendix format suitable for including
in your document, you can see get the XML for this document
from CVS at <A
HREF="http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/fdl-appendix.xml"
TARGET="_top"
>http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/fdl-appendix.xml</A
>.
</P
><P
>&#13; TLDP template files for DocBook (XML and SGML) and Linuxdoc SGML are
available from the TLDP website at <A
HREF="http://www.tldp.org/authors/index.html#resources"
TARGET="_top"
>http://www.tldp.org/authors/index.html#resources</A
>.
</P
></DIV
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="tools"
></A
>Appendix B. System Setup: Editors, Validation and
Transformations</H1
><P
>In this section, we will cover some of the tools
that you may want to use to create your own LDP documentation.
If you use some other tool to assist you in writing
documents for the LDP, please drop us a line and we'll add
a blurb for it here. <A
HREF="#feedback"
>Section 1.3</A
> has contact
information.</P
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tools-distro"
></A
>B.1. Tools for your operating
system</H1
><P
>&#13; A few notes on setting up your system for DocBook
publishing. These tools focus more on the transformation
of documents from DocBook to XHTML (for example).
</P
><P
></P
><DIV
CLASS="variablelist"
><P
><B
>Tools For Your Operating System</B
></P
><DL
><DT
>Debian</DT
><DD
><P
>&#13; <A
HREF="http://www.docbook.org/wiki/moin.cgi/DebianGnuLinuxPackages"
TARGET="_top"
>&#13; http://www.docbook.org/wiki/moin.cgi/DebianGnuLinuxPackages
</A
>
</P
><P
>&#13; <A
HREF="http://www.surgo.net"
TARGET="_top"
>Morgon Kanter</A
>
suggests <B
CLASS="command"
>apt-get install docbook-xml
docbook-xsl xsltproc</B
> as the minimum requirements.
<A
HREF="http://lists.tldp.org/index.cgi?1:mss:4851"
TARGET="_top"
>http://lists.tldp.org/index.cgi?1:mss:4851</A
>
</P
></DD
><DT
>Fedora (aka the new
RedHat)</DT
><DD
><P
>&#13; Notes contributed by <A
HREF="http://www.charlescurley.com"
TARGET="_top"
>Charles
Curley</A
>.
</P
><P
>&#13; Tools for Docbook SGML and XML are included in the distrubution. So
are <SPAN
CLASS="application"
>Emacs</SPAN
> and <SPAN
CLASS="application"
>PSGML
mode</SPAN
>, although you will have to customize your
<TT
CLASS="filename"
>.emacs</TT
>. If you are missing a package after installing
Fedora, get familiar with <SPAN
CLASS="application"
>yum</SPAN
> or
<SPAN
CLASS="application"
>apt</SPAN
>.
</P
><P
> Installation instructions: none; use Red Hat 9
until they are written: <A
HREF="http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/"
TARGET="_top"
>http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/</A
>.
</P
></DD
><DT
>Mandrake</DT
><DD
><P
>&#13; Notes contributed by <A
HREF="http://www.artemio.net"
TARGET="_top"
>Artemio</A
>.
</P
><P
>&#13; In Mandrake (as of my current 9.2), all the
stuff including openjade, xmlto, docbook-utils
etc. comes as standard.
</P
><P
>&#13; So I just needed to get the TLDP XSL sheet and
that's all. Didn't ever have any dependency
or other problems, everything works fine (knock
on wood :-)).
</P
></DD
><DT
>RedHat</DT
><DD
><P
>&#13; According to Hal Burgiss, your system is likely
already ready to edit and process DocBook
documents without installing any additional
packages.
</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tools-edit"
></A
>B.2. Editing tools</H1
><P
>&#13; Editing tools have come a long way in their support for
XML (and specifically DocBook). There are two types of
editors outlined in this section: text editors (emacs,
vim, etc); and word processors (OpenOffice, AbiWord,
etc). New authors who are not comfortable working with
markup languages should probably choose a word processor
that can output DocBook files. For this reason the word
processors are listed first.
</P
><P
>&#13; Although many editors can also validate your DocBook
files, this information has been separated into <A
HREF="#tools-validate"
>Section B.3</A
>.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>More info</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; Check the resources section for more .
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="tools-word-processors"
></A
>B.2.1. Word Processors</H2
><P
>&#13; Even if you are not comfortable working DocBook's tagset
in a text editor you can still produce valid DocBook
documents using a word processor. Support at this point
is very limited, but it does exist in the following
programs. The up side, of course, is that things like
spell check are built in to the program. In addition to
this, support for DocBook (and XML) is constantly
improving.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Converting Microsoft Word documents</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; Even if you want to use MS Word to write your documents, you may
find <A
HREF="http://www.docsoft.com/w2xmlv2.htm"
TARGET="_top"
>w2XML</A
>
useful. Note that this is not free software--the cost is around $130USD.
There is, however, a trial version of the software.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Work on the content!</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; Remember that all formatting changes you make to your
document will be ignored when your document is released
by the LDP. Instead of focusing on how your document
<EM
>looks</EM
>, focus on the content.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="abiword"
></A
>B.2.1.1. AbiWord</H3
><P
>&#13; Through word of mouth I've heard that AbiWord can work (natively)
with DocBook documents. This will need to be tested by someone
(possibly me) and should definitely be included if it is
the case.
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="openoffice"
></A
>B.2.1.2. OpenOffice.org</H3
><P
>&#13; <A
HREF="http://openoffice.org"
TARGET="_top"
>http://openoffice.org</A
>
</P
><P
>&#13; As of OpenOffice.org (OOo) 1.1RC there has been support for
exporting files to DocBook format.
</P
><P
>&#13; Although OOo uses the full DocBook document type declaration,
it does not actually export the full list of DocBook elements. It
uses a <SPAN
CLASS="QUOTE"
>"simplified"</SPAN
> DocBook tagset which is geared
to on-the-fly rendering. (Although it is not the official
Simplified DocBook which is described in <A
HREF="#dtd"
>Section B.5</A
>.)
The OpenOffice simplified (or <SPAN
CLASS="QUOTE"
>"special"</SPAN
> docbook) is available from
<A
HREF="http://xml.openoffice.org/xmerge/docbook/supported_tag_table.html"
TARGET="_top"
>http://xml.openoffice.org/xmerge/docbook/supported_tag_table.html</A
>.
</P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="tools-ooo-1-0"
></A
>B.2.1.2.1. Open Office 1.0.x</H4
><P
>&#13; OOo has been tested by LDP volunteers with mostly positive
results. Thanks to Charles Curley
(<A
HREF="http://www.charlescurley.com"
TARGET="_top"
>charlescurley.com</A
>)
for the following notes on using OOo version 1.0.x:
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Check the version of your OpenOffice</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; These notes may not apply to the version of OOo you
are using.
</P
></TD
></TR
></TABLE
></DIV
><P
></P
><UL
><LI
><P
>&#13; To be able to export to DocBook, you must have a Java runtime
environment (JRE) installed and registered with OOo--a minimum of
version 4.2.x is recommended. The configuration instructions will
depend on how you installed your JRE. Visit the OOo web site for
help with your setup.
</P
><P
>&#13; Contrary to the OOo documentation, the Linux OOo did not come with
a JRE. I got one from Sun.
</P
></LI
><LI
><P
>&#13; The exported file has lots of empty lines. My 54 line exported
file
had 5 lines of actual XML code.
</P
></LI
><LI
><P
>&#13; There was no effort at pretty printing.
</P
></LI
><LI
><P
> The header is:
<TT
CLASS="computeroutput"
>&#13; &#60;?xml version="1.0" encoding="UTF-8"?&#62;
&#60;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"&#62;
</TT
>
</P
></LI
><LI
><P
> The pull-down menu in the <SPAN
CLASS="guimenu"
>File</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Save
As</SPAN
> dialog box for
file format
indicates that the export format is <SPAN
CLASS="QUOTE"
>"DocBook (simplified)."</SPAN
> There is
no explanation of what that <SPAN
CLASS="QUOTE"
>"simplified"</SPAN
> indicates. Does OOo export
a subset of DocBook? If so, which elements are ignored? Is there any
way to enter any of them manually?
</P
></LI
><LI
><P
> There is NO documentation on the DocBook export filter
or whether
OOo will import it again.
</P
></LI
></UL
><P
>&#13; Conclusions: OOo 1.1RC is worth looking at if you want a word
processor for preparing DocBook documents.
</P
><P
>&#13; However, I hope they cure the lack of documentation. For one
thing, it would be nice to know which native OOo styles map to
which DocBook elements. It would also be nice to know how to
map one's own OOo styles to DocBook elements.
</P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="tools-ooo-1-1"
></A
>B.2.1.2.2. Open Office 1.1</H4
><P
>&#13; <A
HREF="http://www.merlinmonroe.com"
TARGET="_top"
>Tabatha Marshall</A
>
offers the following additional information for OOo 1.1.
</P
><A
NAME="AEN1362"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
> The first problem was when I tried to do everything on version
1.0.1. That was
obviously a problem. I have RH8, and it was installed via rpm packages,
so I ripped it out and did a full, new install of OpenOffice 1.1.
It took a while to find out 1.1 was a requirement for XML to work.
</P
><P
>&#13;During the install process I believe I was offered the choice to install
the XML features. I have a tendency to do full installs of my office
programs, so I selected everything.
</P
><P
>&#13;I can't offer any advice to those trying to update their current
OO 1.1. Their <SPAN
CLASS="QUOTE"
>"3 ways"</SPAN
> aren't documented very well at the site
(<A
HREF="http://xml.openoffice.org"
TARGET="_top"
>xml.openoffice.org</A
>) and as of this writing, I can't even find THAT
on their site anymore. I think more current documentation is needed
there to walk people through the process. Most of this was unclear
and I had to pretty much experiment to get things working.
</P
><P
>&#13;Well, after I installed everything I had some configuration to do.
I opened the application, and got started by opening a new file,
choosing templates, then selecting the DocBook template. A nice menu
of <SPAN
CLASS="guisubmenu"
>Paragraph Styles</SPAN
> popped up for me, which are the names for all those
tags, I noticed (you can see I don't use WYSIWYG often).
</P
><P
>&#13; With a blank doc before me (couldn't get to the <SPAN
CLASS="guisubmenu"
>XML Filter
Settings</SPAN
> menu unless some type of doc was opened), I went into
<SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML
Filter Settings</SPAN
>, and edited the entry for DocBook file.
I configured mine as follows:
</P
><P
></P
><UL
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>Doctype</SPAN
>
<TT
CLASS="userinput"
><B
>-//OASIS//DTD DocBook XML V4.2//EN</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>DTD</SPAN
>
<TT
CLASS="userinput"
><B
>http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>XSLT for export</SPAN
>
<TT
CLASS="userinput"
><B
>/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>XSLT for import</SPAN
>
<TT
CLASS="userinput"
><B
>/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffheadings.xsl</B
></TT
>
(this is the default)
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>Template for import</SPAN
>
<TT
CLASS="userinput"
><B
>/home/tabatha/OpenOffice/user/template/DocBook
File/DocBookTemplate.stw</B
></TT
>
</P
></LI
></UL
><P
>&#13;At first, if I opened an XML file that had even one parsing error, it
would just open the file anyway and display the markup in OO. I have
many XML files that use &#38;copy; and other types of entities which show
up as parse errors (depending on the encoding) even though they can be
processed through. But today I was unable to open any of those files.
I got input/output errors instead. Still investigating that one.
</P
><P
>&#13;However when you do successfully open a document (one parsing with no
errors), it puts it automatically into WYSIWYG based on the markup,
and you can then work from the paragraph styles menu like any other
such editor.
</P
><P
>&#13;To validate the document, I used <SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML
Filter Settings</SPAN
>, then
clicked the <SPAN
CLASS="guibutton"
>Test XSLTs</SPAN
> button. On my screen, I set up the XSLT
for export to be <TT
CLASS="filename"
>ldp-html.xsl</TT
>. If you test and there are errors,
a new window pops up with error messages at the bottom, and the lines
that need to be changed up at the top. You can change them there and
progress through the errors until they're all gone, and keep testing
until they're gone.
</P
><P
>&#13;If you want to open a file to see the source instead of the processed
results, go to <SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML Filter
Settings</SPAN
>-&gt;<SPAN
CLASS="guisubmenu"
>Test XSLTs</SPAN
>, and then
under the <SPAN
CLASS="guimenu"
>Import</SPAN
> section, check the
<SPAN
CLASS="guilabel"
>Display Source</SPAN
> box. My import XSLT
is currently <TT
CLASS="filename"
>docbooktosoffheadings.xsl</TT
> (the default) and the template
for import is <TT
CLASS="filename"
>DocBookTemplate.stw</TT
> (also default).
</P
><P
>&#13;I think this might work for some people, but unfortunately not for me.
I've never used WYSIWYG to edit markup. <SPAN
CLASS="application"
>Emacs with
PSGML</SPAN
> can tell me
what my next tag is no matter where I am, validate by moving through
the trouble spots, and I can parse and process from command line.
</P
><P
>&#13;With OpenOffice, you have to visit <A
HREF="http://xml.openoffice.org/filters.html"
TARGET="_top"
>http://xml.openoffice.org/filters.html</A
>
to find conversion tools.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="wordperfect"
></A
>B.2.1.3. WordPerfect 9 (Corel
Office 2000)</H3
><P
>&#13; <A
HREF="http://www.corel.com/"
TARGET="_top"
>&#13; http://www.corel.com/</A
>
</P
><P
>&#13; WordPerfect 9 for the MS Windows platform has
support for SGML and DocBook 3.0. WordPerfect 9 for Linux has
no SGML capabilities.
</P
><P
>&#13; If you are using WordPerfect on the Linux operating system, please
read: <A
HREF="http://en.tldp.org/FAQ/WordPerfect-Linux-FAQ/"
TARGET="_top"
>WordPerfect on
Linux FAQ</A
>
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="XMLmind"
></A
>B.2.1.4. XMLmind's XML editor</H3
><P
>&#13; <A
HREF="http://www.xmlmind.com/xmleditor/"
TARGET="_top"
>http://www.xmlmind.com/xmleditor/</A
>
</P
><P
>&#13; Although strictly speaking, it is not a word processor,
XMLmind's <SPAN
CLASS="application"
>XML editor</SPAN
> allows authors to concentrate
on the content, and not the markup. It has built in
spelling and conversion utilities which allow you to transform your
documents without having to install and configure an additional
processing tool such as jade. There is a free <SPAN
CLASS="QUOTE"
>"standard
edition"</SPAN
>, which is a simplified version of their
<SPAN
CLASS="QUOTE"
>"professional edition."</SPAN
>
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-conglomerate"
></A
>B.2.1.5. Conglomerate</H3
><P
><A
HREF="http://www.conglomerate.org"
TARGET="_top"
>http://www.conglomerate.org</A
></P
><P
>According to their web site, <SPAN
CLASS="QUOTE"
>"Conglomerate aims to be an XML editor that everyone can use. In particular, our primary goal is to create the ultimate editor for DocBook and similar formats. It aims to hide the jargon and complexity of XML and present the information in your documents in a way that makes sense."</SPAN
></P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-vex"
></A
>B.2.1.6. Vex: a visual editor for XML</H3
><P
><A
HREF="http://vex.sourceforge.net/"
TARGET="_top"
>http://vex.sourceforge.net/</A
></P
><P
>According to their web site, <SPAN
CLASS="QUOTE"
>"The visual part comes from the fact that Vex hides the raw XML tags from the user, providing instead a wordprocessor-like interface. Because of this, Vex is best suited for document-style XML documents such as XHTML and DocBook rather than data-style XML documents."</SPAN
></P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="tools-text-editors"
></A
>B.2.2. Text Editors</H2
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>For advanced writers</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; The tools outlined in this section allow you to work with
the DocBook tags directly. If you are not comfortable
working with markup languages you may want to use a word
processor instead. Word processors that support DocBook
are described in <A
HREF="#tools-word-processors"
>Section B.2.1</A
>.
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; If you are comfortable working with markup languages and
text editors, you'll probably want to customize your
current editor of choice to handle DocBook files. Below
are some of the more common text editors that can, with
some tweaking, handle DocBook files.
</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="psgml"
></A
>B.2.2.1. Emacs (PSGML)</H3
><P
>&#13;<A
HREF="http://www.lysator.liu.se/~lenst/about_psgml/"
TARGET="_top"
>&#13; http://www.lysator.liu.se/~lenst/about_psgml/
</A
>
</P
><P
><SPAN
CLASS="application"
>Emacs</SPAN
> has an SGML
writing mode called <SPAN
CLASS="application"
>psgml</SPAN
> that is a
major mode designed for editing SGML and XML documents. It
provides:
</P
><P
></P
><UL
><LI
><P
>&#13; <SPAN
CLASS="QUOTE"
>"syntax highlighting"</SPAN
> or <SPAN
CLASS="QUOTE"
>"pretty
printing"</SPAN
> features that make the tags stand out
</P
></LI
><LI
><P
>&#13; a way to insert tags other than typing them by hand
</P
></LI
><LI
><P
>&#13; and the ability to validate your document while writing
</P
></LI
></UL
><P
>&#13; For users of Emacs, it's a great way to go.
PSGML works with DocBook, LinuxDoc and other DTDs equally well.
</P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="emacs-psgml-install"
></A
>B.2.2.1.1. Verifying PSGML is Installed</H4
><P
>
If you have installed a recent distribution, you may
already have PSGML installed for use with Emacs. To check,
start Emacs and look for the PSGML documentation (<B
CLASS="keycap"
>C</B
>-<B
CLASS="keycap"
>h</B
><B
CLASS="keycap"
>i</B
><B
CLASS="keycap"
>m</B
><B
CLASS="keycap"
>psgml</B
>).
</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Dependencies</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; If you don't have PSGML installed now might be a good
time to upgrade Emacs. The rest of these instructions
will assume you have PSGML installed.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="emacs-config"
></A
>B.2.2.1.2. Configuring Emacs for Use With PSGML</H4
><P
>
If you want GNU Emacs to enter PSGML mode when you open
an <TT
CLASS="filename"
>.xml</TT
> file, it
will need to be able to find the DocBook DTD files.
If your distribution already had PSGML set up for use
with GNU Emacs, you probably won't need to do anything.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Tuning Emacs</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; For more information on how to configure Emacs, check out
.
</P
></TD
></TR
></TABLE
></DIV
><P
>
Once you've configured your system to use PSGML you will
need to override Emacs' default <EM
>sgml-mode</EM
> with the
<EM
>psgml-mode</EM
>. This can be done by configuring your
<TT
CLASS="filename"
>.emacs</TT
> file. After you've edited the
configuration file you will need to restart Emacs.
</P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="emacs-new-file"
></A
>B.2.2.1.3. Creating New DocBook XML Files</H4
><P
>&#13; There are a number of steps to creating a new DocBook XML
file in Emacs.
</P
><P
></P
><UL
><LI
><P
>&#13; Create a new file with an
<TT
CLASS="filename"
>xml</TT
>
extension.
</P
></LI
><LI
><P
>&#13; On the first line of the file enter the doctype for the
version of DocBook that you would like to use.
If you're not sure what a doctype is all about, check <A
HREF="#dtd"
>Section B.5</A
>
</P
></LI
><LI
><P
>
Enter
<B
CLASS="keycap"
>C</B
>-<B
CLASS="keycap"
>c</B
>
<B
CLASS="keycap"
>C</B
>-<B
CLASS="keycap"
>p</B
>.
If Emacs manages to parse your DTD, you will
see <TT
CLASS="computeroutput"
>Parsing prolog...done</TT
>
in the minibuffer.
</P
></LI
><LI
><P
>&#13; Enter
<B
CLASS="keycap"
>C</B
>-<B
CLASS="keycap"
>c</B
>
<B
CLASS="keycap"
>C</B
>-<B
CLASS="keycap"
>e</B
>
<B
CLASS="keycap"
>Enter</B
>
to auto-magically insert the parent element for your
document. (New authors are typically writing
<TT
CLASS="sgmltag"
>article</TT
>s.)
</P
></LI
><LI
><P
>&#13; If things are working correctly, you should see new tags
for the parent element for your document right after the
document type declaration. In other words you should now
see two extra tags:
<TT
CLASS="sgmltag"
>&#60;article&#62;</TT
>
and
<TT
CLASS="sgmltag"
>&#60;/article&#62;</TT
>
in your document.
</P
></LI
></UL
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="emacs-spell"
></A
>B.2.2.1.4. Spell Checking in Emacs</H4
><P
>&#13; Emacs can be configured to use <SPAN
CLASS="application"
>aspell</SPAN
>
by adding the following to your <TT
CLASS="filename"
>~/.emacs</TT
> file.
Thanks to <A
HREF="http://www.ertius.org"
TARGET="_top"
>Rob Weir</A
> for
this configuration information.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;;; Use aspell
(setq-default ispell-program-name "aspell")
;;Setup some dictionary languages
(setq ispell-dictionary "british")
(setq flyspell-default-dictionary "british")
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-epcEdit"
></A
>B.2.2.2. epcEdit</H3
><P
>&#13; <A
HREF="http://www.tksgml.de/"
TARGET="_top"
>&#13; http://www.tksgml.de</A
>
</P
><P
>&#13; The <SPAN
CLASS="application"
>epcEdit</SPAN
> program allows you to edit XML files.
It has the advantages of not needing to know <SPAN
CLASS="application"
>Emacs</SPAN
> or
<SPAN
CLASS="application"
>vi</SPAN
> before starting, and is cross-platform, working in both
Windows and Linux. This is a commercial application, and
pricing can be found at
<A
HREF="http://www.tksgml.de/pricing.html"
TARGET="_top"
>&#13; http://www.tksgml.de/pricing.html</A
>
</P
><P
>&#13; Along with visual editing, epcEdit will also validate
documents on loading, and on demand by using the <SPAN
CLASS="guimenu"
>Document</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Validate</SPAN
>
command.</P
><DIV
CLASS="figure"
><A
NAME="AEN1567"
></A
><P
><B
>Figure B-1. epcEdit screen shot</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="sgeditscreenshot.jpg"></P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-morphoneditor"
></A
>B.2.2.3. Morphon XML editor</H3
><P
>&#13; <A
HREF="http://www.morphon.com/xmleditor/index.shtml"
TARGET="_top"
>&#13; http://www.morphon.com/xmleditor/index.shtml</A
>
</P
><P
>&#13; This is a commercial application which is currently
available for free (with an optional user registration).
It is written in Java, allowing it to run on any platform
that has a Java Virtual Machine (that is, works in both
Windows and Linux).
</P
><P
>&#13; On the plus sides of <SPAN
CLASS="application"
>XMLEditor</SPAN
> is the left side of the
screen shows the hierarchy of the document (starting with Book
and so on). Selecting an item in the list brings you to that
part of the document so you can edit it. The right part of the
screen shows the text without any markup or tags being shown.
If you have external files as ELEMENTS (as the LDP Author Guide
does), <SPAN
CLASS="application"
>XMLEditor</SPAN
> will follow the links and load the files, so
you always work on the entire work. On the minus side of this,
you will get errors if a file is missing.
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-nedit"
></A
>B.2.2.4. nedit</H3
><P
>&#13; <A
HREF="http://nedit.org"
TARGET="_top"
>&#13; http://nedit.org</A
>
</P
><P
>&#13; To be fair, <SPAN
CLASS="application"
>nedit</SPAN
> is more
for programmers, so it might seem a bit of overkill for new
users and especially non-programmers. All that aside, it's
extremely powerful, allowing for syntax highlighting. Unlike
<SPAN
CLASS="application"
>epcEdit</SPAN
>, <SPAN
CLASS="application"
>nedit</SPAN
> doesn't allow you to automatically insert tags
or automatically validate your code. However, it does allow
for shell commands to be run against the contents of the
window (as opposed to saving the file, then checking).
<DIV
CLASS="figure"
><A
NAME="AEN1598"
></A
><P
><B
>Figure B-2. nedit screen shot</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="neditscreenshot.jpg"></P
></DIV
></DIV
>
</P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="usingnedit"
></A
>B.2.2.4.1. Using nedit</H4
><P
>When you open your DocBook file, <SPAN
CLASS="application"
>nedit</SPAN
> should already
have syntax highlighting enabled. If it does not you can
turn it on explicitly using:
<SPAN
CLASS="guimenu"
>Preferences</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Language Mode</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>SGML HTML</SPAN
>
</P
><P
>&#13; If you have line numbers turned on (using
<SPAN
CLASS="guimenu"
>Preferences</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Show
Line Numbers</SPAN
>) then finding
validation errors is much simpler.
<SPAN
CLASS="application"
>nsgmls</SPAN
>, the validation tool
we'll use, lists errors by their line number.
</P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="nedit-scripting"
></A
>B.2.2.4.2. Configuring nedit</H4
><P
>&#13; Since you can feed the contents of your window to
outside programs, you can easily extend nedit to perform
repetitive functions. The example you'll see here is to
validate your document using
<SPAN
CLASS="application"
>nsgmls</SPAN
>.
For more information about <SPAN
CLASS="application"
>nsgmls</SPAN
> and validating
documents please read <A
HREF="#tools-validate"
>Section B.3</A
>.
</P
><P
></P
><UL
><LI
><P
>&#13; Select <SPAN
CLASS="guimenu"
>Preferences</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Default
Settings</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Customize
Menus</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Shell
Menu...</SPAN
>. This will bring up the
Shell Command dialog box, with all the shell commands nedit
has listed under the
<SPAN
CLASS="guimenu"
>Shell</SPAN
> menu.
</P
></LI
><LI
><P
>&#13; Under
Menu Entry, enter <SPAN
CLASS="QUOTE"
>"Validate DocBook."</SPAN
> This will be the entry
you'll see on the screen.
</P
></LI
><LI
><P
>&#13; Under Accelerator, press
<B
CLASS="keycap"
>Alt</B
>-<B
CLASS="keycap"
>S</B
>.
Once this menu item is set up, you can press
<B
CLASS="keycap"
>Alt</B
>-<B
CLASS="keycap"
>S</B
>
to have the Validate DocBook automatically run.
</P
></LI
><LI
><P
>&#13; Under Command
Input, select window, and under Command Output, select
dialog.
</P
></LI
><LI
><P
>&#13; Under Command to Execute, enter
<B
CLASS="command"
>nsgmls
<TT
CLASS="parameter"
><I
>-sv</I
></TT
></B
>. Using
<TT
CLASS="parameter"
><I
>-v</I
></TT
> outputs the version number
is output to the screen so that you know the command
has run.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Check the PATH</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Note
that <SPAN
CLASS="application"
>nsgmls</SPAN
> has to be in your
<TT
CLASS="envar"
>PATH</TT
> for this to work properly.
</P
></TD
></TR
></TABLE
></DIV
></LI
></UL
><DIV
CLASS="figure"
><A
NAME="AEN1659"
></A
><P
><B
>Figure B-3. Adding shell commands to nedit</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="neditshellcommand.jpg"></P
></DIV
></DIV
><P
></P
><UL
><LI
><P
>&#13; Click <SPAN
CLASS="guibutton"
>OK</SPAN
> and you'll now be back
at the main nedit screen. Load up an XML file, and select
<SPAN
CLASS="guimenu"
>Shell</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Validate
DocBook</SPAN
> or press
<B
CLASS="keycap"
>Alt</B
>-<B
CLASS="keycap"
>S</B
>.
</P
></LI
><LI
><P
>&#13; The <B
CLASS="command"
>nedit</B
> program will fire up and check
the contents of the window.
</P
></LI
><LI
><P
>&#13; If all you see is a version number for
<SPAN
CLASS="application"
>nsgml</SPAN
> then your
document is valid. Any errors are reported by line
number in your document.
</P
></LI
></UL
><DIV
CLASS="figure"
><A
NAME="AEN1682"
></A
><P
><B
>Figure B-4. <SPAN
CLASS="application"
>nsgmls</SPAN
> output on success</B
></P
><DIV
CLASS="mediaobject"
><P
><IMG
SRC="neditsuccess.jpg"></P
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-vim"
></A
>B.2.2.5. VIM</H3
><P
>&#13; <A
HREF="http://www.vim.org"
TARGET="_top"
>http://www.vim.org</A
>
</P
><P
>&#13; No mention of text editors is complete
without talking about <SPAN
CLASS="application"
>vi</SPAN
>.
The <SPAN
CLASS="application"
>VIM</SPAN
> (Vi IMproved)
editor has the functionality of
regular vi and includes <SPAN
CLASS="QUOTE"
>"syntax
highlighting"</SPAN
> of tags.</P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="usingvim"
></A
>B.2.2.5.1. Getting Started</H4
><P
>&#13; There are many versions of <SPAN
CLASS="application"
>vi</SPAN
>.
New authors will likely want one of the more
feature-packed versions for syntax highlighting and
a graphical interface including mouse control.
</P
><P
>&#13; Red Hat users will want the following packages:
vim-common, vim-minimal and vim-enhanced.
Debian users will want the following package: vim.
For an X interface (including <SPAN
CLASS="acronym"
>GUI</SPAN
> menus and
mouse control) users will want
<SPAN
CLASS="application"
>gvim</SPAN
>. The <SPAN
CLASS="QUOTE"
>"g"</SPAN
> in gvim is for
<SPAN
CLASS="QUOTE"
>"Graphical"</SPAN
>.
</P
><P
><SPAN
CLASS="application"
>VIM</SPAN
> compiles very easy should you need to build your own. Both <B
CLASS="command"
>vim</B
> and <B
CLASS="command"
>gvim</B
> are built by default. Syntax highlighting is included but not enabled by default if you have to start from scratch; use the <B
CLASS="command"
>:syntax enable</B
> command in <SPAN
CLASS="application"
>VIM</SPAN
> to turn this feature on.
</P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="vim-new-file"
></A
>B.2.2.5.2. Creating New DocBook XML Files</H4
><P
>&#13; In both <SPAN
CLASS="application"
>vim</SPAN
> and
<SPAN
CLASS="application"
>gvim</SPAN
>, <TT
CLASS="filename"
>.xml</TT
> files will be
recognized and enter into <SPAN
CLASS="QUOTE"
>"SGML mode"</SPAN
>.
A series of known DocBook tags and attributes have
been entered into <SPAN
CLASS="application"
>vim</SPAN
>
and will be highlighted one color if the name is known
and another if it is not (for this author the colors are yellow and blue).
</P
><P
>&#13; Having the
correct document type declaration at the top of your
document should add the syntax highlighting.
If you do not see this highlighting you will need to
force VIM into SGML mode (even for XML files) using the
command <B
CLASS="command"
>:set ft=sgml</B
>. If you are
working with multiple files for a single XML document you
can add your document type in &#60;-- comments --&#62; to
the top of the file to get the correct syntax
highlighting (you will need to restart the program to see
the change in highlighting). The top line of this file
(<TT
CLASS="filename"
>tools-text-editors.xml</TT
>) looks like this:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;
&#60;!-- &#60;!DOCTYPE book PUBLIC '-//OASIS//DTD DocBook XML V4.2//EN'&#62; --&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="vim-spellcheck"
></A
>B.2.2.5.3. Spell Check</H4
><P
>&#13; As in <SPAN
CLASS="application"
>Emacs</SPAN
>,
<SPAN
CLASS="application"
>Vim</SPAN
>, will work quite happily with
<SPAN
CLASS="application"
>aspell</SPAN
>. It can be run from within Vim
with the following:
<TT
CLASS="userinput"
><B
>:! aspell -c %</B
></TT
>.
</P
><P
>&#13; For more sophisticated spell check alternatives, give <A
HREF="http://cream.sourceforge.net/"
TARGET="_top"
>Cream</A
> or <A
HREF="http://www.vim.org/scripts/script_search_results.php?keywords=vimspell&#38;script_type=&#38;order_by=rating&#38;direction=descending&#38;search=search"
TARGET="_top"
>vimspell</A
> a try.
</P
></DIV
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="vim-tagcompletion"
></A
>B.2.2.5.4. Tag Completion</H4
><P
>&#13; The following information is provided by <A
HREF="http://www.digitalhermit.com"
TARGET="_top"
>Kwan Lowe</A
>.
</P
><P
>&#13; Vim has a DocBook helper script which can be easily copied into
your <TT
CLASS="filename"
>.vimscripts</TT
>
directory and used to <SPAN
CLASS="QUOTE"
>"auto complete"</SPAN
> tags while
writing DocBook documents. The script can be downloaded from:
<A
HREF="http://www.vim.org/scripts/script.php?script_id=38"
TARGET="_top"
>http://www.vim.org/scripts/script.php?script_id=38</A
>.
</P
><A
NAME="AEN1752"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
>&#13; Grab the file, then untar it. Copy the
<TT
CLASS="filename"
>dbhelper.vim</TT
> to your <TT
CLASS="filename"
>.vimscripts</TT
> directory if you have one.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13; <TT
CLASS="prompt"
>$ </TT
><B
CLASS="command"
>mkdir</B
> <TT
CLASS="filename"
>.vimscripts</TT
>
<TT
CLASS="prompt"
>$ </TT
><B
CLASS="command"
>cp</B
> <TT
CLASS="filename"
>dbhelper.vim</TT
> <TT
CLASS="filename"
>.vimscripts</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; You'll also have to convert the <TT
CLASS="filename"
>dbhelper.vim</TT
> file to unix formatting:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13; <TT
CLASS="prompt"
>$ </TT
><B
CLASS="command"
>dos2unix</B
> <TT
CLASS="filename"
>dbhelper.vim</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; Next, edit your <TT
CLASS="filename"
>.vimrc</TT
> file and add the line:
<TT
CLASS="userinput"
><B
>source
/home/yourname/.vimscripts/dbhelper.vim</B
></TT
>
</P
><P
>&#13; To use the scripts, enter vi and go into insert mode. Press
<B
CLASS="keycap"
>,</B
> (comma) followed by the shortcut. For example:
<TT
CLASS="userinput"
><B
>,dtbk</B
></TT
>
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="xmlform"
></A
>B.2.2.6. XMLForm</H3
><P
><A
HREF="http://www.datamech.com/XMLForm/"
TARGET="_top"
>http://www.datamech.com/XMLForm/</A
></P
><P
>This web-based application allows you to put in the URL for XML source, or copy and paste the XML directly into the web form. The application then breaks down your document into a series of form fields that hide the DocBook tags so that you may edit the content directly. Version 5 is available from <A
HREF="http://www.datamech.com/XMLForm/formGenerator5.html"
TARGET="_top"
>http://www.datamech.com/XMLForm/formGenerator5.html</A
>. This application is best on shorter documents (less than 20 pages printed).</P
><P
>As this is an on-line tool, it will be good for small updates only.</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="tools-xxe"
></A
>B.2.2.7. XMLmind XML Editor (XXE)</H3
><P
>&#13; <A
HREF="http://www.xmlmind.com/xmleditor"
TARGET="_top"
>http://www.xmlmind.com/xmleditor</A
>
</P
><P
>&#13; David Horton offers the following information:
</P
><A
NAME="AEN1788"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
>&#13; I am a big fan of XMLMind's <SPAN
CLASS="application"
>XXE</SPAN
> editor and <SPAN
CLASS="application"
>XFC</SPAN
> FO converter.
It is <SPAN
CLASS="QUOTE"
>"free as in beer,"</SPAN
> but not necessarily
<SPAN
CLASS="QUOTE"
>"free as in speech."</SPAN
> Very liberal license for personal use
however. It's Java-based so it works on all sorts of OS's.
</P
></BLOCKQUOTE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tools-validate"
></A
>B.3. Validation</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="why-validate"
></A
>B.3.1. Why Validate Your Document</H2
><P
>&#13; The LDP uses a number of scripts to distribute your document.
These scripts submit your document to the LDP's CVS (a free
document version management system), and then they transform your document to other formats that
users then read. Your document will also be mirrored on a number
of sites worldwide (yet another set of scripts).
</P
><P
>&#13; In order for these scripts to work correctly, your document must
be both <SPAN
CLASS="QUOTE"
>"well formed"</SPAN
> and use <SPAN
CLASS="QUOTE"
>"valid
markup"</SPAN
>.
<EM
>Well formed</EM
> means your document follows the rules that XML
is expecting: it complies with XML grammar rules. <EM
>Valid
markup</EM
> means you only use elements or tags
which are <SPAN
CLASS="QUOTE"
>"valid"</SPAN
> for your
document: XML vocabulary rules are applied.
</P
><P
>&#13; If your document is not well formed or uses invalid markup, the
scripts will not be able to process it. As a result, your revised
document will not be distributed.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>The Docbook Section</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
> There is more information about how to validate
your document in the DocBook section. Check out <A
HREF="#tools-validate"
>Section B.3</A
> for more help with validating
your document. </P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="validate-online"
></A
>B.3.2. Validation for the Faint of Heart</H2
><P
>&#13; Your life is already hard enough without having to install a full
set of tools just to see if you validate as well. You can upload your
raw XML files to a web site, then go to
<A
HREF="http://validate.sf.net"
TARGET="_top"
>http://validate.sf.net</A
>,
enter the URL to your document, then validate it.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>External entities</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; When this information was added to the Author Guide external entities
were not supported. Follow the instructions provided on the
Validate site if you have trouble.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="validate-local"
></A
>B.3.3. Validation for the Not So Faint Of Heart</H2
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="config-catalog"
></A
>B.3.3.1. Catalogs</H3
><P
>XML and SGML files contain most of the information you need;
however, there are sometimes entities which are specific to SGML in
general. To match these entities to their actual values you need to use a
<EM
>catalog</EM
>. The role of a catalog is to tell your
system where to find the files it is looking for. You may want to think of
a catalog as a guide book (or a map) for your tools.</P
><P
>&#13; Most distributions (Red Hat/Fedora and Debian at least) have a common location
for the main SGML catalog file, called <TT
CLASS="filename"
>/etc/sgml/catalog</TT
>.
In times past, it could also be found in <TT
CLASS="filename"
>/usr/lib/sgml/catalog</TT
>.
</P
><P
>&#13; The structure of XML catalog files is not the same as SGML catalog files.
The section on tailoring a catalog (see <A
HREF="#making-catalogs"
>Section B.3.4</A
>) will give more details about what these
files actually contain.
</P
><P
>&#13; If your system cannot find the catalog file, or you are using
custom catalog files, you may need to set the
<TT
CLASS="envar"
>SGML_CATALOG_FILES</TT
> and
<TT
CLASS="envar"
>XML_CATALOG_FILES</TT
> environment variables. Using
<B
CLASS="command"
>echo <TT
CLASS="varname"
>$SGML_CATALOG_FILES</TT
></B
>,
check to see if it is currently set. If a blank line is returned,
the variable has not been set. Use the same command to see if
<TT
CLASS="envar"
>XML_CATALOG_FILES</TT
> is set as well. If the variables
are not set, use the following example to set them now.
</P
><DIV
CLASS="example"
><A
NAME="ex-catalog-files"
></A
><P
><B
>Example B-1. Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES
Environmental Variables</B
></P
><P
>&#13; <TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
><TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>export</B
> <TT
CLASS="envar"
>SGML_CATALOG_FILES="/etc/sgml/catalog"</TT
></PRE
></FONT
></TD
></TR
></TABLE
></P
><P
>&#13; To make this change permanent, you can add the following lines to
your <TT
CLASS="filename"
>~/.bashrc</TT
> file.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="envar"
>SGML_CATALOG_FILES="/etc/sgml/catalog"</TT
>
<B
CLASS="command"
>export</B
> <TT
CLASS="envar"
>SGML_CATALOG_FILES</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; If you installed XML tools via a RedHat or Debian package, you
probably don't need to do this step. If you are using a custom XML catalog
you will definitely need to do this. There is more on custom catalogs in the next
section. To ensure my backup scripts grab this custom file, I have added
mine in a sub-directory of my home directory named <SPAN
CLASS="QUOTE"
>"docbook"</SPAN
>.
</P
><P
>&#13;<TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
><TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>export</B
> <TT
CLASS="envar"
>XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"</TT
></PRE
></FONT
></TD
></TR
></TABLE
></P
><P
>&#13;You can also change your <TT
CLASS="filename"
>.bashrc</TT
> if you want to
save these changes.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="envar"
>XML_CATALOG_FILES="/home/user/docbook/db-catalog.xml"</TT
>
<B
CLASS="command"
>export</B
> <TT
CLASS="envar"
>XML_CATALOG_FILES</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; If you are adding the changes to your
<TT
CLASS="filename"
>.bashrc</TT
> you will not see the changes
until you open a new terminal window. To make the changes immediate in the current terminal,
<SPAN
CLASS="QUOTE"
>"source"</SPAN
> the configuration file.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="making-catalogs"
></A
>B.3.4. Creating and modifying catalogs</H2
><P
>&#13; In the previous section I mentioned a catalog is like a guide book for
your tools. Specifically, a catalog maps the rules from the public
identifier to your system's files.
</P
><P
>&#13; At the top of every DocBook (or indeed every XML) file there is a
DOCTYPE which tells the processing tool what kind of document it is
about to be processed. At a minimum this declaration will include a public
identifier, such as <TT
CLASS="literal"
>-//OASIS//DTD DocBook
V4.2//EN</TT
>. This public identifier has a number of sections all
separated by <TT
CLASS="literal"
>//</TT
>. It contains the following
information: ISO standard if any (<TT
CLASS="literal"
>-</TT
> -- in this case
there is no ISO standard),
author (OASIS), type of document (DTD DocBook V4.2), language
(English). Your DOCTYPE may also include a URL.
</P
><P
>&#13; A public identifier is useless to a processing tool, as it needs to be
able to access the actual DTD. A URL is useless if the processing tool
is off-line. To help your processor deal with these problems you can
download all of the necessary files and then <SPAN
CLASS="QUOTE"
>"map"</SPAN
>
them for your processing tools by using a catalog.
</P
><P
>&#13; If you are using SGML processing tools (for instance Jade), you will need an
SGML catalog. If you are using XML processing tools (like XSLT), you
will need an XML catalog. Information on both is included.
</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="catalog-sgml"
></A
>B.3.4.1. SGML Catalogs</H3
><DIV
CLASS="example"
><A
NAME="example-catalog-sgml"
></A
><P
><B
>Example B-2. Example of an SGML catalog</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><PRE
CLASS="programlisting"
> <A
NAME="ex.catalog.comment"
><IMG
SRC="../images/callouts/1.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(1)"></A
>
-- Catalog for the Conectiva Styles --
OVERRIDE YES
<A
NAME="ex.catalog.definition"
><IMG
SRC="../images/callouts/2.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(2)"></A
>
PUBLIC "-//Conectiva SA//DTD DocBook Conectiva variant V1.0//EN"
"/home/ldp/styles/books.dtd"
DELEGATE "-//OASIS"
"/home/ldp/SGML/dtds/catalog.dtd"
<A
NAME="ex.catalog.eof"
><IMG
SRC="../images/callouts/3.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(3)"></A
>
DOCTYPE BOOK /home/ldp/SGML/dtds/docbook/db31/docbook.dtd
-- EOF --
</PRE
></TD
></TR
></TABLE
><DIV
CLASS="calloutlist"
><DL
COMPACT="COMPACT"
><DT
><A
HREF="#ex.catalog.comment"
><IMG
SRC="../images/callouts/1.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(1)"></A
></DT
><DD
> Comment. Comments start with <SPAN
CLASS="QUOTE"
>"--"</SPAN
> and
follow to the end of the line. </DD
><DT
><A
HREF="#ex.catalog.definition"
><IMG
SRC="../images/callouts/2.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(2)"></A
></DT
><DD
> The public type association <TT
CLASS="parameter"
><I
>"-//Conectiva SA//DTD books V1.0//EN"</I
></TT
>
with the file <TT
CLASS="filename"
>books.dtd</TT
> on the directory <TT
CLASS="filename"
>/home/ldp/styles</TT
>. </DD
><DT
><A
HREF="#ex.catalog.eof"
><IMG
SRC="../images/callouts/3.gif"
HSPACE="0"
VSPACE="0"
BORDER="0"
ALT="(3)"></A
></DT
><DD
> Comment signifying the end of the file.</DD
></DL
></DIV
></DIV
><P
>As in the example above, to associate an identifier to a file just
follow the sequence shown:</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Copy the identifier <EM
>PUBLIC</EM
></P
></LI
><LI
><P
>Type the identifying text </P
></LI
><LI
><P
>Indicate the path to the associated file</P
></LI
></OL
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="making-catalogs-commands"
></A
>B.3.4.1.1. Useful commands for catalogs</H4
><P
>The most common mappings to be used in catalogs are:</P
><P
></P
><DIV
CLASS="variablelist"
><DL
><DT
><TT
CLASS="literal"
>PUBLIC</TT
></DT
><DD
><P
>The keyword <TT
CLASS="literal"
>PUBLIC</TT
> maps
public identifiers for identifiers on the system.</P
></DD
><DT
><TT
CLASS="literal"
>SYSTEM</TT
></DT
><DD
><P
>The <TT
CLASS="literal"
>SYSTEM</TT
> keyword maps
system identifiers for files on the system.</P
><DIV
CLASS="informalexample"
><A
NAME="AEN1931"
></A
><P
></P
><P
>&#13;SYSTEM
"http://nexus.conectiva/utilidades/publicacoes/livros.dtd"
"publicacoes/livros.dtd"</P
><P
></P
></DIV
></DD
><DT
><TT
CLASS="literal"
>SGMLDECL</TT
></DT
><DD
><P
>The keyword <TT
CLASS="literal"
>SGMLDECL</TT
> designates the
system identifier of the SGML statement that should be used.
</P
><DIV
CLASS="informalexample"
><A
NAME="AEN1939"
></A
><P
></P
><P
>&#13;SGMLDECL "publishings/books.dcl"</P
><P
></P
></DIV
></DD
><DT
><TT
CLASS="literal"
>DTDDECL</TT
></DT
><DD
><P
>Similar to the <TT
CLASS="literal"
>SGMLDECL</TT
> the
keyword <TT
CLASS="literal"
>DTDDECL</TT
> identifies the SGML statement
that should be used. <TT
CLASS="literal"
>DTDDECL</TT
> makes the
association of the statement with a public identifier to a
<SPAN
CLASS="acronym"
>DTD</SPAN
>. Unfortunately, this association isn't
supported by the open source tools available. The benefits of this
statement can be achieved somehow with multiple catalog files.
</P
><DIV
CLASS="informalexample"
><A
NAME="AEN1950"
></A
><P
></P
><P
>&#13;DTDDECL "-//Conectiva SA//DTD livros V1.0//EN" "publicacoes/livros.dcl"</P
><P
></P
></DIV
></DD
><DT
><TT
CLASS="literal"
>CATALOG</TT
></DT
><DD
><P
>The keyword <TT
CLASS="literal"
>CATALOG</TT
> allows a catalog
to be included inside another. This is a way to make use of several
different catalogs without the need to alter them.
</P
></DD
><DT
><TT
CLASS="literal"
>OVERRIDE</TT
></DT
><DD
><P
>The keyword <TT
CLASS="literal"
>OVERRIDE</TT
> informs whether an
identifier has priority over a system identifier.
The standard on most systems is that the system identifier
has priority over the public one.</P
></DD
><DT
><TT
CLASS="literal"
>DELEGATE</TT
></DT
><DD
><P
>The keyword <TT
CLASS="literal"
>DELEGATE</TT
> allows the
association of a catalog to a specific type of public identifier.
The clause <TT
CLASS="literal"
>DELEGATE</TT
> is very similar to the
<TT
CLASS="literal"
>CATALOG</TT
>, except for the fact that it doesn't do
anything until a specific pattern is specified.</P
></DD
><DT
><TT
CLASS="literal"
>DOCTYPE</TT
></DT
><DD
><P
>If a document starts with a type of document, but
has no public identifier and no system identifier the clause
<TT
CLASS="literal"
>DOCTYPE</TT
> associates this document
with a specific DTD.</P
></DD
></DL
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="catalog-xml"
></A
>B.3.4.2. XML Catalogs</H3
><P
>The following sample catalog was provided by Martin A. Brown.</P
><DIV
CLASS="example"
><A
NAME="ex-catalog-xml"
></A
><P
><B
>Example B-3. Sample XML Catalog file</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;?xml version="1.0"?&#62;
&#60;!DOCTYPE catalog PUBLIC "-//OASIS/DTD Entity Resolution XML Catalog V1.0//EN"
"http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd"&#62;
<TT
CLASS="sgmltag"
>&#60;catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;public publicId="-//OASIS//DTD DocBook XML V4.2//EN"
uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;uri name="http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
uri="/home/mabrown/docbook/dtds/4.2/docbookx.dtd"/&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/docbook.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/docbook.xsl"/&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/chunk.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/chunk.xsl"/&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;uri name="http://docbook.sourceforge.net/release/xsl/current/xhtml/profile-chunk.xsl"
uri="/home/mabrown/docbook/xsl/xhtml/profile-chunk.xsl"/&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/catalog&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="validatexml"
></A
>B.3.5. Validating XML</H2
><DIV
CLASS="section"
><H3
CLASS="section"
><A
NAME="validate-nsgmls"
></A
>B.3.5.1. nsgmls</H3
><P
>&#13; You can use <SPAN
CLASS="application"
>nsgmls</SPAN
>, which is part of the
<SPAN
CLASS="application"
>jade</SPAN
> suite (on Debian apt-get the
<SPAN
CLASS="application"
>docbook-utils</SPAN
> package, see <A
HREF="#docbook-utils"
>Section B.4.2</A
>), to validate SGML or XML documents.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>nsgmls <TT
CLASS="parameter"
><I
>-s</I
></TT
> <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
> If there are no issues, you'll just get your command
prompt back. The <TT
CLASS="parameter"
><I
>-s</I
></TT
> tells
<SPAN
CLASS="application"
>nsgmls</SPAN
> to show only the errors.</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Function not found</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; If you get errors about a function not being found, or
something about an ISO character not having an
authoritative source, you may
need to point <B
CLASS="command"
>nsgmls</B
> to your
<TT
CLASS="filename"
>xml.dcl</TT
> file. For Red Hat 9, it
will look like this:
<B
CLASS="command"
>nsgmls <TT
CLASS="parameter"
><I
>-s</I
></TT
>
<TT
CLASS="filename"
>/usr/share/sgml/xml.dcl</TT
>
<TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; For more information on processing files with Jade/OpenJade please read
<A
HREF="http://www.tldp.org/HOWTO/DocBook-OpenJade-SGML-XML-HOWTO/index.html"
TARGET="_top"
>DocBook XML/SGML Processing Using OpenJade</A
>.
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="validate-onsgmls"
></A
>B.3.5.2. onsgmls</H3
><P
>&#13; This is an alternative to <SPAN
CLASS="application"
>nsgmls</SPAN
>. It ships
with the OpenJade package. This program gives more options than nsgmls
and allows you to quietly ignore a number of problems that arise while
trying to validate an XML file (as opposed to an SGML file). This also
means you don't have to type out the location of your
<TT
CLASS="filename"
>xml.dcl</TT
> file each time.
</P
><P
>&#13; I was able to simply use the following to validate a file with only
error messages that were related to my markup errors.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>onsgmls -s <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; According to <A
HREF="http://lists.oasis-open.org/archives/docbook-apps/200305/msg00081.html"
TARGET="_top"
>Bob
Stayton</A
> you can also turn off specific error messages. The
following example turns off XML-specific error messages.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>onsgmls <TT
CLASS="parameter"
><I
>-s</I
></TT
> <TT
CLASS="parameter"
><I
>-wxml</I
></TT
> <TT
CLASS="parameter"
><I
>-wno-explicit-sgml-decl</I
></TT
> <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="validate-xmllint"
></A
>B.3.5.3. xmllint</H3
><P
>&#13; You can also use the <SPAN
CLASS="application"
>xmllint</SPAN
> command-line tool from the <SPAN
CLASS="application"
>libxml2</SPAN
> package to validate your documents. This tool does a simple check on completeness of tags and whether all tags that are opened, are also closed again.
By default
<SPAN
CLASS="application"
>xmllint</SPAN
> will output a results tree. So if your document comes out until the last line, you know there are no heavy errors having to do with tag mismatches, opening and closing errors and the like.</P
><P
>To prevent printing the entire document to your screen, add the <TT
CLASS="parameter"
><I
>--noout</I
></TT
>
parameter.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>xmllint <TT
CLASS="parameter"
><I
>--noout</I
></TT
> <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; If nothing is returned, your document contains no syntax errors. Else, start with the first error that was reported. Fix that one error, and run the tool again on your document. If it still returns output, again fix the first error that you see, don't botter with the rest since further errors are usually generated because of the first one.</P
><P
>&#13; If you would like to check your document for any errors which are
specific to your Document Type Definition, add
<TT
CLASS="parameter"
><I
>--valid</I
></TT
>.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>xmllint <TT
CLASS="parameter"
><I
>--noout</I
></TT
> <TT
CLASS="parameter"
><I
>--valid</I
></TT
> <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>The <B
CLASS="command"
>xmllint</B
> tool may also be used for checking errors in the XML catalogs, see the man pages for more info on how to set this behavior.</P
><P
>&#13; If you are a Mac OSX or Windows user, you may also want to check out
<SPAN
CLASS="application"
>tkxmllint</SPAN
>, a GUI version of
<SPAN
CLASS="application"
>xmllint</SPAN
>. More information is available from:
<A
HREF="http://tclxml.sourceforge.net/tkxmllint.html"
TARGET="_top"
>http://tclxml.sourceforge.net/tkxmllint.html</A
>.
</P
><DIV
CLASS="example"
><A
NAME="xmllint-example"
></A
><P
><B
>Example B-4. Debugging example using xmllint</B
></P
><P
>The example below shows how you can use <SPAN
CLASS="application"
>xmllint</SPAN
> to check your documents. I've created some errors that I made a lot, as a beginning XML writer. At first, the document doesn't come through, and errors are shown:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>xmllint <TT
CLASS="filename"
>ldp-history.xml</TT
></B
>
ldp-history.xml:22: error: Opening and ending tag mismatch: articlinfo line 6 and articleinfo
&#60;/articleinfo&#62;
^
ldp-history.xml:37: error: Opening and ending tag mismatch: listitem line 36 and orderedlist
&#60;/orderedlist&#62;
^
ldp-history.xml:39: error: Opening and ending tag mismatch: orderedlist line 34 and sect2
&#60;/sect2&#62;
^
ldp-history.xml:46: error: Opening and ending tag mismatch: sect1 line 41 and para
for many authors to contribute their part in their area of specialization.&#60;/para
^
ldp-history.xml:57: error: Opening and ending tag mismatch: para line 55 and sect1
&#60;/sect1&#62;
^
ldp-history.xml:59: error: Opening and ending tag mismatch: sect2 line 31 and article
&#60;/article&#62;
^
ldp-history.xml:61: error: Premature end of data in tag sect1 line 24
^
ldp-history.xml:61: error: Premature end of data in tag article line 5
^
</PRE
></FONT
></TD
></TR
></TABLE
><P
>Now, as we already mentioned, don't worry about anything except the first error. The first error says there is an inconsistency between the tags on line 6 and line 22 in the file. Indeed, on line 6 we left out the <SPAN
CLASS="QUOTE"
>"e"</SPAN
> in <SPAN
CLASS="QUOTE"
>"articleinfo"</SPAN
>. Fix the error, and run <B
CLASS="command"
>xmllint</B
> again. The first complaint now is about the offending line 37, where the closing tag for list items has been forgotten. Fix the error and run the validation tool again, until all errors are gone. Most common errors include forgetting to open or close the paragraph tag, spelling errors in tags and messed up sections.</P
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="transformations"
></A
>B.4. Transformations</H1
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>TLDP will convert your document</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>This section is about how to transform documents
from DocBook to other formats. If you do not need
to transform documents for your own web site, or to proof read the content, please <EM
>skip this section</EM
>.</P
><P
>&#13; If you would like to transform your documents for
proofreading purposes, please use the <A
HREF="http://www.xml-dev.com/blog/xml2html.php"
TARGET="_top"
>XML to HTML on-line
converter</A
>. You will need to upload your XML file(s)
to a web site. Then simply drop the URL into the form and
click the submit button. Your document will be magically
transformed into a beautiful (and legible)
HTML document. External files are supported. You may use
either absolute or relative URIs.
</P
><P
>Another easy-to-use package is
<SPAN
CLASS="application"
>xmlto</SPAN
>. It is a front-end for
<SPAN
CLASS="application"
>xsltproc</SPAN
>. It is available as a
RedHat, Debian (etc) package or can be downloaded from <A
HREF="http://cyberelk.net/tim/xmlto/"
TARGET="_top"
>http://cyberelk.net/tim/xmlto/</A
>. You can use it to convert
documents with:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><TT
CLASS="userinput"
><B
>xmlto html <TT
CLASS="filename"
>mydoc.xml</TT
></B
></TT
>
<TT
CLASS="prompt"
>bash$ </TT
><TT
CLASS="userinput"
><B
>xmlto txt <TT
CLASS="filename"
>mydoc.xml</TT
></B
></TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; You do not ever need to transform documents
before submitting to the LDP. The LDP
volunteers have a system which transforms
your DocBook file into HTML, PDF and plain
text formats. There, you've been warned.
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; Still here? Great! Transformations are
a pretty basic requirement to get what
you've written from a messy tag-soup into
something that can be read. This section
will help you get your system set up and
ready to transform your latest document
into other formats. This is very useful
is you want to <EM
>see</EM
>
your document before you release it to
the world.
</P
><P
>&#13; There are currently two ways to transform
your document: Document Style Semantics and
Specification Language (DSSSL); and XML
Style sheets (XSLT). Although the LDP web site uses
DSSSL to convert documents you may use XSLT
if you want. You only need to choose <EM
>one</EM
> of these
methods. For more information about DSSSL read: <A
HREF="#dsssl"
>Section B.4.1</A
>, for more information about XSLT read: <A
HREF="#xsl"
>Section B.4.3</A
>.
</P
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="dsssl"
></A
>B.4.1. DSSSL</H2
><P
>&#13; There are three basic requirements to transform a document using DSSSL:
</P
><P
></P
><UL
><LI
><P
>&#13; The Document Style and Semantics Specification Language files
(these are plain text files). <A
HREF="#dsssl-files"
>Section B.4.1.1</A
>
</P
></LI
><LI
><P
>&#13; The Document Type Definition file
which matches the DOCTYPE of your
document (this is a plain text file).
<A
HREF="#dtd"
>Section B.5</A
>
</P
></LI
><LI
><P
>&#13; A processor to do the actual work. <A
HREF="#dsssl-processors"
>Section B.4.1.2</A
>
</P
></LI
></UL
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="dsssl-files"
></A
>B.4.1.1. The Style Sheets</H3
><P
>There are two versions of the
Document Style Semantics and Specification Language
used by the LDP to transform documents from your
raw DocBook files into other formats (which are then
published on the Web). The LDP version of the style
sheets requires the Norman Walsh version--which
basically means if you're using DSSSL the Norman
Walsh version can be considered a requirement for
system setup.</P
><DIV
CLASS="formalpara"
><P
><B
>Norman Walsh DSSSL <A
HREF="http://docbook.sourceforge.net/projects/dsssl/"
TARGET="_top"
>http://docbook.sourceforge.net/projects/dsssl/</A
>. </B
>The
Document Style Semantics and Specification Language tells
Jade (see <A
HREF="#dsssl-processors"
>Section B.4.1.2</A
>) how to render
a DocBook document into print or on-line
form. The DSSSL is what converts a
<TT
CLASS="sgmltag"
>title</TT
> tag into an
&#60;h1&#62; HTML tag, or to 14 point bold Times Roman for
RTF, for example. Documentation for DSSSL is located at
the same site. Note that modifying the DSSSL doesn't modify
DocBook itself. It merely changes the way the rendered text
looks. The LDP uses a modified DSSSL (see below).</P
></DIV
><DIV
CLASS="formalpara"
><P
><B
>LDP DSSSL <A
HREF="http://www.tldp.org/authors/tools/ldp.dsl"
TARGET="_top"
>http://www.tldp.org/authors/tools/ldp.dsl</A
>. </B
>The LDP DSSSL requires the Norman Walsh version (see
above) but is a slightly modified DSSSL to provide things
like a table of contents.</P
></DIV
><DIV
CLASS="example"
><A
NAME="ex-dsssl"
></A
><P
><B
>Example B-5. <SPAN
CLASS="QUOTE"
>"Installing"</SPAN
> DSSSL style sheets</B
></P
><P
>Create a base directory to store everything such as <TT
CLASS="filename"
>/usr/share/sgml/</TT
>. Copy the DSSSL
style sheets into a sub-directory named
<TT
CLASS="filename"
>dsssl</TT
>.
</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="dsssl-processors"
></A
>B.4.1.2. DSSSL Processors</H3
><P
>&#13;
There are two versions of the <SPAN
CLASS="application"
>Jade</SPAN
> processor: the
original version by James Clark; and an open-source
version of approximately the same program, <SPAN
CLASS="application"
>OpenJade</SPAN
>.
You only need <EM
>one</EM
> of these programs. It should
be installed <EM
>after</EM
> the DTD
and DSSSL have been <SPAN
CLASS="QUOTE"
>"installed."</SPAN
>
</P
><P
></P
><DIV
CLASS="variablelist"
><P
><B
>DSSSL Transformation Tools</B
></P
><DL
><DT
>Jade</DT
><DD
><P
>&#13; <A
HREF="ftp://ftp.jclark.com/pub/jade/"
TARGET="_top"
>ftp://ftp.jclark.com/pub/jade/</A
></P
><P
>Currently, the latest version of the package is <TT
CLASS="filename"
>jade-1.2.1.tar.gz</TT
>.</P
><P
>Jade is the front-end processor for SGML and
XML. It uses the DSSSL and DocBook DTD to perform the
verification and rendering from SGML and XML into the target
format.</P
></DD
><DT
>OpenJade</DT
><DD
><P
><A
HREF="http://openjade.sourceforge.net/"
TARGET="_top"
>http://openjade.sourceforge.net/</A
></P
><P
>An extension of Jade written by the DSSSL
community. Some applications require jade, but are being
updated to support either software package.</P
></DD
></DL
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="dsssl-setup"
></A
>B.4.1.3. System Setup for DSSSL Transformations</H3
><P
></P
><OL
TYPE="1"
><LI
><P
>&#13; Tell your system where to find the SGML_CATALOG_FILES (yes, even if you
are using XML). You can find an example of how to do this in <A
HREF="#ex-catalog-files"
>Example B-1</A
>.
</P
></LI
><LI
><P
>&#13; Download the DSSSL and DTD files and copy them into your working
directory. You can find an example of how to do this in <A
HREF="#ex-dsssl"
>Example B-5</A
> and <A
HREF="#ex-dtd"
>Example B-7</A
>.
</P
></LI
></OL
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="usingjade"
></A
>B.4.1.4. Transformations with DSSSL</H3
><P
>&#13; Once your system is configured (see the previous section), you should
be able to start using <SPAN
CLASS="application"
>jade</SPAN
> to transform
your files from XML to XHTML.
</P
><P
>&#13; To create individual HTML files, point <SPAN
CLASS="application"
>jade</SPAN
>
at the correct DSL (style sheet). The following example uses the LDP
style sheet.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>jade -t xml -i html \
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
<TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; If you would like to produce a single-file HTML page, add the
<TT
CLASS="parameter"
><I
>-V nochunks</I
></TT
> parameter. You can specify the
name of the final HTML file by appending the command with <TT
CLASS="parameter"
><I
>&#13; &#62; <TT
CLASS="replaceable"
><I
>output.html</I
></TT
></I
></TT
>.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>jade -t xml -i html -V nochunks \
-d /usr/local/sgml/dsssl/stylesheets/ldp.dsl#html \
<TT
CLASS="replaceable"
><I
>HOWTO.sgml</I
></TT
> &#62; output.html</B
>
</PRE
></FONT
></TD
></TR
></TABLE
><DIV
CLASS="note"
><A
NAME="dcl-errors"
></A
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
><EM
>Not a function name</EM
> errors</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; If you get an error about <SPAN
CLASS="QUOTE"
>"is not a function name"</SPAN
>, you
will need to add a pointer to <TT
CLASS="filename"
>xml.dcl</TT
>. It has
to be listed immediately before the pointer to your XML
document. Try one of the following locations:
<TT
CLASS="filename"
>/usr/lib/sgml/declaration/xml.dcl</TT
>, or
<TT
CLASS="filename"
>/usr/share/sgml/declaration/xml.dcl</TT
>. Use
<SPAN
CLASS="application"
>locate</SPAN
> to find the file if it is not in
either of those two places. The modified command would be as
follows:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>jade -t xml -i html \
-d /usr/local/sgml/dsssl/docbook/html/ldp.dsl#html \
/usr/lib/sgml/declaration/xml.dcl <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
></TR
></TABLE
></DIV
><P
>&#13; If you would like to create print-friendly files instead of HTML files,
simply change the style sheet that you are using. In the file name
above, note <SPAN
CLASS="QUOTE"
>"html/ldp.dsl"</SPAN
> at the end. Change this to
<SPAN
CLASS="QUOTE"
>"print/docbook.dsl"</SPAN
>, or if you want XHTML output, instead
of HTML, change the file name to <SPAN
CLASS="QUOTE"
>"xhtml/docbook.dsl"</SPAN
>.
</P
><DIV
CLASS="section"
><HR><H4
CLASS="section"
><A
NAME="dsssl-css"
></A
>B.4.1.4.1. Changing CSS Files</H4
><P
>If you want your HTML files to use a specific
<SPAN
CLASS="acronym"
>CSS</SPAN
> stylesheet, you will need to edit
<TT
CLASS="filename"
>ldp.dsl</TT
>. Immediately after
<TT
CLASS="literal"
>;; End of $verbatim-display$ redefinition</TT
>
add the following lines:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;(define %stylesheet-type%
;; The type of the stylesheet to use
"text/css")
(define %stylesheet%
;; Name of the css stylesheet to use, use value #f if you don't want to
;; use css stylesheets
"base.css")
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; Replace <TT
CLASS="filename"
>base.css</TT
> with the name of the
<SPAN
CLASS="acronym"
>CSS</SPAN
> file you would like to use.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="docbook-utils"
></A
>B.4.2. The docbook-utils Package</H2
><P
>The <SPAN
CLASS="application"
>docbook-utils</SPAN
> provide commands like <B
CLASS="command"
>db2html</B
>, <B
CLASS="command"
>db2pdf</B
> and <B
CLASS="command"
>db2ps</B
>, based on the <B
CLASS="command"
>jw</B
> scripts, that is a front-end to <SPAN
CLASS="application"
>Jade</SPAN
>. These tools ease the everyday management of documentation and add comfortable features.</P
><P
>The package, originally created by RedHat and available from <A
HREF="http://sources.redhat.com/docbook-tools/"
TARGET="_top"
>http://sources.redhat.com/docbook-tools/</A
> can be installed on most systems.</P
><DIV
CLASS="example"
><A
NAME="ex-htmloutput"
></A
><P
><B
>Example B-6. Example creating HTML output</B
></P
><P
>After validating your document, simply issue the command
<B
CLASS="command"
>db2html <TT
CLASS="filename"
>mydoc.xml</TT
></B
> to create (a)
HTML file(s). You can also use the
<SPAN
CLASS="application"
>docbook-utils</SPAN
> as validation tools. Remember: when errors occur, always start by solving only the first problem. The rest of the problems may be fixed when you fix the first error.</P
><P
>&#13; If you get errors about a function name, please read .
</P
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="stylesheets"
></A
>B.4.2.1. Using CSS and DSL for pretty output</H3
><P
>You can define your own additional DSL instructions, which can
include a pointer to a personalized CSS file. Sample DSL and CSS files are
provided in <A
HREF="#templates"
>Appendix A</A
>.</P
><P
>The sample DSL file will create a table of contents, and have all
HTML files start with the prefix <TT
CLASS="filename"
>intro2linux-</TT
> and end
with a suffix of <TT
CLASS="filename"
>.html</TT
>. The
<TT
CLASS="varname"
>%stylesheet%</TT
> variable points to the CSS file which
should be called by your HTML file.</P
><P
>To use a specific DSL style sheet the following command should be
used:</P
><P
><B
CLASS="command"
>db2html <TT
CLASS="option"
>-d</TT
> <TT
CLASS="filename"
>mystyle.dsl</TT
> <TT
CLASS="filename"
>mydoc.xml</TT
></B
> </P
><P
>You can compare the result here: <A
HREF="http://tille.xalasys.com/training/unix/"
TARGET="_top"
>http://tille.xalasys.com/training/unix/</A
> is a book formatted with the standard tools; <A
HREF="http://tille.xalasys.com/training/tldp/"
TARGET="_top"
>http://tille.xalasys.com/training/tldp/</A
> is one using personalized DSL and CSS files. Soft tones and special effects, for instance in buttons, were used to achieve maximum effect.</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="xsl"
></A
>B.4.3. XSL</H2
><P
>&#13; There are alternatives to DSSSL and Jade/OpenJade.</P
><P
>When working with DocBook XML, the LDP offers a series of
XSL<A
NAME="AEN2259"
HREF="#FTN.AEN2259"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
>
style sheets to process documents into HTML. These style
sheets create
output files using the XML tool set that are similar to those produced by
the SGML tools using <A
HREF="#dsssl"
>ldp.dsl</A
>.
</P
><P
>The major difference between using <TT
CLASS="filename"
>ldp.dsl</TT
>
and the XSL style sheets is the way that the generation of multiple
files is handled, such as the creation of a separate file for each chapter,
section and appendix. With the SGML tools, such as
<SPAN
CLASS="application"
>jade</SPAN
> or
<SPAN
CLASS="application"
>openjade</SPAN
>, the tool
itself was responsible for generating the separate files. Because of
this, only a single file, <TT
CLASS="filename"
>ldp.dsl</TT
> was necessary as
a customization layer for the standard DocBook DSSSL style sheets.
</P
><P
>With the DocBook XSL style sheets, generation of multiple files is
controlled <EM
>by the style sheet</EM
>. If you want to
generate a single file, you call one style sheet. If you want to generate
multiple files, you call a different style sheet. For that reason the
LDP XSL style sheet distribution is comprised of four files:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
><TT
CLASS="filename"
>tldp-html.xsl</TT
> - style sheet called to generate
a <EM
>single</EM
> file.
</P
></LI
><LI
><P
><TT
CLASS="filename"
>tldp-html-chunk.xsl</TT
><A
NAME="AEN2280"
HREF="#FTN.AEN2280"
><SPAN
CLASS="footnote"
>[3]</SPAN
></A
> - style sheet called to generate
multiple files based on chapter, section and appendix elements.
</P
></LI
><LI
><P
><TT
CLASS="filename"
>tldp-html-common.xsl</TT
> - style sheet containing
the actual XSLT transformations. It is called by the other two HTML
style sheets and is <EM
>never</EM
> directly called.
</P
></LI
><LI
><P
><TT
CLASS="filename"
>tldp-print.xsl</TT
> - style sheet for generation of
XSL Formatting Objects for print output.
</P
></LI
></OL
><P
>&#13; You can find the latest copy of the files at <A
HREF="http://my.core.com/~dhorton/docbook/tldp-xsl/"
TARGET="_top"
>http://my.core.com/~dhorton/docbook/tldp-xsl/</A
>.
The package includes installation instructions which are duplicated
at <A
HREF="http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html"
TARGET="_top"
>http://my.core.com/~dhorton/docbook/tldp-xsl/doc/tldp-xsl-howto.html</A
>. The short version of the install instructions is as follows:
Download and unzip the latest package from the web site. Take the
files from the <TT
CLASS="filename"
>html</TT
>
directory of TLDP-XSL and put them in the
<TT
CLASS="filename"
>html</TT
> directory of Norman Walsh's
stylesheets. Take the file from the TLDP-XSL <TT
CLASS="filename"
>fo</TT
> directory and put it in the Norman Walsh
<TT
CLASS="filename"
>fo</TT
> directory.
</P
><P
>&#13; Once you have installed these files you can use
<SPAN
CLASS="application"
>xsltproc</SPAN
> to generate HTML files from your
XML documents. To transform your XML file(s) into a single-page HTML
document use the following command:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
> xsltproc -o <TT
CLASS="replaceable"
><I
>HOWTO.html</I
></TT
> /usr/local/sgml/stylesheets/tldp-html.xsl <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>To generate a set of linked HTML pages, with a separate page for each
<TT
CLASS="sgmltag"
>chapter</TT
>, <TT
CLASS="sgmltag"
>sect1</TT
> or
<TT
CLASS="sgmltag"
>appendix</TT
>, use the following
command:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
><B
CLASS="command"
>xsltproc /usr/share/sgml/stylesheets/tldp-html-chunk.xsl <TT
CLASS="replaceable"
><I
>HOWTO.xml</I
></TT
></B
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>Note that you never directly call the style sheet
<TT
CLASS="filename"
>tldp-html-common.xsl</TT
>. It is called by both of the
other two style sheets.
</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="xsl-css"
></A
>B.4.3.1. Changing CSS Files</H3
><P
>If you want your HTML files to use a specific
<SPAN
CLASS="acronym"
>CSS</SPAN
> stylesheet, you will need to edit
<TT
CLASS="filename"
>tldp-html-common.xsl</TT
>. Look for a line that
ressembles <TT
CLASS="literal"
>&#60;xsl:param name="html.stylesheet"
select="'style.css'"/&#62;</TT
>.</P
><P
>&#13; Replace <TT
CLASS="filename"
>style.css</TT
> with the name of the
<SPAN
CLASS="acronym"
>CSS</SPAN
> file you would like to use.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="dtd"
></A
>B.5. DocBook DTD</H1
><P
>&#13;
The DocBook DTD defines the structure of a DocBook
document. It contains rules about how the elements
may be used; and what the elements ought to be
describing. For example: it is the DocBook DTD
which states all <TT
CLASS="sgmltag"
>warning</TT
>s are to
<EM
>warn</EM
> the reader (this is the
definition of the element); and may not contain
plain text (this is the content model--and the
bit which forces you to wrap your warning text
in a <TT
CLASS="sgmltag"
>para</TT
> or perhaps a list).
</P
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Versions</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; It is important that you download the
version(s) that match your document. You
may want to configure your system now to
deal with <SPAN
CLASS="QUOTE"
>"all"</SPAN
> DocBook DTDs
if you are going to be editing older LDP
documents. If you are a new author, you
only need the first one listed: XML DTD
for DocBook version 4.2.
</P
></TD
></TR
></TABLE
></DIV
><P
>The XML DTD is available from <A
HREF="http://www.oasis-open.org/docbook/xml/4.2"
TARGET="_top"
>http://www.oasis-open.org/xml/4.2/</A
>.
The LDP prefers this version of the DocBook DTD.
</P
><P
>&#13; If you are going to be working with SGML
versions of DocBook you will need one
(or both) of:
<A
HREF="http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip"
TARGET="_top"
>http://www.oasis-open.org/docbook/sgml/4.1/docbk41.zip</A
>
or <A
HREF="http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip"
TARGET="_top"
>http://www.oasis-open.org/docbook/sgml/3.1/docbk31.zip</A
>
</P
><DIV
CLASS="example"
><A
NAME="ex-dtd"
></A
><P
><B
>Example B-7. <SPAN
CLASS="QUOTE"
>"Installing"</SPAN
> DocBook Document Type Definitions</B
></P
><P
>Create a base directory to store everything such as <TT
CLASS="filename"
>/opt/local/sgml/</TT
>. Copy the DTDs
into a sub-directory named <TT
CLASS="filename"
>dtd</TT
>.
</P
></DIV
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Do not edit DTD files</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; The DocBook standard is described in these
files. If you change these files, you are no longer working
with DocBook.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="doc-components"
></A
>B.6. Formatting Documents</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="toc-articles"
></A
>B.6.1. Inserting a summary on the initial articles page</H2
><P
>A feature that might be valuable in some cases is
the insertion of the summary on the initial page of an
article. DocBook articles do not include it as a standard
feature.</P
><P
>To enable this, it is necessary to modify the style
sheet file.</P
><DIV
CLASS="example"
><A
NAME="AEN2358"
></A
><P
><B
>Example B-8. Style sheet to insert summaries in articles</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;&#60;!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
&#60;!entity html-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook HTML Stylesheet//EN" CDATA DSSSL&#62;
&#60;!entity print-docbook PUBLIC "-//Norman Walsh//DOCUMENT DocBook Print Stylesheet//EN" CDATA DSSSL&#62;
]&#62;
&#60;style-sheet&#62;
&#60;style-specification use="html"&#62;
&#60;style-specification-body&#62;
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
&#60;/style-specification-body&#62;
&#60;/style-specification&#62;
&#60;style-specification use="print"&#62;
&#60;style-specification-body&#62;
; Includes a summary at the beginning of an item.
(define %generate-article-toc% #t)
&#60;/style-specification-body&#62;
&#60;/style-specification&#62;
&#60;external-specification id="html" document="html-docbook"&#62;
&#60;external-specification id="print" document="print-docbook"&#62;
&#60;/style-sheet&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="automatic-indexes"
></A
>B.6.2. Inserting indexes automatically</H2
><P
>&#13; Although DocBook has markups for the composition of
them, indexes are not generated automatically. The
<B
CLASS="command"
>collateindex.pl</B
> command allows indexes
to be generated from the source DocBook for inclusion into the
finished/transformed document.
</P
><P
></P
><OL
TYPE="1"
><LI
><P
>Process the document with
<SPAN
CLASS="application"
>jade</SPAN
> using the style to
<I
CLASS="glossterm"
><SPAN
CLASS="acronym"
>HTML</SPAN
></I
> with
the option <TT
CLASS="option"
>-V html-index</TT
>.</P
><DIV
CLASS="informalexample"
><A
NAME="AEN2377"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$</TT
> <B
CLASS="command"
>jade</B
> <TT
CLASS="option"
>-t sgml \
-d html/docbook.dsl -V html-index document.sgml</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
></P
></DIV
></LI
><LI
><P
>&#13; Generate the <TT
CLASS="filename"
>index.sgml</TT
> file with
<B
CLASS="command"
>collateindex.pl</B
>.
</P
><DIV
CLASS="informalexample"
><A
NAME="AEN2386"
></A
><P
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="prompt"
>bash$ </TT
> <B
CLASS="command"
>perl</B
> <TT
CLASS="option"
>collateindex.pl \
-o index.sgml HTML.index</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
></P
></DIV
></LI
></OL
><P
>For the above example to work, it is necessary to define
an <I
CLASS="glossterm"
>external entity</I
> by calling the
file <TT
CLASS="filename"
>index.sgml</TT
>.</P
><DIV
CLASS="example"
><A
NAME="ex-entity-external-index"
></A
><P
><B
>Example B-9. Configuring an external entity to include the
index</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;!DOCTYPE article PUBLIC "-//OASIS//DTD
DocBook V3.1//EN" [
&#60;!-- Insertion of the index --&#62; &#60;!entity index SYSTEM
"index.sgml"&#62; ]&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>See also <A
HREF="#encoding-index"
>Section D.4</A
> for information
on how to
insert necessary information on the text.</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Odd behavior generating indexes for print versions</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Remember that if you're trying to get Tables of
Contents or Indexes on PS or PDF output you'll need to
run <SPAN
CLASS="application"
>jadetex</SPAN
>
or <SPAN
CLASS="application"
>pdfjadetex</SPAN
>
at least three times. This is required by <SPAN
CLASS="application"
>TeX</SPAN
> but not by DocBook or
related applications.</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="cvs"
></A
>Appendix C. Concurrent Version System (CVS)</H1
><P
>&#13; The LDP provides optional CVS access to its authors. This enables
collaborative writing and has the following positive effects:
</P
><P
></P
><OL
TYPE="1"
><LI
><P
> CVS will keep an off-site backup of your documents. In
the event that you hand over a document to another author,
they can just retrieve the document from CVS and continue
on. In the event you need to go back to a previous version of
a document, you can retrieve it as well. </P
></LI
><LI
><P
>However difficult from an organizational point of view, it's great to have multiple people working on the same
document. CVS enables you to do this. You can have CVS tell you what changes were made by another author
while you were editing your copy, and
integrate those changes.</P
></LI
><LI
><P
>CVS keeps a log of what changes were made. These logs (and
a date stamp) can be placed automatically inside your documents
when they are published.
</P
></LI
><LI
><P
> CVS can be combined with scripts to automatically
update the LDP web site with new documentation as it's written
and submitted. This is not in place yet, but it is a goal.
Currently, CVS updates signal the HOWTO coordinator to
update the LDP web page, meaning that if you use CVS, you're not
required to e-mail your XML code. (Although you do
still need to send the submit list an email when you
are ready for your document to be published, because the whole publishing process has not been fully automated yet.) </P
></LI
></OL
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Access to our CVS repository</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Only authors with at least three submissions get access to our CVS, see <A
HREF="#cvs"
>Appendix C</A
>.</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; You can browse the LDP CVS repository via the web at <A
HREF="http://cvs.tldp.org/"
TARGET="_top"
>http://cvs.tldp.org/</A
>.
</P
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="getaccount"
></A
>C.1. Getting a CVS account</H1
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>CVS accounts will not be granted to all applicants</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>To be granted a CVS account you must qualify under one of the following categories:</P
><P
></P
><UL
><LI
><P
>authors with documents already in the collection who have made a minimum of three submits to the LDP through <TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
></P
></LI
><LI
><P
>technical and language reviewers approved by one of the Review Coordinators</P
></LI
><LI
><P
>new authors in the review process (also requires approval from one of the Review Coordinators)</P
></LI
></UL
><P
>Please do not apply for a CVS account if you do not qualify.</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; If you qualify for a CVS account you may apply for one contacting CVS master Sergiusz <A
HREF="mailto:ser@gnu.org"
TARGET="_top"
>mailto:ser@gnu.org</A
>
Include information about which documents you maintain.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="usingcvs"
></A
>C.2. Using CVS</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="cvs-setup"
></A
>C.2.1. Setting Up Your CVS Account</H2
><P
> First you'll need to get an account at the LDP's CVS
Repository. Please see the notes above on obtaining an account. This repository houses various documents including
HOWTOs and Guides. Documents are sorted by the type of document (for
example a HOWTO or a Guide), and by the markup language the document
uses (for example DocBook or LinuxDoc).
</P
><P
>When your account is ready you can log in using one of the following commands. In all instances <TT
CLASS="replaceable"
><I
>your_userid</I
></TT
> should be replaced by the user name you were issued in the response email. You will be prompted for a password after this first step.</P
><P
></P
><DIV
CLASS="variablelist"
><P
><B
>Initializing Your CVS Account</B
></P
><DL
><DT
>Linux system</DT
><DD
><P
>&#13; <B
CLASS="command"
>cvs <TT
CLASS="parameter"
><I
>-d :pserver:<TT
CLASS="replaceable"
><I
>your_userid</I
></TT
>@cvs.tldp.org:/cvsroot</I
></TT
> login</B
>
</P
></DD
><DT
>Windows system</DT
><DD
><P
><B
CLASS="command"
>set <TT
CLASS="varname"
>CVSROOT</TT
>=":pserver:<TT
CLASS="replaceable"
><I
>your_userid</I
></TT
>@cvs.tldp.org:/cvsroot"</B
>
</P
><P
><B
CLASS="command"
>cvs <TT
CLASS="parameter"
><I
>-d %CVSROOT%</I
></TT
> login</B
></P
></DD
></DL
></DIV
><P
> Wait patiently while the system tries to log you in. It can often take more
that 10-20 seconds for the system to either accept (or reject)
your password. Once you've
used <B
CLASS="command"
>cvs login</B
> for the first time and have
been given access to the system, your password is stored in
<TT
CLASS="filename"
>.cvspass</TT
> and you will not
have to use <B
CLASS="command"
>cvs login</B
>
again. Just set the CVSROOT with the export command listed above
and continue on. If TLDP's CVS server is the only one you work with, you might also add an <B
CLASS="command"
>export <TT
CLASS="varname"
>CVSROOT</TT
></B
> line to your <TT
CLASS="filename"
>~/.bashrc</TT
> shell configuration file.</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="get-repository"
></A
>C.2.2. Getting the Documents</H2
><P
>&#13; You can get the entire repository (about 150 MB) with: <B
CLASS="command"
>cvs checkout LDP</B
>
</P
><P
> Or you can get the source for your own document with:
<B
CLASS="command"
>cvs checkout LDP/howto/docbook/YOUR-HOWTO.xml</B
> OR
<B
CLASS="command"
>cvs checkout LDP/guide/docbook/YOURGUIDE</B
>
</P
><P
>Windows users will need to use a modified version of this command. Instead they should use:
<B
CLASS="command"
>cvs -d %CVSROOT% checkout LDP/howto/docbook/YOUR-HOWTO.xml</B
>
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Keep an overview</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; <B
CLASS="command"
>checkout</B
> will add the full directory structure
from tldp.org on down. Although it doesn't really matter where
you put these files on your local file system you may not want to
bury the directories too deeply.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="cvs-commands"
></A
>C.2.3. CVS Commands</H2
><P
></P
><DIV
CLASS="variablelist"
><P
><B
>CVS Commands: a brief reminder</B
></P
><DL
><DT
>commit</DT
><DD
><P
>&#13; This CVS command will upload your changes to the CVS server.</P
><P
>Please be sure to include a useful description of the changes that have been made to your document.</P
><P
>If you want to bypass the editor screen you can use </P
><P
><B
CLASS="command"
>&#13; cvs <TT
CLASS="option"
>commit</TT
> <TT
CLASS="option"
>-m "A description of the work done on this version of the document."</TT
>
</B
> </P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Ready for publication warning</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>You must still email <TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
>
when you are ready to have your changes
appear on the live site. Your email should include the relative
path to the file(s) in the LDP CVS tree that you wish to
update.
</P
></TD
></TR
></TABLE
></DIV
></DD
><DT
>add</DT
><DD
><P
>&#13; You can add new files to your CVS repository. These may be image
files or additional XML files. First check that your HOWTO is in
its own directory. You may want to coordinate with the
people at <TT
CLASS="email"
>&#60;<A
HREF="mailto:submit@en.tldp.org"
>submit@en.tldp.org</A
>&#62;</TT
> to ensure you can
add graphics or other files to your HOWTO.
</P
><P
>&#13; Copy the files you want to add into your local CVS repository
(where all of your downloaded/working files are). Then:</P
><P
><B
CLASS="command"
>cvs add <TT
CLASS="replaceable"
><I
>filename</I
></TT
></B
> </P
><P
>&#13; After you've added the files, you still need to <B
CLASS="command"
>commit</B
> them to the
repository (see above).
</P
></DD
><DT
>remove</DT
><DD
><P
>&#13; </P
></DD
><DT
>$Id: cvs.xml,v 1.32 2011/01/14 16:24:52 serek Exp $</DT
><DD
><P
>&#13; While this is not a CVS <SPAN
CLASS="QUOTE"
>"command"</SPAN
> it can be used to
automatically insert information about the file including the
time and date it was last modified, the version number it was
assigned by the CVS and the filename of this particular file.
The output will look like this:
<TT
CLASS="computeroutput"
>$Id: cvs.xml,v 1.9 2002/04/21 09:44:26 serek Exp
$</TT
>
</P
></DD
></DL
></DIV
><P
>&#13; If you need to change a file name, you
still need to use the <B
CLASS="command"
>add</B
> command. First remove the copy of the
file from your local disk. Then remove it from the CVS tree with:
<B
CLASS="command"
>cvs remove <TT
CLASS="replaceable"
><I
>filename</I
></TT
></B
>.
As with the <B
CLASS="command"
>add</B
> command, you need to <B
CLASS="command"
>&#62;commit</B
> your
removed file. Finally, now that the old file has been removed, add
your new file using the instructions above (first <B
CLASS="command"
>add</B
> and then
<B
CLASS="command"
>commit</B
> the additional file).
</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="recovery"
></A
>C.2.3.1. Recovering old versions</H3
><P
>&#13; There you are, typing away, when you screw up. Real bad.
Doesn't matter what it is, but suffice it to say that you've
toasted not only the version on your local drive, but
created a new version on the CVS server. What you need
to do is go back in time and resurrect an older
version of your file.
</P
><P
>&#13; To do this, you'll need to know the version number of the
file you want to retrieve. <B
CLASS="command"
>cvs diff</B
>
will give a list of revisions if there are differences. You
can pick the revision number, subtract one, and that is
probably the revision you want to look at.
</P
><P
>&#13; The command</P
><P
><B
CLASS="command"
>cvs -Q update -p -r <TT
CLASS="replaceable"
><I
>revision</I
></TT
>
<TT
CLASS="replaceable"
><I
>filename</I
></TT
></B
> </P
><P
>will output to stdout
the contents of the <TT
CLASS="replaceable"
><I
>revision</I
></TT
> version
of <TT
CLASS="replaceable"
><I
>filename</I
></TT
>. You can pipe it to
<B
CLASS="command"
>more</B
> or redirect the output to a file.
Conveniently, you can redirect stdout to a file called
<TT
CLASS="replaceable"
><I
>filename</I
></TT
>. Your local file
is now the revision you want, and</P
><P
><B
CLASS="command"
>cvs update</B
> </P
><P
>will update the CVS server with the new (old)
version of <TT
CLASS="replaceable"
><I
>filename</I
></TT
>.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="cvs-resources"
></A
>C.3. CVS Resources</H1
><P
> If you're completely new to CVS, there are a few web pages
you may want to look at which can help you out: </P
><P
></P
><UL
><LI
><P
> <A
HREF="http://cvshome.org/docs/blandy.html"
TARGET="_top"
>http://cvshome.org/docs/blandy.html</A
>
</P
></LI
><LI
><P
> <A
HREF="http://www.loria.fr/~molli/cvs/doc/cvs_toc.html"
TARGET="_top"
>http://www.loria.fr/~molli/cvs/doc/cvs_toc.html</A
></P
></LI
></UL
></DIV
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="using-docbook"
></A
>Appendix D. DocBook: Sample Markup</H1
><DIV
CLASS="section"
><H1
CLASS="section"
><A
NAME="writing-docbook"
></A
>D.1. General Tips and Tricks</H1
><P
>&#13; For a general overview of what markup is all about, please read <A
HREF="#ag-markup"
>Chapter 5</A
>
</P
><P
></P
><UL
><LI
><P
>An editor capable of inserting elements according to the
<SPAN
CLASS="acronym"
>DTD</SPAN
> will help a lot since it will enforce
the DTD.
This way you can be sure that no invalid elements were added
anywhere in your document.</P
></LI
><LI
><P
>In order to ensure that future changes are as easy as possible,
authors should try to keep compatibility with
the <SPAN
CLASS="acronym"
>XML</SPAN
> version of the DocBook DTD. This means
keeping element names in lower case, using double quotes in all
attributes, and not omitting end tags. Most tools that
automatically insert elements (like psgml+emacs) follow these
rules automatically or with some fine tuning.</P
></LI
><LI
><P
>Each type of document created has a specific structure. This
document is in <SPAN
CLASS="QUOTE"
>"book"</SPAN
> format. Most authors, however, will
want to use the shorter <SPAN
CLASS="QUOTE"
>"article"</SPAN
> format instead.
Templates are available from <A
HREF="#templates"
>Appendix A</A
>.
</P
></LI
></UL
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="useful-markup"
></A
>D.1.1. Useful markup</H2
><P
><A
HREF="#table-useful-markup"
>Table D-1</A
> shows some markup that
is useful for generating generic documents. Remember that some
elements are valid only on some contexts.</P
><DIV
CLASS="tip"
><P
></P
><TABLE
CLASS="tip"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/tip.gif"
HSPACE="5"
ALT="Tip"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Check several formats</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Sometimes the appearance of a particular tag changes
from one conversion format to another. As a beginner in DocBook writing,
you may wish to see how your document looks in several formats
before you publish them. You are advised to look at how your document is presented in HTML, PDF and PostScript, since these formats will be made available by TLDP once you publish your document.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Better too much than not enough</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>Since the formatting depends on the output style chosen, it's
recommended to use as much markup as possible. Even if the appearance
of the output doesn't seem to change with the standard output
style, there may be specific output formats that will make
these tags stand out.</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="table"
><A
NAME="table-useful-markup"
></A
><P
><B
>Table D-1. Useful markup</B
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><THEAD
><TR
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Description</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Sample markup</TH
><TH
ALIGN="LEFT"
VALIGN="MIDDLE"
>Result</TH
></TR
></THEAD
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>E-mail address</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;email&#62;</TT
>address@domain<TT
CLASS="sgmltag"
>&#60;/email&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="email"
>&#60;<A
HREF="mailto:address@domain"
>address@domain</A
>&#62;</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>About the author</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;author&#62;</TT
>...<TT
CLASS="sgmltag"
>&#60;/author&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(see example below)</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Author's name</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>Mary<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;othername&#62;</TT
>Margaret<TT
CLASS="sgmltag"
>&#60;/othername&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>O'Hara<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Mary Margaret O'Hara</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Keys' name (printings on the keyboard)</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;keycap&#62;</TT
>F1<TT
CLASS="sgmltag"
>&#60;/keycap&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
CLASS="keycap"
>F1</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Symbol represented by the keys</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;keysym&#62;</TT
>KEY_F1<TT
CLASS="sgmltag"
>&#60;/keysym&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="keysym"
>KEY_F1</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Key's code</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;keycode&#62;</TT
>0x3B<TT
CLASS="sgmltag"
>&#60;/keycode&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="keycode"
>0x3B</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Combinations or sequences of keys</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;keycombo&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;keycap&#62;</TT
>Ctrl<TT
CLASS="sgmltag"
>&#60;/keycap&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;keycap&#62;</TT
>S<TT
CLASS="sgmltag"
>&#60;/keycap&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/keycombo&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><B
CLASS="keycap"
>Ctrl</B
>-<B
CLASS="keycap"
>S</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Program Menus</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;guimenu&#62;</TT
>File<TT
CLASS="sgmltag"
>&#60;/guimenu&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="guimenu"
>File</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Menu Items</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;guimenuitem&#62;</TT
>Save<TT
CLASS="sgmltag"
>&#60;/guimenuitem&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="guimenuitem"
>Save</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Menu Sequences</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;menuchoice&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;shortcut&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;keycombo&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;keycap&#62;</TT
>Ctrl<TT
CLASS="sgmltag"
>&#60;/keycap&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;keycap&#62;</TT
>S<TT
CLASS="sgmltag"
>&#60;/keycap&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/keycombo&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/shortcut&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;guimenu&#62;</TT
>File<TT
CLASS="sgmltag"
>&#60;/guimenu&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;guimenuitem&#62;</TT
>Save<TT
CLASS="sgmltag"
>&#60;/guimenuitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/menuchoice&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="guimenu"
>File</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Save</SPAN
> (<B
CLASS="shortcut"
><B
CLASS="keycap"
>Ctrl</B
>-<B
CLASS="keycap"
>S</B
></B
>)</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Mouse Button</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;mousebutton&#62;</TT
>left<TT
CLASS="sgmltag"
>&#60;/mousebutton&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="mousebutton"
>left</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Application Names</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;application&#62;</TT
>application<TT
CLASS="sgmltag"
>&#60;/application&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><SPAN
CLASS="application"
>application</SPAN
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Text Bibliographical Reference</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="sgmltag"
>&#60;citation&#62;</TT
>reference<TT
CLASS="sgmltag"
>&#60;/citation&#62;</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>[<SPAN
CLASS="citation"
>reference</SPAN
>]</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Quote</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;blockquote&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;attribution&#62;</TT
>Text Author<TT
CLASS="sgmltag"
>&#60;/attribution&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Quote Text.<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/blockquote&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
><A
NAME="AEN2742"
></A
><TABLE
BORDER="0"
WIDTH="100%"
CELLSPACING="0"
CELLPADDING="0"
CLASS="BLOCKQUOTE"
><TR
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
><TD
WIDTH="80%"
VALIGN="TOP"
><P
>Quote Text.</P
></TD
><TD
WIDTH="10%"
VALIGN="TOP"
>&nbsp;</TD
></TR
><TR
><TD
COLSPAN="2"
ALIGN="RIGHT"
VALIGN="TOP"
>--<SPAN
CLASS="attribution"
>Text Author</SPAN
></TD
><TD
WIDTH="10%"
>&nbsp;</TD
></TR
></TABLE
></P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Index</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(NA)</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>See <A
HREF="#encoding-index"
>Section D.4</A
>.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>File Names</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;filename&#62;</TT
>file<TT
CLASS="sgmltag"
>&#60;/filename&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="filename"
>file</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Directories</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;filename id="directory"&#62;</TT
>directory<TT
CLASS="sgmltag"
>&#60;/filename&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TT
CLASS="filename"
>directory/</TT
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Emphasize Text<A
NAME="AEN2768"
HREF="#FTN.AEN2768"
><SPAN
CLASS="footnote"
>[a]</SPAN
></A
>
</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;emphasis&#62;</TT
>text<TT
CLASS="sgmltag"
>&#60;/emphasis&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><EM
>text</EM
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Footnotes</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;footnote&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Footnote text<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/footnote&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(See note at the end of this table for an example)</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>URLs</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;ulink url="http://www.conectiva.com"&#62;</TT
>Conectiva S.A.<TT
CLASS="sgmltag"
>&#60;/&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><A
HREF="http://www.conectiva.com"
TARGET="_top"
>Conectiva S.A.</A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Itemized (unnumbered) List</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;itemizedlist&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>item<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>item<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/itemizedlist&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
></P
><UL
><LI
><P
>item</P
></LI
><LI
><P
>item</P
></LI
></UL
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Ordered (numbered) List</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;orderedlist&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>item<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>item<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/orderedlist&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
></P
><OL
TYPE="1"
><LI
><P
>item</P
></LI
><LI
><P
>item</P
></LI
></OL
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Segmented List</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;segmentedlist&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Binary to decimal conversion<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;segtitle&#62;</TT
>Binary<TT
CLASS="sgmltag"
>&#60;/segtitle&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;segtitle&#62;</TT
>Decimal<TT
CLASS="sgmltag"
>&#60;/segtitle&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/seglistitem&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>00<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>0<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/seglistitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;seglistitem&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>01<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>1<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/seglistitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;seglistitem&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>10<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
><TT
CLASS="sgmltag"
>&#60;seg&#62;</TT
>2<TT
CLASS="sgmltag"
>&#60;/seg&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/seglistitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/segmentedlist&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
><B
>Binary to Decimal Conversion</B
></P
><P
><B
>Binary: </B
>00</P
><P
><B
>Decimal: </B
>0</P
><P
><B
>Binary: </B
>01</P
><P
><B
>Decimal: </B
>1</P
><P
><B
>Binary: </B
>10</P
><P
><B
>Decimal: </B
>2</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Variable List</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;variablelist&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;varlistentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;term&#62;</TT
>Entry 1<TT
CLASS="sgmltag"
>&#60;/term&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Description<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/varlistentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;varlistentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;term&#62;</TT
>Entry 2<TT
CLASS="sgmltag"
>&#60;/term&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Description<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/listitem&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/varlistentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/variablelist&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
></P
><DIV
CLASS="variablelist"
><DL
><DT
>Entry 1</DT
><DD
><P
>Description</P
></DD
><DT
>Entry 2</DT
><DD
><P
>Description</P
></DD
></DL
></DIV
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Simple Lists</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;simplelist type="horiz" columns="3"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>1<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>2<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>3<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>4<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>5<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>6<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/simplelist&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;simplelist type="inline"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>A<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>B<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>C<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>D<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>E<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;member&#62;</TT
>F<TT
CLASS="sgmltag"
>&#60;/member&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/simplelist&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><P
></P
><TABLE
BORDER="0"
><TBODY
><TR
><TD
>1</TD
><TD
>2</TD
><TD
>3</TD
></TR
><TR
><TD
>4</TD
><TD
>5</TD
><TD
>6</TD
></TR
></TBODY
></TABLE
><P
></P
>A, B, C, D, E, F</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Pictures</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(NA)</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>See <A
HREF="#inserting-pictures"
>Section D.5</A
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Glossary</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;glossentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;glossterm&#62;</TT
>Term<TT
CLASS="sgmltag"
>&#60;/glossterm&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;glossdef&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Definition<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/glossdef&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/glossentry&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(See the glossary at the end of this document)</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>Crossed References</TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;section id="secao"&#62;</TT
>
...
<TT
CLASS="sgmltag"
>&#60;/section&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;section id="reference the other section"&#62;</TT
>
...
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Please, see<TT
CLASS="sgmltag"
>&#60;xref linkend="secao" /&#62;</TT
> for more information.</PRE
></FONT
></TD
></TR
></TABLE
></TD
><TD
ALIGN="LEFT"
VALIGN="MIDDLE"
>(NA)</TD
></TR
></TBODY
><TR
><TD
COLSPAN="3"
>Notes:<BR><A
NAME="FTN.AEN2768"
>a. </A
>Text can be emphasized in a few ways. The most
common ways are italics and bold. DocBook, however, supports only
italics. The use of bold requires additional settings on the
style sheet used.<BR></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="section"
></A
>D.2. <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> and <TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
>: what's the difference?</H1
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Acknowledgment</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; These notes were provided by:
<A
HREF="http://geekhavoc.com"
TARGET="_top"
>John Daily</A
> and
Saqib Ali (<TT
CLASS="email"
>&#60;<A
HREF="mailto:saqib@seagate.com"
>saqib@seagate.com</A
>&#62;</TT
>).
</P
></TD
></TR
></TABLE
></DIV
><P
>&#13; <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> versus <TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
> is largely a
question of flexibility. The stylesheets can make a
<TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> in a <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> look just
like a <TT
CLASS="sgmltag"
>&#60;sect2&#62;</TT
> within a <TT
CLASS="sgmltag"
>&#60;sect1&#62;</TT
>, so there's no output advantage.
</P
><P
>&#13; But, a <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> within a
<TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> can be extracted into its own
top-level section, nested even more deeply, or moved to an
entirely different part of the document, without it and its own
<TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> children being renamed. That is not true of the
numbered section tags, which are very sensitive to
rearrangements. This can be easier for authors who are new to
DocBook than using <TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
>.
</P
><P
>&#13; The main idea behind creating structured data is that it should be easy
to access and query. One should be able to retrieve a subsection of any
structured data, by using querying languages for XML (<SPAN
CLASS="application"
>XPath</SPAN
> and <SPAN
CLASS="application"
>XQuery</SPAN
>).
<TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
> are useful when traversing a document using <SPAN
CLASS="application"
>XPath</SPAN
>/<SPAN
CLASS="application"
>XQuery</SPAN
>.
<TT
CLASS="sgmltag"
>&#60;sectN&#62;</TT
> gives more flexibility, and control while writing an <SPAN
CLASS="application"
>XPath</SPAN
>
expression.
</P
><P
>&#13; A well-defined, valid and well-structured document makes it easier for
one to write <SPAN
CLASS="application"
>XPath</SPAN
>/<SPAN
CLASS="application"
>Query</SPAN
> to retreive <SPAN
CLASS="QUOTE"
>"specific"</SPAN
> data from a document.
For example you can use <SPAN
CLASS="application"
>XPath</SPAN
> to retrieve information in the
<TT
CLASS="sgmltag"
>&#60;sect3&#62;</TT
> block with certain attributes.
However if you just used <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
> for all subsections,
it becomes harder to retrieve the block of information that you need.
</P
><P
>&#13; So which one should you use? The one you feel most
comfortable with is a good place to start. This document
is written with <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
>s. You may,
or may not, think this is a good idea. :)
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="commandprompt"
></A
>D.3. Command Prompts</H1
><P
>&#13; There are likely as many ways of doing this as there are DocBook
authors; however, here are two ways that you might find useful.
Thanks to <A
HREF="http://www.appaji.net/"
TARGET="_top"
>Y Giridhar Appaji Nag</A
>
and
<A
HREF="http://linux-ip.net/"
TARGET="_top"
>Martin Brown</A
>
for the markup used here.
</P
><DIV
CLASS="example"
><A
NAME="ex-programlisting"
></A
><P
><B
>Example D-1. Command Prompt with <TT
CLASS="sgmltag"
>programlisting</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="sgmltag"
>&#60;programlisting&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;prompt&#62;</TT
># <TT
CLASS="sgmltag"
>&#60;/prompt&#62;</TT
><TT
CLASS="sgmltag"
>&#60;userinput&#62;</TT
><TT
CLASS="sgmltag"
>&#60;command&#62;</TT
>cd<TT
CLASS="sgmltag"
>&#60;/command&#62;</TT
> /some/dir<TT
CLASS="sgmltag"
>&#60;/userinput&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;prompt&#62;</TT
># <TT
CLASS="sgmltag"
>&#60;/prompt&#62;</TT
><TT
CLASS="sgmltag"
>&#60;userinput&#62;</TT
><TT
CLASS="sgmltag"
>&#60;command&#62;</TT
>ls<TT
CLASS="sgmltag"
>&#60;/command&#62;</TT
> -l<TT
CLASS="sgmltag"
>&#60;/userinput&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/programlisting&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>Displays as:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="prompt"
># </TT
><TT
CLASS="userinput"
><B
><B
CLASS="command"
>cd</B
> /some/dir</B
></TT
>
<TT
CLASS="prompt"
># </TT
><TT
CLASS="userinput"
><B
><B
CLASS="command"
>ls</B
> -l</B
></TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="example"
><A
NAME="ex-screen"
></A
><P
><B
>Example D-2. Command Prompt with <TT
CLASS="sgmltag"
>screen</TT
></B
></P
><P
>&#13; First create a general entity in the internal subset at the very
beginning of your document. This entity will define a name for the
shortcut which you can use to display the full prompt at any point
in your document.
<TT
CLASS="literal"
>&#60;!ENTITY prompt "&#60;prompt&#62;[user@machine
~/dir]$&#60;/prompt&#62;"&#62;</TT
>
</P
><P
>&#13; For more information about entities, read <A
HREF="#tools-entities"
>Section D.8</A
>.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="sgmltag"
>&#60;screen&#62;</TT
>
&#38;prompt; <TT
CLASS="sgmltag"
>&#60;userinput&#62;</TT
>cd /some/dir<TT
CLASS="sgmltag"
>&#60;/userinput&#62;</TT
>
&#38;prompt; <TT
CLASS="sgmltag"
>&#60;userinput&#62;</TT
>ls -l<TT
CLASS="sgmltag"
>&#60;/userinput&#62;</TT
> <TT
CLASS="sgmltag"
>&#60;/screen&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>Displays as:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>
<TT
CLASS="prompt"
>[user@machine ~/dir]$ </TT
><TT
CLASS="userinput"
><B
>cd /some/dir</B
></TT
>
<TT
CLASS="prompt"
>[user@machine ~/dir]$ </TT
><TT
CLASS="userinput"
><B
>ls -l</B
></TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>&#13; If you would like to add the output of your commands you can add
<TT
CLASS="sgmltag"
>&#60;computeroutput&#62;</TT
> text<TT
CLASS="sgmltag"
>&#60;/computeroutput&#62;</TT
> within the
<TT
CLASS="sgmltag"
>&#60;screen&#62;</TT
> or <TT
CLASS="sgmltag"
>&#60;programlisting&#62;</TT
>
as appropriate.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="encoding-index"
></A
>D.4. Encoding Indexes</H1
><P
>The generation of indexes depends on the markups inserted in
the text.</P
><P
>Such markups will be processed afterwards by an external
tool and will generate the index. An example of such a
tool is the <TT
CLASS="filename"
>collateindex.pl</TT
> script
(see <A
HREF="#automatic-indexes"
>Section B.6.2</A
>). Details about the
process used to generate these indexes are shown in <A
HREF="#automatic-indexes"
>Section B.6.2</A
>.</P
><P
>The indexes have nesting levels. The markup of an index is
done by the code <A
HREF="#example-code-index"
>Example D-3</A
>.</P
><DIV
CLASS="example"
><A
NAME="example-code-index"
></A
><P
><B
>Example D-3. Code for the generation of an index</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;indexterm&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;primary&#62;</TT
>Main level<TT
CLASS="sgmltag"
>&#60;/primary&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;secondary&#62;</TT
>Second level<TT
CLASS="sgmltag"
>&#60;/secondary&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;tertiary&#62;</TT
>Third level<TT
CLASS="sgmltag"
>&#60;/tertiary&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/indexterm&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>It is possible to refer to chapters, sections, and other
parts of the document using the <I
CLASS="glossterm"
>attribute</I
>
<TT
CLASS="sgmltag"
>zone</TT
>.</P
><DIV
CLASS="example"
><A
NAME="index-zone"
></A
><P
><B
>Example D-4. Use of the attribute <TT
CLASS="sgmltag"
>zone</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;section id="encoding-index"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Encoding Indexes<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;indexterm zone="encoding-index"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;primary&#62;</TT
>edition<TT
CLASS="sgmltag"
>&#60;/primary&#62;</TT
> <TT
CLASS="sgmltag"
>&#60;secondary&#62;</TT
>index<TT
CLASS="sgmltag"
>&#60;/secondary&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/indexterm&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>
The generation of indexes depend on the inserted markups on the text.
<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>The <A
HREF="#index-zone"
>Example D-4</A
> has the code used to
generate the entry of this edition on the index. In fact, since
the attribute <TT
CLASS="sgmltag"
>zone</TT
> is used,
the index statement could be located anywhere in the document or
even in a separate file. </P
><P
>However, to facilitate maintenance the entries for the index
were all placed after the text to which it refers. </P
><DIV
CLASS="example"
><A
NAME="ex-index"
></A
><P
><B
>Example D-5. Usage of values <TT
CLASS="sgmltag"
>startofrange</TT
> and <TT
CLASS="sgmltag"
>endofrange</TT
> on the attribute<TT
CLASS="sgmltag"
>class</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13; <TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Typing the text normally
sometimes there's the need of
<TT
CLASS="sgmltag"
>&#60;indexterm class="startofrange"
id="example-band-index"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;primary&#62;</TT
>examples<TT
CLASS="sgmltag"
>&#60;/primary&#62;</TT
> <TT
CLASS="sgmltag"
>&#60;secondary&#62;</TT
>index<TT
CLASS="sgmltag"
>&#60;/secondary&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/indexterm&#62;</TT
> mark large amounts of
text.<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Keep inserting the paragraphs
normally.<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Until the end of the section
intended to be indexed. <TT
CLASS="sgmltag"
>&#60;indexterm
startref="example-band-index" class="endofrange"&#62;</TT
>.
<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="inserting-pictures"
></A
>D.5. Inserting Pictures</H1
><P
>It is necessary to insert pictures formats for all possible
finished document types. For example: JPG files for web pages and EPS
for PostScript and PDF files.</P
><P
>If you use the TeX format you'll need the images as
a PostScript file. For on-line publishing you can use any
kind of common image file, such as <SPAN
CLASS="acronym"
>JPG</SPAN
>,
<SPAN
CLASS="acronym"
>GIF</SPAN
> or <SPAN
CLASS="acronym"
>PNG</SPAN
>.</P
><P
>&#13; The easiest way to insert pictures is to use the <TT
CLASS="sgmltag"
>fileref</TT
> attribute. Usually pictures are
generated in <SPAN
CLASS="acronym"
>JPG</SPAN
> and in PostScript (PS or EPS).
</P
><DIV
CLASS="example"
><A
NAME="ex-picture-fileref"
></A
><P
><B
>Example D-6. Inserting a picture</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;figure&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Picture's
Title<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
> <TT
CLASS="sgmltag"
>&#60;graphic fileref="images/file"&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/graphic&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/figure&#62;</TT
> </PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>Replacing <TT
CLASS="sgmltag"
>&#60;figure&#62;</TT
> by
<TT
CLASS="sgmltag"
>&#60;informalfigure&#62;</TT
> eliminates the
need to insert a title for the picture.</P
><P
>There's still the <TT
CLASS="sgmltag"
>float</TT
>
attribute on which the value <TT
CLASS="literal"
>0</TT
> indicates that
the picture should be placed exactly where the tag appears. The
value <TT
CLASS="literal"
>1</TT
> allows the picture to be moved to a
more convenient location (this location can be described on the
style sheet, or it can be controlled by the application).</P
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="acceptedgfx"
></A
>D.5.1. Graphics formats</H2
><P
> When
submitting graphics to the LDP, please submit one
set of graphics in <TT
CLASS="filename"
>.eps</TT
>, and
another in <TT
CLASS="filename"
>.gif</TT
>,
<TT
CLASS="filename"
>.jpg</TT
> or <TT
CLASS="filename"
> .png</TT
>. The preferred format is
<TT
CLASS="filename"
> .png</TT
> or <TT
CLASS="filename"
>.jpg</TT
> due to patent problems with
<TT
CLASS="filename"
>.gif</TT
>. </P
><P
>&#13; You can use <TT
CLASS="filename"
>.jpg</TT
> files for
continuous-tone images such as photos or images with gradual
changes in color. Use <TT
CLASS="filename"
>.png</TT
>
for simple images like diagrams, some screen shots, and images
with a low number of colors. </P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="inserting-figures-mediaobject"
></A
>D.5.2. Alternative Methods</H2
><P
>The first alternative to <A
HREF="#ex-picture-fileref"
>Example D-6</A
>
is to eliminate the <TT
CLASS="sgmltag"
>&#60;figure&#62;</TT
> or
<TT
CLASS="sgmltag"
>&#60;informalfigure&#62;</TT
> elements.</P
><P
>Another interesting alternative when you have
decided to publish the text on media where pictures
are not accepted, is the use of a wrapper, <TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
>.</P
><DIV
CLASS="example"
><A
NAME="former-figure-imageobject"
></A
><P
><B
>Example D-7. Using <TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
></B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;figure&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Title<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;mediaobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;imagedata fileref="images/file.eps" format="EPS"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/imageobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;imagedata fileref="images/file.jpg" format="JPG"&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/imageobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;textobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;phrase&#62;</TT
>Here there's an image of this example<TT
CLASS="sgmltag"
>&#60;/phrase&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/textobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;caption&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>Image Description. Optional. <TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/caption&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/mediaobject&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/figure&#62;</TT
> </PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>Files using the following formats are available BMP, CGM-BINARY, CGM-CHAR, CGM-CLEAR, DITROFF, DVI, EPS, EQN, FAX, GIF, GIF87A, GIF89A, IGES, JPEG, JPG, LINESPECIFIC, PCX, PIC, PS, SGML, TBL, TEX, TIFF, WMF, WPG.</P
><P
>This method presents an advantage: a better
control of the application. The elements <TT
CLASS="sgmltag"
>&#60;imageobject&#62;</TT
> are consecutively tested
until one of them is accepted. If the output format does not
support images the <TT
CLASS="sgmltag"
>&#60;textobject&#62;</TT
>
element will be used. However, the biggest advantage in usage
of the format <A
HREF="#former-figure-imageobject"
>Example D-7</A
>
is that in DocBook <TT
CLASS="literal"
>5.0</TT
>, the <TT
CLASS="sgmltag"
>&#60;graphic&#62;</TT
> element will cease to
exist.</P
><P
>As a disadvantage, there is the need for more than one
representation code of the same information. It is up to the
author to decide how they will implement illustrations and
pictures in the document, but for compatibility with future
versions <EM
>I recommend</EM
> the use of this method
for pictures and graphics.</P
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Title page exception</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; <TT
CLASS="sgmltag"
>&#60;mediaobject&#62;</TT
>s will not display if they are
used on a title page. For more information read:
<A
HREF="http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage"
TARGET="_top"
>http://www.sagehill.net/docbookxsl/HtmlCustomEx.html#HTMLTitlePage</A
>
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>ASCII Images</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; You may also want to try converting your image to an ASCII
representation of the file. <SPAN
CLASS="application"
>JavE</SPAN
>
(Java ASCII Versatile Editor) can do this conversion for you.
It can be downloaded from <A
HREF="http://www.jave.de/"
TARGET="_top"
>http://www.jave.de/</A
>. It has an easy to use GUI interface.
</P
><P
>&#13; If you're more command-line oriented you may want to try:
<SPAN
CLASS="application"
>tgif</SPAN
>
(<A
HREF="http://bourbon.usc.edu:8001/tgif/"
TARGET="_top"
>http://bourbon.usc.edu:8001/tgif/</A
>) and
AA-Lib (<A
HREF="http://aa-project.sourceforge.net/"
TARGET="_top"
>http://aa-project.sourceforge.net/</A
>).
</P
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="metadata-markup"
></A
>D.6. Markup for Metadata</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="crediting"
></A
>D.6.1. Crediting Translators, Converters and Co-authors</H2
><P
>There are several ways that these folks, as well as other
contributors to your document, can be given some recognition for
the help they've given you.</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="crediting-othercredit"
></A
>D.6.1.1. <TT
CLASS="sgmltag"
>&#60;othercredit&#62;</TT
></H3
><P
>All translators, converters and co-authors
should be credited with an
<TT
CLASS="sgmltag"
>&#60;othercredit&#62;</TT
> tag entry.
To properly credit a translator or converter, use the <TT
CLASS="sgmltag"
>&#60;othercredit&#62;</TT
> tag with
the <TT
CLASS="sgmltag"
>role</TT
>
attribute set to <SPAN
CLASS="QUOTE"
>"converter"</SPAN
> or
<SPAN
CLASS="QUOTE"
>"translator"</SPAN
>,
as indicated in the example below:</P
><DIV
CLASS="example"
><A
NAME="ex-othercredit"
></A
><P
><B
>Example D-8. Other Credit</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="sgmltag"
>&#60;othercredit role='converter'&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>David<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>Merrill<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;contrib&#62;</TT
>Conversion from HTML to DocBook v3.1 (SGML).<TT
CLASS="sgmltag"
>&#60;/contrib&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/othercredit&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="crediting-editors"
></A
>D.6.1.2. Crediting Editors and Reviewers</H3
><P
>&#13; To help track the review process all new documents must include a
reference to the reviewers for the <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/techreview.html"
TARGET="_top"
>technical</A
>,
<A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/languagereview.html"
TARGET="_top"
>language</A
>
and <A
HREF="http://www.tldp.org/HOWTO/LDP-Reviewer-HOWTO/metadatareview.html"
TARGET="_top"
>metadata</A
>
reviews.
</P
><DIV
CLASS="example"
><A
NAME="ex-editor"
></A
><P
><B
>Example D-9. Editor</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="sgmltag"
>&#60;editor&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>Tabatha<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>Marshall<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;contrib&#62;</TT
>Language review of version 0.8<TT
CLASS="sgmltag"
>&#60;/contrib&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/editor&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="crediting-version"
></A
>D.6.2. <TT
CLASS="sgmltag"
>&#60;revremark&#62;</TT
>s</H2
><P
>Within the <TT
CLASS="sgmltag"
>&#60;revision&#62;</TT
>
tag hierarchy is a tag called <TT
CLASS="sgmltag"
>&#60;revremark&#62;</TT
>. Within this tag,
you can make any brief notes you wish about each
particular revision of your document.</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="acceptedrev"
></A
>D.6.3. Revision History</H2
><P
> The <TT
CLASS="sgmltag"
>&#60;revhistory&#62;</TT
> tag should be used to denote
the various revisions of the document. Specify the date, revision
number and comments regarding what has changed.</P
><P
>&#13; Revisions should be listed with the most-recent version at the
top (list in descending order).
</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="accepteddates"
></A
>D.6.4. Date formats</H2
><P
> The <TT
CLASS="sgmltag"
>&#60;pubdate&#62;</TT
> tag in your header should list
the publication date of this particular version of the document
(coincide with the revision date). It should be in the following
format: </P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
><TT
CLASS="sgmltag"
>&#60;pubdate&#62;</TT
>2002-04-25<TT
CLASS="sgmltag"
>&#60;/pubdate&#62;</TT
></PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; The date is in the format YYYY-MM-DD, which is one of the <A
HREF="http://www.w3.org/TR/NOTE-datetime"
TARGET="_top"
>ISO 8601</A
>
standard formats for representing dates. For you Yanks out
there (me too), think of it as going from the largest unit of
time to the smallest.
</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="sampleai"
></A
>D.6.5. Sample Article (or Book) Information Element</H2
><P
> Here is a sample of a complete DocBook (SGML or XML)
<TT
CLASS="sgmltag"
>&#60;articleinfo&#62;</TT
> element
which contains some of the items and constructs previously
described. </P
><DIV
CLASS="example"
><A
NAME="sample-metadata"
></A
><P
><B
>Example D-10. Sample Meta Data</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;&#60;!--
Above these lines in a typical DocBook article would be the article
element (the immediate parent of the articleinfo element) and above
that typically, the DOCTYPE declaration and internal subset.
--&#62;
<TT
CLASS="sgmltag"
>&#60;articleinfo&#62;</TT
>
&#60;!--
Use "HOWTO", "mini HOWTO", "FAQ" in title, if appropriate
--&#62;
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Sample HOWTO<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;author&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>Your Firstname<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>Your Surname<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;affiliation&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;address&#62;</TT
><TT
CLASS="sgmltag"
>&#60;email&#62;</TT
>your email<TT
CLASS="sgmltag"
>&#60;/email&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/address&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/affiliation&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/author&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;editor&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>Tabatha<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>Marshall<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;contrib&#62;</TT
>Language review of version 0.8<TT
CLASS="sgmltag"
>&#60;/contrib&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/editor&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;othercredit role='converter'&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
>David<TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
>Merrill<TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;contrib&#62;</TT
>Conversion from HTML to DocBook v3.1 (SGML).<TT
CLASS="sgmltag"
>&#60;/contrib&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/othercredit&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;pubdate&#62;</TT
>YYYY-MM-DD<TT
CLASS="sgmltag"
>&#60;/pubdate&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revhistory&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revision&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revnumber&#62;</TT
>1.0<TT
CLASS="sgmltag"
>&#60;/revnumber&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;date&#62;</TT
>YYYY-MM-DD<TT
CLASS="sgmltag"
>&#60;/date&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;authorinitials&#62;</TT
>ABC<TT
CLASS="sgmltag"
>&#60;/authorinitials&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/revremark&#62;</TT
>first official release<TT
CLASS="sgmltag"
>&#60;/revremark&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/revision&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revision&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revnumber&#62;</TT
>0.9<TT
CLASS="sgmltag"
>&#60;/revnumber&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;date&#62;</TT
>YYYY-MM-DD<TT
CLASS="sgmltag"
>&#60;/date&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;authorinitials&#62;</TT
>ABC<TT
CLASS="sgmltag"
>&#60;/authorinitials&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;revremark&#62;</TT
>First draft<TT
CLASS="sgmltag"
>&#60;/revremark&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/revision&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/revhistory&#62;</TT
>
&#60;!--
Provide a good abstract; a couple of sentences is sufficient
--&#62;
<TT
CLASS="sgmltag"
>&#60;abstract&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>
This is a sample DocBook (SGML or XML) HOWTO which has been
constructed to serve as a template.
<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/abstract&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/articleinfo&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="doc-bib"
></A
>D.7. Bibliographies</H1
><P
>&#13; Not everyone will choose to use the correct formatting for a
bibliography. Most will use a list of some kind. And that's ok. But
when you're ready to move to the next level, here's how to do it.
</P
><P
>&#13; Below are two examples of bibliographic entries. The first is a very
simple entry. It has only a title, URL and possibly a short
description (abstract). The second is a little more complex and is
for a full entry (for instance a book) with an ISBN, publisher and copyright
date.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>DocBook requirements for bibliographic references</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; At least one element within <TT
CLASS="sgmltag"
>&#60;biblioentry&#62;</TT
> is
required, but it doesn't matter which one you have. So you might
have a <TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>, or a URL (<TT
CLASS="sgmltag"
>&#60;bibliosource&#62;</TT
>), or an
<TT
CLASS="sgmltag"
>&#60;author&#62;</TT
>, or, ...
</P
><P
>&#13; For a full list of all options, visit <A
HREF="http://docbook.org/tdg/en/html/biblioentry.html"
TARGET="_top"
>http://docbook.org/tdg/en/html/biblioentry.html</A
>. For
more examples visit <A
HREF="http://docbook.org/tdg/en/html/bibliography.html"
TARGET="_top"
>http://docbook.org/tdg/en/html/bibliography.html</A
>.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="caution"
><P
></P
><TABLE
CLASS="caution"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/caution.gif"
HSPACE="5"
ALT="Caution"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Displaying <TT
CLASS="sgmltag"
>&#60;abstract&#62;</TT
> content</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; By default <TT
CLASS="sgmltag"
>&#60;abstract&#62;</TT
>s do not display on web
pages. You need to modify the <TT
CLASS="filename"
>biblio.xsl</TT
> file.
Do a search for the word <SPAN
CLASS="QUOTE"
>"abstract"</SPAN
> and then add
this information inside the &#60;xsl:template&#62; tags. If that
doesn't make sense, don't worry about it too much, but do be
aware that it's required for the abstracts to show up.
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;div xmlns="http://www.w3.org/1999/xhtml" class="{name(.)}"&#62;
&#60;xsl:apply-templates mode="bibliography.mode"/&#62;
&#60;/div&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="example"
><A
NAME="ex-bib"
></A
><P
><B
>Example D-11. A Bibliography</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;<TT
CLASS="sgmltag"
>&#60;bibliography&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Bibliography title<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;bibliodiv&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Section title<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;biblioentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
>Book or Web Site Title<TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;bibliosource&#62;</TT
><TT
CLASS="sgmltag"
>&#60;ulink url=""/&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/bibliosource&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;abstract&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/abstract&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/biblioentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;biblioentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;title&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/title&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;bibliosource&#62;</TT
><TT
CLASS="sgmltag"
>&#60;ulink url=""/&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/bibliosource&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;author&#62;</TT
><TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/author&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;copyright&#62;</TT
><TT
CLASS="sgmltag"
>&#60;year&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/year&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;holder&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/holder&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/copyright&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;editor&#62;</TT
><TT
CLASS="sgmltag"
>&#60;firstname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/firstname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;surname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/surname&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/editor&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;isbn&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/isbn&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;publisher&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;publishername&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/publishername&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/publisher&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;abstract&#62;</TT
><TT
CLASS="sgmltag"
>&#60;/abstract&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/biblioentry&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/bibliodiv&#62;</TT
>
<TT
CLASS="sgmltag"
>&#60;/bibliography&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; View <A
HREF="#bibliography"
><I
>References</I
></A
> to see this in action.
</P
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tools-entities"
></A
>D.8. Entities (shortcuts,
text macros and re-usable text)</H1
><P
>&#13; There may be some segments of text, or markup
that you want to use over and over again. Instead
of typing it up multiple times (and then having
to edit it multiple times if you want to make
a change) you can use <I
CLASS="glossterm"
>external
entities</I
>. Entities can give you a short
cut to:
re-using whole documents, text snippets, and
special markup. Some common ways to use an
entity would be for:
</P
><P
></P
><UL
><LI
><DIV
CLASS="formalpara"
><P
><B
>text macros
for markup. </B
>An example would be a company
URL. By using a parameter entity you
could refer simply to &#38;my-company-url;
instead of typing out the full &#60;ulink
url="http://foo.bar"&#62;Foo.bar&#60;/ulink&#62;
each time. </P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>software
license. </B
>Such as the GNU Free
Documentation License: it is long. And must
be included in full in each document. By
leaving the license in a separate file you can
easily include it in many documents without
having to redo the markup each time. </P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
>repeated
text. </B
>For instance an introduction to a
topic which is included both as a summary in
one section and as an introduction to the full
information in another. Saves on editing time if
you need to make changes to both sets of text.
</P
></DIV
></LI
></UL
><DIV
CLASS="example"
><A
NAME="ex-entities"
></A
><P
><B
>Example D-12. Adding
Entities</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;?xml version="1.0" encoding="UTF-8"?&#62;
&#60;!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
&#60;-- I can add comments here --&#62;
&#60;!ENTITY shortcut "Replace 'shortcut' with this text."&#62;
&#60;!ENTITY sc-to-a-file SYSTEM "anotherfile.xml"&#62;
&#60;-- note: the square bracket on the third line is closed on the next
line--&#62; ]&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>&#13; To use these entities simply insert the name
you gave the entity between a <SPAN
CLASS="QUOTE"
>"&#38;"</SPAN
> (ampersand) and a <SPAN
CLASS="QUOTE"
>";"</SPAN
> (semicolon). For
example: <SPAN
CLASS="QUOTE"
>"&#38;shortcut;"</SPAN
> would expand into <SPAN
CLASS="QUOTE"
>"Replace
'shortcut' with this text"</SPAN
>; <SPAN
CLASS="QUOTE"
>"&#38;sc-to-a-file;"</SPAN
>
would include the full contents of whatever
is in <TT
CLASS="replaceable"
><I
>anotherfile.xml</I
></TT
>.
</P
><P
>An important feature while writing a text is the ability to
check whether or not it will be presented in the final draft. It is
common to have several parts of the text marked as draft,
especially when updating an already existing document.</P
><P
>With the use of parameter entities, you can include or
eliminate these drafts by altering only one line at the beginning
of a document.</P
><DIV
CLASS="example"
><A
NAME="ex-entity-parameters"
></A
><P
><B
>Example D-13. Use of parameter entities</B
></P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;!ENTITY % review "INCLUDE"&#62;</TT
> ...
<TT
CLASS="sgmltag"
>&#60;![%review;[ &#60;para&#62;This paragraph will
be included on the draft when the entity "review" is defined with the
value "INCLUDE". &#60;/para&#62; ]]&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
></DIV
><P
>The entity <TT
CLASS="literal"
>review</TT
> might have several texts
defined, as in <A
HREF="#ex-entity-parameters"
>Example D-13</A
>. When the
changes to the text are considered final, you need only to remove
parts of the text between the 3<SUP
>rd.</SUP
>
and 6<SUP
>th.</SUP
> lines.</P
><P
>To keep the draft definitions and hide the text in the
final draft, just alter the specification of the entity from
<TT
CLASS="literal"
>INCLUDE</TT
> to <TT
CLASS="literal"
>IGNORE</TT
>.</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="namedfiles"
></A
>D.9. Customizing your HTML files</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="filenames"
></A
>D.9.1. HTML file names</H2
><P
>By default,
when separate HTML files are made, the SGML processor will assign
arbitrary names to the resulting files. This can be confusing
to readers who may bookmark a page only to have it change.
Whatever your reasoning, here's how to make separate files
named the way you want:</P
><P
>In your first <TT
CLASS="sgmltag"
>&#60;article&#62;</TT
> tag (which should be the only
one) include an <TT
CLASS="parameter"
><I
>id</I
></TT
> parameter and call it <SPAN
CLASS="QUOTE"
>"index"</SPAN
>. This will make
your tag look like this:</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>&#13;<TT
CLASS="sgmltag"
>&#60;article id="index"&#62;</TT
> </PRE
></FONT
></TD
></TR
></TABLE
><P
>Do not modify the first
<TT
CLASS="sgmltag"
>&#60;chapter&#62;</TT
>
tag, as it's usually an introduction and you want that on the first
page. For each other <TT
CLASS="sgmltag"
>&#60;section&#62;</TT
>
tag, include the id parameter and name it. A name should include
only alphanumeric characters, and it should be short enough to
understand what it is.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="programlisting"
>
<TT
CLASS="sgmltag"
>&#60;chapter id="tips"&#62;</TT
>
</PRE
></FONT
></TD
></TR
></TABLE
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Pick section IDs intelligently</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; We all know that <A
HREF="http://www.w3.org/Provider/Style/URI.html"
TARGET="_top"
>Cool URIs Don't
Change</A
>. This means your ids should not change either. Unless of
course the content for the id has changed substantially and the id name is no longer
relevant.
</P
></TD
></TR
></TABLE
></DIV
><DIV
CLASS="warning"
><P
></P
><TABLE
CLASS="warning"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/warning.gif"
HSPACE="5"
ALT="Warning"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>HTML file name generation using Jade</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; If you are using <SPAN
CLASS="application"
>Jade</SPAN
> to transform
your DocBook into HTML you must use the following parameter:
<TT
CLASS="parameter"
><I
>-V %use-id-as-filename%</I
></TT
>.
</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="header"
></A
>D.9.2. Headers and Footers</H2
><P
>&#13; There is no <SPAN
CLASS="QUOTE"
>"easy"</SPAN
> way to add headers and
footers to your document. If you are using DocBook XSL and
doing your own document transformations you
may customize the XSL template to suit your needs. For more
information read <A
HREF="http://www.sagehill.net/docbookxsl/HTMLHeaders.html"
TARGET="_top"
>http://www.sagehill.net/docbookxsl/HTMLHeaders.html</A
>.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="x2docbook"
></A
>Appendix E. Converting Documents to DocBook XML</H1
><P
>A variety of free and commercial tools exist for doing <SPAN
CLASS="QUOTE"
>"up conversion"</SPAN
> of non-XML formats to DocBook. A few are listed here for your convenience. A more comprehensive list is available from <A
HREF="http://wiki.docbook.org/topic/ConvertOtherFormatsToDocBook"
TARGET="_top"
>Convert Other Formats to DocBook</A
>.</P
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="txt2docbook"
></A
>E.1. Text to DocBook</H1
><P
>The <SPAN
CLASS="application"
>txt2docbook</SPAN
> tool allows one to convert a ascii (README-like) file to a valid docbook xml document. It simplifies the publishing of rather small papers significantly. The input format was inspired by the APT-Convert tool from <A
HREF="http://www.xmlmind.com/aptconvert.html"
TARGET="_top"
>http://www.xmlmind.com/aptconvert.html</A
>.</P
><P
>The script can be downloaded from <A
HREF="http://txt2docbook.sourceforge.net/"
TARGET="_top"
>http://txt2docbook.sourceforge.net/</A
>.</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="oo2docbook"
></A
>E.2. OpenOffice.org to DocBook</H1
><P
>As of <A
HREF="http://www.openoffice.org"
TARGET="_top"
>OpenOffice.org (OOo)</A
> 1.1RC there has been support for
exporting files to DocBook format.</P
><P
>Although OOo uses the full DocBook document type declaration,
it does not actually export the full list of DocBook elements. It
uses a <SPAN
CLASS="QUOTE"
>"simplified"</SPAN
> DocBook tag set which is geared
to on-the-fly rendering. (Although it is not the official
Simplified DocBook which is described in <A
HREF="#dtd"
>Section B.5</A
>.)
The OpenOffice simplified (or <SPAN
CLASS="QUOTE"
>"special"</SPAN
> docbook) is available from
<A
HREF="http://www.chez.com/ebellot/ooo2sdbk/"
TARGET="_top"
>http://www.chez.com/ebellot/ooo2sdbk/</A
>.</P
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="ooo-1-0"
></A
>E.2.1. Open Office 1.0.x</H2
><P
>&#13; OOo has been tested by LDP volunteers with mostly positive
results. Thanks to Charles Curley
(<A
HREF="http://www.charlescurley.com"
TARGET="_top"
>charlescurley.com</A
>)
for the following notes on using OOo version 1.0.x:
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Check the version of your OpenOffice</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; These notes may not apply to the version of OOo you
are using.
</P
></TD
></TR
></TABLE
></DIV
><P
></P
><UL
><LI
><P
>&#13; To be able to export to DocBook, you must have a Java runtime
environment (JRE) installed and registered with OOo--a minimum of
version 4.2.x is recommended. The configuration instructions will
depend on how you installed your JRE. Visit the OOo web site for
help with your setup.
</P
><P
>&#13; Contrary to the OOo documentation, the Linux OOo did not come with
a JRE. I got one from Sun.
</P
></LI
><LI
><P
>The exported file has lots of empty lines. My 54 line exported
file
had 5 lines of actual XML code.</P
></LI
><LI
><P
>There was no effort at pretty printing.</P
></LI
><LI
><P
> The header is:
<TT
CLASS="computeroutput"
>&#13; &#60;?xml version="1.0" encoding="UTF-8"?&#62;
&#60;!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"&#62;
</TT
>
</P
></LI
><LI
><P
> The pull-down menu in the <SPAN
CLASS="guimenu"
>File</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>Save
As</SPAN
> dialog box for
file format
indicates that the export format is <SPAN
CLASS="QUOTE"
>"DocBook (simplified)."</SPAN
> There is
no explanation of what that <SPAN
CLASS="QUOTE"
>"simplified"</SPAN
> indicates. Does OOo export
a subset of DocBook? If so, which elements are ignored? Is there any
way to enter any of them manually?
</P
></LI
><LI
><P
> There is NO documentation on the DocBook export filter
or whether
OOo will import it again.
</P
></LI
></UL
><P
>&#13; Conclusions: OOo 1.1RC is worth looking at if you want a word
processor for preparing DocBook documents.
</P
><P
>However, I hope they cure the lack of documentation. For one
thing, it would be nice to know which native OOo styles map to
which DocBook elements. It would also be nice to know how to
map one's own OOo styles to DocBook elements.</P
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="ooo-1-1"
></A
>E.2.2. Open Office 1.1</H2
><P
>&#13; <A
HREF="http://www.merlinmonroe.com"
TARGET="_top"
>Tabatha Marshall</A
>
offers the following additional information for OOo 1.1.
</P
><A
NAME="AEN3622"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
> The first problem was when I tried to do everything on version
1.0.1. That was
obviously a problem. I have RH8, and it was installed via rpm packages,
so I ripped it out and did a full, new install of OpenOffice 1.1.
It took a while to find out 1.1 was a requirement for XML to work.
</P
><P
>&#13;During the install process I believe I was offered the choice to install
the XML features. I have a tendency to do full installs of my office
programs, so I selected everything.
</P
><P
>&#13;I can't offer any advice to those trying to update their current
OO 1.1. Their <SPAN
CLASS="QUOTE"
>"3 ways"</SPAN
> aren't documented very well at the site
(<A
HREF="http://xml.openoffice.org"
TARGET="_top"
>xml.openoffice.org</A
>) and as of this writing, I can't even find THAT
on their site anymore. I think more current documentation is needed
there to walk people through the process. Most of this was unclear
and I had to pretty much experiment to get things working.
</P
><P
>&#13;Well, after I installed everything I had some configuration to do.
I opened the application, and got started by opening a new file,
choosing templates, then selecting the DocBook template. A nice menu
of <SPAN
CLASS="guisubmenu"
>Paragraph Styles</SPAN
> popped up for me, which are the names for all those
tags, I noticed (you can see I don't use WYSIWYG often).
</P
><P
>&#13; With a blank doc before me (couldn't get to the <SPAN
CLASS="guisubmenu"
>XML Filter
Settings</SPAN
> menu unless some type of doc was opened), I went into
<SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML
Filter Settings</SPAN
>, and edited the entry for DocBook file.
I configured mine as follows:
</P
><P
></P
><UL
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>Doctype</SPAN
>
<TT
CLASS="userinput"
><B
>-//OASIS//DTD DocBook XML V4.2//EN</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>DTD</SPAN
>
<TT
CLASS="userinput"
><B
>http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>XSLT for export</SPAN
>
<TT
CLASS="userinput"
><B
>/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/ldp-html.xsl</B
></TT
>
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>XSLT for import</SPAN
>
<TT
CLASS="userinput"
><B
>/usr/local/OpenOffice.org1.1.0/share/xslt/docbook/docbooktosoffheadings.xsl</B
></TT
>
(this is the default)
</P
></LI
><LI
><P
>&#13; <SPAN
CLASS="guilabel"
>Template for import</SPAN
>
<TT
CLASS="userinput"
><B
>/home/tabatha/OpenOffice/user/template/DocBook
File/DocBookTemplate.stw</B
></TT
>
</P
></LI
></UL
><P
>&#13;At first, if I opened an XML file that had even one parsing error, it
would just open the file anyway and display the markup in OO. I have
many XML files that use &#38;copy; and other types of entities which show
up as parse errors (depending on the encoding) even though they can be
processed through. But today I was unable to open any of those files.
I got input/output errors instead. Still investigating that one.
</P
><P
>&#13;However when you do successfully open a document (one parsing with no
errors), it puts it automatically into WYSIWYG based on the markup,
and you can then work from the paragraph styles menu like any other
such editor.
</P
><P
>&#13;To validate the document, I used <SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML
Filter Settings</SPAN
>, then
clicked the <SPAN
CLASS="guibutton"
>Test XSLTs</SPAN
> button. On my screen, I set up the XSLT
for export to be <TT
CLASS="filename"
>ldp-html.xsl</TT
>. If you test and there are errors,
a new window pops up with error messages at the bottom, and the lines
that need to be changed up at the top. You can change them there and
progress through the errors until they're all gone, and keep testing
until they're gone.
</P
><P
>&#13;If you want to open a file to see the source instead of the processed
results, go to <SPAN
CLASS="guimenu"
>Tools</SPAN
>-&gt;<SPAN
CLASS="guimenuitem"
>XML Filter
Settings</SPAN
>-&gt;<SPAN
CLASS="guisubmenu"
>Test XSLTs</SPAN
>, and then
under the <SPAN
CLASS="guimenu"
>Import</SPAN
> section, check the
<SPAN
CLASS="guilabel"
>Display Source</SPAN
> box. My import XSLT
is currently <TT
CLASS="filename"
>docbooktosoffheadings.xsl</TT
> (the default) and the template
for import is <TT
CLASS="filename"
>DocBookTemplate.stw</TT
> (also default).
</P
><P
>&#13;I think this might work for some people, but unfortunately not for me.
I've never used WYSIWYG to edit markup. <SPAN
CLASS="application"
>Emacs with
PSGML</SPAN
> can tell me
what my next tag is no matter where I am, validate by moving through
the trouble spots, and I can parse and process from command line.
</P
><P
>&#13;With OpenOffice, you have to visit <A
HREF="http://xml.openoffice.org/filters.html"
TARGET="_top"
>http://xml.openoffice.org/filters.html</A
>
to find conversion tools.
</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="word2docbook"
></A
>E.3. Microsoft Word to DocBook</H1
><P
>Even if you want to use MS Word to write your documents, you may
find <A
HREF="http://www.docsoft.com/w2xmlv2.htm"
TARGET="_top"
>w2XML</A
>
useful. Note that this is not free software--the cost is around $130USD.
There is, however, a trial version of the software.</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="tex4ht"
></A
>E.4. LaTeX to DocBook</H1
><P
>Siep Kroonenberg reports that there is a package <SPAN
CLASS="application"
>tex4ht</SPAN
> <A
HREF="http://www.cse.ohio-state.edu/~gurari/TeX4ht/"
TARGET="_top"
>http://www.cse.ohio-state.edu/~gurari/TeX4ht/</A
> that converts TeX and LaTeX to various flavors of XML. Currently, its support for DocBook output is limited. If you want to use <SPAN
CLASS="application"
>tex4ht</SPAN
> in its current state for LDP you will probably have to hack your LaTeX source beforehand and the generated XML afterwords.</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="lyx2docbook"
></A
>E.5. LyX to DocBook</H1
><P
>This section is contributed by Chris Karakas.</P
><P
>You can use the <SPAN
CLASS="application"
>LyX-to-X</SPAN
> package to write your document conveniently in <SPAN
CLASS="application"
>LyX</SPAN
> (a visual editor originally developped as a graphical frontend to <SPAN
CLASS="application"
>LaTeX</SPAN
>), then export it to DocBook SGML and submit it to The LDP. This method is presented by <A
HREF="http://www.karakas-online.de"
TARGET="_top"
>Chris Karakas</A
> <A
HREF="http://www.karakas-online.de/mySGML"
TARGET="_top"
><I
CLASS="citetitle"
>Document processing with LyX and SGML</I
></A
>.</P
><P
>In the LyX-to-X project, LyX is used as a comfortable graphical SGML editor. Once the document is exported to SGML from LyX, it undergoes a series of transformations through <SPAN
CLASS="application"
>sed</SPAN
> and <SPAN
CLASS="application"
>awk</SPAN
> scripts that correct the SGML code, computes the Index, inserts the Bibliography and the Appendix and takes care of the correct invocation of <SPAN
CLASS="application"
>openjade</SPAN
>, <SPAN
CLASS="application"
>pdftex</SPAN
>, <SPAN
CLASS="application"
>pdfjadetex</SPAN
> and all the other necessary programs for the generation of HTML (chunked or not), PDF (with images, bookmarks, thumbnails and hyperlinks), PS, RTF and TXT versions.</P
><P
>All aspects of document processing are handled,
including automatic Index generation, display of Mathematics in TeX quality both online and in print formats, as well as the use of bibliographic databases with <A
HREF="http://refdb.sourceforge.net/"
TARGET="_top"
>RefDB</A
>. Special care is taken so that the document processing is as transparent to the user as possible - the aim being that the user writes in LyX, then presses a button, and the LyX-to-X script does the rest. Download the documentation and the LyX-to-X package from the <A
HREF="http://www.karakas-online.de/mySGML/formats.html"
TARGET="_top"
>Formats section</A
>.
</P
></DIV
><DIV
CLASS="section"
><HR><H1
CLASS="section"
><A
NAME="docbook2docbook"
></A
>E.6. DocBook to DocBook Transformations</H1
><DIV
CLASS="section"
><H2
CLASS="section"
><A
NAME="xmldifferences"
></A
>E.6.1. XML and SGML DocBook</H2
><P
>&#13; There are a few changes between DocBook XML and SGML. Handling
these differences should be relatively easy for most small documents,
and many authors will not need to make any changes
to convert their documents other than the XML and DocBook
declarations at the start of their document.
</P
><P
>&#13; For others, here is a list of what you should keep in mind
when converting your documents from SGML to XML.
</P
><DIV
CLASS="note"
><P
></P
><TABLE
CLASS="note"
WIDTH="100%"
BORDER="0"
><TR
><TD
WIDTH="25"
ALIGN="CENTER"
VALIGN="TOP"
><IMG
SRC="../images/note.gif"
HSPACE="5"
ALT="Note"></TD
><TH
ALIGN="LEFT"
VALIGN="CENTER"
><B
>Differences between XML and SGML elements</B
></TH
></TR
><TR
><TD
>&nbsp;</TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
><P
>&#13; An XML element typically has three parts: the start tag,
the content (your words) and the end tag. Qualifiers
are added in the start tag and are known as
attributes. They will always have a name and a
quoted value.</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;filename class="directory"&#62;/usr/local&#60;filename&#62;
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; The start tag contains one attribute (class)
with a value of <SPAN
CLASS="QUOTE"
>"directory"</SPAN
>. The end tag (also filename)
must not contain any attributes.
</P
></TD
></TR
></TABLE
></DIV
><P
></P
><UL
><LI
><P
>&#13; Element names (tags) and their attributes are
case-dependent--typically lowercase.
The following will not validate because the end tag
&#60;PARA&#62; is uppercase:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;para&#62;This part will fail XML validation&#60;/PARA&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></LI
><LI
><P
>&#13; All attributes in the start tag must be
"quoted". This can
be either single (') or double (") quotes, but
not
reverse (`) or <SPAN
CLASS="QUOTE"
>"smart quotes"</SPAN
>.
The quote used to start a name="value"
pair must be the same quote used at the end of
the value. In other words: "this" would
validate, but 'that" would not.
</P
></LI
><LI
><P
>&#13; Tags that have a start tag, but no end tag are
referred to as <SPAN
CLASS="QUOTE"
>"empty"</SPAN
> because they do
not contain (wrap around) anything. These tags must still be
closed with a trailing slash (/). For example:
<TT
CLASS="sgmltag"
>xref</TT
> must be written as
&#60;xref linkend="software"/&#62;. You may not
have any spaces between the / and &#62;.
(Although you may have a space after the final
attribute: &#60;xref linkend="foo" /&#62;.)
</P
></LI
><LI
><P
>&#13; Processing instructions that get sent to the transformation
engine (DSSSL or XSLT) and must have a question mark at the
end of the tag. All processing instructions are removed from
the output stream. The XML version of this tag
would look like this:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;?dbhtml filename="foo"?&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></LI
><LI
><P
>&#13; If you're converting from SGML to XML, be sure
file names refer to .xml files instead of .sgml.
Some tools may get confused if a .sgml file contains XML.
</P
></LI
><LI
><P
>&#13; Tag minimizations were used in SGML instead of
writing out the element name in the end tag.
Example: <TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>This is foo.<TT
CLASS="sgmltag"
>&#60;/&#62;</TT
> Tag minimizations are
not supported in XML and their use is
discouraged in DocBook.
</P
></LI
></UL
></DIV
><DIV
CLASS="section"
><HR><H2
CLASS="section"
><A
NAME="differences"
></A
>E.6.2. Changing DTDs</H2
><P
>&#13; The significant changes between version changes in the DTD
involve changes to the elements (tags). Elements may be:
deprecated (which means they will be removed in
future versions); removed; modified; or added.
Almost all authors will run into a changed or
deprecated tag when going from a lower version
of DocBook to a higher version.
</P
><P
>&#13; <I
CLASS="citetitle"
>DocBook: The Definitive Guide</I
> does
an excellent job of showing you how elements fit
together. For each element it tells you what an
element must contain (its content model) and what is
may be contained in (who its parents are). For
example: a <TT
CLASS="sgmltag"
>note</TT
> must contain a
<TT
CLASS="sgmltag"
>para</TT
>. If you try to write
&#60;note&#62;Content in a
note&#60;/note&#62; your document will not validate.
Learning how elements are assembled will make it a
lot easier to understand any validation errors that
are thrown at you. If you get truly stuck you can
also email the LDP's docbook mailing list for extra
hints. Information on subscribing is available from
<A
HREF="#mailinglists"
>Section 2.2</A
>
</P
><P
>&#13; All tags that have been deprecated or changed for 4.x are listed
in <I
CLASS="citetitle"
>DocBook: The definitive guide</I
>,
published by O'Reilly and Associates. This book is
also available on-line from <A
HREF="http://www.docbook.org"
TARGET="_top"
>http://www.docbook.org</A
>.
</P
><DIV
CLASS="section"
><HR><H3
CLASS="section"
><A
NAME="differences3040"
></A
>E.6.2.1. Differences between version 3.x and 4.x</H3
><P
>&#13; Here are a few elements that are of particular
relevance to LDP authors:
</P
><P
></P
><UL
><LI
><DIV
CLASS="formalpara"
><P
><B
><TT
CLASS="sgmltag"
>artheader</TT
>. </B
>has been changed to
<TT
CLASS="sgmltag"
>articleinfo</TT
>.
Most other header elements have been renamed to info.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
><TT
CLASS="sgmltag"
>graphic</TT
>. </B
>has been deprecated and will be removed as of DocBook 5.x.
To prepare for this, start using
<TT
CLASS="sgmltag"
>mediaobject</TT
>. There is more
information about <TT
CLASS="sgmltag"
>mediaobject</TT
>
in <A
HREF="#inserting-pictures"
>Section D.5</A
>.
</P
></DIV
></LI
><LI
><DIV
CLASS="formalpara"
><P
><B
><TT
CLASS="sgmltag"
>imagedata</TT
>. </B
>file formats
must now be written in UPPERCASE letters. If you
use lowercase or mixed-case spellings
for your file formats, it will fail.
</P
></DIV
><P
>&#13; Valid:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;imagedata format="EPS" fileref="foo.eps"&#62;
</PRE
></FONT
></TD
></TR
></TABLE
><P
>&#13; Invalid:
</P
><TABLE
BORDER="0"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="screen"
>&#13;&#60;imagedata format="eps" fileref="foo.eps"&#62;
</PRE
></FONT
></TD
></TR
></TABLE
></LI
></UL
></DIV
></DIV
></DIV
></DIV
><DIV
CLASS="GLOSSARY"
><H1
><A
NAME="glossary"
></A
>Glossary</H1
><DL
><DT
><B
>Abiword</B
></DT
><DD
><P
>Open Source word processor.
</P
></DD
><DT
><B
>aspell</B
></DT
><DD
><P
>Spell check program.
</P
></DD
><DT
><B
>attribute</B
></DT
><DD
><P
>An attribute makes available extra information regarding the
element on which it appears. The attributes always appear as a
name-value pair on the initialization pointers
(i.e. the <SPAN
CLASS="QUOTE"
>"start tag"</SPAN
>). Example of an
attribute is <TT
CLASS="parameter"
><I
>id="identification"</I
></TT
>, which gives the
attribute <TT
CLASS="parameter"
><I
>id</I
></TT
> the value
<TT
CLASS="parameter"
><I
>identification</I
></TT
>.</P
></DD
><DT
><B
>Cascading Style Sheet
(<SPAN
CLASS="acronym"
>CSS</SPAN
>)</B
></DT
><DD
><P
>Set of overlay rules that are read by your HTML browser, which uses these rules for doing the display, layout and formatting of the XML-generated HTML file(s). <SPAN
CLASS="acronym"
>CSS</SPAN
> allows for fast changes in look and feel without having to plunge in the HTML file(s).
</P
></DD
><DT
><B
>Catalog</B
></DT
><DD
><P
>Helper file for the display and transformation tools, which
maps public identifiers and URLs to the local file system.
</P
></DD
><DT
><B
>Concurrent Versions System
(<SPAN
CLASS="acronym"
>CVS</SPAN
>)</B
></DT
><DD
><P
>A common document management system used by the LDP.
</P
></DD
><DT
><B
>DocBook</B
></DT
><DD
><P
>An SGML (and XML) application, describing a document format
that allows easy management of documentation.
</P
></DD
><DT
><B
>docbook-utils</B
></DT
><DD
><P
>Software package easing XML conversions.
</P
></DD
><DT
><B
>Document Type Definition
(<SPAN
CLASS="acronym"
>DTD</SPAN
>)</B
></DT
><DD
><P
>A group of statements that define element names and their attributes
specifying the rules for combinations and sequences. It's the
<SPAN
CLASS="acronym"
>DTD</SPAN
> that defines which elements can or cannot
be inserted in the given context.
</P
></DD
><DT
><B
><SPAN
CLASS="acronym"
>DSSSL</SPAN
></B
></DT
><DD
><P
><SPAN
CLASS="acronym"
>DSSSL</SPAN
> stands for Document Style Semantics and
Specification Language. It's an <SPAN
CLASS="acronym"
>ISO</SPAN
> standard
(ISO/IEC 10179:1996). The <SPAN
CLASS="acronym"
>DSSSL</SPAN
> standard is
internationally used as a language for documents style sheets pages for
<SPAN
CLASS="acronym"
>SGML</SPAN
>.</P
></DD
><DT
><B
>element</B
></DT
><DD
><P
>&#13; The elements describe the content's structure in a document.
Most elements contain a start tag, content and a closing tag. For
example a paragraph element includes all of the following <TT
CLASS="sgmltag"
>&#60;para&#62;</TT
>This is the paragraph.<TT
CLASS="sgmltag"
>&#60;/para&#62;</TT
>. Some elements are <SPAN
CLASS="QUOTE"
>"empty"</SPAN
> and do not
contain content and a closing tag. An example of this is a link to
an external document where the URL is printed to the page. This
element would include only the following <TT
CLASS="sgmltag"
>&#60;ulink url="http://google.com/&#62;</TT
>.
</P
></DD
><DT
><B
>Emacs</B
></DT
><DD
><P
>Popular text editor, especially on UNIX systems or alikes.
</P
></DD
><DT
><B
>entity</B
></DT
><DD
><P
>An entity is a name designated for some part of data so that it
can be referenced by a name. The data could be anything from
from simple characters to chapters to sets
of statements in a <SPAN
CLASS="acronym"
>DTD</SPAN
>.
Entity parameters can be generic, external, internal or
<SPAN
CLASS="acronym"
>SGML</SPAN
> data. An entity is similar to a variable
in a programming language, or a macro.
</P
></DD
><DT
><B
>epcEdit</B
></DT
><DD
><P
>Cross-platform XML editor.
</P
></DD
><DT
><B
>external entity</B
></DT
><DD
><P
>An external entity points to an external document. External entities
are used to include texts on certain locations of a
<SPAN
CLASS="acronym"
>SGML</SPAN
> document. It could be used to include
sample screens, legal notes, and chapters for example.</P
></DD
><DT
><B
>float</B
></DT
><DD
><P
>Objects such as side bars, pictures, tables, and charts are called floats when they don't have a fixed placement on the text. For
printed text, a chart can appear either at the top or at the
bottom of the page. It can also be placed on the next page if it is
too large.</P
></DD
><DT
><B
>Frequently Asked Questions
(<SPAN
CLASS="acronym"
>FAQ</SPAN
>)</B
></DT
><DD
><P
>LDP hosts a number of documents that are a list in the form of
questions and answers. These documents are called FAQs. A FAQ is usually a single-page document.
</P
></DD
><DT
><B
>generic entities</B
></DT
><DD
><P
>An entity referenced by a name, which starts with
<SPAN
CLASS="QUOTE"
>"&#38;"</SPAN
> and ends with semicolon is a generic
entity. Most of the time this type of entity is used in the
document and not on the <SPAN
CLASS="acronym"
>DTD</SPAN
>. There are two types
of entities: external and internal. They can refer to special
characters or to text objects such as repeated sentences, names or
chapters.</P
></DD
><DT
><B
>GNU Free Documentation License
(<SPAN
CLASS="acronym"
>GFDL</SPAN
>)</B
></DT
><DD
><P
>Like the GNU Public License for free software, but with specifics for written text and documentation with software.
</P
></DD
><DT
><B
>GNU Public License
(<SPAN
CLASS="acronym"
>GPL</SPAN
>)</B
></DT
><DD
><P
>License type for software that guarantees that the software remains freely distributable, that the source code is available, that you can make changes to it and redistribute those changes if you want, on the condition that you keep on using the same license for your derived works.
</P
></DD
><DT
><B
>Guide</B
></DT
><DD
><P
>TLDP documents that are too long to be a HOWTO are usually stored
as guides. These are more like entire books that treat a particular
subject in-dept.
</P
></DD
><DT
><B
>HOWTO</B
></DT
><DD
><P
>Documents that discuss how to do something with a system or
application. Most documents hosted at TLDP are HOWTOs,
explaining how to install, configure or manage tens of applications
on a variety of systems. HOWTOs are typically 10-25 pages.
</P
></DD
><DT
><B
>internal entity</B
></DT
><DD
><P
>An internal entity refers to part of the text and is often used
as a shortcut for frequently repeated text.</P
></DD
><DT
><B
>ispell</B
></DT
><DD
><P
>Spell check program.
</P
></DD
><DT
><B
>Jade</B
></DT
><DD
><P
>An application which applies the rules defined in a DSSSL
style sheet to an SGML or XML document, transforming the document
into the desired output.
</P
></DD
><DT
><B
>Markup, markup language
(<SPAN
CLASS="acronym"
>ML</SPAN
>)</B
></DT
><DD
><P
>Code added to the content of a document, describing its structure.
</P
></DD
><DT
><B
>Metadata</B
></DT
><DD
><P
>Text in your document that is not important for understanding the subject, but that should be there anyway, such as version information, co-authors, credits to people etc.
</P
></DD
><DT
><B
>nedit</B
></DT
><DD
><P
>Text editor oriented to programmers.
</P
></DD
><DT
><B
>nsgmls, onsgmls</B
></DT
><DD
><P
>SGML document parser and validator program.
</P
></DD
><DT
><B
>OpenOffice
(<SPAN
CLASS="acronym"
>OOo</SPAN
>)</B
></DT
><DD
><P
>Open Source office suite, compatible with Microsoft Office.
</P
></DD
><DT
><B
>parameter entity</B
></DT
><DD
><P
>An entity type often used in the <SPAN
CLASS="acronym"
>DTD</SPAN
> or a
document's internal subset. The entity's
name starts with a percent sign (%) and ends with a
semicolon.</P
></DD
><DT
><B
>PSGML</B
></DT
><DD
><P
>Emacs <EM
>major mode</EM
> that customizes Emacs for editing SGML documents.
</P
></DD
><DT
><B
>Organization for the Advancement of Structured Information Standards
(<SPAN
CLASS="acronym"
>OASIS</SPAN
>)</B
></DT
><DD
><P
>OASIS is a non-profit, global consortium that drives the development, convergence and adoption of e-business standards.
</P
></DD
><DT
><B
>Outline</B
></DT
><DD
><P
>Draft of your document that conceptualizes the subject and scope. Summary and To-Do list for the work to come.
</P
></DD
><DT
><B
>Portable Document Format
(<SPAN
CLASS="acronym"
>PDF</SPAN
>)</B
></DT
><DD
><P
>Standard document type supported on a wide range of operating systems.
</P
></DD
><DT
><B
>processing instruction</B
></DT
><DD
><P
>A processing instruction is a command passed to the document
formatting tool. It starts with <SPAN
CLASS="QUOTE"
>"&#60;?"</SPAN
>. This document
uses processing instructions for naming files when it
is rendered into
<SPAN
CLASS="acronym"
>HTML</SPAN
>: <TT
CLASS="sgmltag"
>&#60;?dbhtml
filename="file.html"&#62;</TT
></P
></DD
><DT
><B
>PostScript
(<SPAN
CLASS="acronym"
>PS</SPAN
>)</B
></DT
><DD
><P
>Document format designed for printable documents. PS is the standard print format on UNIX(-alikes).
</P
></DD
><DT
><B
>Reviewer, review process</B
></DT
><DD
><P
>TLDP doesn't accept just anything. Once you submit a document, it will be checked for consistency, grammar, spelling and style by a reviewer, a volunteer assigned by the review coordinator.
</P
></DD
><DT
><B
><SPAN
CLASS="acronym"
>SGML</SPAN
></B
></DT
><DD
><P
><I
CLASS="foreignphrase"
>Standard Generalized Markup
Language</I
>.
It is an international standard (<SPAN
CLASS="acronym"
>ISO</SPAN
>8879) that
specifies rules for the creation of electronic documents in markup
systems, regardless of the platform used.</P
></DD
><DT
><B
>Subject and scope</B
></DT
><DD
><P
>Obviously, the subject is what your documentation is about. The scope defines which areas of the subject you are going to discuss, and how much detail will be involved.
</P
></DD
><DT
><B
>tag</B
></DT
><DD
><P
>An <SPAN
CLASS="acronym"
>SGML</SPAN
> element bounded by the marks
<SPAN
CLASS="QUOTE"
>"&#60;"</SPAN
> and <SPAN
CLASS="QUOTE"
>"&#62;"</SPAN
>. Tags are used
to mark the semantic or logical structure of a document. A sample
is the tag <EM
><TT
CLASS="sgmltag"
>&#60;title&#62;</TT
></EM
> to mark the beginning
of a title.</P
></DD
><DT
><B
>TeX</B
></DT
><DD
><P
>Popular UNIX text formatting and typesetting tool.
</P
></DD
><DT
><B
>Transformation</B
></DT
><DD
><P
>The process of converting a document from its original DocBook XML form to another format, such as PDF, HTML or PostScript.
</P
></DD
><DT
><B
>Validation</B
></DT
><DD
><P
>The process of checking your XML code to ensure it complies
with the XML DTD you declared at the top of your document.
</P
></DD
><DT
><B
>vi Improved
(<SPAN
CLASS="acronym"
>vIm</SPAN
>)</B
></DT
><DD
><P
>Popular text editor on UNIX and alike systems.
</P
></DD
><DT
><B
>WordPerfect
(<SPAN
CLASS="acronym"
>WP</SPAN
>)</B
></DT
><DD
><P
>Popular word processor, runs on many systems.
</P
></DD
><DT
><B
><SPAN
CLASS="acronym"
>XML</SPAN
></B
></DT
><DD
><P
>eXtensible Markup Language. A sub-product of <SPAN
CLASS="acronym"
>SGML</SPAN
>
created specifically for Internet use.</P
></DD
><DT
><B
>xmllint</B
></DT
><DD
><P
>Command line XML parser and validator.
</P
></DD
><DT
><B
>XMLmind XML Editor
(<SPAN
CLASS="acronym"
>XXE</SPAN
>)</B
></DT
><DD
><P
>Free but not Open XML editor.
</P
></DD
><DT
><B
>xmlto</B
></DT
><DD
><P
>Command line XML transformation program.
</P
></DD
><DT
><B
><SPAN
CLASS="acronym"
>XSL</SPAN
></B
></DT
><DD
><P
><SPAN
CLASS="acronym"
>XML</SPAN
> Style
Language. XSL is to a <SPAN
CLASS="acronym"
>XML</SPAN
> document what a
<SPAN
CLASS="acronym"
>DSSSL</SPAN
> style is for a <SPAN
CLASS="acronym"
>SGML</SPAN
>
document. The XSL is written in
<SPAN
CLASS="acronym"
>XML</SPAN
>.</P
></DD
><DT
><B
>Extensible Stylesheet Transformation
(<SPAN
CLASS="acronym"
>XSLT</SPAN
>)</B
></DT
><DD
><P
>Framework for managing documents, consisting of the XSLT transformation language, the XPath expression language and XSL formatting objects.
</P
></DD
></DL
></DIV
><DIV
CLASS="appendix"
><HR><H1
><A
NAME="fdl"
></A
>Appendix F. GNU Free Documentation License</H1
><DIV
CLASS="sect1"
><H1
CLASS="sect1"
><A
NAME="fdl-preamble"
></A
>F.1. 0. PREAMBLE</H1
><P
>&#13; The purpose of this License is to make a manual, textbook, or
other written document <SPAN
CLASS="QUOTE"
>"free"</SPAN
> in the sense of
freedom: to assure everyone the effective freedom to copy and
redistribute it, with or without modifying it, either
commercially or noncommercially. Secondarily, this License
preserves for the author and publisher a way to get credit for
their work, while not being considered responsible for
modifications made by others.
</P
><P
>&#13; This License is a kind of <SPAN
CLASS="QUOTE"
>"copyleft"</SPAN
>, which means
that derivative works of the document must themselves be free in
the same sense. It complements the GNU General Public License,
which is a copyleft license designed for free software.
</P
><P
>&#13; We have designed this License in order to use it for manuals for
free software, because free software needs free documentation: a
free program should come with manuals providing the same
freedoms that the software does. But this License is not limited
to software manuals; it can be used for any textual work,
regardless of subject matter or whether it is published as a
printed book. We recommend this License principally for works
whose purpose is instruction or reference.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section1"
></A
>F.2. 1. APPLICABILITY AND DEFINITIONS</H1
><P
>&#13; This License applies to any manual or other work that contains a
notice placed by the copyright holder saying it can be
distributed under the terms of this License. The
<SPAN
CLASS="QUOTE"
>"Document"</SPAN
>, below, refers to any such manual or
work. Any member of the public is a licensee, and is addressed
as <SPAN
CLASS="QUOTE"
>"you"</SPAN
>.
</P
><P
>&#13; A <SPAN
CLASS="QUOTE"
>"Modified Version"</SPAN
> of the Document means any work
containing the Document or a portion of it, either copied
verbatim, or with modifications and/or translated into another
language.
</P
><P
>&#13; A <SPAN
CLASS="QUOTE"
>"Secondary Section"</SPAN
> is a named appendix or a
front-matter section of the <A
HREF="#fdl-document"
>Document</A
> that deals exclusively
with the relationship of the publishers or authors of the
Document to the Document's overall subject (or to related
matters) and contains nothing that could fall directly within
that overall subject. (For example, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of
legal, commercial, philosophical, ethical or political position
regarding them.
</P
><P
>&#13; The <SPAN
CLASS="QUOTE"
>"Invariant Sections"</SPAN
> are certain <A
HREF="#fdl-secondary"
> Secondary Sections</A
> whose titles
are designated, as being those of Invariant Sections, in the
notice that says that the <A
HREF="#fdl-document"
>Document</A
> is released under this
License.
</P
><P
>&#13; The <SPAN
CLASS="QUOTE"
>"Cover Texts"</SPAN
> are certain short passages of
text that are listed, as Front-Cover Texts or Back-Cover Texts,
in the notice that says that the <A
HREF="#fdl-document"
>Document</A
> is released under this
License.
</P
><P
>&#13; A <SPAN
CLASS="QUOTE"
>"Transparent"</SPAN
> copy of the <A
HREF="#fdl-document"
> Document</A
> means a machine-readable
copy, represented in a format whose specification is available
to the general public, whose contents can be viewed and edited
directly and straightforwardly with generic text editors or (for
images composed of pixels) generic paint programs or (for
drawings) some widely available drawing editor, and that is
suitable for input to text formatters or for automatic
translation to a variety of formats suitable for input to text
formatters. A copy made in an otherwise Transparent file format
whose markup has been designed to thwart or discourage
subsequent modification by readers is not Transparent. A copy
that is not <SPAN
CLASS="QUOTE"
>"Transparent"</SPAN
> is called
<SPAN
CLASS="QUOTE"
>"Opaque"</SPAN
>.
</P
><P
>&#13; Examples of suitable formats for Transparent copies include
plain ASCII without markup, Texinfo input format, LaTeX input
format, SGML or XML using a publicly available DTD, and
standard-conforming simple HTML designed for human
modification. Opaque formats include PostScript, PDF,
proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD
and/or processing tools are not generally available, and the
machine-generated HTML produced by some word processors for
output purposes only.
</P
><P
>&#13; The <SPAN
CLASS="QUOTE"
>"Title Page"</SPAN
> means, for a printed book, the
title page itself, plus such following pages as are needed to
hold, legibly, the material this License requires to appear in
the title page. For works in formats which do not have any title
page as such, <SPAN
CLASS="QUOTE"
>"Title Page"</SPAN
> means the text near the
most prominent appearance of the work's title, preceding the
beginning of the body of the text.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section2"
></A
>F.3. 2. VERBATIM COPYING</H1
><P
>&#13; You may copy and distribute the <A
HREF="#fdl-document"
>Document</A
> in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License
applies to the Document are reproduced in all copies, and that
you add no other conditions whatsoever to those of this
License. You may not use technical measures to obstruct or
control the reading or further copying of the copies you make or
distribute. However, you may accept compensation in exchange for
copies. If you distribute a large enough number of copies you
must also follow the conditions in <A
HREF="#fdl-section3"
>section 3</A
>.
</P
><P
>&#13; You may also lend copies, under the same conditions stated
above, and you may publicly display copies.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section3"
></A
>F.4. 3. COPYING IN QUANTITY</H1
><P
>&#13; If you publish printed copies of the <A
HREF="#fdl-document"
>Document</A
> numbering more than 100,
and the Document's license notice requires <A
HREF="#fdl-cover-texts"
>Cover Texts</A
>, you must enclose
the copies in covers that carry, clearly and legibly, all these
Cover Texts: Front-Cover Texts on the front cover, and
Back-Cover Texts on the back cover. Both covers must also
clearly and legibly identify you as the publisher of these
copies. The front cover must present the full title with all
words of the title equally prominent and visible. You may add
other material on the covers in addition. Copying with changes
limited to the covers, as long as they preserve the title of the
<A
HREF="#fdl-document"
>Document</A
> and satisfy these
conditions, can be treated as verbatim copying in other
respects.
</P
><P
>&#13; If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto
adjacent pages.
</P
><P
>&#13; If you publish or distribute <A
HREF="#fdl-transparent"
>Opaque</A
> copies of the <A
HREF="#fdl-document"
>Document</A
> numbering more than 100,
you must either include a machine-readable <A
HREF="#fdl-transparent"
>Transparent</A
> copy along with
each Opaque copy, or state in or with each Opaque copy a
publicly-accessible computer-network location containing a
complete Transparent copy of the Document, free of added
material, which the general network-using public has access to
download anonymously at no charge using public-standard network
protocols. If you use the latter option, you must take
reasonably prudent steps, when you begin distribution of Opaque
copies in quantity, to ensure that this Transparent copy will
remain thus accessible at the stated location until at least one
year after the last time you distribute an Opaque copy (directly
or through your agents or retailers) of that edition to the
public.
</P
><P
>&#13; It is requested, but not required, that you contact the authors
of the <A
HREF="#fdl-document"
>Document</A
> well before
redistributing any large number of copies, to give them a chance
to provide you with an updated version of the Document.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section4"
></A
>F.5. 4. MODIFICATIONS</H1
><P
>&#13; You may copy and distribute a <A
HREF="#fdl-modified"
>Modified Version</A
> of the <A
HREF="#fdl-document"
>Document</A
> under the conditions of
sections <A
HREF="#fdl-section2"
>2</A
> and <A
HREF="#fdl-section3"
>3</A
> above, provided that you release
the Modified Version under precisely this License, with the
Modified Version filling the role of the Document, thus
licensing distribution and modification of the Modified Version
to whoever possesses a copy of it. In addition, you must do
these things in the Modified Version:
</P
><P
></P
><UL
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>A. </B
>
Use in the <A
HREF="#fdl-title-page"
>Title
Page</A
> (and on the covers, if any) a title distinct
from that of the <A
HREF="#fdl-document"
>Document</A
>, and from those of
previous versions (which should, if there were any, be
listed in the History section of the Document). You may
use the same title as a previous version if the original
publisher of that version gives permission.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>B. </B
>
List on the <A
HREF="#fdl-title-page"
>Title
Page</A
>, as authors, one or more persons or entities
responsible for authorship of the modifications in the
<A
HREF="#fdl-modified"
>Modified Version</A
>,
together with at least five of the principal authors of
the <A
HREF="#fdl-document"
>Document</A
> (all of
its principal authors, if it has less than five).
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>C. </B
>
State on the <A
HREF="#fdl-title-page"
>Title
Page</A
> the name of the publisher of the <A
HREF="#fdl-modified"
>Modified Version</A
>, as the
publisher.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>D. </B
>
Preserve all the copyright notices of the <A
HREF="#fdl-document"
>Document</A
>.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>E. </B
>
Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>F. </B
>
Include, immediately after the copyright notices, a
license notice giving the public permission to use the
<A
HREF="#fdl-modified"
>Modified Version</A
> under
the terms of this License, in the form shown in the
Addendum below.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>G. </B
>
Preserve in that license notice the full lists of <A
HREF="#fdl-invariant"
> Invariant Sections</A
> and
required <A
HREF="#fdl-cover-texts"
>Cover
Texts</A
> given in the <A
HREF="#fdl-document"
>Document's</A
> license notice.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>H. </B
>
Include an unaltered copy of this License.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>I. </B
>
Preserve the section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
>, and
its title, and add to it an item stating at least the
title, year, new authors, and publisher of the <A
HREF="#fdl-modified"
>Modified Version </A
>as given on
the <A
HREF="#fdl-title-page"
>Title Page</A
>. If
there is no section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
> in the
<A
HREF="#fdl-document"
>Document</A
>, create one
stating the title, year, authors, and publisher of the
Document as given on its Title Page, then add an item
describing the Modified Version as stated in the previous
sentence.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>J. </B
>
Preserve the network location, if any, given in the <A
HREF="#fdl-document"
>Document</A
> for public access
to a <A
HREF="#fdl-transparent"
>Transparent</A
>
copy of the Document, and likewise the network locations
given in the Document for previous versions it was based
on. These may be placed in the <SPAN
CLASS="QUOTE"
>"History"</SPAN
>
section. You may omit a network location for a work that
was published at least four years before the Document
itself, or if the original publisher of the version it
refers to gives permission.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>K. </B
>
In any section entitled <SPAN
CLASS="QUOTE"
>"Acknowledgements"</SPAN
> or
<SPAN
CLASS="QUOTE"
>"Dedications"</SPAN
>, preserve the section's title,
and preserve in the section all the substance and tone of
each of the contributor acknowledgements and/or
dedications given therein.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>L. </B
>
Preserve all the <A
HREF="#fdl-invariant"
>Invariant
Sections</A
> of the <A
HREF="#fdl-document"
>Document</A
>, unaltered in their
text and in their titles. Section numbers or the
equivalent are not considered part of the section titles.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>M. </B
>
Delete any section entitled
<SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
>. Such a section may not be
included in the <A
HREF="#fdl-modified"
>Modified
Version</A
>.
</P
></DIV
></LI
><LI
STYLE="list-style-type: opencircle"
><DIV
CLASS="formalpara"
><P
><B
>N. </B
>
Do not retitle any existing section as
<SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
> or to conflict in title with
any <A
HREF="#fdl-invariant"
>Invariant
Section</A
>.
</P
></DIV
></LI
></UL
><P
>&#13; If the <A
HREF="#fdl-modified"
>Modified Version</A
>
includes new front-matter sections or appendices that qualify as
<A
HREF="#fdl-secondary"
>Secondary Sections</A
> and
contain no material copied from the Document, you may at your
option designate some or all of these sections as invariant. To
do this, add their titles to the list of <A
HREF="#fdl-invariant"
>Invariant Sections</A
> in the
Modified Version's license notice. These titles must be
distinct from any other section titles.
</P
><P
>&#13; You may add a section entitled <SPAN
CLASS="QUOTE"
>"Endorsements"</SPAN
>,
provided it contains nothing but endorsements of your <A
HREF="#fdl-modified"
>Modified Version</A
> by various
parties--for example, statements of peer review or that the text
has been approved by an organization as the authoritative
definition of a standard.
</P
><P
>&#13; You may add a passage of up to five words as a <A
HREF="#fdl-cover-texts"
>Front-Cover Text</A
>, and a passage
of up to 25 words as a <A
HREF="#fdl-cover-texts"
>Back-Cover Text</A
>, to the end of
the list of <A
HREF="#fdl-cover-texts"
>Cover Texts</A
>
in the <A
HREF="#fdl-modified"
>Modified Version</A
>.
Only one passage of Front-Cover Text and one of Back-Cover Text
may be added by (or through arrangements made by) any one
entity. If the <A
HREF="#fdl-document"
>Document</A
>
already includes a cover text for the same cover, previously
added by you or by arrangement made by the same entity you are
acting on behalf of, you may not add another; but you may
replace the old one, on explicit permission from the previous
publisher that added the old one.
</P
><P
>&#13; The author(s) and publisher(s) of the <A
HREF="#fdl-document"
>Document</A
> do not by this License
give permission to use their names for publicity for or to
assert or imply endorsement of any <A
HREF="#fdl-modified"
>Modified Version </A
>.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section5"
></A
>F.6. 5. COMBINING DOCUMENTS</H1
><P
>&#13; You may combine the <A
HREF="#fdl-document"
>Document</A
>
with other documents released under this License, under the
terms defined in <A
HREF="#fdl-section4"
>section 4</A
>
above for modified versions, provided that you include in the
combination all of the <A
HREF="#fdl-invariant"
>Invariant
Sections</A
> of all of the original documents, unmodified,
and list them all as Invariant Sections of your combined work in
its license notice.
</P
><P
>&#13; The combined work need only contain one copy of this License,
and multiple identical <A
HREF="#fdl-invariant"
>Invariant
Sections</A
> may be replaced with a single copy. If there are
multiple Invariant Sections with the same name but different
contents, make the title of each such section unique by adding
at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique
number. Make the same adjustment to the section titles in the
list of Invariant Sections in the license notice of the combined
work.
</P
><P
>&#13; In the combination, you must combine any sections entitled
<SPAN
CLASS="QUOTE"
>"History"</SPAN
> in the various original documents,
forming one section entitled <SPAN
CLASS="QUOTE"
>"History"</SPAN
>; likewise
combine any sections entitled <SPAN
CLASS="QUOTE"
>"Acknowledgements"</SPAN
>,
and any sections entitled <SPAN
CLASS="QUOTE"
>"Dedications"</SPAN
>. You must
delete all sections entitled <SPAN
CLASS="QUOTE"
>"Endorsements."</SPAN
>
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section6"
></A
>F.7. 6. COLLECTIONS OF DOCUMENTS</H1
><P
>&#13; You may make a collection consisting of the <A
HREF="#fdl-document"
>Document</A
> and other documents
released under this License, and replace the individual copies
of this License in the various documents with a single copy that
is included in the collection, provided that you follow the
rules of this License for verbatim copying of each of the
documents in all other respects.
</P
><P
>&#13; You may extract a single document from such a collection, and
dispbibute it individually under this License, provided you
insert a copy of this License into the extracted document, and
follow this License in all other respects regarding verbatim
copying of that document.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section7"
></A
>F.8. 7. AGGREGATION WITH INDEPENDENT WORKS</H1
><P
>&#13; A compilation of the <A
HREF="#fdl-document"
>Document</A
> or its derivatives with
other separate and independent documents or works, in or on a
volume of a storage or distribution medium, does not as a whole
count as a <A
HREF="#fdl-modified"
>Modified Version</A
>
of the Document, provided no compilation copyright is claimed
for the compilation. Such a compilation is called an
<SPAN
CLASS="QUOTE"
>"aggregate"</SPAN
>, and this License does not apply to the
other self-contained works thus compiled with the Document , on
account of their being thus compiled, if they are not themselves
derivative works of the Document. If the <A
HREF="#fdl-cover-texts"
>Cover Text</A
> requirement of <A
HREF="#fdl-section3"
>section 3</A
> is applicable to these
copies of the Document, then if the Document is less than one
quarter of the entire aggregate, the Document's Cover Texts may
be placed on covers that surround only the Document within the
aggregate. Otherwise they must appear on covers around the whole
aggregate.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section8"
></A
>F.9. 8. TRANSLATION</H1
><P
>&#13; Translation is considered a kind of modification, so you may
distribute translations of the <A
HREF="#fdl-document"
>Document</A
> under the terms of <A
HREF="#fdl-section4"
>section 4</A
>. Replacing <A
HREF="#fdl-invariant"
> Invariant Sections</A
> with
translations requires special permission from their copyright
holders, but you may include translations of some or all
Invariant Sections in addition to the original versions of these
Invariant Sections. You may include a translation of this
License provided that you also include the original English
version of this License. In case of a disagreement between the
translation and the original English version of this License,
the original English version will prevail.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section9"
></A
>F.10. 9. TERMINATION</H1
><P
>&#13; You may not copy, modify, sublicense, or distribute the <A
HREF="#fdl-document"
>Document</A
> except as expressly
provided for under this License. Any other attempt to copy,
modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-section10"
></A
>F.11. 10. FUTURE REVISIONS OF THIS LICENSE</H1
><P
>&#13; The <A
HREF="http://www.gnu.org/fsf/fsf.html"
TARGET="_top"
>Free Software
Foundation</A
> may publish new, revised versions of the GNU
Free Documentation License from time to time. Such new versions
will be similar in spirit to the present version, but may differ
in detail to address new problems or concerns. See <A
HREF="http://www.gnu.org/copyleft"
TARGET="_top"
>http://www.gnu.org/copyleft/</A
>.
</P
><P
>&#13; Each version of the License is given a distinguishing version
number. If the <A
HREF="#fdl-document"
>Document</A
>
specifies that a particular numbered version of this License
<SPAN
CLASS="QUOTE"
>"or any later version"</SPAN
> applies to it, you have the
option of following the terms and conditions either of that
specified version or of any later version that has been
published (not as a draft) by the Free Software Foundation. If
the Document does not specify a version number of this License,
you may choose any version ever published (not as a draft) by
the Free Software Foundation.
</P
></DIV
><DIV
CLASS="sect1"
><HR><H1
CLASS="sect1"
><A
NAME="fdl-using"
></A
>F.12. Addendum</H1
><P
>&#13; To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
</P
><A
NAME="AEN4253"
></A
><BLOCKQUOTE
CLASS="BLOCKQUOTE"
><P
>&#13; Copyright <20> YEAR YOUR NAME.
</P
><P
>&#13; Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation
License, Version 1.1 or any later version published by the
Free Software Foundation; with the <A
HREF="#fdl-invariant"
>Invariant Sections</A
> being LIST
THEIR TITLES, with the <A
HREF="#fdl-cover-texts"
>Front-Cover Texts</A
> being LIST,
and with the <A
HREF="#fdl-cover-texts"
>Back-Cover
Texts</A
> being LIST. A copy of the license is included in
the section entitled <SPAN
CLASS="QUOTE"
>"GNU Free Documentation
License"</SPAN
>.
</P
></BLOCKQUOTE
><P
>&#13; If you have no <A
HREF="#fdl-invariant"
>Invariant
Sections</A
>, write <SPAN
CLASS="QUOTE"
>"with no Invariant Sections"</SPAN
>
instead of saying which ones are invariant. If you have no
<A
HREF="#fdl-cover-texts"
>Front-Cover Texts</A
>, write
<SPAN
CLASS="QUOTE"
>"no Front-Cover Texts"</SPAN
> instead of
<SPAN
CLASS="QUOTE"
>"Front-Cover Texts being LIST"</SPAN
>; likewise for <A
HREF="#fdl-cover-texts"
>Back-Cover Texts</A
>.
</P
><P
>&#13; If your document contains nontrivial examples of program code,
we recommend releasing these examples in parallel under your
choice of free software license, such as the <A
HREF="http://www.gnu.org/copyleft/gpl.html"
TARGET="_top"
> GNU General Public
License</A
>, to permit their use in free software.
</P
></DIV
></DIV
></DIV
><H3
CLASS="FOOTNOTES"
>Notes</H3
><TABLE
BORDER="0"
CLASS="FOOTNOTES"
WIDTH="100%"
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN127"
HREF="#AEN127"
><SPAN
CLASS="footnote"
>[1]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>Please, take a look at the <A
HREF="http://cvsview.tldp.org/index.cgi/LDP/guide/docbook/LDP-Author-Guide/"
TARGET="_top"
>&#13; source</A
> to see how to get
similar results on your documents. You should also remember that
the way this appears to you depends on the format in which you are reading
this document: online appearance is slightly different from the
PostScript or PDF ones.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN2259"
HREF="#AEN2259"
><SPAN
CLASS="footnote"
>[2]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>In truth, "XSL" is actually comprised of three
components: the <EM
>XSLT</EM
> transformation language,
the <EM
>XPath</EM
> expression language (used by XSLT),
and XSL Formatting Objects (FO) that are used for describing a page.
The style sheets are actually written in XSLT and generate either HTML
or (for print output) FO. The FO file is then run through a FO processor
to create the actual print (PDF or PostScript) output. See the
<A
HREF="http://www.w3.org/Style/XSL/WhatIsXSL.html"
TARGET="_top"
>W3C web
site</A
> for more information.</P
></TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="5%"
><A
NAME="FTN.AEN2280"
HREF="#AEN2280"
><SPAN
CLASS="footnote"
>[3]</SPAN
></A
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
WIDTH="95%"
><P
>In XSL
terminology, the process of generating multiple files is referred to
as "chunking".</P
></TD
></TR
></TABLE
></BODY
></HTML
>
Reference in New Issue View Git Blame Copy Permalink