FreeBSD Documentation Project Primer for New Contributors
   Next

FreeBSD Documentation Project Primer for New Contributors

The FreeBSD Documentation Project

Revision: 41645

Copyright © 1998-2009 DocEng

Copyright
Last modified on 2013-05-17 by gabor.
Abstract

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
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. Mandatory Tools
2.2. Optional Tools
3. XML Primer
3.1. Overview
3.2. Elements, Tags, and Attributes
3.3. The DOCTYPE Declaration
3.4. Escaping Back to SGML
3.5. Comments
3.6. Entities
3.7. Using Entities to Include Files
3.8. Marked Sections
3.9. Conclusion
4. XML Markup
4.1. XHTML
4.2. DocBook
5. Stylesheets
5.1. CSS
6. Structuring Documents Under doc/
6.1. The Top Level, doc/
6.2. The lang.encoding/ Directories
6.3. Document Specific Information
7. The Documentation Build Process
7.1. The FreeBSD Documentation Build Toolset
7.2. Understanding Makefiles in the Documentation Tree
7.3. FreeBSD Documentation Project Make Includes
8. The Website
8.1. Preparation
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.2. Word List
11. Using sgml-mode with Emacs
12. See Also
12.1. The FreeBSD Documentation Project
12.2. XML
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
List of Examples
1. A Sample Example
3.1. Using an Element (Start and End Tags)
3.2. Using an Element (Without Content)
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. XML Generic Comment
3.9. Erroneous XML 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 XHTML Document Structure
4.2. h1, h2, and Other Header Tags
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. tt
4.15. Using <a href="...">
4.16. Using <a id="...">
4.17. Linking to a Named Part of Another Document
4.18. Linking to a Named Part of the Same Document
4.19. Boilerplate book with bookinfo
4.20. Boilerplate article with articleinfo
4.21. A Simple Chapter
4.22. Empty Chapters
4.23. Sections in Chapters
4.24. para
4.25. blockquote
4.26. warning
4.27. itemizedlist, orderedlist, and procedure
4.28. programlisting
4.29. co and calloutlist
4.30. informaltable
4.31. Tables Where frame="none"
4.32. screen, prompt, and userinput
4.33. emphasis
4.34. Quotations
4.35. Keys, Mouse Buttons, and Combinations
4.36. Applications, Commands, and Options
4.37. filename
4.38. filename Tag with package Role
4.39. devicename
4.40. hostid and Roles
4.41. username
4.42. maketarget and makevar
4.43. literal
4.44. replaceable
4.45. errorname
4.46. Attribute id on Chapters and Sections
4.47. anchor
4.48. Using xref
4.49. Using link
4.50. 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

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.

For questions about this documentation, e-mail <doc@FreeBSD.org>.