FreeBSD Documentation Project Primer for New Contributors
		Next

FreeBSD Documentation Project Primer for New Contributors

The FreeBSD Documentation Project

Last modified on 2021-01-12 19:33:23 +0100 by Daniel Ebdrup Jensen.

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. Quick Start
1.2. The FreeBSD Documentation Set

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
12.7. Submitting the New Translation

13. Manual Pages

13.1. Introduction
13.2. Sections
13.3. Markup
13.4. Sample Manual Page Structures
13.5. Testing
13.6. Example Manual Pages to Use as Templates
13.7. Resources

14. Writing Style

14.1. Tips
14.2. Guidelines
14.3. Style Guide
14.4. Word List

15. Editor Configuration

15.1. Vim
15.2. Emacs
15.3. nano

16. See Also

16.1. The FreeBSD Documentation Project
16.2. XML
16.3. HTML
16.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 Comments
7.7. Erroneous XML Comment
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 Example
8.4. blockquote Example
8.5. ul and ol Example
8.6. Definition Lists with dl
8.7. pre Example
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 Example
8.13. tt Example
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 Example
9.7. blockquote Example
9.8. tip and important Example
9.9. example Source
9.10. Rendered example
9.11. itemizedlist and orderedlist Example
9.12. variablelist Example
9.13. procedure Example
9.14. programlisting Example
9.15. co and calloutlist Example
9.16. informaltable Example
9.17. Table with frame="none" Example
9.18. screen, prompt, and userinput Example
9.19. emphasis Example
9.20. acronym Example
9.21. quote Example
9.22. Keys, Mouse Buttons, and Combinations Example
9.23. Applications, Commands, and Options Example
9.24. filename Example
9.25. package Example
9.26. systemitem and Classes Example
9.27. uri Example
9.28. email with a Hyperlink Example
9.29. email Without a Hyperlink Example
9.30. buildtarget and varname Example
9.31. literal Example
9.32. replaceable Example
9.33. guibutton Example
9.34. errorname Example
9.35. xml:id on Chapters and Sections Example
9.36. xref Example
9.37. link to a FreeBSD Documentation Web Page Example
9.38. link to a FreeBSD Web Page Example
9.39. link to an External Web Page Example
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
12.6. Spanish Translation of the NanoBSD Article
12.7. Korean UTF-8 Translation of the Explaining-BSD Article
A.1. DocBook book
A.2. DocBook article

		Next
		Preface