LDP Author Guide
   Next

LDP Author Guide

Jorge Godoy

Conectiva S.A.
 Publishing Department

Emma Jane Hogbin

Mark F. Komarinski

David C. Merrill

david -AT- lupercalia.net

2005-03-04

Revision History
Revision 4.82006-04-20MG
Added notes about prefered submission formats, corrected links, packaged templates.
Revision 4.72005-03-04ejh
Typo fixed in sample DocBook markup. Added new web-based authoring tool and information on LaTeX to DocBook conversions.
Revision 4.62005-01-23ejh
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.
Revision 4.52004-07-14ejh
Updated information regarding CVS accounts and connecting to the CVS server.
Revision 4.42004-04-19ejh
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.
Revision 4.32004-04-04ejh
Removed the section Contributing to The LDP (replaced by Summary of The LDP Process).
Revision 4.22004-04-02ejh
Added references for LyX to DocBook conversions in the bibliography.
Revision 4.12004-01-27ejh
Updated the license requirements and added them to the table of contents (moved them out of the sub-section).

Abstract

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.

Table of Contents

1. About this Guide
1. About this Guide
2. About The LDP
3. Feedback
4. Copyrights and Trademarks
5. Acknowledgments and Thanks
5.1. Version 1 - Version 3
5.2. Version 4
6. Document Conventions
2. Authoring TLDP Documents: An Introduction
1. Summary of The LDP Process
2. Mailing Lists
3. Writing Your Proposal
1. Choosing a Subject
2. Scope of Your Document
2.1. Documentation Templates
3. Unmaintained and Out-of-date Documents
4. Developing an Outline
5. Research
4. Write
1. Writing the Text
1.1. Writing Style and Style Guides
1.2. On-line Writing Resources
2. Edit and Proofread the Text
3. Tools for Writing, Editing and Maintaining your Document
3.1. Editing Tools
3.2. git
3.3. Spell Check
5. Markup
1. Markup: A General Overview
2. DocBook: What it is and why we use it
3. XML and SGML: Why we use XML
4. Markup Languages Accepted by TLDP
6. Distributing Your Documentation
1. Before Distributing Your Documentation
2. Licensing and Copyright
2.1. Copyright
2.2. Disclaimer
2.3. Licensing source code
3. Acknowledgments
4. TLDP Review Process
5. Submission to LDP for publication
7. Maintenance
1. Maintaining Your Document
2. Fixing Errors
2.1. Fixing Your Own Documents
2.2. Fixing Other Documents in the Collection
References
A. Templates
1. Document Templates
2. Style Sheets
3. GNU Free Documentation License
B. System Setup: Editors, Validation and Transformations
1. Tools for your operating system
2. Editing tools
2.1. Word Processors
2.2. Text Editors
3. Validation
3.1. Why Validate Your Document
3.2. Validation for the Faint of Heart
3.3. Validation for the Not So Faint Of Heart
3.4. Creating and modifying catalogs
3.5. Validating XML
4. Transformations
4.1. DSSSL
4.2. The docbook-utils Package
4.3. XSL
5. DocBook DTD
6. Formatting Documents
6.1. Inserting a summary on the initial articles page
6.2. Inserting indexes automatically
C. git revision control
1. Introduction to git
2. Setting up git on your local Linux system
3. First time git setup
4. Submitting changes to TLDP
D. DocBook: Sample Markup
1. General Tips and Tricks
1.1. Useful markup
2. <section> and <sectN>: what's the difference?
3. Command Prompts
4. Encoding Indexes
5. Inserting Pictures
5.1. Graphics formats
5.2. Alternative Methods
6. Markup for Metadata
6.1. Crediting Translators, Converters and Co-authors
6.2. <revremark>s
6.3. Revision History
6.4. Date formats
6.5. Sample Article (or Book) Information Element
7. Bibliographies
8. Entities (shortcuts, text macros and re-usable text)
9. Customizing your HTML files
9.1. HTML file names
9.2. Headers and Footers
E. Converting Documents to DocBook XML
1. Text to DocBook
2. OpenOffice.org to DocBook
2.1. Open Office 1.0.x
2.2. Open Office 1.1
3. Microsoft Word to DocBook
4. LaTeX to DocBook
5. LyX to DocBook
6. DocBook to DocBook Transformations
6.1. XML and SGML DocBook
6.2. Changing DTDs
Glossary
F. GNU Free Documentation License
1. 0. PREAMBLE
2. 1. APPLICABILITY AND DEFINITIONS
3. 2. VERBATIM COPYING
4. 3. COPYING IN QUANTITY
5. 4. MODIFICATIONS
6. 5. COMBINING DOCUMENTS
7. 6. COLLECTIONS OF DOCUMENTS
8. 7. AGGREGATION WITH INDEPENDENT WORKS
9. 8. TRANSLATION
10. 9. TERMINATION
11. 10. FUTURE REVISIONS OF THIS LICENSE
12. Addendum

List of Figures

B.1. nedit screen shot
B.2. Adding shell commands to nedit
B.3. nsgmls output on success

List of Tables

D.1. Useful markup

List of Examples

B.1. Setting the SGML_CATALOG_FILES and XML_CATALOG_FILES Environmental Variables
B.2. Example of an SGML catalog
B.3. Sample XML Catalog file
B.4. Debugging example using xmllint
B.5. “Installing” DSSSL style sheets
B.6. Example creating HTML output
B.7. “Installing” DocBook Document Type Definitions
B.8. Style sheet to insert summaries in articles
B.9. Configuring an external entity to include the index
D.1. Command Prompt with programlisting
D.2. Command Prompt with screen
D.3. Code for the generation of an index
D.4. Use of the attribute zone
D.5. Usage of values startofrange and endofrange on the attributeclass
D.6. Inserting a picture
D.7. Using <imageobject>
D.8. Other Credit
D.9. Editor
D.10. Sample Meta Data
D.11. A Bibliography
D.12. Adding Entities
D.13. Use of parameter entities
   Next
   Chapter 1. About this Guide