LDP Author Guide

Mark F. Komarinski

VA Linux Systems

markk@wayga.net

Jorge Godoy

Conectiva S.A.
Publishing Department

godoy@conectiva.com

godoy@metalab.unc.edu

David C. Merrill

dcmerrill@mindspring.com

Revision History
Revision 3.82001-09-25Revised by: dy
XML/XSLT information.
Revision 3.72001-06-20Revised by: mfk
Now under the GFDL.
Revision 3.622001-03-13Revised by: mfk
Spelling and grammar changes from Dave Edwards (amoamasam@sympatico.ca). Also performed some housecleaning from comments of discuss@linuxdoc.org.
Revision 3.62001-01-10Revised by: mfk
First revision in DocBook XML. Added section covering writing in DB XML, since first rev is 4.1.
Revision 3.512001-01-05Revised by: mfk
sgedit (now tksgml) is not free, included link for pricing, more XML info
Revision 3.5Dec 4, 2000Revised by: mfk
Changed mailing list pointers to new lists.
Revision 3.4Dec 1, 2000Revised by: dcm
Added Crediting Translators and Converters
Revision 3.3Nov 11, 2000Revised by: mfk
Added links to SGML GPL and FDL
Revision 3.1Oct 10, 2000Revised by: mfk
Spelling changes, changed list of LDP policies to now accept DocBook XML. More information about how to use *jade with XML will follow.
Revision 3.0Aug 24, 2000Revised by: gjf
Integrated David Merrill's style guide document. Further clean-up and additions.
Revision 2.0Jul 13, 2000Revised by: mfk
Cleaned up using-docbook a bit. Moved some chapters
Revision 1.9Jun 26, 2000Revised by: mfk
Integrated Jorge's using-docbook document.
Revision 1.5Jun 14, 2000Revised by: mfk
Documented sgedit
Revision 1.4Jun 12, 2000Revised by: mfk
Documented vim and sgedit. Spelling and other changes from ldp list. Also added LDP guidelines under style guide.

List the tools, procedures, and hints to get LDP authors up to speed and writing.


Table of Contents
1. About this Guide
1.1. Purpose / Scope of this Guide
1.2. About the LDP
1.3. Feedback
1.4. Copyrights and Trademarks
1.5. Acknowledgments and Thanks
1.6. Documents
2. Introduction to the LDP and DocBook
2.1. The LDP
2.2. DocBook
2.3. Why DocBook instead of HTML or other formats?
2.4. Writing in DocBook XML
2.5. For New Authors
2.6. Mailing Lists
3. The tools
3.1. DSSSL
3.2. DocBook DTD (version 4.1 or 3.1)
3.3. Jade
3.4. Jade wrappers
3.5. Editing tools
3.6. CVS
3.7. Other/Reference
4. Using DocBook Tags
4.1. Introduction
4.2. Configuration needed
4.3. Creating and modifying catalogues
4.4. Writing with DocBook elements
4.5. Encoding Indexes
4.6. Inserting Pictures
4.7. Tables
4.8. Listings and program codes
4.9. Crediting Translators and Converters
4.10. Tools & Hints
4.11. Document samples
5. LDP Style Guide
5.1. Deciding on a Subject
5.2. Developing an Outline
5.3. Writing the Text
5.4. Editing and Proofing the Text
5.5. Maintaining Your HOWTO
5.6. References
6. Additional Style-related Items
6.1. Date formats
6.2. Graphics formats
6.3. DocBook Versions
6.4. Obsolete Tags
6.5. Tag Minimization
6.6. Conventions
7. Tips and Tricks with DocBook
7.1. Including Images
7.2. Naming separate HTML files
7.3. Using ldp.dsl
7.4. Using the LDP XSL stylesheets
8. Distributing your documentation
8.1. Before you distribute
8.2. Copyright and Licensing issues
8.3. Submission to LDP
8.4. Maintaining Your HOWTO
9. FAQs about the LDP
A. GNU Free Documentation License
A.1. 0. PREAMBLE
A.2. 1. APPLICABILITY AND DEFINITIONS
A.3. 2. VERBATIM COPYING
A.4. 3. COPYING IN QUANTITY
A.5. 4. MODIFICATIONS
A.6. 5. COMBINING DOCUMENTS
A.7. 6. COLLECTIONS OF DOCUMENTS
A.8. 7. AGGREGATION WITH INDEPENDENT WORKS
A.9. 8. TRANSLATION
A.10. 9. TERMINATION
A.11. 10. FUTURE REVISIONS OF THIS LICENSE
A.12. Addendum
Glossary
Index
List of Tables
4-1. Useful commands
4-2. Example Table
List of Figures
3-1. epcEdit screen shot
3-2. nedit screen shot
3-3. Adding shell commands to nedit
3-4. nsgmls output on success
List of Examples
4-1. Example of catalogue
4-2. Code for the generation of an index
4-3. Use of the attribute zone
4-4. Usage of values startofrange and endofrange on the attributeclass
4-5. Inserting a picture
4-6. Using <imageobject>
4-7. Inserting tables
4-8. Script compiles-sgml
4-9. Stylesheet to insert summaries in articles
4-10. Configuring an external entity to include the index
4-11. Use of parameter entities