LDP Author Guide Jorge Godoy Conectiva S.A. Publishing Department <[email protected]> Emma Jane Hogbin <[email protected]> Mark F. Komarinski <[email protected]> David C. Merrill david −AT− lupercalia.net 2005−03−04 Revision History Revision Revised by: 2006−04−202005−03−042005−01−232004−07−142004−04−192004−04−042004−04−022004−01−27 4.84.74.64.54.44.34.24.1 MGejhejhejhejhejhejhejh 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). 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. LDP Author Guide Table of Contents Chapter 1. About this Guide..............................................................................................................................1 1.1. About this Guide...............................................................................................................................1 1.2. About The LDP.................................................................................................................................1 1.3. Feedback...........................................................................................................................................2 1.4. Copyrights and Trademarks..............................................................................................................2 1.5. Acknowledgments and Thanks.........................................................................................................2 1.5.1. Version 1 − Version 3.............................................................................................................2 1.5.2. Version 4.................................................................................................................................2 1.6. Document Conventions.....................................................................................................................2 Chapter 2. Authoring TLDP Documents: An Introduction............................................................................4 2.1. Summary of The LDP Process..........................................................................................................4 2.2. Mailing Lists.....................................................................................................................................5 Chapter 3. Writing Your Proposal....................................................................................................................6 3.1. Choosing a Subject...........................................................................................................................6 3.2. Scope of Your Document..................................................................................................................6 3.2.1. Documentation Templates.......................................................................................................7 3.3. Unmaintained and Out−of−date Documents....................................................................................7 3.4. Developing an Outline......................................................................................................................8 3.5. Research............................................................................................................................................9 Chapter 4. Write...............................................................................................................................................10 4.1. Writing the Text..............................................................................................................................10 4.1.1. Writing Style and Style Guides.............................................................................................10 4.1.2. On−line Writing Resources...................................................................................................11 4.2. Edit and Proofread the Text............................................................................................................11 4.3. Tools for Writing, Editing and Maintaining your Document.........................................................12 4.3.1. Editing Tools.........................................................................................................................12 4.3.2. Concurrent Versions System (CVS)......................................................................................12 4.3.3. Spell Check............................................................................................................................13 Chapter 5. Markup...........................................................................................................................................14 5.1. Markup: A General Overview........................................................................................................14 5.2. DocBook: What it is and why we use it..........................................................................................14 5.3. XML and SGML: Why we use XML.............................................................................................15 5.4. Markup Languages Accepted by TLDP.........................................................................................16 Chapter 6. Distributing Your Documentation...............................................................................................17 6.1. Before Distributing Your Documentation......................................................................................17 6.2. Licensing and Copyright.................................................................................................................17 6.2.1. Copyright...............................................................................................................................18 6.2.2. Disclaimer.............................................................................................................................18 6.2.3. Licensing source code...........................................................................................................18 6.3. Acknowledgments...........................................................................................................................18 6.4. TLDP Review Process....................................................................................................................19 6.5. Submission to LDP for publication................................................................................................20 i LDP Author Guide Table of Contents Chapter 7. Maintenance...................................................................................................................................21 7.1. Maintaining Your Document..........................................................................................................21 7.2. Fixing Errors...................................................................................................................................21 7.2.1. Fixing Your Own Documents...............................................................................................21 7.2.2. Fixing Other Documents in the Collection............................................................................21 References..........................................................................................................................................................23 Markup and general information...........................................................................................................23 DocBook References.......................................................................................................................23 LinuxDoc.........................................................................................................................................24 Converting Other Formats to DocBook..........................................................................................24 LDP templates, tools & links..........................................................................................................24 DocBook Transformations..............................................................................................................25 General Writing Links and Style Guides........................................................................................25