FreeBSD Documentation Project Primer for New Contributors

The FreeBSD Documentation Project

Revision: 47339
Copyright
Last modified on 2015-09-02 by wblock.
Abstract

Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it.

This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, including tools, software, and the philosophy behind the Documentation Project.

This is a work in progress. Corrections and additions are always welcome.

[ Split HTML / Single HTML ]

Table of Contents
Preface
1. Shell Prompts
2. Typographic Conventions
3. Notes, Tips, Important Information, Warnings, and Examples
4. Acknowledgments
1. Overview
1.1. The FreeBSD Documentation Set
1.2. Quick Start
2. Tools
2.1. Required Tools
2.2. Optional Tools
3. The Working Copy
3.1. Documentation and Manual Pages
3.2. Choosing a Directory
3.3. Checking Out a Copy
3.4. Updating a Working Copy
3.5. Reverting Changes
3.6. Making a Diff
3.7. Subversion References
4. Documentation Directory Structure
4.1. The Top Level, doc/
4.2. The lang.encoding/ Directories
4.3. Document-Specific Information
5. The Documentation Build Process
5.1. Rendering DocBook into Output
5.2. The FreeBSD Documentation Build Toolset
5.3. Understanding Makefiles in the Documentation Tree
5.4. FreeBSD Documentation Project Make Includes
6. The Website
6.1. Environment Variables
6.2. Building and Installing the Web Pages
7. XML Primer
7.1. Overview
7.2. Elements, Tags, and Attributes
7.3. The DOCTYPE Declaration
7.4. Escaping Back to XML
7.5. Comments
7.6. Entities
7.7. Using Entities to Include Files
7.8. Marked Sections
7.9. Conclusion
8. XHTML Markup
8.1. Introduction
8.2. Formal Public Identifier (FPI)
8.3. Sectional Elements
8.4. Block Elements
8.5. In-line Elements
9. DocBook Markup
9.1. Introduction
9.2. FreeBSD Extensions
9.3. Formal Public Identifier (FPI)
9.4. Document Structure
9.5. Block Elements
9.6. In-line Elements
9.7. Images
9.8. Links
10. Style Sheets
10.1. CSS
11. Translations
12. PO Translations
12.1. Introduction
12.2. Quick Start
12.3. Creating New Translations
12.4. Translating
12.5. Tips for Translators
12.6. Building a Translated Document
13. Writing Style
13.1. Tips
13.2. Guidelines
13.3. Style Guide
13.4. Word List
14. Editor Configuration
14.1. Vim
14.2. Emacs
14.3. nano
15. See Also
15.1. The FreeBSD Documentation Project
15.2. XML
15.3. HTML
15.4. DocBook
A. Examples
A.1. DocBook book
A.2. DocBook article
Index
List of Tables
5.1. Common Output Formats
12.1. Language Names
List of Examples
1. A Sample Example
5.1. Build a Single HTML Output File
5.2. Build HTML-Split and PDF Output Files
6.1. Build the Full Web Site and All Documents
6.2. Build Only the Web Site in English
6.3. Build and Install the Web Site
7.1. Using an Element (Start and End Tags)
7.2. Using an Element Without Content
7.3. Elements Within Elements; em
7.4. Using an Element with an Attribute
7.5. Single Quotes Around Attributes
7.6. XML Generic Comment
7.7. Erroneous XML Comments
7.8. Defining General Entities
7.9. Defining Parameter Entities
7.10. Using General Entities to Include Files
7.11. Using Parameter Entities to Include Files
7.12. Structure of a Marked Section
7.13. Using a CDATA Marked Section
7.14. Using INCLUDE and IGNORE in Marked Sections
7.15. Using a Parameter Entity to Control a Marked Section
8.1. Normal XHTML Document Structure
8.2. h1, h2, and Other Header Tags
8.3. p
8.4. blockquote
8.5. ul and ol
8.6. Definition Lists with dl
8.7. pre
8.8. Simple Use of table
8.9. Using rowspan
8.10. Using colspan
8.11. Using rowspan and colspan Together
8.12. em and strong
8.13. tt
8.14. Using <a href="...">
8.15. Creating an Anchor
8.16. Linking to a Named Part of a Different Document
8.17. Linking to a Named Part of the Same Document
9.1. Boilerplate book with info
9.2. Boilerplate article with info
9.3. A Simple Chapter
9.4. Empty Chapters
9.5. Sections in Chapters
9.6. para
9.7. blockquote
9.8. tip and important
9.9. example Source
9.10. Rendered example
9.11. itemizedlist and orderedlist
9.12. variablelist
9.13. procedure
9.14. programlisting
9.15. co and calloutlist
9.16. informaltable
9.17. Tables Where frame="none"
9.18. screen, prompt, and userinput
9.19. emphasis
9.20. Acronyms
9.21. Quotations
9.22. Keys, Mouse Buttons, and Combinations
9.23. Applications, Commands, and Options
9.24. filename
9.25. package Tag
9.26. systemitem and Classes
9.27. email with a Hyperlink
9.28. email Without a Hyperlink
9.29. buildtarget and varname
9.30. literal
9.31. replaceable
9.32. guibutton
9.33. errorname
9.34. xml:id on Chapters and Sections
9.35. anchor
9.36. Using xref
9.37. Using link
9.38. link to a FreeBSD Documentation Web Page
9.39. link to a FreeBSD Web Page
9.40. ulink to an External Web Page
12.1. Creating a Spanish Translation of the Porter's Handbook
12.2. Creating a French Translation of the PGP Keys Article
12.3. Translating the Porter's Handbook to Spanish
12.4. Preserving XML Tags
12.5. Building the Spanish Porter's Handbook
A.1. DocBook book
A.2. DocBook article

All FreeBSD documents are available for download at http://ftp.FreeBSD.org/pub/FreeBSD/doc/

Questions that are not answered by the documentation may be sent to <freebsd-questions@FreeBSD.org>.
Send questions about this document to <freebsd-doc@FreeBSD.org>.