This is an archive of past FreeBSD releases; it's part of the FreeBSD Documentation Archive.

FreeBSD Documentation Project Primer for New Contributors

FreeBSD Documentation Project Primer for New Contributors

Nik Clayton

nik@FreeBSD.org

Copyright © 1998, 1999 by Nik Clayton

Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable.

This primer covers everything you will need to know in order to start contributing to the FreeBSD Documentation Project, from the tools and software you will be using (both mandatory and recommended) to the philosophy behind the Documentation Project.

This document is a work in progress, and is not complete. Sections that are known to be incomplete are indicated with a * in their name.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.

  2. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

Important: THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Table of Contents
Preface
1. Shell Prompts
2. Typographic Conventions
3. Notes, warnings, and examples
4. Acknowledgments
1. Overview
1.1. The FreeBSD Documentation Set
1.2. Before you start
2. Tools
2.1. Mandatory tools
2.1.1. Software
2.1.2. DTDs and Entities
2.1.3. Stylesheets
2.2. Optional tools
2.2.1. Software
3. SGML Primer
3.1. Overview
3.2. Elements, tags, and attributes
3.2.1. For you to do...
3.3. The DOCTYPE declaration
3.3.1. Formal Public Identifiers (FPIs)
3.3.2. Alternatives to FPIs
3.4. Escaping back to SGML
3.5. Comments
3.5.1. For you to do...
3.6. Entities
3.6.1. General Entities
3.6.2. Parameter entities
3.6.3. For you to do...
3.7. Using entities to include files
3.7.1. Using general entities to include files
3.7.2. Using parameter entities to include files
3.7.3. For you to do...
3.8. Marked sections
3.8.1. Marked section keywords
3.8.2. For you to do...
3.9. Conclusion
4. SGML Markup
4.1. HTML
4.1.1. Formal Public Identifier (FPI)
4.1.2. Sectional elements
4.1.3. Block elements
4.1.4. In-line elements
4.1.5. Links
4.2. DocBook
4.2.1. FreeBSD extensions
4.2.2. Formal Public Identifier (FPI)
4.2.3. Document structure
4.2.4. Block elements
4.2.5. In-line elements
4.2.6. Links
4.3. * LinuxDoc
5. * Stylesheets
5.1. * DSSSL
5.2. * CSS
6. Structuring documents under doc/
6.1. The top level, doc/
6.2. The lang.encoding/ directories
6.3. Document specific information
6.3.1. The Handbook
7. * The Website
8. Translations
9. Writing style
9.1. Style guide
9.1.1. Letter case
9.1.2. Indentation
9.1.3. Tag style
9.1.4. White space changes
10. Using sgml-mode with Emacs
11. See Also
11.1. The FreeBSD Documentation Project
11.2. SGML
11.3. HTML
11.4. DocBook
11.5. The Linux Documentation Project
    Next
    Preface