FreeBSD Documentation Project Primer for New Contributors FreeBSD Documentation Project Primer for New Contributors Revision: eab1c5d1f6 2021-01-12 19:33:23 +0100 by Daniel Ebdrup Jensen. Copyright © 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 DocEng Abstract Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valu- able, and we appreciate it. This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, in- cluding tools, software, and the philosophy behind the Documentation Project. This is a work in progress. Corrections and additions are always welcome. Copyright Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of condi- tions and the following disclaimer as the rst lines of this le unmodified. 2. Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Important THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICU- LAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ii Table of Contents Preface .................................................................................................................................... ix 1. Shell Prompts ................................................................................................................. ix 2. Typographic Conventions ................................................................................................. ix 3. Notes, Tips, Important Information, Warnings, and Examples ................................................... ix 4. Acknowledgments ............................................................................................................ x 1. Overview ................................................................................................................................ 1 1.1. Quick Start ................................................................................................................... 1 1.2. The FreeBSD Documentation Set ....................................................................................... 2 2. Tools ..................................................................................................................................... 3 2.1. Required Tools .............................................................................................................. 3 2.2. Optional Tools ............................................................................................................... 3 3. The Working Copy ................................................................................................................... 5 3.1. Documentation and Manual Pages ..................................................................................... 5 3.2. Choosing a Directory ...................................................................................................... 5 3.3. Checking Out a Copy ...................................................................................................... 5 3.4. Updating a Working Copy ................................................................................................ 5 3.5. Reverting Changes ......................................................................................................... 6 3.6. Making a Di ................................................................................................................ 6 3.7. Subversion References .................................................................................................... 6 4. Documentation Directory Structure ............................................................................................. 7 4.1. The Top Level, doc/ ...................................................................................................... 7 4.2. The lang.encoding/ Directories ...................................................................................... 7 4.3. Document-Specific Information ........................................................................................ 8 5. The Documentation Build Process .............................................................................................. 11 5.1. Rendering DocBook into Output ...................................................................................... 11 5.2. The FreeBSD Documentation Build Toolset ......................................................................... 11 5.3. Understanding Makefiles in the Documentation Tree ....................................................... 12 5.4. FreeBSD Documentation Project Make Includes ................................................................... 13 6. The Website .......................................................................................................................... 17 6.1. Environment Variables .................................................................................................. 17 6.2. Building and Installing the Web Pages .............................................................................. 17 7. XML Primer .......................................................................................................................... 21 7.1. Overview .................................................................................................................... 21 7.2. Elements, Tags, and Attributes ........................................................................................ 22 7.3. The DOCTYPE Declaration .............................................................................................. 25 7.4. Escaping Back to XML ................................................................................................... 27 7.5. Comments .................................................................................................................. 27 7.6. Entities ...................................................................................................................... 28 7.7. Using Entities to Include Files ......................................................................................... 30 7.8. Marked Sections ........................................................................................................... 33 7.9. Conclusion .................................................................................................................. 35 8. XHTML Markup ..................................................................................................................... 37 8.1. Introduction ................................................................................................................ 37 8.2. Formal Public Identifier (FPI) .......................................................................................... 37 8.3. Sectional Elements ....................................................................................................... 37 8.4. Block Elements ............................................................................................................ 38 8.5. In-line Elements ........................................................................................................... 43 9. DocBook Markup .................................................................................................................... 45 9.1. Introduction ................................................................................................................ 45 9.2. FreeBSD Extensions ...................................................................................................... 45 9.3. Formal Public Identifier (FPI) .......................................................................................... 47 9.4. Document Structure ..................................................................................................... 47 9.5. Block Elements ............................................................................................................ 51 9.6. In-line Elements ........................................................................................................... 60 9.7. Images ....................................................................................................................... 69 9.8. Links ......................................................................................................................... 72 Table of Contents 10. Style