FreeBSD Documentation Project Primer for New Contributors
		Next

FreeBSD Documentation Project Primer for New Contributors

The FreeBSD Documentation Project

Revision: 43126

Last modified on 2013-11-07 by gabor.

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 Mirror
3.3. Choosing a Directory
3.4. Checking Out a Copy
3.5. Updating a Working Copy
3.6. Reverting Changes
3.7. Making a Diff
3.8. 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. The FreeBSD Documentation Build Toolset
5.2. Understanding Makefiles in the Documentation Tree
5.3. FreeBSD Documentation Project Make Includes

6. The Website

6.1. Build the Web Pages
6.2. Install the Web Pages
6.3. Environment Variables

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. Writing Style

12.1. Tips
12.2. Guidelines
12.3. Style Guide
12.4. Word List

13. Editor Configuration

13.1. Vim
13.2. Emacs
13.3. nano

14. See Also

14.1. The FreeBSD Documentation Project
14.2. XML
14.3. HTML
14.4. DocBook
14.5. The Linux Documentation Project

A. Examples

A.1. DocBook book
A.2. DocBook article
A.3. Producing Formatted Output

Index

List of Examples

1. A Sample Example
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. .profile, for sh(1) and bash(1) Users
7.7. .cshrc, for csh(1) and tcsh(1) Users
7.8. XML Generic Comment
7.9. Erroneous XML Comments
7.10. Defining General Entities
7.11. Defining Parameter Entities
7.12. Using General Entities to Include Files
7.13. Using Parameter Entities to Include Files
7.14. Structure of a Marked Section
7.15. Using a CDATA Marked Section
7.16. Using INCLUDE and IGNORE in Marked Sections
7.17. 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 bookinfo
9.2. Boilerplate article with articleinfo
9.3. A Simple Chapter
9.4. Empty Chapters
9.5. Sections in Chapters
9.6. para
9.7. blockquote
9.8. warning
9.9. itemizedlist, orderedlist, and procedure
9.10. programlisting
9.11. co and calloutlist
9.12. informaltable
9.13. Tables Where frame="none"
9.14. screen, prompt, and userinput
9.15. emphasis
9.16. Acronyms
9.17. Quotations
9.18. Keys, Mouse Buttons, and Combinations
9.19. Applications, Commands, and Options
9.20. filename
9.21. filename Tag with package Role
9.22. devicename
9.23. hostid and Roles
9.24. username
9.25. email with a Hyperlink
9.26. email Without a Hyperlink
9.27. maketarget and makevar
9.28. literal
9.29. replaceable
9.30. guibutton
9.31. errorname
9.32. id on Chapters and Sections
9.33. anchor
9.34. Using xref
9.35. Using link
9.36. ulink to a FreeBSD Documentation Web Page
9.37. ulink to a FreeBSD Web Page
9.38. ulink to an External Web Page
A.1. DocBook book
A.2. DocBook article
A.3. Converting DocBook to XHTML (One Large File)
A.4. Converting DocBook to XHTML (Several Small Files)
A.5. Converting DocBook to PostScript®
A.6. Converting DocBook to PDF

		Next
		Preface