FreeBSD Documentation Project Primer for New Contributors

The FreeBSD Documentation Project

Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 DocEng

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.

[ Split HTML / Single HTML ]
Table of Contents
Preface
Shell Prompts
Typographic Conventions
Notes, Tips, Important Information, Warnings, and Examples
Acknowledgments
1 Overview
1.1 The FreeBSD Documentation Set
1.2 Before You Start
1.3 Quick 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 Images
4.2.7 Links
5 * Stylesheets
5.1 * DSSSL
5.2 CSS
5.2.1 The DocBook Documents
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 Documentation Build Process
7.1 The FreeBSD Documentation Build Toolset
7.2 Understanding Makefiles in the Documentation tree
7.2.1 Subdirectory Makefiles
7.2.2 Documentation Makefiles
7.3 FreeBSD Documentation Project make includes
7.3.1 doc.project.mk
7.3.2 doc.subdir.mk
8 The Website
8.1 Preparation
8.1.1 Simple Method: Using csup
8.1.2 Advanced Method: Maintaining a Local CVS doc/www Repository
8.2 Build the Web Pages from Scratch
8.3 Install the Web Pages into Your Web Server
8.4 Environment Variables
9 Translations
10 Writing Style
10.1 Style Guide
10.1.1 Letter Case
10.1.2 Acronyms
10.1.3 Indentation
10.1.4 Tag Style
10.1.5 White Space Changes
10.1.6 Non-Breaking Space
10.2 Word List
11 Using sgml-mode with Emacs
12 See Also
12.1 The FreeBSD Documentation Project
12.2 SGML
12.3 HTML
12.4 DocBook
12.5 The Linux Documentation Project
A. Examples
A.1 DocBook <book>
A.2 DocBook <article>
A.3 Producing Formatted Output
A.3.1 Using Jade
List of Examples
1. A Sample Example
3-1. Using an Element (Start and End Tags)
3-2. Using an Element (Start Tag Only)
3-3. Elements within Elements; <em>
3-4. Using An Element with An Attribute
3-5. Single Quotes Around Attributes
3-6. .profile, for sh(1) and bash(1) Users
3-7. .cshrc, for csh(1) and tcsh(1) Users
3-8. SGML Generic Comment
3-9. Erroneous SGML Comments
3-10. Defining General Entities
3-11. Defining Parameter Entities
3-12. Using General Entities to Include Files
3-13. Using Parameter Entities to Include Files
3-14. Structure of A Marked Section
3-15. Using a CDATA Marked Section
3-16. Using INCLUDE and IGNORE in Marked Sections
3-17. Using A Parameter Entity to Control a Marked Section
4-1. Normal HTML Document Structure
4-2. <h1>, <h2>, etc.
4-3. Bad Ordering of <hn> Elements
4-4. <p>
4-5. <blockquote>
4-6. <ul> and <ol>
4-7. Definition Lists with <dl>
4-8. <pre>
4-9. Simple Use of <table>
4-10. Using rowspan
4-11. Using colspan
4-12. Using rowspan and colspan together
4-13. <em> and <strong>
4-14. <b> and <i>
4-15. <tt>
4-16. <big>, <small>, and <font>
4-17. Using <a href="...">
4-18. Using <a name="...">
4-19. Linking to A Named Part of Another Document
4-20. Linking to A Named Part of the Same Document
4-21. Boilerplate <book> with <bookinfo>
4-22. Boilerplate <article> with <articleinfo>
4-23. A Simple Chapter
4-24. Empty Chapters
4-25. Sections in Chapters
4-26. <para>
4-27. <blockquote>
4-28. <warning>
4-29. <itemizedlist>, <orderedlist>, and <procedure>
4-30. <programlisting>
4-31. <co> and <calloutlist>
4-32. <informaltable>
4-33. Tables Where frame="none"
4-34. <screen>, <prompt>, and <userinput>
4-35. <emphasis>
4-36. Quotations
4-37. Keys, Mouse Buttons, and Combinations
4-38. Applications, Commands, and Options
4-39. <filename>
4-40. <filename> tag with package role
4-41. <devicename>
4-42. <hostid> and Roles
4-43. <username>
4-44. <maketarget> and <makevar>
4-45. <literal>
4-46. <replaceable>
4-47. <errorname>
4-48. Attribute id on Chapters and Sections
4-49. <anchor>
4-50. Using <xref>
4-51. Using <link>
4-52. <ulink>
A-1. DocBook <book>
A-2. DocBook <article>
A-3. Converting DocBook to HTML (one large file)
A-4. Converting DocBook to HTML (several small files)
A-5. Converting DocBook to Postscript
A-6. Converting DocBook to PDF
    Next
    Preface