           ********************* FreeBSD ***************************

  FreeBSD ******************

   Revision: f69fa39963

   ****** (c) 1998-2014 DocEng

   ******

   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 conditions and the following disclaimer
       as the first lines of this file 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.

  ******:

   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 PARTICULAR
   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.

   Last modified on 2017-07-17 06:35:59 +0000 by Ruey-Cherng Yu.
   ******

   *************** FreeBSD
   *******************************************************._

   ************************************************** FreeBSD
   ****************** (FreeBSD Documentation Project, FDP)
   ***********************************************,_***********************************._

   *********************************._***************************************************._

   [ ************ / ************ ]

     ----------------------------------------------------------------------

   ************

   ***

                1. Shell ************

                2. ***************************

                3. ******,_******,_******,_***************

                4. ******

   1. ******

                1.1. ************

                1.2. FreeBSD ***************

   2. ******

                2.1. ************

                2.2. ************

   3. ************

                3.1. ***************************

                3.2. ******************

                3.3. ******************

                3.4. ******************

                3.5. ************

                3.6. ************

                3.7. Subversion ************

   4. ************************

                4.1. ***********doc/

                4.2. lang.encoding/ ******

                4.3. ******************

   5. ************************

                5.1. ****** Docbook ***************

                5.2. FreeBSD ***************************

                5.3. ****************************** Makefile

                5.4. FreeBSD ****************** Make *********

   6. ******

                6.1. ************

                6.2. *********************

   7. XML ******

                7.1. ******

                7.2. ******,_***************

                7.3. DOCTYPE ******

                7.4. ********* XML

                7.5. ******

                7.6. Entities

                7.7. ****************** Entities

                7.8. ***************

                7.9. ******

   8. XHTML ******

                8.1. ******

                8.2. ********************* (FPI)

                8.3. ************

                8.4. ************

                8.5. ************

   9. DocBook ******

                9.1. ******

                9.2. FreeBSD ************

                9.3. ********************* (FPI)

                9.4. ************

                9.5. ************

                9.6. ************

                9.7. ******

                9.8. ******

   10. *********

                10.1. CSS

   11. ******

   12. PO ******

                12.1. ******

                12.2. ************

                12.3. ***************

                12.4. ******

                12.5. *********************

                12.6. *********************

                12.7. ***************

   13. ************

                13.1. ******

                13.2. ******

                13.3. ************

                13.4. *********

   14. ***************

                14.1. Vim

                14.2. Emacs

                14.3. nano

   15. ************

                15.1. FreeBSD ******************

                15.2. XML

                15.3. HTML

                15.4. DocBook

   A. ******

                A.1. DocBook book

                A.2. DocBook article

   ******

   ************

   5.1. ******************

   12.1. ************

   ************

   1. ***************

   5.1. ************ HTML *********

   5.2. ************ HTML *** PDF *********

   6.1. ***************************************

   6.2. ************************

   6.3. *********************

   7.1. ************ (*********************)

   7.2. ***************************

   7.3. *********************; em

   7.4. *********************

   7.5. ******************

   7.6. XML ************

   7.7. *********XML ******

   7.8. ************ Entities

   7.9. ************ Entities

   7.10. ************************ Entities

   7.11. ************************ Entities

   7.12. ******************

   7.13. ****** CDATA ***************

   7.14. *************************** INCLUDE *** IGNORE

   7.15. ************ Entities ************************

   8.1. ********* XHTML ************

   8.2. h1, h2, ************************

   8.3. p ******

   8.4. blockquote ******

   8.5. ul *** ol ******

   8.6. ****** dl ***************

   8.7. pre ******

   8.8. table ***************

   8.9. ****** rowspan

   8.10. ****** colspan

   8.11. rowspan *** colspan ************

   8.12. em *** strong ******

   8.13. tt ******

   8.14. ****** <a href="...">

   8.15. ************

   8.16. *********************************************

   8.17. ******************************************

   9.1. ****** info *** book ******

   9.2. ****** info *** article ******

   9.3. ***************

   9.4. ************

   9.5. ***************

   9.6. para ******

   9.7. blockquote ******

   9.8. tip *** important ******

   9.9. example *********

   9.10. example *********

   9.11. itemizedlist *** orderedlist ******

   9.12. variablelist ******

   9.13. procedure ******

   9.14. programlisting ******

   9.15. co *** calloutlist ******

   9.16. informaltable ******

   9.17. ************ frame="none" ******

   9.18. screen, prompt *** userinput ******

   9.19. emphasis ******

   9.20. acronym ******

   9.21. quote ******

   9.22. ************,_******************************

   9.23. ************,_******,_************

   9.24. filename ******

   9.25. package ******

   9.26. systemitem ********* (Class) ******

   9.27. uri ******

   9.28. *************** email ******

   9.29. ****************** email ******

   9.30. buildtarget *** varname ******

   9.31. literal ******

   9.32. replaceable ******

   9.33. guibutton ******

   9.34. errorname ******

   9.35. ****************** xml:id *********

   9.36. xref ******

   9.37. link *** FreeBSD ************************

   9.38. link *** FreeBSD ************

   9.39. link *********************

   12.1. ****** Porter ***************************

   12.2. ****** PGP ***************************._

   12.3. ****** Porter *********************

   12.4. ****** XML ******

   12.5. ****************** Porter ******

   12.6. NanoBSD ***************************

   12.7. Explaining-BSD *************** UTF-8 ******

   A.1. DocBook book

   A.2. DocBook article

                                      ***

   ************

   1. Shell ************

   2. ***************************

   3. ******,_******,_******,_***************

   4. ******

1. Shell ************

   *************************************** root
   **************************************************************
   (Prompt)**************************************._

                   ******                            ************             
   ***************                        %                                   
   root                                   #                                   

2. ***************************

   *********************************************

                    ************                                        ******                    
******                                               ****** ls -l ************************._      
******                                               ****** .login ._                             
***************************                          You have mail.                               
**************************************************._ % date +"The time is %H:%M"                  
                                                     The time is 09:18                            
************************                             ****** su(1) ***************._               
******************************                       ****** root *********************._          
***************._                                    ************************                     
********************************                     ******************************************** 
                                                     man -k *********                             
************._                                       $HOME *********************************._    

3. ******,_******,_******,_***************

   ***************************,_******,_*********._

  ******:

   ***************************************************************************************************************************._

  ******:

   **********************************************************************************._

  ******:

   **************************************._********************************************************************._

  ******:

   **********************************************************************._**********************************************************************************************************************************...._

   ****** 1. ***************

   *******************************************************************************************************************._

4. ******

   *************** Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn,
   Christopher Maden
   **************************************************************************************._

                                 *** 1. ******

   ************

   1.1. ************

   1.2. FreeBSD ***************

   ************ FreeBSD ****************** (FreeBSD Documentation Project,
   FDP)._****************************** FreeBSD
   ********************************************************************._

   *****************<" FDP
   ******************>",_<"***************************>",_
   <"***************************************>"._

   *************** FDP
   ************._******************************************._

   **************************

     * *************************** FDP ************._

     * ******************************************._

     * ******************._

     * ********************************* FreeBSD ************._

1.1. ************

   ********* FreeBSD
   ***********************************************._***************** FreeBSD
   ************************._********************************* EFnet
   ***#bsddocs IRC ******._************************************************._

    1. ****** textproc/docproj ********* Port._****** meta-port
       ****************************** FreeBSD ***************************._

    2. *** ~/doc ****** FreeBSD *********************************************
       (****** *** 3, ************)._

 % svn checkout https://svn.FreeBSD.org/doc/head ~/doc

    3. ***********************

          * ************ (Word wrap) ****** 70 *********._

          * Tab ********* (Tab stops) ****** 2._

          * ************ 8 ****************** 1 *** Tab._

       ************************************ *** 14, ***************._

    4. ***************************

 % svn up ~/doc

    5. ***************************************._**************************************************************._

       ****** (Tag) *** Entity *************************** *** 8, XHTML
       ****** *** *** 9, DocBook ******._

    6. **********************************************************

 % igor -R filename.xml | less -RS

       ***********************************************************************************************************._******************************************._

    7. ********************************************* (Build-test)
       ._*********************************************
       make*********************** HTML ****** (Split HTML)
       *********._*************** HTML **************************************
       en_US.ISO8859-1/books/handbook/ ************ make ._

    8. ***************************** "diff ***"**

 % cd ~/doc
 % svn diff > bsdinstall.diff.txt

       ***************************._********************************
       bsdinstall ***************._

    9. *************** ************ ************ diff
       ***._******************************** [patch] ******************
       ********* ._****** docs *********
       doc-bug******._***********************************************************************************._******
       [ Browse... ] *************** diff ***._

1.2. FreeBSD ***************

   FDP ************ FreeBSD ************._

     * ************ (Handbook)************************** FreeBSD
       ******************************************._

     * ***************
       (FAQ)********************************************************************************
       FreeBSD *********************._(*****************<"*********>"******)
       ***********************************************************************._

     * ************ (Manual page)************************************** FDP
       *********************************************** (Base system)
       *********._********FDP
       *******************************************************************************************._

     * ************** FreeBSD ***********************************
       http://www.FreeBSD.org/ ***************************
       (Mirror)._************************************ FreeBSD *********

   ***************************************************************._******************************

   FreeBSD ******,_************,_*** FAQ ***************************
   https://svn.FreeBSD.org/doc/ ************************._

   ********************************* https://svn.FreeBSD.org/base/
   ***************************._

   ********************************* svn log
   ******._***************************
   http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all._

   ********************************* https://svnweb.FreeBSD.org/doc/ ***
   https://svnweb.FreeBSD.org/base/._

   *************** FreeBSD ********************* how-to
   ******._*************** FDP
   ************._******************************************************._FDP
   ******************************************._

                                 *** 2. ******

   ************

   2.1. ************

   2.2. ************

   ****************************** FreeBSD
   *****************************************************._******************************************************************._*****************************************************************************************._

2.1. ************

   *** Port *************** textproc/docproj._****** meta-port
   *************** FreeBSD
   ***************************************._******************************************._

  2.1.1. DTDs *** Entities

   FreeBSD ****************************************** (DTDs) *** XML entities
   ******._****************** textproc/docproj Port *********._

   XHTML DTD (textproc/xhtml)

           XHTML *****************************************************
           FreeBSD ************************._

   DocBook DTD (textproc/docbook-xml)

           DocBook
           ******************************************************._FreeBSD
           ****************** DocBook *********._

   ISO 8879 entities (textproc/iso8879)

           *** ISO 8879:1986 ********* entity ********* DTD
           **************************************,_******************(******************************)******************._

2.2. ************

   **************************************************************************************************._

  2.2.1. ******

   Vim (editors/vim)

           ******************************************** XML
           *********************************** DocBook XML._

   Emacs *** XEmacs (editors/emacs *** editors/xemacs)

           *************************************************** XML DTD
           ***************._********************************************************************************._

                              *** 3. ************

   ************

   3.1. ***************************

   3.2. ******************

   3.3. ******************

   3.4. ******************

   3.5. ************

   3.6. ************

   3.7. Subversion ************

   ************ (Working copy) ************************************ FreeBSD
   *****************************************************************************************
   (Patch) *********************************._

   *************************************** 700 MB
   ********************************************************************************************
   1 GB *********._

   FreeBSD ************************ Subversion ***************** Subversion
   *** textproc/docproj ********************************************
   textproc/docproj ************._

3.1. ***************************

   FreeBSD
   ***********************************************************************************
   (Manual page) ************************************************** FDP
   *********._*****************************doc **************************
   base
   ************************************._******************************************
   (Checkout) base *********._

   ******************************************************************._***************************************
   head *********._

3.2. ******************

   FreeBSD ******************************
   /usr/doc/***********************************************
   /usr/src/._**********************************************************************************************************************************************************._************************
   ~/doc ****** ~/src ***************************************._

3.3. ******************

   ********************************************* ****** (Checkout)********
   svn checkout
   *********._**************************************************************

 % svn checkout https://svn.FreeBSD.org/doc/head ~/doc

   ********************************************************

 % svn checkout https://svn.FreeBSD.org/base/head ~/src

3.4. ******************

   *** FreeBSD
   **********************************************************************************************************************
   (Checkout) **************************************************************
   FreeBSD
   *********************._******************************************************************************************************
   svn update**

 % svn update ~/doc

   *************************************************** svn
   update********************************************************************************************************************************************************************************************************************************************************._

3.5. ************

   **************************************************************************************._*********************
   svn revert
   ***"******"****************************************************************
   chapter.xml ***********************************************

 % svn revert chapter.xml

3.6. ************

   *****************************************************************************
   FreeBSD ***************************************************._****** ******
   (Diff) *************** svn diff ***********************************

 % cd ~/doc
 % svn diff > doc-fix-spelling.diff

   ***********************************************************************************************************************************._

   *** diff ********************* "Submit a FreeBSD problem report"
   ************************** .txt
   ***************************************************************************************._

   ***********svn diff
   *********************************************************************************************************************************************************************************

 % cd ~/doc
 % svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff

3.7. Subversion ************

   ********************* Subversion
   ******************************************** Subversion Book ***
   Subversion ************._

                        *** 4. ************************

   ************

   4.1. ***********doc/

   4.2. lang.encoding/ ******

   4.3. ******************

   *** doc/ ***********************************************************

    1. ***************************************************._

    2. *****************************************************************************************************._

    3. *********************************************************************************._

   **************************************************************************************._********************************************************************************************._

4.1. ***********doc/

   *** doc/
   ********************************************************************************._

   ******                                                                                                              ******                                                                                                          
share         ************************************************************._**************************************************************** make(1) ****************************** share/mk************** XML ********* (*** FreeBSD  
              ********* DocBook DTD) ********* share/xml._                                                                                                                                                                             
lang.encoding ***************************************************************** en_US.ISO8859-1/ ***                                                                                                                                   
              zh_TW.UTF-8/._********************************************************************************************************************************************************************************************************** 
              (Unicode) *********************._                                                                                                                                                                                        

4.2. lang.encoding/ ******

   *********************************._********************************************************************************._

 ******                                                      ******                                                      
articles *** DocBook article (************)                                                                              
         *********************._******************************************************************* XHTML ******._       
books    *** DocBook book (************)                                                                                 
         *********************._***********************************************._*************************************** 
         XHTML *** (***********************************************************************************)                 
         *********************************._                                                                             
man      ********************* (Manual page) ************._************************************ mann                     
         ************************************._                                                                          

   ************ lang.encoding
   ***********************************************************************************************._

4.3. ******************

   ********************* FDP *********************************************._

  4.3.1. ************ (Handbook)

    books/handbook/

   ************************ FreeBSD DocBook ****** DTD *** DocBook XML
   *********._

   ****************** DocBook book
   ********************************************
   (part)******************************** (chapter)******** (chapter)
   ************************************ (sect1) ********* (sect2, sect3)
   ************._

    4.3.1.1. ******************

   *** handbook *********************************._

  ******:

   *****************************************************************************************************************._***************************************************
   FreeBSD documentation project mailing list._

      4.3.1.1.1. Makefile

   Makefile ************************ XML
   ****************************************************************************************************************************************************************
   doc.project.mk *********._

      4.3.1.1.2. book.xml

   ********************************************************************
   DOCTYPE ***************************************************._

   book.xml ********* ****** Entities ********* .ent
   ******************._************ (***************)
   *************************************************** ****** Entities._

      4.3.1.1.3. directory/chapter.xml

   ************************************************ chapter.xml
   *****************************************._************************
   chapter ********* id ************************._

   ****************************************

 <chapter id="kernelconfig">
 ...
 </chapter>

   ****************** chapter.xml ************************
   kernelconfig._************************************************************._

   ****** XHTML ***********************************************
   kernelconfig.html***************************** id
   ***********************************._

   ***************************************************** book.xml
   *********************************** chapter ************ id
   *********************._*****************************************************************************************
   share/images/books/handbook*****************************************************
   XML
   ************************._**************************************************,_*********************,_***********************************,_******************************************************._

   ********************************* chapter.xml ***********************
   basics/chapter.xml, introduction/chapter.xml ****** printing/chapter.xml._

  ******:

   **************************************************************************************************************************************._**************************************************************************************************._

   chapter.xml ********************************************* XML
   **************************************************************._

                        *** 5. ************************

   ************

   5.1. ****** Docbook ***************

   5.2. FreeBSD ***************************

   5.3. ****************************** Makefile

   5.4. FreeBSD ****************** Make *********

   *************************************************************** make(1)
   *********************._

5.1. ****** Docbook ***************

   ************ DocBook
   *****************************************************************************
   FORMATS ***************._*************************** KNOWN_FORMATS *****

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make -V KNOWN_FORMATS

   ****** 5.1. ******************

 FORMATS   ************                            ******                            
   ***     
html       HTML******** ****** book.html *** article.html._                          
html-split HTML******** ****** HTML                                                  
                        **********************************************************._ 
pdf        PDF          *********************                                        

   **************************************************************
   html-split._********************* FORMATS *********************._***
   FORMATS ******************************************************._

   ****** 5.1. ************ HTML *********

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS=html

   ****** 5.2. ************ HTML *** PDF *********

 % cd ~/doc/en_US.ISO8859-1/books/handbook
 % make FORMATS="html-split pdf"

5.2. FreeBSD ***************************

   *************** FDP ************************************._

     * ************************ make(1)*********** Berkeley Make._

     * ********************* FreeBSD *** pkg-create(8) *********._

     * gzip(1) ***************************************** bzip2(1)
       ******._tar(1) *********************._

     * install(1) ************************._

5.3. ****************************** Makefile

   *** FreeBSD ****************************** Makefile
   *********************._

     * ************ Makefile
       ************************************************._

     * *************** Makefiles
       ***************************************************._

     * Make ********* *****************************************************
       doc.xxx.mk._

  5.3.1. ************ Makefile

   ****** Makefile **************************

 SUBDIR =articles
 SUBDIR+=books

 COMPAT_SYMLINK = en

 DOC_PREFIX?= ${.CURDIR}/..
 .include "${DOC_PREFIX}/share/mk/doc.project.mk"

   ************************************ make(1) ********* SUBDIR,
   COMPAT_SYMLINK *** DOC_PREFIX._

   SUBDIR ********* COMPAT_SYMLINK
   ********************************************************************._

   SUBDIR
   **************************************************************************SUBDIR
   ********************* articles books._

   DOC_PREFIX
   ***************************************************************************._******************
   DOC_PREFIX ****** Makefile
   ****************************************************************************._

   *********************************************** SUBDIR
   ***************************************************************._

   COMPAT_SYMLINK
   *************************************************************** (doc/en
   ********* en_US.ISO-8859-1)._

   DOC_PREFIX ****** FreeBSD
   ***************************************._*************************************************************************************._.CURDIR
   ********* make(1) ********************************************._

   ********************* FreeBSD ****************************** make(1)
   ********* doc.project.mk***********************************************._

  5.3.2. *************** Makefile

   ****** Makefile ************ make(1)
   ************************************************************._

   ***********************

 MAINTAINER=nik@FreeBSD.org

 DOC?= book

 FORMATS?= html-split html

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # SGML content
 SRCS=  book.xml

 DOC_PREFIX?= ${.CURDIR}/../../..

 .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"

   MAINTAINER *************************************** FreeBSD
   ***********************************************************._

   DOC ************************************************ (********* .xml
   *********)._SRCS
   ********************************************************************************
   (Rebuild) ************************._

   FORMATS
   *********************************************************._INSTALL_COMPRESSED
   ************************************************************._INSTALL_ONLY_COMPRESS
   **************************************************************************************._

   DOC_PREFIX ****** include ******************************._

5.4. FreeBSD ****************** Make *********

   make(1) includes are best explained by inspection of the code. Here are
   the system include files:

     * doc.project.mk is the main project include file, which includes all
       the following include files, as necessary.

     * doc.subdir.mk handles traversing of the document tree during the build
       and install processes.

     * doc.install.mk provides variables that affect ownership and
       installation of documents.

     * doc.docbook.mk is included if DOCFORMAT is docbook and DOC is set.

  5.4.1. doc.project.mk

   By inspection:

 DOCFORMAT?=     docbook
 MAINTAINER?=    doc@FreeBSD.org

 PREFIX?=        /usr/local
 PRI_LANG?=      en_US.ISO8859-1

 .if defined(DOC)
 .if ${DOCFORMAT} == "docbook"
 .include "doc.docbook.mk"
 .endif
 .endif

 .include "doc.subdir.mk"
 .include "doc.install.mk"

    5.4.1.1. ******

   DOCFORMAT and MAINTAINER are assigned default values, if these are not set
   by the document make file.

   PREFIX is the prefix under which the documentation building tools are
   installed. For normal package and port installation, this is /usr/local.

   PRI_LANG should be set to whatever language and encoding is natural
   amongst users these documents are being built for. US English is the
   default.

  ******:

   PRI_LANG does not affect which documents can, or even will, be built. Its
   main use is creating links to commonly referenced documents into the
   FreeBSD documentation install root.

    5.4.1.2. ******

   The .if defined(DOC) line is an example of a make(1) conditional which,
   like in other programs, defines behavior if some condition is true or if
   it is false. defined is a function which returns whether the variable
   given is defined or not.

   .if ${DOCFORMAT} == "docbook", next, tests whether the DOCFORMAT variable
   is "docbook", and in this case, includes doc.docbook.mk.

   The two .endifs close the two above conditionals, marking the end of their
   application.

  5.4.2. doc.subdir.mk

   This file is too long to explain in detail. These notes describe the most
   important features.

    5.4.2.1. ******

     * SUBDIR is a list of subdirectories that the build process should go
       further down into.

     * ROOT_SYMLINKS is the name of directories that should be linked to the
       document install root from their actual locations, if the current
       language is the primary language (specified by PRI_LANG).

     * COMPAT_SYMLINK is described in the Subdirectory Makefile section.

    5.4.2.2. ***************

   Dependencies are described by target: dependency1 dependency2 ... tuples,
   where to build target, the given dependencies must be built first.

   After that descriptive tuple, instructions on how to build the target may
   be given, if the conversion process between the target and its
   dependencies are not previously defined, or if this particular conversion
   is not the same as the default conversion method.

   A special dependency .USE defines the equivalent of a macro.

 _SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
         @${ECHO} "===> ${DIRPRFX}${entry}"
         @(cd ${.CURDIR}/${entry} && \
         ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor

   In the above, _SUBDIRUSE is now a macro which will execute the given
   commands when it is listed as a dependency.

   What sets this macro apart from other targets? Basically, it is executed
   after the instructions given in the build procedure it is listed as a
   dependency to, and it does not adjust .TARGET, which is the variable which
   contains the name of the target currently being built.

 clean: _SUBDIRUSE
         rm -f ${CLEANFILES}

   In the above, clean will use the _SUBDIRUSE macro after it has executed
   the instruction rm -f ${CLEANFILES}. In effect, this causes clean to go
   further and further down the directory tree, deleting built files as it
   goes down, not on the way back up.

      5.4.2.2.1. ******************

     * install and package both go down the directory tree calling the real
       versions of themselves in the subdirectories (realinstall and
       realpackage respectively).

     * clean removes files created by the build process (and goes down the
       directory tree too). cleandir does the same, and also removes the
       object directory, if any.

    5.4.2.3. ************

     * exists is another condition function which returns true if the given
       file exists.

     * empty returns true if the given variable is empty.

     * target returns true if the given target does not already exist.

    5.4.2.4. *** make (.for) ******************

   .for provides a way to repeat a set of instructions for each
   space-separated element in a variable. It does this by assigning a
   variable to contain the current element in the list being examined.

 _SUBDIRUSE: .USE
 .for entry in ${SUBDIR}
         @${ECHO} "===> ${DIRPRFX}${entry}"
         @(cd ${.CURDIR}/${entry} && \
         ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
 .endfor

   In the above, if SUBDIR is empty, no action is taken; if it has one or
   more elements, the instructions between .for and .endfor would repeat for
   every element, with entry being replaced with the value of the current
   element.

                                 *** 6. ******

   ************

   6.1. ************

   6.2. *********************

   FreeBSD ********* FreeBSD
   ******************._*****************************************************
   ~/doc***** en_US.ISO8859-1/htdocs *********._

6.1. ************

   Several environment variables control which parts of the web site are
   built or installed, and to which directories.

  ******:

   The web build system uses make(1), and considers variables to be set when
   they have been defined, even if they are empty. The examples here show the
   recommended ways of defining and using these variables. Setting or
   defining these variables with other values or methods might lead to
   unexpected surprises.

   DESTDIR

           DESTDIR specifies the path where the web site files are to be
           installed.

           This variable is best set with env(1) or the user shell's method
           of setting environment variables, setenv for csh(1) or export for
           sh(1).

   ENGLISH_ONLY

           Default: undefined. Build and include all translations.

           ENGLISH_ONLY=yes: use only the English documents and ignore all
           translations.

   WEB_ONLY

           Default: undefined. Build both the web site and all the books and
           articles.

           WEB_ONLY=yes: build or install only HTML pages from the
           en_US.ISO8859-1/htdocs directory. Other directories and documents,
           including books and articles, will be ignored.

   WEB_LANG

           Default: undefined. Build and include all the available languages
           on the web site.

           Set to a space-separated list of languages to be included in the
           build or install. The formats are the same as the directory names
           in the document root directory. For example, to include the German
           and French documents:

 WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1"

   WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are make(1) variables and can be set
   in /etc/make.conf, Makefile.inc, as environment variables on the command
   line, or in dot files.

6.2. *********************

   Having obtained the documentation and web site source files, the web site
   can be built.

   An actual installation of the web site is run as the root user because the
   permissions on the web server directory will not allow files to be
   installed by an unprivileged user. For testing, it can be useful to
   install the files as a normal user to a temporary directory.

   In these examples, the web site files are built by user jru in their home
   directory, ~/doc, with a full path of /usr/home/jru/doc.

  ******:

   The web site build uses the INDEX from the Ports Collection and might fail
   if that file or /usr/ports is not present. The simplest approach is to
   install the Ports Collection.

   ****** 6.1. ***************************************

   Build the web site and all documents. The resulting files are left in the
   document tree:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % make all

   ****** 6.2. ************************

   Build the web site only, in English, as user jru, and install the
   resulting files into /tmp/www for testing:

 % cd ~/doc/en_US.ISO8859-1/htdocs/
 % env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install

   Changes to static files can usually be tested by viewing the modified
   files directly with a web browser. If the site has been built as shown
   above, a modified main page can be viewed with:

 % firefox /tmp/www/data/index.html

   Modifications to dynamic files can be tested with a web server running on
   the local system. After building the site as shown above, this
   /usr/local/etc/apache24/httpd.conf can be used with www/apache24:

 # httpd.conf for testing the FreeBSD website
 Define TestRoot "/tmp/www/data"

 # directory for configuration files
 ServerRoot "/usr/local"

 Listen 80

 # minimum required modules
 LoadModule authz_core_module libexec/apache24/mod_authz_core.so
 LoadModule mime_module libexec/apache24/mod_mime.so
 LoadModule unixd_module libexec/apache24/mod_unixd.so
 LoadModule cgi_module libexec/apache24/mod_cgi.so
 LoadModule dir_module libexec/apache24/mod_dir.so

 # run the webserver as user and group
 User www
 Group www

 ServerAdmin you@example.com
 ServerName fbsdtest

 # deny access to all files
 <Directory />
     AllowOverride none
     Require all denied
 </Directory>

 # allow access to the website directory
 DocumentRoot "${TestRoot}"
 <Directory "${TestRoot}">
     Options Indexes FollowSymLinks
     AllowOverride None
     Require all granted
 </Directory>

 # prevent access to .htaccess and .htpasswd files
 <Files ".ht*">
     Require all denied
 </Files>

 ErrorLog "/var/log/httpd-error.log"
 LogLevel warn

 # set up the CGI script directory
 <Directory "${TestRoot}/cgi">
     AllowOverride None
     Options None
     Require all granted
     Options +ExecCGI
     AddHandler cgi-script .cgi
 </Directory>

 Include etc/apache24/Includes/*.conf

   Start the web server with

 # service apache24 onestart

   The web site can be viewed at http://localhost. Be aware that many links
   refer to the real FreeBSD site by name, and those links will still go to
   the external site instead of the local test version. Fully testing the
   local site will require temporarily setting DNS so www.FreeBSD.org
   resolves to localhost or the local IP address.

   ****** 6.3. *********************

   Build the web site and all documents as user jru. Install the resulting
   files as root into the default directory, /root/public_html:

 % cd ~/doc/en_US.ISO8859-1/htdocs
 % make all
 % su -
 Password:
 # cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs
 # make install

   The install process does not delete any old or outdated files that existed
   previously in the same directory. If a new copy of the site is built and
   installed every day, this command will find and delete all files that have
   not been updated in three days:

 # find /usr/local/www -ctime 3 -delete

                               *** 7. XML ******

   ************

   7.1. ******

   7.2. ******,_***************

   7.3. DOCTYPE ******

   7.4. ********* XML

   7.5. ******

   7.6. Entities

   7.7. ****************** Entities

   7.8. ***************

   7.9. ******

   Most FDP documentation is written with markup languages based on XML. This
   chapter explains what that means, how to read and understand the
   documentation source, and the XML techniques used.

   Portions of this section were inspired by Mark Galassi's Get Going With
   DocBook.

7.1. ******

   In the original days of computers, electronic text was simple. There were
   a few character sets like ASCII or EBCDIC, but that was about it. Text was
   text, and what you saw really was what you got. No frills, no formatting,
   no intelligence.

   Inevitably, this was not enough. When text is in a machine-usable format,
   machines are expected to be able to use and manipulate it intelligently.
   Authors want to indicate that certain phrases should be emphasized, or
   added to a glossary, or made into hyperlinks. Filenames could be shown in
   a "typewriter" style font for viewing on screen, but as "italics" when
   printed, or any of a myriad of other options for presentation.

   It was once hoped that Artificial Intelligence (AI) would make this easy.
   The computer would read the document and automatically identify key
   phrases, filenames, text that the reader should type in, examples, and
   more. Unfortunately, real life has not happened quite like that, and
   computers still require assistance before they can meaningfully process
   text.

   More precisely, they need help identifying what is what. Consider this
   text:

     To remove /tmp/foo, use rm(1).

 % rm /tmp/foo

   It is easy to see which parts are filenames, which are commands to be
   typed in, which parts are references to manual pages, and so on. But the
   computer processing the document cannot. For this we need markup.

   "Markup" is commonly used to describe "adding value" or "increasing cost".
   The term takes on both these meanings when applied to text. Markup is
   additional text included in the document, distinguished from the
   document's content in some way, so that programs that process the document
   can read the markup and use it when making decisions about the document.
   Editors can hide the markup from the user, so the user is not distracted
   by it.

   The extra information stored in the markup adds value to the document.
   Adding the markup to the document must typically be done by a person-after
   all, if computers could recognize the text sufficiently well to add the
   markup then there would be no need to add it in the first place. This
   increases the cost (the effort required) to create the document.

   The previous example is actually represented in this document like this:

 <para>To remove <filename>/tmp/foo</filename>, use &man.rm.1;.</para>

 <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>

   The markup is clearly separate from the content.

   Markup languages define what the markup means and how it should be
   interpreted.

   Of course, one markup language might not be enough. A markup language for
   technical documentation has very different requirements than a markup
   language that is intended for cookery recipes. This, in turn, would be
   very different from a markup language used to describe poetry. What is
   really needed is a first language used to write these other markup
   languages. A meta markup language.

   This is exactly what the eXtensible Markup Language (XML) is. Many markup
   languages have been written in XML, including the two most used by the
   FDP, XHTML and DocBook.

   Each language definition is more properly called a grammar, vocabulary,
   schema or Document Type Definition (DTD). There are various languages to
   specify an XML grammar, or schema.

   A schema is a complete specification of all the elements that are allowed
   to appear, the order in which they should appear, which elements are
   mandatory, which are optional, and so forth. This makes it possible to
   write an XML parser which reads in both the schema and a document which
   claims to conform to the schema. The parser can then confirm whether or
   not all the elements required by the vocabulary are in the document in the
   right order, and whether there are any errors in the markup. This is
   normally referred to as "validating the document".

  ******:

   Validation confirms that the choice of elements, their ordering, and so
   on, conforms to that listed in the grammar. It does not check whether
   appropriate markup has been used for the content. If all the filenames in
   a document were marked up as function names, the parser would not flag
   this as an error (assuming, of course, that the schema defines elements
   for filenames and functions, and that they are allowed to appear in the
   same place).

   Most contributions to the Documentation Project will be content marked up
   in either XHTML or DocBook, rather than alterations to the schemas. For
   this reason, this book will not touch on how to write a vocabulary.

7.2. ******,_***************

   All the vocabularies written in XML share certain characteristics. This is
   hardly surprising, as the philosophy behind XML will inevitably show
   through. One of the most obvious manifestations of this philosophy is that
   of content and elements.

   Documentation, whether it is a single web page, or a lengthy book, is
   considered to consist of content. This content is then divided and further
   subdivided into elements. The purpose of adding markup is to name and
   identify the boundaries of these elements for further processing.

   For example, consider a typical book. At the very top level, the book is
   itself an element. This "book" element obviously contains chapters, which
   can be considered to be elements in their own right. Each chapter will
   contain more elements, such as paragraphs, quotations, and footnotes. Each
   paragraph might contain further elements, identifying content that was
   direct speech, or the name of a character in the story.

   It may be helpful to think of this as "chunking" content. At the very top
   level is one chunk, the book. Look a little deeper, and there are more
   chunks, the individual chapters. These are chunked further into
   paragraphs, footnotes, character names, and so on.

   Notice how this differentiation between different elements of the content
   can be made without resorting to any XML terms. It really is surprisingly
   straightforward. This could be done with a highlighter pen and a printout
   of the book, using different colors to indicate different chunks of
   content.

   Of course, we do not have an electronic highlighter pen, so we need some
   other way of indicating which element each piece of content belongs to. In
   languages written in XML (XHTML, DocBook, et al) this is done by means of
   tags.

   A tag is used to identify where a particular element starts, and where the
   element ends. The tag is not part of the element itself. Because each
   grammar was normally written to mark up specific types of information,
   each one will recognize different elements, and will therefore have
   different names for the tags.

   For an element called element-name the start tag will normally look like
   <element-name>. The corresponding closing tag for this element is
   </element-name>.

   ****** 7.1. ************ (*********************)

   XHTML has an element for indicating that the content enclosed by the
   element is a paragraph, called p.

 <p>This is a paragraph.  It starts with the start tag for
   the 'p' element, and it will end with the end tag for the 'p'
   element.</p>

 <p>This is another paragraph.  But this one is much shorter.</p>

   Some elements have no content. For example, in XHTML, a horizontal line
   can be included in the document. For these "empty" elements, XML
   introduced a shorthand form that is completely equivalent to the two-tag
   version:

   ****** 7.2. ***************************

   XHTML has an element for indicating a horizontal rule, called hr. This
   element does not wrap content, so it looks like this:

 <p>One paragraph.</p>
 <hr></hr>

 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>

   The shorthand version consists of a single tag:

 <p>One paragraph.</p>
 <hr/>

 <p>This is another paragraph.  A horizontal rule separates this
   from the previous paragraph.</p>

   As shown above, elements can contain other elements. In the book example
   earlier, the book element contained all the chapter elements, which in
   turn contained all the paragraph elements, and so on.

   ****** 7.3. *********************; em

 <p>This is a simple <em>paragraph</em> where some
   of the <em>words</em> have been <em>emphasized</em>.</p>

   The grammar consists of rules that describe which elements can contain
   other elements, and exactly what they can contain.

  ******:

   People often confuse the terms tags and elements, and use the terms as if
   they were interchangeable. They are not.

   An element is a conceptual part of your document. An element has a defined
   start and end. The tags mark where the element starts and ends.

   When this document (or anyone else knowledgeable about XML) refers to "the
   <p> tag" they mean the literal text consisting of the three characters <,
   p, and >. But the phrase "the p element" refers to the whole element.

   This distinction is very subtle. But keep it in mind.

   Elements can have attributes. An attribute has a name and a value, and is
   used for adding extra information to the element. This might be
   information that indicates how the content should be rendered, or might be
   something that uniquely identifies that occurrence of the element, or it
   might be something else.

   An element's attributes are written inside the start tag for that element,
   and take the form attribute-name="attribute-value".

   In XHTML, the p element has an attribute called align, which suggests an
   alignment (justification) for the paragraph to the program displaying the
   XHTML.

   The align attribute can take one of four defined values, left, center,
   right and justify. If the attribute is not specified then the default is
   left.

   ****** 7.4. *********************

 <p align="left">The inclusion of the align attribute
   on this paragraph was superfluous, since the default is left.</p>

 <p align="center">This may appear in the center.</p>

   Some attributes only take specific values, such as left or justify. Others
   allow any value.

   ****** 7.5. ******************

 <p align='right'>I am on the right!</p>

   Attribute values in XML must be enclosed in either single or double
   quotes. Double quotes are traditional. Single quotes are useful when the
   attribute value contains double quotes.

   Information about attributes, elements, and tags is stored in catalog
   files. The Documentation Project uses standard DocBook catalogs and
   includes additional catalogs for FreeBSD-specific features. Paths to the
   catalog files are defined in an environment variable so they can be found
   by the document build tools.

  7.2.1. ************...

   Before running the examples in this document, install textproc/docproj
   from the FreeBSD Ports Collection. This is a meta-port that downloads and
   installs the standard programs and supporting files needed by the
   Documentation Project. csh(1) users must use rehash for the shell to
   recognize new programs after they have been installed, or log out and then
   log back in again.

    1. Create example.xml, and enter this text:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>This is a paragraph containing some text.</p>

     <p>This paragraph contains some more text.</p>

     <p align="right">This paragraph might be right-justified.</p>
   </body>
 </html>

    2. Try to validate this file using an XML parser.

       textproc/docproj includes the xmllint validating parser.

       Use xmllint to validate the document:

 % xmllint --valid --noout example.xml

       xmllint returns without displaying any output, showing that the
       document validated successfully.

    3. See what happens when required elements are omitted. Delete the line
       with the <title> and </title> tags, and re-run the validation.

 % xmllint --valid --noout example.xml
 example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()

       This shows that the validation error comes from the fifth line of the
       example.xml file and that the content of the <head> is the part which
       does not follow the rules of the XHTML grammar.

       Then xmllint shows the line where the error was found and marks the
       exact character position with a ^ sign.

    4. Replace the title element.

7.3. DOCTYPE ******

   The beginning of each document can specify the name of the DTD to which
   the document conforms. This DOCTYPE declaration is used by XML parsers to
   identify the DTD and ensure that the document does conform to it.

   A typical declaration for a document written to conform with version 1.0
   of the XHTML DTD looks like this:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

   That line contains a number of different components.

   <!

           The indicator shows this is an XML declaration.

   DOCTYPE

           Shows that this is an XML declaration of the document type.

   html

           Names the first element that will appear in the document.

   PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

           Lists the Formal Public Identifier (FPI) for the DTD to which this
           document conforms. The XML parser uses this to find the correct
           DTD when processing this document.

           PUBLIC is not a part of the FPI, but indicates to the XML
           processor how to find the DTD referenced in the FPI. Other ways of
           telling the XML parser how to find the DTD are shown later.

   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"

           A local filename or a URL to find the DTD.

   >

           Ends the declaration and returns to the document.

  7.3.1. ********************* (FPI)

  ******:

   It is not necessary to know this, but it is useful background, and might
   help debug problems when the XML processor can not locate the DTD.

   FPIs must follow a specific syntax:

 "Owner//Keyword Description//Language"

   Owner

           The owner of the FPI.

           The beginning of the string identifies the owner of the FPI. For
           example, the FPI "ISO 8879:1986//ENTITIES Greek Symbols//EN" lists
           ISO 8879:1986 as being the owner for the set of entities for Greek
           symbols. ISO 8879:1986 is the International Organization for
           Standardization (ISO) number for the SGML standard, the
           predecessor (and a superset) of XML.

           Otherwise, this string will either look like -//Owner or +//Owner
           (notice the only difference is the leading + or -).

           If the string starts with - then the owner information is
           unregistered, with a + identifying it as registered.

           ISO 9070:1991 defines how registered names are generated. It might
           be derived from the number of an ISO publication, an ISBN code, or
           an organization code assigned according to ISO 6523. Additionally,
           a registration authority could be created in order to assign
           registered names. The ISO council delegated this to the American
           National Standards Institute (ANSI).

           Because the FreeBSD Project has not been registered, the owner
           string is -//FreeBSD. As seen in the example, the W3C are not a
           registered owner either.

   Keyword

           There are several keywords that indicate the type of information
           in the file. Some of the most common keywords are DTD, ELEMENT,
           ENTITIES, and TEXT. DTD is used only for DTD files, ELEMENT is
           usually used for DTD fragments that contain only entity or element
           declarations. TEXT is used for XML content (text and tags).

   Description

           Any description can be given for the contents of this file. This
           may include version numbers or any short text that is meaningful
           and unique for the XML system.

   Language

           An ISO two-character code that identifies the native language for
           the file. EN is used for English.

    7.3.1.1. catalog ******

   With the syntax above, an XML processor needs to have some way of turning
   the FPI into the name of the file containing the DTD. A catalog file
   (typically called catalog) contains lines that map FPIs to filenames. For
   example, if the catalog file contained the line:

 PUBLIC  "-//W3C//DTD XHTML 1.0 Transitional//EN"             "1.0/transitional.dtd"

   The XML processor knows that the DTD is called transitional.dtd in the 1.0
   subdirectory of the directory that held catalog.

   Examine the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. This
   is the catalog file for the XHTML DTDs that were installed as part of the
   textproc/docproj port.

  7.3.2. FPI ***************

   Instead of using an FPI to indicate the DTD to which the document conforms
   (and therefore, which file on the system contains the DTD), the filename
   can be explicitly specified.

   The syntax is slightly different:

 <!DOCTYPE html SYSTEM "/path/to/file.dtd">

   The SYSTEM keyword indicates that the XML processor should locate the DTD
   in a system specific fashion. This typically (but not always) means the
   DTD will be provided as a filename.

   Using FPIs is preferred for reasons of portability. If the SYSTEM
   identifier is used, then the DTD must be provided and kept in the same
   location for everyone.

7.4. ********* XML

   Some of the underlying XML syntax can be useful within documents. For
   example, comments can be included in the document, and will be ignored by
   the parser. Comments are entered using XML syntax. Other uses for XML
   syntax will be shown later.

   XML sections begin with a <! tag and end with a >. These sections contain
   instructions for the parser rather than elements of the document.
   Everything between these tags is XML syntax. The DOCTYPE declaration shown
   earlier is an example of XML syntax included in the document.

7.5. ******

   An XML document may contain comments. They may appear anywhere as long as
   they are not inside tags. They are even allowed in some locations inside
   the DTD (e.g., between entity declarations).

   XML comments start with the string "<!--" and end with the string "-->".

   Here are some examples of valid XML comments:

   ****** 7.6. XML ************

 <!-- This is inside the comment -->

 <!--This is another comment-->

 <!-- This is how you
      write multiline comments -->

 <p>A simple <!-- Comment inside an element's content --> paragraph.</p>

   XML comments may contain any strings except "--":

   ****** 7.7. *********XML ******

 <!-- This comment--is wrong -->

  7.5.1. ************...

    1. Add some comments to example.xml, and check that the file still
       validates using xmllint.

    2. Add some invalid comments to example.xml, and see the error messages
       that xmllint gives when it encounters an invalid comment.

7.6. Entities

   Entities are a mechanism for assigning names to chunks of content. As an
   XML parser processes a document, any entities it finds are replaced by the
   content of the entity.

   This is a good way to have re-usable, easily changeable chunks of content
   in XML documents. It is also the only way to include one marked up file
   inside another using XML.

   There are two types of entities for two different situations: general
   entities and parameter entities.

  7.6.1. ****** Entities

   General entities are used to assign names to reusable chunks of text.
   These entities can only be used in the document. They cannot be used in an
   XML context.

   To include the text of a general entity in the document, include
   &entity-name; in the text. For example, consider a general entity called
   current.version which expands to the current version number of a product.
   To use it in the document, write:

 <para>The current version of our product is
   &current.version;.</para>

   When the version number changes, edit the definition of the general
   entity, replacing the value. Then reprocess the document.

   General entities can also be used to enter characters that could not
   otherwise be included in an XML document. For example, < and & cannot
   normally appear in an XML document. The XML parser sees the < symbol as
   the start of a tag. Likewise, when the & symbol is seen, the next text is
   expected to be an entity name.

   These symbols can be included by using two predefined general entities:
   &lt; and &amp;.

   General entities can only be defined within an XML context. Such
   definitions are usually done immediately after the DOCTYPE declaration.

   ****** 7.8. ************ Entities

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>

   The DOCTYPE declaration has been extended by adding a square bracket at
   the end of the first line. The two entities are then defined over the next
   two lines, the square bracket is closed, and then the DOCTYPE declaration
   is closed.

   The square brackets are necessary to indicate that the DTD indicated by
   the DOCTYPE declaration is being extended.

  7.6.2. ****** Entities

   Parameter entities, like general entities, are used to assign names to
   reusable chunks of text. But parameter entities can only be used within an
   XML context.

   Parameter entity definitions are similar to those for general entities.
   However, parameter entries are included with %entity-name;. The definition
   also includes the % between the ENTITY keyword and the name of the entity.

   For a mnemonic, think "Parameter entities use the Percent symbol".

   ****** 7.9. ************ Entities

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY % param.some "some">
 <!ENTITY % param.text "text">
 <!ENTITY % param.new  "%param.some more %param.text">

 <!-- %param.new now contains "some more text" -->
 ]>

  7.6.3. ************...

    1. Add a general entity to example.xml.

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY version "1.1">
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <!-- There may be some comments in here as well -->

   <body>
     <p>This is a paragraph containing some text.</p>

     <p>This paragraph contains some more text.</p>

     <p align="right">This paragraph might be right-justified.</p>

     <p>The current version of this document is: &version;</p>
   </body>
 </html>

    2. Validate the document using xmllint.

    3. Load example.xml into a web browser. It may have to be copied to
       example.html before the browser recognizes it as an XHTML document.

       Older browsers with simple parsers may not render this file as
       expected. The entity reference &version; may not be replaced by the
       version number, or the XML context closing ]> may not be recognized
       and instead shown in the output.

    4. The solution is to normalize the document with an XML normalizer. The
       normalizer reads valid XML and writes equally valid XML which has been
       transformed in some way. One way the normalizer transforms the input
       is by expanding all the entity references in the document, replacing
       the entities with the text that they represent.

       xmllint can be used for this. It also has an option to drop the
       initial DTD section so that the closing ]> does not confuse browsers:

 % xmllint --noent --dropdtd example.xml > example.html

       A normalized copy of the document with entities expanded is produced
       in example.html, ready to load into a web browser.

7.7. ****************** Entities

   Both general and parameter entities are particularly useful for including
   one file inside another.

  7.7.1. ************************ Entities

   Consider some content for an XML book organized into files, one file per
   chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml
   that will contain these chapters.

   In order to use the contents of these files as the values for entities,
   they are declared with the SYSTEM keyword. This directs the XML parser to
   include the contents of the named file as the value of the entity.

   ****** 7.10. ************************ Entities

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY chapter.1 SYSTEM "chapter1.xml">
 <!ENTITY chapter.2 SYSTEM "chapter2.xml">
 <!ENTITY chapter.3 SYSTEM "chapter3.xml">
 <!-- And so forth -->
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <!-- Use the entities to load in the chapters -->

   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>

  ******:

   When using general entities to include other files within a document, the
   files being included (chapter1.xml, chapter2.xml, and so on) must not
   start with a DOCTYPE declaration. This is a syntax error because entities
   are low-level constructs and they are resolved before any parsing happens.

  7.7.2. ************************ Entities

   Parameter entities can only be used inside an XML context. Including a
   file in an XML context can be used to ensure that general entities are
   reusable.

   Suppose that there are many chapters in the document, and these chapters
   were reused in two different books, each book organizing the chapters in a
   different fashion.

   The entities could be listed at the top of each book, but that quickly
   becomes cumbersome to manage.

   Instead, place the general entity definitions inside one file, and use a
   parameter entity to include that file within the document.

   ****** 7.11. ************************ Entities

   Place the entity definitions in a separate file called chapters.ent and
   containing this text:

 <!ENTITY chapter.1 SYSTEM "chapter1.xml">
 <!ENTITY chapter.2 SYSTEM "chapter2.xml">
 <!ENTITY chapter.3 SYSTEM "chapter3.xml">

   Create a parameter entity to refer to the contents of the file. Then use
   the parameter entity to load the file into the document, which will then
   make all the general entities available for use. Then use the general
   entities as before:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!-- Define a parameter entity to load in the chapter general entities -->
 <!ENTITY % chapters SYSTEM "chapters.ent">

 <!-- Now use the parameter entity to load in this file -->
 %chapters;
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>

  7.7.3. ************...

    7.7.3.1. ************************ Entities

    1. Create three files, para1.xml, para2.xml, and para3.xml.

       Put content like this in each file:

 <p>This is the first paragraph.</p>

    2. Edit example.xml so that it looks like this:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.xml">
 <!ENTITY para2 SYSTEM "para2.xml">
 <!ENTITY para3 SYSTEM "para3.xml">
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>The current version of this document is: &version;</p>

     &para1;
     &para2;
     &para3;
   </body>
 </html>

    3. Produce example.html by normalizing example.xml.

 % xmllint --dropdtd --noent example.xml > example.html

    4. Load example.html into the web browser and confirm that the paran.xml
       files have been included in example.html.

    7.7.3.2. ************************ Entities

  ******:

   The previous steps must have completed before this step.

    1. Edit example.xml so that it looks like this:

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [
 <!ENTITY % entities SYSTEM "entities.ent"> %entities;
 ]>

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
     <title>An Example XHTML File</title>
   </head>

   <body>
     <p>The current version of this document is: &version;</p>

     &para1;
     &para2;
     &para3;
   </body>
 </html>

    2. Create a new file called entities.ent with this content:

 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.xml">
 <!ENTITY para2 SYSTEM "para2.xml">
 <!ENTITY para3 SYSTEM "para3.xml">

    3. Produce example.html by normalizing example.xml.

 % xmllint --dropdtd --noent example.xml > example.html

    4. Load example.html into the web browser and confirm that the paran.xml
       files have been included in example.html.

7.8. ***************

   XML provides a mechanism to indicate that particular pieces of the
   document should be processed in a special way. These are called "marked
   sections".

   ****** 7.12. ******************

 <![KEYWORD[
   Contents of marked section
 ]]>

   As expected of an XML construct, a marked section starts with <!.

   The first square bracket begins the marked section.

   KEYWORD describes how this marked section is to be processed by the
   parser.

   The second square bracket indicates the start of the marked section's
   content.

   The marked section is finished by closing the two square brackets, and
   then returning to the document context from the XML context with >.

  7.8.1. ******************

    7.8.1.1. CDATA

   These keywords denote the marked sections content model, and allow you to
   change it from the default.

   When an XML parser is processing a document, it keeps track of the
   "content model".

   The content model describes the content the parser is expecting to see and
   what it will do with that content.

   The CDATA content model is one of the most useful.

   CDATA is for "Character Data". When the parser is in this content model,
   it expects to see only characters. In this model the < and & symbols lose
   their special status, and will be treated as ordinary characters.

  ******:

   When using CDATA in examples of text marked up in XML, remember that the
   content of CDATA is not validated. The included text must be check with
   other means. For example, the content could be written in another
   document, validated, and then pasted into the CDATA section.

   ****** 7.13. ****** CDATA ***************

 <para>Here is an example of how to include some text that contains
   many <literal>&lt;</literal> and <literal>&amp;</literal>
   symbols.  The sample text is a fragment of
   <acronym>XHTML</acronym>.  The surrounding text (<para> and
   <programlisting>) are from DocBook.</para>

 <programlisting><![CDATA[<p>This is a sample that shows some of the
   elements within <acronym>XHTML</acronym>.  Since the angle
   brackets are used so many times, it is simpler to say the whole
   example is a CDATA marked section than to use the entity names for
   the left and right angle brackets throughout.</p>

     <ul>
       <li>This is a listitem</li>
       <li>This is a second listitem</li>
       <li>This is a third listitem</li>
     </ul>

     <p>This is the end of the example.</p>]]></programlisting>

    7.8.1.2. INCLUDE *** IGNORE

   When the keyword is INCLUDE, then the contents of the marked section will
   be processed. When the keyword is IGNORE, the marked section is ignored
   and will not be processed. It will not appear in the output.

   ****** 7.14. *************************** INCLUDE *** IGNORE

 <![INCLUDE[
   This text will be processed and included.
 ]]>

 <![IGNORE[
   This text will not be processed or included.
 ]]>

   By itself, this is not too useful. Text to be removed from the document
   could be cut out, or wrapped in comments.

   It becomes more useful when controlled by parameter entities, yet this
   usage is limited to entity files.

   For example, suppose that documentation was produced in a hard-copy
   version and an electronic version. Some extra text is desired in the
   electronic version content that was not to appear in the hard-copy.

   Create an entity file that defines general entities to include each
   chapter and guard these definitions with a parameter entity that can be
   set to either INCLUDE or IGNORE to control whether the entity is defined.
   After these conditional general entity definitions, place one more
   definition for each general entity to set them to an empty value. This
   technique makes use of the fact that entity definitions cannot be
   overridden but the first definition always takes effect. So the inclusion
   of the chapter is controlled with the corresponding parameter entity. Set
   to INCLUDE, the first general entity definition will be read and the
   second one will be ignored. Set to IGNORE, the first definition will be
   ignored and the second one will take effect.

   ****** 7.15. ************ Entities ************************

 <!ENTITY % electronic.copy "INCLUDE">

 <![%electronic.copy;[
 <!ENTITY chap.preface   SYSTEM "preface.xml">
 ]]>

 <!ENTITY chap.preface "">

   When producing the hard-copy version, change the parameter entity's
   definition to:

 <!ENTITY % electronic.copy "IGNORE">

  7.8.2. ************...

    1. Modify entities.ent to contain the following:

 <!ENTITY version "1.1">
 <!ENTITY % conditional.text "IGNORE">

 <![%conditional.text;[
 <!ENTITY para1 SYSTEM "para1.xml">
 ]]>

 <!ENTITY para1 "">

 <!ENTITY para2 SYSTEM "para2.xml">
 <!ENTITY para3 SYSTEM "para3.xml">

    2. Normalize example.xml and notice that the conditional text is not
       present in the output document. Set the parameter entity guard to
       INCLUDE and regenerate the normalized document and the text will
       appear again. This method makes sense if there are more conditional
       chunks depending on the same condition. For example, to control
       generating printed or online text.

7.9. ******

   That is the conclusion of this XML primer. For reasons of space and
   complexity, several things have not been covered in depth (or at all).
   However, the previous sections cover enough XML to introduce the
   organization of the FDP documentation.

                              *** 8. XHTML ******

   ************

   8.1. ******

   8.2. ********************* (FPI)

   8.3. ************

   8.4. ************

   8.5. ************

8.1. ******

   This chapter describes usage of the XHTML markup language used for the
   FreeBSD web site.

   XHTML is the XML version of the HyperText Markup Language, the markup
   language of choice on the World Wide Web. More information can be found at
   http://www.w3.org/.

   XHTML is used to mark up pages on the FreeBSD web site. It is usually not
   used to mark up other documentation, since DocBook offers a far richer set
   of elements from which to choose. Consequently, XHTML pages will normally
   only be encountered when writing for the web site.

   HTML has gone through a number of versions. The XML-compliant version
   described here is called XHTML. The latest widespread version is XHTML
   1.0, available in both strict and transitional variants.

   The XHTML DTDs are available from the Ports Collection in textproc/xhtml.
   They are automatically installed by the textproc/docproj port.

  ******:

   This is not an exhaustive list of elements, since that would just repeat
   the documentation for XHTML. The aim is to list those elements most
   commonly used. Please post questions about elements or uses not covered
   here to the FreeBSD documentation project mailing list.

  Inline Versus Block:

   In the remainder of this document, when describing elements, inline means
   that the element can occur within a block element, and does not cause a
   line break. A block element, by comparison, will cause a line break (and
   other processing) when it is encountered.

8.2. ********************* (FPI)

   There are a number of XHTML FPIs, depending upon the version, or level of
   XHTML to which a document conforms. Most XHTML documents on the FreeBSD
   web site comply with the transitional version of XHTML 1.0.

 PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"

8.3. ************

   An XHTML document is normally split into two sections. The first section,
   called the head, contains meta-information about the document, such as its
   title, the name of the author, the parent document, and so on. The second
   section, the body, contains content that will be displayed to the user.

   These sections are indicated with head and body elements respectively.
   These elements are contained within the top-level html element.

   ****** 8.1. ********* XHTML ************

 <html xmlns="http://www.w3.org/1999/xhtml">
   <head>
           <title>The Document's Title</title>
   </head>

   <body>

     ...

   </body>
 </html>

8.4. ************

  8.4.1. ******

   XHTML has tags to denote headings in the document at up to six different
   levels.

   The largest and most prominent heading is h1, then h2, continuing down to
   h6.

   The element's content is the text of the heading.

   ****** 8.2. h1, h2, ************************

   ********

 <h1>First section</h1>

 <!-- Document introduction goes here -->

 <h2>This is the heading for the first section</h2>

 <!-- Content for the first section goes here -->

 <h3>This is the heading for the first sub-section</h3>

 <!-- Content for the first sub-section goes here -->

 <h2>This is the heading for the second section</h2>

 <!-- Content for the second section goes here -->

   Generally, an XHTML page should have one first level heading (h1). This
   can contain many second level headings (h2), which can in turn contain
   many third level headings. Do not leave gaps in the numbering.

  8.4.2. ******

   XHTML supports a single paragraph element, p.

   ****** 8.3. p ******

   ********

 <p>This is a paragraph.  It can contain just about any
   other element.</p>

  8.4.3. ************

   A block quotation is an extended quotation from another document that will
   appear in a separate paragraph.

   ****** 8.4. blockquote ******

   ********

 <p>A small excerpt from the US Constitution:</p>

 <blockquote>We the People of the United States, in Order to form
   a more perfect Union, establish Justice, insure domestic
   Tranquility, provide for the common defence, promote the general
   Welfare, and secure the Blessings of Liberty to ourselves and our
   Posterity, do ordain and establish this Constitution for the
   United States of America.</blockquote>

  8.4.4. ******

   XHTML can present the user with three types of lists: ordered, unordered,
   and definition.

   Entries in an ordered list will be numbered, while entries in an unordered
   list will be preceded by bullet points. Definition lists have two sections
   for each entry. The first section is the term being defined, and the
   second section is the definition.

   Ordered lists are indicated by the ol element, unordered lists by the ul
   element, and definition lists by the dl element.

   Ordered and unordered lists contain listitems, indicated by the li
   element. A listitem can contain textual content, or it may be further
   wrapped in one or more p elements.

   Definition lists contain definition terms (dt) and definition descriptions
   (dd). A definition term can only contain inline elements. A definition
   description can contain other block elements.

   ****** 8.5. ul *** ol ******

   ********

 <p>An unordered list.  Listitems will probably be
   preceded by bullets.</p>

 <ul>
   <li>First item</li>

   <li>Second item</li>

   <li>Third item</li>
 </ul>

 <p>An ordered list, with list items consisting of multiple
   paragraphs.  Each item (note: not each paragraph) will be
   numbered.</p>

 <ol>
   <li><p>This is the first item.  It only has one paragraph.</p></li>

   <li><p>This is the first paragraph of the second item.</p>

     <p>This is the second paragraph of the second item.</p></li>

   <li><p>This is the first and only paragraph of the third
     item.</p></li>
 </ol>

   ****** 8.6. ****** dl ***************

   ********

 <dl>
   <dt>Term 1</dt>

   <dd><p>Paragraph 1 of definition 1.</p>

     <p>Paragraph 2 of definition 1.</p></dd>

   <dt>Term 2</dt>

   <dd><p>Paragraph 1 of definition 2.</p></dd>

   <dt>Term 3</dt>

   <dd><p>Paragraph 1 of definition 3.</p></dd>
 </dl>

  8.4.5. ***************

   Pre-formatted text is shown to the user exactly as it is in the file. Text
   is shown in a fixed font. Multiple spaces and line breaks are shown
   exactly as they are in the file.

   Wrap pre-formatted text in the pre element.

   ****** 8.7. pre ******

   For example, the pre tags could be used to mark up an email message:

 <pre>  From: nik@FreeBSD.org
   To: freebsd-doc@FreeBSD.org
   Subject: New documentation available

   There is a new copy of my primer for contributors to the FreeBSD
   Documentation Project available at

     &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;

   Comments appreciated.

   N</pre>

   Keep in mind that < and & still are recognized as special characters in
   pre-formatted text. This is why the example shown had to use &lt; instead
   of <. For consistency, &gt; was used in place of >, too. Watch out for the
   special characters that may appear in text copied from a plain-text
   source, like an email message or program code.

  8.4.6. ******

   Mark up tabular information using the table element. A table consists of
   one or more table rows (tr), each containing one or more cells of table
   data (td). Each cell can contain other block elements, such as paragraphs
   or lists. It can also contain another table (this nesting can repeat
   indefinitely). If the cell only contains one paragraph then the pelement
   is not needed.

   ****** 8.8. table ***************

   ********

 <p>This is a simple 2x2 table.</p>

 <table>
   <tr>
     <td>Top left cell</td>

     <td>Top right cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

   A cell can span multiple rows and columns by adding the rowspan or colspan
   attributes with values for the number of rows or columns to be spanned.

   ****** 8.9. ****** rowspan

   ********

 <p>One tall thin cell on the left, two short cells next to
   it on the right.</p>

 <table>
   <tr>
     <td rowspan="2">Long and thin</td>
   </tr>

   <tr>
     <td>Top cell</td>

     <td>Bottom cell</td>
   </tr>
 </table>

   ****** 8.10. ****** colspan

   ********

 <p>One long cell on top, two short cells below it.</p>

 <table>
   <tr>
     <td colspan="2">Top cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

   ****** 8.11. rowspan *** colspan ************

   ********

 <p>On a 3x3 grid, the top left block is a 2x2 set of
   cells merged into one.  The other cells are normal.</p>

 <table>
   <tr>
     <td colspan="2" rowspan="2">Top left large cell</td>

     <td>Top right cell</td>
   </tr>

   <tr>
     <!-- Because the large cell on the left merges into
          this row, the first <td> will occur on its
          right -->

     <td>Middle right cell</td>
   </tr>

   <tr>
     <td>Bottom left cell</td>

     <td>Bottom middle cell</td>

     <td>Bottom right cell</td>
   </tr>
 </table>

8.5. ************

  8.5.1. ************

   Two levels of emphasis are available in XHTML, em and strong. em is for a
   normal level of emphasis and strong indicates stronger emphasis.

   em is typically rendered in italic and strong is rendered in bold. This is
   not always the case, and should not be relied upon. According to best
   practices, web pages only hold structural and semantical information, and
   stylesheets are later applied to them. Think of semantics, not formatting,
   when using these tags.

   ****** 8.12. em *** strong ******

   ********

 <p><em>This</em> has been emphasized, while
   <strong>this</strong> has been strongly emphasized.</p>

  8.5.2. ******************

   Content that should be rendered in a fixed pitch (typewriter) typeface is
   tagged with tt (for "teletype").

   ****** 8.13. tt ******

   ********

 <p>Many system settings are stored in
   <tt>/etc</tt>.</p>

  8.5.3. ******

  ******:

   Links are also inline elements.

    8.5.3.1. *********************************

   A link points to the URL of a document on the web. The link is indicated
   with a, and the href attribute contains the URL of the target document.
   The content of the element becomes the link, indicated to the user by
   showing it in a different color or with an underline.

   ****** 8.14. ****** <a href="...">

   ********

 <p>More information is available at the
   <a href="http://www.&os;.org/">&os; web site</a>.</p>

   This link always takes the user to the top of the linked document.

    8.5.3.2. *********************************

   To link to a specific point within a document, that document must include
   an anchor at the desired point. Anchors are included by setting the id
   attribute of an element to a name. This example creates an anchor by
   setting the id attribute of a p element.

   ****** 8.15. ************

   ********

 <p id="samplepara">This paragraph can be referenced
   in other links with the name <tt>samplepara</tt>.</p>

   Links to anchors are similar to plain links, but include a # symbol and
   the anchor's ID at the end of the URL.

   ****** 8.16. *********************************************

   The samplepara example is part of a document called foo.html. A link to
   that specific paragraph in the document is constructed in this example.

 <p>More information can be found in the
   <a href="foo.html#samplepara">sample paragraph</a> of
   <tt>foo.html</tt>.</p>

   To link to a named anchor within the same document, omit the document's
   URL, and just use the # symbol followed by the name of the anchor.

   ****** 8.17. ******************************************

   The samplepara example resides in this document. To link to it:

 <p>More information can be found in the
   <a href="#samplepara">sample paragraph</a> of this
   document.</p>

                             *** 9. DocBook ******

   ************

   9.1. ******

   9.2. FreeBSD ************

   9.3. ********************* (FPI)

   9.4. ************

   9.5. ************

   9.6. ************

   9.7. ******

   9.8. ******

9.1. ******

   This chapter is an introduction to DocBook as it is used for FreeBSD
   documentation. DocBook is a large and complex markup system, but the
   subset described here covers the parts that are most widely used for
   FreeBSD documentation. While a moderate subset is covered, it is
   impossible to anticipate every situation. Please post questions that this
   document does not answer to the FreeBSD documentation project mailing
   list.

   DocBook was originally developed by HaL Computer Systems and O'Reilly &
   Associates to be a Document Type Definition (DTD) for writing technical
   documentation [1]. Since 1998 it is maintained by the DocBook Technical
   Committee. As such, and unlike LinuxDoc and XHTML, DocBook is very heavily
   oriented towards markup that describes what something is, rather than
   describing how it should be presented.

   The DocBook DTD is available from the Ports Collection in the
   textproc/docbook-xml port. It is automatically installed as part of the
   textproc/docproj port.

  Formal Versus Informal:

   Some elements may exist in two forms, formal and informal. Typically, the
   formal version of the element will consist of a title followed by the
   informal version of the element. The informal version will not have a
   title.

  Inline Versus Block:

   In the remainder of this document, when describing elements, inline means
   that the element can occur within a block element, and does not cause a
   line break. A block element, by comparison, will cause a line break (and
   other processing) when it is encountered.

9.2. FreeBSD ************

   The FreeBSD Documentation Project has extended the DocBook DTD with
   additional elements and entities. These additions serve to make some of
   the markup easier or more precise.

   Throughout the rest of this document, the term "DocBook" is used to mean
   the FreeBSD-extended DocBook DTD.

  ******:

   Most of these extensions are not unique to FreeBSD, it was just felt that
   they were useful enhancements for this particular project. Should anyone
   from any of the other *nix camps (NetBSD, OpenBSD, Linux, ...) be
   interested in collaborating on a standard DocBook extension set, please
   contact Documentation Engineering Team <doceng@FreeBSD.org>.

  9.2.1. FreeBSD ******

   The additional FreeBSD elements are not (currently) in the Ports
   Collection. They are stored in the FreeBSD Subversion tree, as
   head/share/xml/freebsd.dtd.

   FreeBSD-specific elements used in the examples below are clearly marked.

  9.2.2. FreeBSD Entities

   This table shows some of the most useful entities available in the FDP.
   For a complete list, see the *.ent files in doc/share/xml.

                                                                                                                                                              
FreeBSD Name Entities           
&os;                            FreeBSD                                                                                                                       
&os.stable;                     FreeBSD-STABLE                                                                                                                
&os.current;                    FreeBSD-CURRENT                                                                                                               
                                                                                                                                                              
Manual Page Entities            
&man.ls.1;                      ls(1)                                                     Usage: &man.ls.1; is the manual page for <command>ls</command>.     
&man.cp.1;                      cp(1)                                                     Usage: The manual page for <command>cp</command> is &man.cp.1;.     
&man.command.sectionnumber;     link to command manual page in section sectionnumber      Entities are defined for all the FreeBSD manual pages.              
                                                                                                                                                              
FreeBSD Mailing List Entities   
&a.doc;                         FreeBSD documentation project mailing list                Usage: A link to the &a.doc;.                                       
&a.questions;                   FreeBSD general questions mailing list                    Usage: A link to the &a.questions;.                                 
&a.listname;                    link to listname                                          Entities are defined for all the FreeBSD mailing lists.             
                                                                                                                                                              
FreeBSD Document Link Entities  
&url.books.handbook;            ../../../../doc/en_US.ISO8859-1/books/handbook            Usage: A link to the <link                                          
                                                                                          xlink:href="&url.books.handbook;/advanced-networking.html">Advanced 
                                                                                          Networking</link> chapter of the Handbook.                          
&url.books.bookname;            relative path to bookname                                 Entities are defined for all the FreeBSD books.                     
&url.articles.committers-guide; ../../../../doc/en_US.ISO8859-1/articles/committers-guide Usage: A link to the <link                                          
                                                                                          xlink:href="&url.articles.committers-guide;">Committer's            
                                                                                          Guide</link> article.                                               
&url.articles.articlename;      relative path to articlename                              Entities are defined for all the FreeBSD articles.                  
                                                                                                                                                              
Other Operating System Name Entities
&linux;                         Linux(R)                                                  The Linux(R) operating system.                                      
&unix;                          UNIX(R)                                                   The UNIX(R) operating system.                                       
&windows;                       Windows(R)                                                The Windows(R) operating system.                                    
                                                                                                                                                              
Miscellaneous Entities          
&prompt.root;                   #                                                         The root user prompt.                                               
&prompt.user;                   %                                                         A prompt for an unprivileged user.                                  
&postscript;                    PostScript(R)                                             The PostScript(R) programming language.                             
&tex;                           TeX                                                       The TeX typesetting language.                                       
&xorg;                          Xorg                                                      The Xorg open source X Window System.                               

9.3. ********************* (FPI)

   In compliance with the DocBook guidelines for writing FPIs for DocBook
   customizations, the FPI for the FreeBSD extended DocBook DTD is:

 PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"

9.4. ************

   DocBook allows structuring documentation in several ways. The FreeBSD
   Documentation Project uses two primary types of DocBook document: the book
   and the article.

   Books are organized into chapters. This is a mandatory requirement. There
   may be parts between the book and the chapter to provide another layer of
   organization. For example, the Handbook is arranged in this way.

   A chapter may (or may not) contain one or more sections. These are
   indicated with the sect1 element. If a section contains another section
   then use the sect2 element, and so on, up to sect5.

   Chapters and sections contain the remainder of the content.

   An article is simpler than a book, and does not use chapters. Instead, the
   content of an article is organized into one or more sections, using the
   same sect1 (and sect2 and so on) elements that are used in books.

   The nature of the document being written should be used to determine
   whether it is best marked up as a book or an article. Articles are well
   suited to information that does not need to be broken down into several
   chapters, and that is, relatively speaking, quite short, at up to 20-25
   pages of content. Books are best suited to information that can be broken
   up into several chapters, possibly with appendices and similar content as
   well.

   The FreeBSD tutorials are all marked up as articles, while this document,
   the FAQ, and the Handbook are all marked up as books, for example.

  9.4.1. ******************

   The content of a book is contained within the book element. As well as
   containing structural markup, this element can contain elements that
   include additional information about the book. This is either
   meta-information, used for reference purposes, or additional content used
   to produce a title page.

   This additional information is contained within info.

   ****** 9.1. ****** info *** book ******

 <book>
   <info>
     <title>Your Title Here</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>Your email address</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:your email address">Your name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Include an abstract of the book's contents here.</para>
     </abstract>
   </info>

   ...

 </book>

  9.4.2. ******************

   The content of the article is contained within the article element. As
   well as containing structural markup, this element can contain elements
   that include additional information about the article. This is either
   meta-information, used for reference purposes, or additional content used
   to produce a title page.

   This additional information is contained within info.

   ****** 9.2. ****** info *** article ******

 <article>
   <info>
     <title>Your title here</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>Your email address</email></address>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>1998</year>
       <holder role="mailto:your email address">Your name</holder>
     </copyright>

     <releaseinfo>$FreeBSD$</releaseinfo>

     <abstract>
       <para>Include an abstract of the article's contents here.</para>
     </abstract>
   </info>

   ...

 </article>

  9.4.3. ************

   Use chapter to mark up your chapters. Each chapter has a mandatory title.
   Articles do not contain chapters, they are reserved for books.

   ****** 9.3. ***************

 <chapter>
   <title>The Chapter's Title</title>

   ...
 </chapter>

   A chapter cannot be empty; it must contain elements in addition to title.
   If you need to include an empty chapter then just use an empty paragraph.

   ****** 9.4. ************

 <chapter>
   <title>This is An Empty Chapter</title>

   <para></para>
 </chapter>

  9.4.4. ******************

   In books, chapters may (but do not need to) be broken up into sections,
   subsections, and so on. In articles, sections are the main structural
   element, and each article must contain at least one section. Use the sectn
   element. The n indicates the section number, which identifies the section
   level.

   The first sectn is sect1. You can have one or more of these in a chapter.
   They can contain one or more sect2 elements, and so on, down to sect5.

   ****** 9.5. ***************

 <chapter>
   <title>A Sample Chapter</title>

   <para>Some text in the chapter.</para>

   <sect1>
     <title>First Section</title>

     ...
   </sect1>

   <sect1>
     <title>Second Section</title>

     <sect2>
       <title>First Sub-Section</title>

       <sect3>
         <title>First Sub-Sub-Section</title>

         ...
       </sect3>
     </sect2>

     <sect2>
       <title>Second Sub-Section (1.2.2)</title>

       ...
     </sect2>
   </sect1>
 </chapter>

  ******:

   Section numbers are automatically generated and prepended to titles when
   the document is rendered to an output format. The generated section
   numbers and titles from the example above will be:

     * 1.1. First Section

     * 1.2. Second Section

     * 1.2.1. First Sub-Section

     * 1.2.1.1. First Sub-Sub-Section

     * 1.2.2. Second Sub-Section

  9.4.5. ****** part ***************

   parts introduce another level of organization between book and chapter
   with one or more parts. This cannot be done in an article.

 <part>
   <title>Introduction</title>

   <chapter>
     <title>Overview</title>

     ...
   </chapter>

   <chapter>
     <title>What is FreeBSD?</title>

     ...
   </chapter>

   <chapter>
     <title>History</title>

     ...
   </chapter>
 </part>

9.5. ************

  9.5.1. ******

   DocBook supports three types of paragraphs: formalpara, para, and simpara.

   Almost all paragraphs in FreeBSD documentation use para. formalpara
   includes a title element, and simpara disallows some elements from within
   para. Stick with para.

   ****** 9.6. para ******

   ********

 <para>This is a paragraph.  It can contain just about any
   other element.</para>

   **************

   This is a paragraph. It can contain just about any other element.

  9.5.2. ************

   A block quotation is an extended quotation from another document that
   should not appear within the current paragraph. These are rarely needed.

   Blockquotes can optionally contain a title and an attribution (or they can
   be left untitled and unattributed).

   ****** 9.7. blockquote ******

   ********

 <para>A small excerpt from the US Constitution:</para>

 <blockquote>
   <title>Preamble to the Constitution of the United States</title>

   <attribution>Copied from a web site somewhere</attribution>

   <para>We the People of the United States, in Order to form a more
     perfect Union, establish Justice, insure domestic Tranquility,
     provide for the common defence, promote the general Welfare, and
     secure the Blessings of Liberty to ourselves and our Posterity, do
     ordain and establish this Constitution for the United States of
     America.</para>
 </blockquote>

   **************

   A small excerpt from the US Constitution:

     Preamble to the Constitution of the United States                        
                                                                            
     We the People of the United States, in Order to form a more perfect    
     Union, establish Justice, insure domestic Tranquility, provide for the 
     common defence, promote the general Welfare, and secure the Blessings  
     of Liberty to ourselves and our Posterity, do ordain and establish     
     this Constitution for the United States of America.                    
                                           --Copied from a web site somewhere

  9.5.3. ******,_******,_******,_***************************

   Extra information may need to be separated from the main body of the text.
   Typically this is "meta" information of which the user should be aware.

   Several types of admonitions are available: tip, note, warning, caution,
   and important.

   Which admonition to choose depends on the situation. The DocBook
   documentation suggests:

     * Note is for information that should be heeded by all readers.

     * Important is a variation on Note.

     * Caution is for information regarding possible data loss or software
       damage.

     * Warning is for information regarding possible hardware damage or
       injury to life or limb.

   ****** 9.8. tip *** important ******

   ********

 <tip>
   <para>&os; may reduce stress.</para>
 </tip>

 <important>
   <para>Please use admonitions sparingly.  Too many admonitions
     are visually jarring and can have the opposite of the
     intended effect.</para>
 </important>

   **************

  ******:

   FreeBSD may reduce stress.

  ******:

   Please use admonitions sparingly. Too many admonitions are visually
   jarring and can have the opposite of the intended effect.

  9.5.4. ******

   Examples can be shown with example.

   ****** 9.9. example *********

   ********

 <example>
   <para>Empty files can be created easily:</para>

   <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen>
 </example>

   **************

   ****** 9.10. example *********

   Empty files can be created easily:

 % touch file1 file2 file3

  9.5.5. ***************

   Information often needs to be presented as lists, or as a number of steps
   that must be carried out in order to accomplish a particular goal.

   To do this, use itemizedlist, orderedlist, variablelist, or procedure.
   There are other types of list elements in DocBook, but we will not cover
   them here.

   itemizedlist and orderedlist are similar to their counterparts in HTML, ul
   and ol. Each one consists of one or more listitem elements, and each
   listitem contains one or more block elements. The listitem elements are
   analogous to HTML's li tags. However, unlike HTML, they are required.

   ****** 9.11. itemizedlist *** orderedlist ******

   ********

 <itemizedlist>
   <listitem>
     <para>This is the first itemized item.</para>
   </listitem>

   <listitem>
     <para>This is the second itemized item.</para>
   </listitem>
 </itemizedlist>

 <orderedlist>
   <listitem>
     <para>This is the first ordered item.</para>
   </listitem>

   <listitem>
     <para>This is the second ordered item.</para>
   </listitem>
 </orderedlist>

   **************

     * This is the first itemized item.

     * This is the second itemized item.

    1. This is the first ordered item.

    2. This is the second ordered item.

   An alternate and often useful way of presenting information is the
   variablelist. These are lists where each entry has a term and a
   description. They are well suited for many types of descriptions, and
   present information in a form that is often easier for the reader than
   sections and subsections.

   A variablelist has a title, and then pairs of term and listitem entries.

   ****** 9.12. variablelist ******

   ********

 <variablelist>
   <varlistentry>
     <term>Parallel</term>

     <listitem>
       <para>In parallel communications, groups of bits arrive
         at the same time over multiple communications
         channels.</para>
     </listitem>
   </varlistentry>

   <varlistentry>
     <term>Serial</term>

     <listitem>
       <para>In serial communications, bits arrive one at a
         time over a single communications
         channel.</para>
     </listitem>
   </varlistentry>
 </variablelist>

   **************

   Parallel

           In parallel communications, groups of bits arrive at the same time
           over multiple communications channels.

   Serial

           In serial communications, bits arrive one at a time over a single
           communications channel.

   A procedure shows a series of steps, which may in turn consist of more
   steps or substeps. Each step contains block elements and may include an
   optional title.

   Sometimes, steps are not sequential, but present a choice: do this or do
   that, but not both. For these alternative choices, use stepalternatives.

   ****** 9.13. procedure ******

   ********

 <procedure>
   <step>
     <para>Do this.</para>
   </step>

   <step>
     <para>Then do this.</para>
   </step>

   <step>
     <para>And now do this.</para>
   </step>

   <step>
     <para>Finally, do one of these.</para>

     <stepalternatives>
       <step>
         <para>Go left.</para>
       </step>

       <step>
         <para>Go right.</para>
       </step>
     </stepalternatives>
   </step>
 </procedure>

   **************

    1. Do this.

    2. Then do this.

    3. And now do this.

    4. Finally, do one of these:

          * Go left.

          * Go right.

  9.5.6. ******************

   Fragments of a file (or perhaps a complete file) are shown by wrapping
   them in the programlisting element.

   White space and line breaks within programlisting are significant. In
   particular, this means that the opening tag should appear on the same line
   as the first line of the output, and the closing tag should appear on the
   same line as the last line of the output, otherwise spurious blank lines
   may be included.

   ****** 9.14. programlisting ******

   ********

 <para>When finished, the program will look like
   this:</para>

 <programlisting>#include &lt;stdio.h&gt;

 int
 main(void)
 {
     printf("hello, world\n");
 }</programlisting>

   Notice how the angle brackets in the #include line need to be referenced
   by their entities instead of being included literally.

   **************

   When finished, the program will look like this:

 #include <stdio.h>

 int
 main(void)
 {
     printf("hello, world\n");
 }

  9.5.7. ******

   A callout is a visual marker for referring to a piece of text or specific
   position within an example.

   Callouts are marked with the co element. Each element must have a unique
   id assigned to it. After the example, include a calloutlist that describes
   each callout.

   ****** 9.15. co *** calloutlist ******

 <para>When finished, the program will look like
   this:</para>

 <programlisting>#include &lt;stdio.h&gt; <co xml:id="co-ex-include"/>

 int <co xml:id="co-ex-return"/>
 main(void)
 {
     printf("hello, world\n"); <co xml:id="co-ex-printf"/>
 }</programlisting>

 <calloutlist>
   <callout arearefs="co-ex-include">
     <para>Includes the standard IO header file.</para>
   </callout>

   <callout arearefs="co-ex-return">
     <para>Specifies that <function>main()</function> returns an
       int.</para>
   </callout>

   <callout arearefs="co-ex-printf">
     <para>The <function>printf()</function> call that writes
       <literal>hello, world</literal> to standard output.</para>
   </callout>
 </calloutlist>

   **************

   When finished, the program will look like this:

 #include <stdio.h> 1

 int 2
 main(void)
 {
     printf("hello, world\n"); 3
 }

   1   Includes the standard IO header file.                           
   2   Specifies that main() returns an int.                           
   3   The printf() call that writes hello, world to standard output.  

  9.5.8. ******

   Unlike HTML, DocBook does not need tables for layout purposes, as the
   stylesheet handles those issues. Instead, just use tables for marking up
   tabular data.

   In general terms (and see the DocBook documentation for more detail) a
   table (which can be either formal or informal) consists of a table
   element. This contains at least one tgroup element, which specifies (as an
   attribute) the number of columns in this table group. Within the
   tablegroup there is one thead element, which contains elements for the
   table headings (column headings), and one tbody which contains the body of
   the table.

   Both tgroup and thead contain row elements, which in turn contain entry
   elements. Each entry element specifies one cell in the table.

   ****** 9.16. informaltable ******

   ********

 <informaltable pgwide="1">
   <tgroup cols="2">
     <thead>
       <row>
         <entry>This is Column Head 1</entry>
         <entry>This is Column Head 2</entry>
       </row>
     </thead>

     <tbody>
       <row>
         <entry>Row 1, column 1</entry>
         <entry>Row 1, column 2</entry>
       </row>

       <row>
         <entry>Row 2, column 1</entry>
         <entry>Row 2, column 2</entry>
       </row>
     </tbody>
   </tgroup>
 </informaltable>

   **************

   +------------------------------------------------------------------------+
   |       This is Column Head 1        |       This is Column Head 2       |
   |------------------------------------+-----------------------------------|
   | Row 1, column 1                    | Row 1, column 2                   |
   |------------------------------------+-----------------------------------|
   | Row 2, column 1                    | Row 2, column 2                   |
   +------------------------------------------------------------------------+

   Always use the pgwide attribute with a value of 1 with the informaltable
   element. A bug in Internet Explorer can cause the table to render
   incorrectly if this is omitted.

   Table borders can be suppressed by setting the frame attribute to none in
   the informaltable element. For example, informaltable frame="none".

   ****** 9.17. ************ frame="none" ******

   **************

           This is Column Head 1                This is Column Head 2         
   Row 1, column 1                       Row 1, column 2                      
   Row 2, column 1                       Row 2, column 2                      

  9.5.9. ***************************

   Examples for the user to follow are often necessary. Typically, these will
   consist of dialogs with the computer; the user types in a command, the
   user gets a response back, the user types another command, and so on.

   A number of distinct elements and entities come into play here.

   screen

           Everything the user sees in this example will be on the computer
           screen, so the next element is screen.

           Within screen, white space is significant.

   prompt, &prompt.root; and &prompt.user;

           Some of the things the user will be seeing on the screen are
           prompts from the computer (either from the operating system,
           command shell, or application). These should be marked up using
           prompt.

           As a special case, the two shell prompts for the normal user and
           the root user have been provided as entities. To indicate the user
           is at a shell prompt, use one of &prompt.root; and &prompt.user;
           as necessary. They do not need to be inside prompt.

  ******:

           &prompt.root; and &prompt.user; are FreeBSD extensions to DocBook,
           and are not part of the original DTD.

   userinput

           When displaying text that the user should type in, wrap it in
           userinput tags. It will be displayed differently than system
           output text.

   ****** 9.18. screen, prompt *** userinput ******

   ********

 <screen>&prompt.user; <userinput>ls -1</userinput>
 foo1
 foo2
 foo3
 &prompt.user; <userinput>ls -1 | grep foo2</userinput>
 foo2
 &prompt.user; <userinput>su</userinput>
 <prompt>Password: </prompt>
 &prompt.root; <userinput>cat foo2</userinput>
 This is the file called 'foo2'</screen>

   **************

 % ls -1
 foo1
 foo2
 foo3
 % ls -1 | grep foo2
 foo2
 % su
 Password:
 # cat foo2
 This is the file called 'foo2'

  ******:

   Even though we are displaying the contents of the file foo2, it is not
   marked up as programlisting. Reserve programlisting for showing fragments
   of files outside the context of user actions.

9.6. ************

  9.6.1. ************

   To emphasize a particular word or phrase, use emphasis. This may be
   presented as italic, or bold, or might be spoken differently with a
   text-to-speech system.

   There is no way to change the presentation of the emphasis within the
   document, no equivalent of HTML's b and i. If the information being
   presented is important, then consider presenting it in important rather
   than emphasis.

   ****** 9.19. emphasis ******

   ********

 <para>&os; is without doubt <emphasis>the</emphasis>
   premiere &unix;-like operating system for the Intel
   architecture.</para>

   **************

   FreeBSD is without doubt the premiere UNIX(R)-like operating system for
   the Intel architecture.

  9.6.2. ******

   Many computer terms are acronyms, words formed from the first letter of
   each word in a phrase. Acronyms are marked up into acronym elements. It is
   helpful to the reader when an acronym is defined on the first use, as
   shown in the example below.

   ****** 9.20. acronym ******

   ********

 <para>Request For Comments (<acronym>RFC</acronym>) 1149
   defined the use of avian carriers for transmission of
   Internet Protocol (<acronym>IP</acronym>) data.  The
   quantity of <acronym>IP</acronym> data currently
   transmitted in that manner is unknown.</para>

   **************

   Request For Comments (RFC) 1149 defined the use of avian carriers for
   transmission of Internet Protocol (IP) data. The quantity of IP data
   currently transmitted in that manner is unknown.

  9.6.3. ******

   To quote text from another document or source, or to denote a phrase that
   is used figuratively, use quote. Most of the markup tags available for
   normal text are also available from within a quote.

   ****** 9.21. quote ******

   ********

 <para>However, make sure that the search does not go beyond the
   <quote>boundary between local and public administration</quote>,
   as <acronym>RFC</acronym> 1535 calls it.</para>

   **************

   However, make sure that the search does not go beyond the "boundary
   between local and public administration", as RFC 1535 calls it.

  9.6.4. ************,_************************

   To refer to a specific key on the keyboard, use keycap. To refer to a
   mouse button, use mousebutton. And to refer to combinations of key presses
   or mouse clicks, wrap them all in keycombo.

   keycombo has an attribute called action, which may be one of click,
   double-click, other, press, seq, or simul. The last two values denote
   whether the keys or buttons should be pressed in sequence, or
   simultaneously.

   The stylesheets automatically add any connecting symbols, such as +,
   between the key names, when wrapped in keycombo.

   ****** 9.22. ************,_******************************

   ********

 <para>To switch to the second virtual terminal, press
   <keycombo action="simul"><keycap>Alt</keycap>
     <keycap>F1</keycap></keycombo>.</para>

 <para>To exit <command>vi</command> without saving changes, type
   <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap>
     <keycap>q</keycap><keycap>!</keycap></keycombo>.</para>

 <para>My window manager is configured so that
   <keycombo action="simul"><keycap>Alt</keycap>
     <mousebutton>right</mousebutton>
   </keycombo> mouse button is used to move windows.</para>

   **************

   To switch to the second virtual terminal, press Alt+F1.

   To exit vi without saving changes, type Esc : q !.

   My window manager is configured so that Alt+right mouse button is used to
   move windows.

  9.6.5. ************,_******,_***************

   Both applications and commands are frequently referred to when writing
   documentation. The distinction between them is that an application is the
   name of a program or suite of programs that fulfill a particular task. A
   command is the filename of a program that the user can type and run at a
   command line.

   It is often necessary to show some of the options that a command might
   take.

   Finally, it is often useful to list a command with its manual section
   number, in the "command(number)" format so common in Unix manuals.

   Mark up application names with application.

   To list a command with its manual section number (which should be most of
   the time) the DocBook element is citerefentry. This will contain a further
   two elements, refentrytitle and manvolnum. The content of refentrytitle is
   the name of the command, and the content of manvolnum is the manual page
   section.

   This can be cumbersome to write, and so a series of general entities have
   been created to make this easier. Each entity takes the form
   &man.manual-page.manual-section;.

   The file that contains these entities is in doc/share/xml/man-refs.ent,
   and can be referred to using this FPI:

 PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

   Therefore, the introduction to FreeBSD documentation will usually include
   this:

 <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [

 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;

 ...

 ]>

   Use command to include a command name "in-line" but present it as
   something the user should type.

   Use option to mark up the options which will be passed to a command.

   When referring to the same command multiple times in close proximity, it
   is preferred to use the &man.command.section; notation to markup the first
   reference and use command to markup subsequent references. This makes the
   generated output, especially HTML, appear visually better.

   ****** 9.23. ************,_******,_************

   ********

 <para><application>Sendmail</application> is the most
   widely used Unix mail application.<para>

 <para><application>Sendmail</application> includes the
   <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, &man.mailq.1;, and &man.newaliases.1;
   programs.</para>

 <para>One of the command line parameters to <citerefentry>
     <refentrytitle>sendmail</refentrytitle>
     <manvolnum>8</manvolnum>
   </citerefentry>, <option>-bp</option>, will display the current
   status of messages in the mail queue.  Check this on the command
   line by running <command>sendmail -bp</command>.</para>

   **************

   Sendmail is the most widely used Unix mail application.

   Sendmail includes the sendmail(8), mailq(1), and newaliases(1) programs.

   One of the command line parameters to sendmail(8), -bp, will display the
   current status of messages in the mail queue. Check this on the command
   line by running sendmail -bp.

  ******:

   Notice how the &man.command.section; notation is easier to follow.

  9.6.6. ******,_******,_*********,_************

   To refer to the name of a file, a directory, a file extension, or a device
   name, use filename.

   ****** 9.24. filename ******

   ********

 <para>The source for the Handbook in English is found in
   <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>.
   The main file is called <filename>book.xml</filename>.
   There is also a <filename>Makefile</filename> and a
   number of files with a <filename>.ent</filename> extension.</para>

 <para><filename>kbd0</filename> is the first keyboard detected
   by the system, and appears in
   <filename>/dev</filename>.</para>

   **************

   The source for the Handbook in English is found in
   /usr/doc/en_US.ISO8859-1/books/handbook/. The main file is called
   book.xml. There is also a Makefile and a number of files with a .ent
   extension.

   kbd0 is the first keyboard detected by the system, and appears in /dev.

  9.6.7. Port ******

  FreeBSD Extension:

   These elements are part of the FreeBSD extension to DocBook, and do not
   exist in the original DocBook DTD.

   To include the name of a program from the FreeBSD Ports Collection in the
   document, use the package tag. Since the Ports Collection can be installed
   in any number of locations, only include the category and the port name;
   do not include /usr/ports.

   By default, package refers to a binary package. To refer to a port that
   will be built from source, set the role attribute to port.

   ****** 9.25. package ******

   ********

 <para>Install the <package>net/wireshark</package> binary
   package to view network traffic.</para>

 <para><package role="port">net/wireshark</package> can also be
   built and installed from the Ports Collection.</para>

   **************

   Install the net/wireshark binary package to view network traffic.

   net/wireshark can also be built and installed from the Ports Collection.

  9.6.8. ******,_******,_IP
  ******,_************,_*********************************

  FreeBSD Extension:

   These elements are part of the FreeBSD extension to DocBook, and do not
   exist in the original DocBook DTD.

   Information for "system items" is marked up with systemitem. The class
   attribute is used to identify the particular type of information shown.

   class="domainname"

           The text is a domain name, such as FreeBSD.org or ngo.org.uk.
           There is no hostname component.

   class="etheraddress"

           The text is an Ethernet MAC address, expressed as a series of 2
           digit hexadecimal numbers separated by colons.

   class="fqdomainname"

           The text is a Fully Qualified Domain Name, with both hostname and
           domain name parts.

   class="ipaddress"

           The text is an IP address, probably expressed as a dotted quad.

   class="netmask"

           The text is a network mask, which might be expressed as a dotted
           quad, a hexadecimal string, or as a / followed by a number (CIDR
           notation).

   class="systemname"

           With class="systemname" the marked up information is the simple
           hostname, such as freefall or wcarchive.

   class="username"

           The text is a username, like root.

   class="groupname"

           The text is a groupname, like wheel.

   ****** 9.26. systemitem ********* (Class) ******

   ********

 <para>The local machine can always be referred to by the
   name <systemitem class="systemname">localhost</systemitem>, which will have the IP
   address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para>

 <para>The <systemitem class="domainname">FreeBSD.org</systemitem>
   domain contains a number of different hosts, including
   <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and
   <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para>

 <para>When adding an <acronym>IP</acronym> alias to an
   interface (using <command>ifconfig</command>)
   <emphasis>always</emphasis> use a netmask of
   <systemitem class="netmask">255.255.255.255</systemitem> (which can
   also be expressed as
   <systemitem class="netmask">0xffffffff</systemitem>).</para>

 <para>The <acronym>MAC</acronym> address uniquely identifies
   every network card in existence.  A typical
   <acronym>MAC</acronym> address looks like
   <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para>

 <para>To carry out most system administration functions
   requires logging in as <systemitem class="username">root</systemitem>.</para>

   **************

   The local machine can always be referred to by the name localhost, which
   will have the IP address 127.0.0.1.

   The FreeBSD.org domain contains a number of different hosts, including
   freefall.FreeBSD.org and bento.FreeBSD.org.

   When adding an IP alias to an interface (using ifconfig) always use a
   netmask of 255.255.255.255 (which can also be expressed as 0xffffffff).

   The MAC address uniquely identifies every network card in existence. A
   typical MAC address looks like 08:00:20:87:ef:d0.

   To carry out most system administration functions requires logging in as
   root.

  9.6.9. ********************* (URI)

   Occasionally it is useful to show a Uniform Resource Identifier (URI)
   without making it an active hyperlink. The uri element makes this
   possible:

   ****** 9.27. uri ******

   ********

 <para>This URL shows only as text:
   <uri>https://www.FreeBSD.org</uri>.  It does not
   create a link.</para>

   **************

   This URL shows only as text: https://www.FreeBSD.org. It does not create a
   link.

   To create links, see *** 9.8, "******".

  9.6.10. ************

   Email addresses are marked up as email elements. In the HTML output
   format, the wrapped text becomes a hyperlink to the email address. Other
   output formats that support hyperlinks may also make the email address
   into a link.

   ****** 9.28. *************** email ******

   ********

 <para>An email address that does not actually exist, like
   <email>notreal@example.com</email>, can be used as an
   example.</para>

   **************

   An email address that does not actually exist, like <notreal@example.com>,
   can be used as an example.

   A FreeBSD-specific extension allows setting the role attribute to nolink
   to prevent the creation of the hyperlink to the email address.

   ****** 9.29. ****************** email ******

   ********

 <para>Sometimes a link to an email address like
   <email role="nolink">notreal@example.com</email> is not
   desired.</para>

   **************

   Sometimes a link to an email address like <notreal@example.com> is not
   desired.

  9.6.11. ****** Makefile

  FreeBSD Extension:

   These elements are part of the FreeBSD extension to DocBook, and do not
   exist in the original DocBook DTD.

   Two elements exist to describe parts of Makefiles, buildtarget and
   varname.

   buildtarget identifies a build target exported by a Makefile that can be
   given as a parameter to make. varname identifies a variable that can be
   set (in the environment, on the command line with make, or within the
   Makefile) to influence the process.

   ****** 9.30. buildtarget *** varname ******

   ********

 <para>Two common targets in a <filename>Makefile</filename>
   are <buildtarget>all</buildtarget> and
   <buildtarget>clean</buildtarget>.</para>

 <para>Typically, invoking <buildtarget>all</buildtarget> will
   rebuild the application, and invoking
   <buildtarget>clean</buildtarget> will remove the temporary
   files (<filename>.o</filename> for example) created by the
   build process.</para>

 <para><buildtarget>clean</buildtarget> may be controlled by a
   number of variables, including <varname>CLOBBER</varname>
   and <varname>RECURSE</varname>.</para>

   **************

   Two common targets in a Makefile are all and clean.

   Typically, invoking all will rebuild the application, and invoking clean
   will remove the temporary files (.o for example) created by the build
   process.

   clean may be controlled by a number of variables, including CLOBBER and
   RECURSE.

  9.6.12. ************ (Literal)

   Literal text, or text which should be entered verbatim, is often needed in
   documentation. This is text that is excerpted from another file, or which
   should be copied exactly as shown from the documentation into another
   file.

   Some of the time, programlisting will be sufficient to denote this text.
   But programlisting is not always appropriate, particularly when you want
   to include a portion of a file "in-line" with the rest of the paragraph.

   On these occasions, use literal.

   ****** 9.31. literal ******

   ********

 <para>The <literal>maxusers 10</literal> line in the kernel
   configuration file determines the size of many system tables, and is
   a rough guide to how many simultaneous logins the system will
   support.</para>

   **************

   The maxusers 10 line in the kernel configuration file determines the size
   of many system tables, and is a rough guide to how many simultaneous
   logins the system will support.

  9.6.13. ******************************

   There will often be times when the user is shown what to do, or referred
   to a file or command line, but cannot simply copy the example provided.
   Instead, they must supply some information themselves.

   replaceable is designed for this eventuality. Use it inside other elements
   to indicate parts of that element's content that the user must replace.

   ****** 9.32. replaceable ******

   ********

 <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>

   **************

 % man command

   replaceable can be used in many different elements, including literal.
   This example also shows that replaceable should only be wrapped around the
   content that the user is meant to provide. The other content should be
   left alone.

   ********

 <para>The <literal>maxusers <replaceable>n</replaceable></literal>
   line in the kernel configuration file determines the size of many system
   tables, and is a rough guide to how many simultaneous logins the system will
   support.</para>

 <para>For a desktop workstation, <literal>32</literal> is a good value
   for <replaceable>n</replaceable>.</para>

   **************

   The maxusers n line in the kernel configuration file determines the size
   of many system tables, and is a rough guide to how many simultaneous
   logins the system will support.

   For a desktop workstation, 32 is a good value for n.

  9.6.14. ****** GUI ******

   Buttons presented by a graphical user interface are marked with guibutton.
   To make the text look more like a graphical button, brackets and
   non-breaking spaces are added surrounding the text.

   ****** 9.33. guibutton ******

   ********

 <para>Edit the file, then click
   <guibutton>[&nbsp;Save&nbsp;]</guibutton> to save the
   changes.</para>

   **************

   Edit the file, then click [ Save ] to save the changes.

  9.6.15. ******************

   System errors generated by FreeBSD are marked with errorname. This
   indicates the exact error that appears.

   ****** 9.34. errorname ******

   ********

 <screen><errorname>Panic: cannot mount root</errorname></screen>

   **************

 Panic: cannot mount root

9.7. ******

  ******:

   Image support in the documentation is somewhat experimental. The
   mechanisms described here are unlikely to change, but that is not
   guaranteed.

   To provide conversion between different image formats, the
   graphics/ImageMagick port must be installed. This port is not included in
   the textproc/docproj meta port, and must be installed separately.

   A good example of the use of images is the
   doc/en_US.ISO8859-1/articles/vm-design/ document. Examine the files in
   that directory to see how these elements are used together. Build
   different output formats to see how the format determines what images are
   shown in the rendered document.

  9.7.1. ************

   The following image formats are currently supported. An image file will
   automatically be converted to bitmap or vector image depending on the
   output document format.

   These are the only formats in which images should be committed to the
   documentation repository.

   EPS (Encapsulated Postscript)

           Images that are primarily vector based, such as network diagrams,
           time lines, and similar, should be in this format. These images
           have a .eps extension.

   PNG (Portable Network Graphic)

           For bitmaps, such as screen captures, use this format. These
           images have the .png extension.

   PIC (PIC graphics language)

           PIC is a language for drawing simple vector-based figures used in
           the pic(1) utility. These images have the .pic extension.

   SCR (SCReen capture)

           This format is specific to screenshots of console output. The
           following command generates an SCR file shot.scr from video buffer
           of /dev/ttyv0:

 # vidcontrol -p < /dev/ttyv0 > shot.scr

           This is preferable to PNG format for screenshots because the SCR
           file contains plain text of the command lines so that it can be
           converted to a PNG image or a plain text depending on the output
           document format.

   Use the appropriate format for each image. Documentation will often have a
   mix of EPS and PNG images. The Makefiles ensure that the correct format
   image is chosen depending on the output format used. Do not commit the
   same image to the repository in two different formats.

  ******:

   The Documentation Project may eventually switch to using the SVG (Scalable
   Vector Graphic) format for vector images. However, the current state of
   SVG capable editing tools makes this impractical.

  9.7.2. ******************

   Image files can be stored in one of several locations, depending on the
   document and image:

     * In the same directory as the document itself, usually done for
       articles and small books that keep all their files in a single
       directory.

     * In a subdirectory of the main document. Typically done when a large
       book uses separate subdirectories to organize individual chapters.

       When images are stored in a subdirectory of the main document
       directory, the subdirectory name must be included in their paths in
       the Makefile and the imagedata element.

     * In a subdirectory of doc/share/images named after the document. For
       example, images for the Handbook are stored in
       doc/share/images/books/handbook. Images that work for multiple
       translations are stored in this upper level of the documentation file
       tree. Generally, these are images that can be used unchanged in
       non-English translations of the document.

  9.7.3. ************

   Images are included as part of a mediaobject. The mediaobject can contain
   other, more specific objects. We are concerned with two, the imageobject
   and the textobject.

   Include one imageobject, and two textobject elements. The imageobject will
   point to the name of the image file without the extension. The textobject
   elements contain information that will be presented to the user as well
   as, or instead of, the image itself.

   Text elements are shown to the reader in several situations. When the
   document is viewed in HTML, text elements are shown while the image is
   loading, or if the mouse pointer is hovered over the image, or if a
   text-only browser is being used. In formats like plain text where graphics
   are not possible, the text elements are shown instead of the graphical
   ones.

   This example shows how to include an image called fig1.png in a document.
   The image is a rectangle with an A inside it:

 <mediaobject>
   <imageobject>
     <imagedata fileref="fig1"/> 1
   </imageobject>

   <textobject>
     <literallayout class="monospaced">+---------------+ 2
 |       A       |
 +---------------+</literallayout>
   </textobject>

   <textobject>
     <phrase>A picture</phrase> 3
   </textobject>
 </mediaobject>

   1 Include an imagedata element inside the imageobject element. The fileref 
     attribute should contain the filename of the image to include, without   
     the extension. The stylesheets will work out which extension should be   
     added to the filename automatically.                                     
   2 The first textobject contains a literallayout element, where the class   
     attribute is set to monospaced. This is an opportunity to demonstrate    
     ASCII art skills. This content will be used if the document is converted 
     to plain text.                                                           
                                                                              
     Notice how the first and last lines of the content of the literallayout  
     element butt up next to the element's tags. This ensures no extraneous   
     white space is included.                                                 
   3 The second textobject contains a single phrase element. The contents of  
     this phrase will become the alt attribute for the image when this        
     document is converted to HTML.                                           

  9.7.4. ****** Makefile ******

   Images must be listed in the Makefile in the IMAGES variable. This
   variable must contain the names of all the source images. For example, if
   there are three figures, fig1.eps, fig2.png, fig3.png, then the Makefile
   should have lines like this in it.

 ...
 IMAGES= fig1.eps fig2.png fig3.png
 ...

   or

 ...
 IMAGES=  fig1.eps
 IMAGES+= fig2.png
 IMAGES+= fig3.png
 ...

   Again, the Makefile will work out the complete list of images it needs to
   build the source document, you only need to list the image files you
   provided.

  9.7.5. *********************************

   Be careful when separating documentation into smaller files in different
   directories (see *** 7.7.1, "************************ Entities").

   Suppose there is a book with three chapters, and the chapters are stored
   in their own directories, called chapter1/chapter.xml,
   chapter2/chapter.xml, and chapter3/chapter.xml. If each chapter has images
   associated with it, place those images in each chapter's subdirectory
   (chapter1/, chapter2/, and chapter3/).

   However, doing this requires including the directory names in the IMAGES
   variable in the Makefile, and including the directory name in the
   imagedata element in the document.

   For example, if the book has chapter1/fig1.png, then chapter1/chapter.xml
   should contain:

 <mediaobject>
   <imageobject>
     <imagedata fileref="chapter1/fig1"/> 1
   </imageobject>

   ...

 </mediaobject>

   1   The directory name must be included in the fileref attribute.  

   The Makefile must contain:

 ...
 IMAGES=  chapter1/fig1.png
 ...

9.8. ******

  ******:

   Links are also in-line elements. To show a URI without creating a link,
   see *** 9.6.9, "********************* (URI)".

  9.8.1. xml:id ******

   Most DocBook elements accept an xml:id attribute to give that part of the
   document a unique name. The xml:id can be used as a target for a
   crossreference or link.

   Any portion of the document that will be a link target must have an xml:id
   attribute. Assigning an xml:id to all chapters and sections, even if there
   are no current plans to link to them, is a good idea. These xml:ids can be
   used as unique reference points by anyone referring to the HTML version of
   the document.

   ****** 9.35. ****************** xml:id *********

 <chapter xml:id="introduction">
   <title>Introduction</title>

   <para>This is the introduction.  It contains a subsection,
     which is identified as well.</para>

   <sect1 xml:id="introduction-moredetails">
     <title>More Details</title>

     <para>This is a subsection.</para>
   </sect1>
 </chapter>

   Use descriptive values for xml:id names. The values must be unique within
   the entire document, not just in a single file. In the example, the
   subsection xml:id is constructed by appending text to the chapter xml:id.
   This ensures that the xml:ids are unique. It also helps both reader and
   anyone editing the document to see where the link is located within the
   document, similar to a directory path to a file.

  9.8.2. ****** xref ************

   xref provides the reader with a link to jump to another section of the
   document. The target xml:id is specified in the linkend attribute, and
   xref generates the link text automatically.

   ****** 9.36. xref ******

   Assume that this fragment appears somewhere in a document that includes
   the xml:id example shown above:

 <para>More information can be found
   in <xref linkend="introduction"/>.</para>

 <para>More specific information can be found
   in <xref linkend="introduction-moredetails"/>.</para>

   The link text will be generated automatically, looking like (emphasized
   text indicates the link text):

     More information can be found in Chapter 1, Introduction.

     More specific information can be found in Section 1.1, "More Details".

   The link text is generated automatically from the chapter and section
   number and title elements.

  9.8.3. *********************************

   The link element described here allows the writer to define the link text.
   When link text is used, it is very important to be descriptive to give the
   reader an idea of where the link goes. Remember that DocBook can be
   rendered to multiple types of media. The reader might be looking at a
   printed book or other form of media where there are no links. If the link
   text is not descriptive enough, the reader might not be able to locate the
   linked section.

   The xlink:href attribute is the URL of the page, and the content of the
   element is the text that will be displayed for the user to activate.

   In many situations, it is preferable to show the actual URL rather than
   text. This can be done by leaving out the element text entirely.

   ****** 9.37. link *** FreeBSD ************************

   Link to the book or article URL entity. To link to a specific chapter in a
   book, add a slash and the chapter file name, followed by an optional
   anchor within the chapter. For articles, link to the article URL entity,
   followed by an optional anchor within the article. URL entities can be
   found in doc/share/xml/urls.ent.

   Usage for FreeBSD book links:

 <para>Read the <link
     xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN
     introduction</link>, then pick the nearest mirror from
   the list of <link
     xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion
     mirror sites</link>.</para>

   **************

   Read the SVN introduction, then pick the nearest mirror from the list of
   Subversion mirror sites.

   Usage for FreeBSD article links:

 <para>Read this
   <link xlink:href="&url.articles.bsdl-gpl;">article
     about the BSD license</link>, or just the
   <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para>

   **************

   Read this article about the BSD license, or just the introduction.

   ****** 9.38. link *** FreeBSD ************

   ********

 <para>Of course, you could stop reading this document and go to the
   <link xlink:href="&url.base;/index.html">FreeBSD home page</link> instead.</para>

   **************

   Of course, you could stop reading this document and go to the FreeBSD home
   page instead.

   ****** 9.39. link *********************

   ********

 <para>Wikipedia has an excellent reference on
   <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID
     Partition Tables</link>.</para>

   **************

   Wikipedia has an excellent reference on GUID Partition Tables.

   The link text can be omitted to show the actual URL:

 <para>Wikipedia has an excellent reference on
   GUID Partition Tables: <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"></link>.</para>

   The same link can be entered using shorter notation instead of a separate
   ending tag:

 <para>Wikipedia has an excellent reference on
   GUID Partition Tables: <link
     xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"/>.</para>

   The two methods are equivalent. Appearance:

   Wikipedia has an excellent reference on GUID Partition Tables:
   http://en.wikipedia.org/wiki/GUID_Partition_Table.

     ----------------------------------------------------------------------

   [1] A short history can be found under
   http://www.oasis-open.org/docbook/intro.shtml#d0e41.

                               *** 10. *********

   ************

   10.1. CSS

   XML is concerned with content, and says nothing about how that content
   should be presented to the reader or rendered on paper. Multiple style
   sheet languages have been developed to describe visual layout, including
   Extensible Stylesheet Language Transformation (XSLT), Document Style
   Semantics and Specification Language (DSSSL), and Cascading Style Sheets
   (CSS).

   The FDP documents use XSLT stylesheets to transform DocBook into XHTML,
   and then CSS formatting is applied to the XHTML pages. Printable output is
   currently rendered with legacy DSSSL stylesheets, but this will probably
   change in the future.

10.1. CSS

   Cascading Style Sheets (CSS) are a mechanism for attaching style
   information (font, weight, size, color, and so forth) to elements in an
   XHTML document without abusing XHTML to do so.

  10.1.1. DocBook ******

   The FreeBSD XSLT and DSSSL stylesheets refer to docbook.css, which is
   expected to be present in the same directory as the XHTML files. The
   project-wide CSS file is copied from doc/share/misc/docbook.css when
   documents are converted to XHTML, and is installed automatically.

                                 *** 11. ******

   ************************ FreeBSD ************ (***************
   (FAQ),_************ (Handbook),_****** (Tutorial),_************ (Manual
   page) ***) ********************************* (FAQ)._

   ********* ****** ****** FreeBSD
   **************************************************************************************
   Frank Gru:nder <elwood@mc5sys.in-berlin.de>******** Bernd Warken
   <bwarken@mayn.de> *********************._

   ****************************************** Documentation Engineering Team
   <doceng@FreeBSD.org> *********._

   11.1. i18n *** l10n **************************

   11.2. ********************************************* (Mailing list) *****

   11.3. **************************************

   11.4. ******************************

   11.5. ***********************************

   11.6. ********************************************************

   11.7. *******************************************************

   11.8. ****************************************************

   11.9.
   *************************************************************************

   11.10.
   ***********************************************************************

   11.11. **************************************************************

   11.12. ***********************

   11.13. *****************************************************

11.1.  i18n *** l10n **************************                                                                                                                                                                     
       i18n ****************** (Internationalization) *** l10n ****************** (Localization)._*********************************************._                                                                   
                                                                                                                                                                                                                    
       i18n *************** "i" ********* 18 ******************** "n"._***********l10n ************ "l" ********* 10 ******************** "n"._                                                                     
11.2.  ********************************************* (Mailing list) *****                                                                                                                                           
       ********************************************************************._****** ****************** ********************************* mailing lists                                                              
       ***************._********************************<freebsd-translators@freebsd.org>************._                                                                                                             
11.3.  **************************************                                                                                                                                                                       
       ******************************************************************************************************,_**************************************************._                                                 
                                                                                                                                                                                                                    
       **************************************************._                                                                                                                                                         
11.4.  ******************************                                                                                                                                                                               
       ************************************************************************************************************._                                                                                               
                                                                                                                                                                                                                    
       ******************************._******************************** (Spanish) *** FAQ ********************* (Hungarian)._                                                                                       
11.5.  ***********************************                                                                                                                                                                          
       *************************************** FreeBSD Subversion ****************** (*********************************)*******************                                                                         
                                                                                                                                                                                                                    
       % svn checkout https://svn.FreeBSD.org/doc/head/ head                                                                                                                                                        
                                                                                                                                                                                                                    
       svn.FreeBSD.org ************ SVN *********._********* Subversion ********* ******************************._                                                                                                  
                                                                                                                                                                                                                    
         ******:                                                                                                                                                                                                    
                                                                                                                                                                                                                    
       *************** devel/subversion ******._                                                                                                                                                                    
                                                                                                                                                                                                                    
       *************************** svn._************************************************************************._                                                                                                  
                                                                                                                                                                                                                    
       *************** en_US.ISO8859-1/books/fdp-primer/book.xml ******r33733 *** r33734 **********************                                                                                                     
                                                                                                                                                                                                                    
       % svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml                                                                                                                                           
11.6.  ********************************************************                                                                                                                                                     
       ***************************                                                                                                                                                                                  
       ******************************************************************************************************************************************************************************************************._     
                                                                                                                                                                                                                    
       **************************************************************************************************************** FreeBSD ****************************** ._                                                   
11.7.  *******************************************************                                                                                                                                                      
       ************************** "FreeBSD ************ ************************"*****************************._                                                                                                    
                                                                                                                                                                                                                    
       **************************************************************************************************************************,_******************************************************************************._ 
                                                                                                                                                                                                                    
       ********************************* (Documentation Project mailing list) ***********************************************************************************************._                                     
                                                                                                                                                                                                                    
       ********************************* FreeBSD ************ (Mirror)                                                                                                                                              
       ***************************************************************************************************************************************************************************************._                    
                                                                                                                                                                                                                    
       ********************************************************************************************************* -- ****** FAQ ********************************************._                                       
11.8.  ****************************************************                                                                                                                                                         
       *********************._************************************                                                                                                                                                  
       (******************,_************)****************************************************************************************************************._                                                         
                                                                                                                                                                                                                    
       ************************************ (******************************************************** FreeBSD ******)************************************************** FreeBSD ******._(************************)  
11.9.  *************************************************************************                                                                                                                                    
                                                                                                                                                                                                                    
       or                                                                                                                                                                                                           
                                                                                                                                                                                                                    
       *************************************************************************                                                                                                                                    
       ******************************************************************************************** ******************************************************************._                                            
                                                                                                                                                                                                                    
       ********FreeBSD ************************************ head/ *********._****************************** ISO639 ********************************************* (*** 1999/1/20 ********* FreeBSD ************      
       /usr/share/misc/iso639)._                                                                                                                                                                                    
                                                                                                                                                                                                                    
       ************************************************ (**************) **************************************************************************._                                                               
                                                                                                                                                                                                                    
       ***********************************************._                                                                                                                                                            
                                                                                                                                                                                                                    
       ******************************** (Swedish) *************************************                                                                                                                             
                                                                                                                                                                                                                    
       head/                                                                                                                                                                                                        
           sv_SE.ISO8859-1/                                                                                                                                                                                         
                            Makefile                                                                                                                                                                                
                            htdocs/                                                                                                                                                                                 
                                  docproj/                                                                                                                                                                          
                            books/                                                                                                                                                                                  
                                  faq/                                                                                                                                                                              
                                      Makefile                                                                                                                                                                      
                                      book.xml                                                                                                                                                                      
                                                                                                                                                                                                                    
       sv_SE.ISO8859-1********* ****** (Lang).****** (Encoding) ***************************._************************** Makefile *****************************************._                                        
                                                                                                                                                                                                                    
       ************ tar(1) *** gzip(1) ***********************************************************._                                                                                                                
                                                                                                                                                                                                                    
       % cd doc                                                                                                                                                                                                     
       % tar cf swedish-docs.tar sv_SE.ISO8859-1                                                                                                                                                                    
       % gzip -9 swedish-docs.tar                                                                                                                                                                                   
                                                                                                                                                                                                                    
       *********** swedish-docs.tar.gz *********************************************************** (ISP *********)******************************************** Documentation Engineering Team <doceng@FreeBSD.org>  
       ***._                                                                                                                                                                                                        
                                                                                                                                                                                                                    
       ***************** Bugzilla                                                                                                                                                                                   
       ****************************************************************************************************,_**********************************************************************************************._       
                                                                                                                                                                                                                    
       ***************** (******************************************************** Documentation Engineering Team <doceng@FreeBSD.org> ******)                                                                      
       ***********************************************************._*******************************************                                                                                                     
                                                                                                                                                                                                                    
        1. *************************** RCS tag (****** "ID" *********)**                                                                                                                                            
                                                                                                                                                                                                                    
        2. sv_SE.ISO8859-1 ******************make all ***********                                                                                                                                                   
                                                                                                                                                                                                                    
        3. make install *********************                                                                                                                                                                       
                                                                                                                                                                                                                    
       *******************************************************************************************._                                                                                                                
                                                                                                                                                                                                                    
       *****************************************************************._                                                                                                                                          
11.10. ***********************************************************************                                                                                                                                      
       ***************************._                                                                                                                                                                                
                                                                                                                                                                                                                    
       *********************************************** (Handbook) ********************************************************************************************._                                                    
                                                                                                                                                                                                                    
       **********************************************************************************(************,_************,_********* ...) ******************************************************* FreeBSD                
       ************._************************** FreeBSD ****************************************************._                                                                                                      
                                                                                                                                                                                                                    
       ******************************************************************************** (*** Bugzilla)**************************************************************************._                                  
                                                                                                                                                                                                                    
       ******._                                                                                                                                                                                                     
11.11. **************************************************************                                                                                                                                               
       *************************** ASCII (Non-ASCII) *********************** SGML entities ***************._                                                                                                        
                                                                                                                                                                                                                    
       *********************************** and ****** (&)************** Entity ************************** (;)._                                                                                                     
                                                                                                                                                                                                                    
       ****** Entity ************ ISO8879 ******************** Port ********* textproc/iso8879._                                                                                                                    
                                                                                                                                                                                                                    
       ***********************                                                                                                                                                                                      
                                                                                                                                                                                                                    
       Entity ******: &eacute;                                                                                                                                                                                      
       ******: e                                                                                                                                                                                                    
       ******: *** "e"***********,_****** (Acute accent)                                                                                                                                                            
       Entity ******: &Eacute;                                                                                                                                                                                      
       ******: E                                                                                                                                                                                                    
       ******: *** "E"***********,_****** (Acute accent)                                                                                                                                                            
       Entity ******: &uuml;                                                                                                                                                                                        
       ******: u:                                                                                                                                                                                                   
       ******: *** "u"***************************************** (Umlaut)                                                                                                                                            
                                                                                                                                                                                                                    
       ********* iso8879 ****** Port ******************** /usr/local/share/xml/iso8879 ***************************._                                                                                                
11.12. ***********************                                                                                                                                                                                      
       *********************************** "you" *****************************************/******************._                                                                                                     
                                                                                                                                                                                                                    
       **************************************************************************************************************************._**************************************************************************._     
11.13. *****************************************************                                                                                                                                                        
       ***._                                                                                                                                                                                                        
                                                                                                                                                                                                                    
       ****************************************************************                                                                                                                                             
                                                                                                                                                                                                                    
       <!--                                                                                                                                                                                                         
            The FreeBSD Documentation Project                                                                                                                                                                       
                                                                                                                                                                                                                    
            $FreeBSD$                                                                                                                                                                                               
       -->                                                                                                                                                                                                          
                                                                                                                                                                                                                    
       ***************************************************************** $FreeBSD$ *************** The FreeBSD Documentation Project ******._***********$FreeBSD$ ************************ Subversion               
       ************************************************************************** (****************** $FreeBSD$ *********)._                                                                                        
                                                                                                                                                                                                                    
       ******************************** $FreeBSD$ ***************** FreeBSD Documentation Project ************ The FreeBSD language Documentation Project._                                                         
                                                                                                                                                                                                                    
       ****************************************************************************************************************************._                                                                               
                                                                                                                                                                                                                    
       ************************** (Spanish) **************************************                                                                                                                                  
                                                                                                                                                                                                                    
       <!--                                                                                                                                                                                                         
            The FreeBSD Spanish Documentation Project                                                                                                                                                               
                                                                                                                                                                                                                    
            $FreeBSD$                                                                                                                                                                                               
            Original revision: r38674                                                                                                                                                                               
       -->                                                                                                                                                                                                          

                               *** 12. PO ******

   ************

   12.1. ******

   12.2. ************

   12.3. ***************

   12.4. ******

   12.5. *********************

   12.6. *********************

   12.7. ***************

12.1. ******

   GNU gettext
   ***************************************************************************._*********************************************
   PO (Portable Object)
   ***._******************************************._***********************************************************************************._

12.2. ************

   ****************************** *** 1.1, "************"
   ***************************************** textproc/docproj Port ******
   TRANSLATOR
   ******._**************************************************************
   Port._

 # cd /usr/ports/textproc/docproj
 # make config
 # make clean deinstall install clean

   ****************************** Leap Seconds ***************************._

   ****** 12.1. ****** PO *********
     * ************************ PO *********._******************
       editors/poedit._

 # cd /usr/ports/editors/poedit
 # make install clean

   ****** 12.2. ************

   *********************************************** Makefile
   ******************************************._

    1. ************************._***************************
       ~/doc/en_US.ISO8859-1/articles/leap-seconds/
       ._******************************
       ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
       ._**************************************************._

 % svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

    2. ********************* Makefile *********************._

 % svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \
     ~/doc/es_ES.ISO8859-1/articles/leap-seconds/

   ****** 12.3. ******

   **********************************************************************************************************._***********************************************************************************************************._

    1. *************************************** PO *****

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make po

    2. ****** PO ************************ PO
       ***._***************************************._***************
       editors/poedit *** poedit ._

       PO
       ***************************************************************************._********************************
       es_ES.po ._

 % poedit es_ES.po

   ****** 12.4. ******************
    1. ******************

 % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/
 % make tran

       ***********************************************************************
       article.xml*********** book.xml ._

    2. *************** HTML
       **************************************************._

 % make FORMATS=html
 % firefox article.html

12.3. ***************

   ************************************************************************._FreeBSD
   ***************************************************** ****** (lang)_******
   (REGION) *********._****** (lang)
   ********************************************************************
   REGION ***._

   ****** 12.1. ************

      ******        ******      ****************** PO *********  *********  
   ******       ******          en_US.ISO8859-1    en_US.po     ISO 8859-1  
   ************ *********       bn_BD.UTF-8        bn_BD.po     UTF-8       
   *********    ******          da_DK.ISO8859-1    da_DK.po     ISO 8859-1  
   ******       ******          de_DE.ISO8859-1    de_DE.po     ISO 8859-1  
   *********    ******          el_GR.ISO8859-7    el_GR.po     ISO 8859-7  
   ************ *********       es_ES.ISO8859-1    es_ES.po     ISO 8859-1  
   ******       ******          fr_FR.ISO8859-1    fr_FR.po     ISO 8859-1  
   ************ *********       hu_HU.ISO8859-2    hu_HU.po     ISO 8859-2  
   ************ *********       it_IT.ISO8859-15   it_IT.po     ISO 8859-15 
   ******       ******          ja_JP.eucJP        ja_JP.po     EUC JP      
   ******       ******          ko_KR.UTF-8        ko_KR.po     UTF-8       
   *********    ******          mn_MN.UTF-8        mn_MN.po     UTF-8       
   *********    ******          nl_NL.ISO8859-1    nl_NL.po     ISO 8859-1  
   *********    ******          no_NO.ISO8859-1    no_NO.po     ISO 8859-1  
   *********    ******          pl_PL.ISO8859-2    pl_PL.po     ISO 8859-2  
   ************ ******          pt_BR.ISO8859-1    pt_BR.po     ISO 8859-1  
   ******       *********       ru_RU.KOI8-R       ru_RU.po     KOI8-R      
   ************ *************** sr_YU.ISO8859-2    sr_YU.po     ISO 8859-2  
   ************ *********       tr_TR.ISO8859-9    tr_TR.po     ISO 8859-9  
   ******       ******          zh_CN.UTF-8        zh_CN.po     UTF-8       
   ******       ******          zh_TW.UTF-8        zh_TW.po     UTF-8       

   ***************************************************************** *** 1.1,
   "************" *********** ~/doc/._******************
   ~/doc/de_DE.ISO8859-1/************** ~/doc/fr_FR.ISO8859-1/._

   *****************************************************************
   articles/ *** books/._

   ************************************************************._********NanoBSD
   ************************ ~/doc/fr_FR.ISO8859-1/articles/nanobsd/
   ._************************************~/doc/mn_MN.UTF-8/books/handbook/ ._

   ******************************************************************._***********************************************
   articles/ *** books/ ************._

   FreeBSD ********************************************* Makefile
   ******._********************************************************* Makefile
   ******._****************************************** book.xml ***
   chapter.xml ***************************************** Makefile
   *********************._

   ****** 12.1. ****** Porter ***************************

   ****** Porter ****** *********************._***************
   ~/doc/en_US.ISO8859-1/books/porters-handbook/ *********._

    1. ************ books ****** ~/doc/es_ES.ISO8859-1/books/
       ******************************** Porter ********************

 % cd ~/doc/es_ES.ISO8859-1/books/
 % svn mkdir porters-handbook
 A         porters-handbook

    2. ****************************** Makefile**

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .
 A         Makefile

       ****** Makefile ************************ book.xml**

 #
 # $FreeBSD$
 #
 # Build the FreeBSD Porter's Handbook.
 #

 MAINTAINER=doc@FreeBSD.org

 DOC?= book

 FORMATS?= html-split

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # XML content
 SRCS=  book.xml

 # Images from the cross-document image library
 IMAGES_LIB+=    callouts/1.png
 IMAGES_LIB+=    callouts/2.png
 IMAGES_LIB+=    callouts/3.png
 IMAGES_LIB+=    callouts/4.png
 IMAGES_LIB+=    callouts/5.png
 IMAGES_LIB+=    callouts/6.png
 IMAGES_LIB+=    callouts/7.png
 IMAGES_LIB+=    callouts/8.png
 IMAGES_LIB+=    callouts/9.png
 IMAGES_LIB+=    callouts/10.png
 IMAGES_LIB+=    callouts/11.png
 IMAGES_LIB+=    callouts/12.png
 IMAGES_LIB+=    callouts/13.png
 IMAGES_LIB+=    callouts/14.png
 IMAGES_LIB+=    callouts/15.png
 IMAGES_LIB+=    callouts/16.png
 IMAGES_LIB+=    callouts/17.png
 IMAGES_LIB+=    callouts/18.png
 IMAGES_LIB+=    callouts/19.png
 IMAGES_LIB+=    callouts/20.png
 IMAGES_LIB+=    callouts/21.png

 URL_RELPREFIX?= ../../../..
 DOC_PREFIX?= ${.CURDIR}/../../..

 .include "${DOC_PREFIX}/share/mk/doc.project.mk"

       *************************************************** make po
       ************._

   ****** 12.2. ****** PGP ***************************._

   ****** PGP ************ ***************._***************
   ~/doc/en_US.ISO8859-1/articles/pgpkeys/ *********._

    1. ****************** ~/doc/fr_FR.ISO8859-1/articles/
       ******************************** PGP **************************

 % cd ~/doc/fr_FR.ISO8859-1/articles/
 % svn mkdir pgpkeys
 A         pgpkeys

    2. ****************************** Makefile**

 % cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys
 % svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .
 A         Makefile

       ****** Makefile *********._**************************************
       Makefile ************._************ $FreeBSD...$
       ******************************************************************._

 #
 # $FreeBSD$
 #
 # Article: PGP Keys

 DOC?= article

 FORMATS?= html
 WITH_ARTICLE_TOC?= YES

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 SRCS=   article.xml

 # To build with just key fingerprints, set FINGERPRINTS_ONLY.

 URL_RELPREFIX?= ../../../..
 DOC_PREFIX?=    ${.CURDIR}/../../..

 .include "${DOC_PREFIX}/share/mk/doc.project.mk"

       ******************************************** make po ****** PO ***._

12.4. ******

   gettext
   *********************************************._******************************
   PO ***._****** PO *********************************._

   FreeBSD PO *************************** PO
   ***._************************************************************ PO ***._

   *** PO ***************************._************
   editors/poedit*****************************************._********* PO
   ***********************************************************._Port
   ************************************** devel/gtranslator ._

   ****** PO ******************._******************************._

   ****** 12.3. ****** Porter *********************

   ****** Porter ***************************

    1. ********************* Porter ************************ PO
       ***._********* PO ****** ****** 12.1, "************" **************
       es_ES.po ._

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make po

    2. ****** PO **************************

 % poedit es_ES.po

12.5. *********************

  12.5.1. ****** XML ******

   ************************ XML ******._

   ****** 12.4. ****** XML ******

   **************

 If <acronym>NTP</acronym> is not being used

   ********************

 Si <acronym>NTP</acronym> no se utiliza

  12.5.2. ************

   ********************************************************************************._

  12.5.3. *********************

   ***********************************************************._

     * <citerefentry>

     * <command>

     * <filename>

     * <literal>

     * <manvolnum>

     * <orgname>

     * <package>

     * <programlisting>

     * <prompt>

     * <refentrytitle>

     * <screen>

     * <userinput>

     * <varname>

  12.5.4. $FreeBSD$ ******

   ************************ $FreeBSD$
   ******************************************** ****** 12.1, "****** Porter
   ***************************"*****************************************************._******************************
   &dollar; Entity *****************************************

 &dollar;FreeBSD&dollar;

   *************************** &dollar; entities
   **************************************************************._

   *** PO ***************************************** &dollar; Entity
   ************************************************** $FreeBSD$
   *********************************************************************._

   *********************************************************************** PO
   ************ &dollar; ***********************

 &dollar;FreeBSD&dollar;

12.6. *********************

   ***************************************************._************************************._*********
   PO
   *********************************************._*********************************************************************************._

   ****** 12.5. ****************** Porter ******

   *************************************************** Porter ******

    1. ************************._***********************************************
       book.xml._

 % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook
 % make tran

    2. ****************** book.xml *** HTML ****** Firefox
       *********._***************************************** FORMATS
       ******************._****** ****** 5.1, "******************" ._

 % make FORMATS=html
 % firefox book.html

12.7. ***************

   ***************************._*************************************************************************************
   diff *********._

   ****************** diff ********************* ******************
   (Documentation bug report) *** *************** (Code review) ._

   ****** 12.6. NanoBSD ***************************
    1. ****** FreeBSD ********************* PO *****************

 #$FreeBSD$

    2. ****** Makefile ,_PO *************** XML *****************************

 % cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/
 % ls
 Makefile        article.xml     es_ES.po
 % svn add Makefile article.xml es_ES.po
 A         Makefile
 A         article.xml
 A         es_ES.po

    3. ********************* Subversion svn:keywords ********* FreeBSD=%H ***
       $FreeBSD$
       *********************************************,_******,_********************

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'es_ES.po'

    4. *************** MIME ******._****************** text/xml**PO ******
       text/x-gettext-translation ._

 % svn propset svn:mime-type text/x-gettext-translation es_ES.po
 property 'svn:mime-type' set on 'es_ES.po'
 % svn propset svn:mime-type text/xml article.xml
 property 'svn:mime-type' set on 'article.xml'

    5. *** ~/doc/ ************************
       diff********************************._************************************************._

 % cd ~/doc
 svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff

   ****** 12.7. Explaining-BSD *************** UTF-8 ******
    1. ****** FreeBSD ********************* PO *****************

 #$FreeBSD$

    2. ****** Makefile ,_PO *************** XML *****************************

 % cd ~/doc/ko_KR.UTF-8/articles/explaining-bsd/
 % ls
 Makefile        article.xml     ko_KR.po
 % svn add Makefile article.xml ko_KR.po
 A         Makefile
 A         article.xml
 A         ko_KR.po

    3. ********************* Subversion svn:keywords ********* FreeBSD=%H ***
       $FreeBSD$
       *********************************************,_******,_********************

 % svn propset svn:keywords FreeBSD=%H Makefile article.xml ko_KR.po
 property 'svn:keywords' set on 'Makefile'
 property 'svn:keywords' set on 'article.xml'
 property 'svn:keywords' set on 'ko_KR.po'

    4. *************** MIME ******._************************ UTF-8
       *****************************._***********************************************************************fbsd:notbinary
       *********************._

 % svn propset svn:mime-type 'text/x-gettext-translation**charset=UTF-8' ko_KR.po
 property 'svn:mime-type' set on 'ko_KR.po'
 % svn propset fbsd:notbinary yes ko_KR.po
 property 'fbsd:notbinary' set on 'ko_KR.po'
 % svn propset svn:mime-type 'text/xml**charset=UTF-8' article.xml
 property 'svn:mime-type' set on 'article.xml'
 % svn propset fbsd:notbinary yes article.xml
 property 'fbsd:notbinary' set on 'article.xml'

    5. *** ~/doc/ ************************ diff._

 % cd ~/doc
 svn diff ko_KR.UTF-8/articles/explaining-bsd > /tmp/ko-explaining.diff

                              *** 13. ************

   ************

   13.1. ******

   13.2. ******

   13.3. ************

   13.4. *********

13.1. ******

   Technical documentation can be improved by consistent use of several
   principles. Most of these can be classified into three goals: be clear, be
   complete, and be concise. These goals can conflict with each other. Good
   writing consists of a balance between them.

  13.1.1. *********

   Clarity is extremely important. The reader may be a novice, or reading the
   document in a second language. Strive for simple, uncomplicated text that
   clearly explains the concepts.

   Avoid flowery or embellished speech, jokes, or colloquial expressions.
   Write as simply and clearly as possible. Simple text is easier to
   understand and translate.

   Keep explanations as short, simple, and clear as possible. Avoid empty
   phrases like "in order to", which usually just means "to". Avoid
   potentially patronizing words like "basically". Avoid Latin terms like
   "i.e." or "cf.", which may be unknown outside of academic or scientific
   groups.

   Write in a formal style. Avoid addressing the reader as "you". For
   example, say "copy the file to /tmp" rather than "you can copy the file to
   /tmp".

   Give clear, correct, tested examples. A trivial example is better than no
   example. A good example is better yet. Do not give bad examples,
   identifiable by apologies or sentences like "but really it should never be
   done that way". Bad examples are worse than no examples. Give good
   examples, because even when warned not to use the example as shown, the
   reader will usually just use the example as shown.

   Avoid weasel words like "should", "might", "try", or "could". These words
   imply that the speaker is unsure of the facts, and create doubt in the
   reader.

   Similarly, give instructions as imperative commands: not "you should do
   this", but merely "do this".

  13.1.2. *********

   Do not make assumptions about the reader's abilities or skill level. Tell
   them what they need to know. Give links to other documents to provide
   background information without having to recreate it. Put yourself in the
   reader's place, anticipate the questions they will ask, and answer them.

  13.1.3. *********

   While features should be documented completely, sometimes there is so much
   information that the reader cannot easily find the specific detail needed.
   The balance between being complete and being concise is a challenge. One
   approach is to have an introduction, then a "quick start" section that
   describes the most common situation, followed by an in-depth reference
   section.

13.2. ******

   To promote consistency between the myriad authors of the FreeBSD
   documentation, some guidelines have been drawn up for authors to follow.

   ************************

           There are several variants of English, with different spellings
           for the same word. Where spellings differ, use the American
           English variant. "color", not "colour", "rationalize", not
           "rationalise", and so on.

  ******:

           The use of British English may be accepted in the case of a
           contributed article, however the spelling must be consistent
           within the whole document. The other documents such as books, web
           site, manual pages, etc. will have to use American English.

   *********************

           Do not use contractions. Always spell the phrase out in full.
           "Don't use contractions" is wrong.

           Avoiding contractions makes for a more formal tone, is more
           precise, and is slightly easier for translators.

   ******************

           In a list of items within a paragraph, separate each item from the
           others with a comma. Separate the last item from the others with a
           comma and the word "and".

           For example:

             This is a list of one, two and three items.

           Is this a list of three items, "one", "two", and "three", or a
           list of two items, "one" and "two and three"?

           It is better to be explicit and include a serial comma:

             This is a list of one, two, and three items.

   *********************

           Do not use redundant phrases. In particular, "the command", "the
           file", and "man command" are often redundant.

           For example, commands:

           Wrong: Use the svn command to update sources.

           Right: Use svn to update sources.

           Filenames:

           Wrong: ... in the filename /etc/rc.local...

           Right: ... in /etc/rc.local...

           Manual page references (the second example uses citerefentry with
           the &man.csh.1; entity):.

           Wrong: See man csh for more information.

           Right: See csh(1).

   ******************************

           Always use two spaces between sentences, as it improves
           readability and eases use of tools such as Emacs.

           A period and spaces followed by a capital letter does not always
           mark a new sentence, especially in names. "Jordan K. Hubbard" is a
           good example. It has a capital H following a period and a space,
           and is certainly not a new sentence.

   For more information about writing style, see Elements of Style, by
   William Strunk.

13.3. ************

   **********************************************************************************************************************._

  13.3.1. *********

   Tag ******************************************** para********PARA._

   *** SGML ******************************************* <!ENTITY...> ***
   <!DOCTYPE...>*********** <!entity...> *** <!doctype...>._

  13.3.2. ******

   ********* (Acronym)
   ***************************************************************************"Network
   Time Protocol
   (NTP)"._********************************************************(********************************************************************)***************._*******************************************************************************************************************************************._

   *********************acronym*********._

  13.3.3. ******

   ********************************************************************._

   *****************************************************************************************************._*********
   8 ***************** tab *********._*********** tab
   **************************************************************._****** tag
   *****************************************************************************._

   **********************************************************

 <chapter>
   <title>...</title>

   <sect1>
     <title>...</title>

     <sect2>
       <title>Indentation</title>

       <para>The first line in each file starts with no indentation,
         <emphasis>regardless</emphasis> of the indentation level of
         the file which might contain the current file.</para>

       ...
     </sect2>
   </sect1>
 </chapter>

   ************************************************._*****************************************************************************

 <para>See the <link
     linkend="gmirror-troubleshooting">Troubleshooting</link>
   section if there are problems booting.  Powering down and
   disconnecting the original <filename>ada0</filename> disk
   will allow it to be kept as an offline backup.</para>

 <para>It is also possible to journal the boot disk of a &os;
   system.  Refer to the article <link
     xlink:href="&url.articles.gjournal-desktop;">Implementing UFS
     Journaling on a Desktop PC</link> for detailed
   instructions.</para>

   When an element is too long to fit on the remainder of a line without
   wrapping, moving the start tag to the next line can make the source easier
   to read. In this example, the systemitem element has been moved to the
   next line to avoid wrapping and indenting:

 <para>With file flags, even
   <systemitem class="username">root</systemitem> can be
   prevented from removing or altering files.</para>

   Configurations to help various text editors conform to these guidelines
   can be found in *** 14, ***************.

  13.3.4. ************

    13.3.4.1. ************

   *****************************************************************************************._********

 <article lang='en'>
   <articleinfo>
     <title>NIS</title>

     <pubdate>October 1999</pubdate>

     <abstract>
       <para>...
         ...
         ...</para>
     </abstract>
   </articleinfo>

   <sect1>
     <title>...</title>

     <para>...</para>
   </sect1>

   <sect1>
     <title>...</title>

     <para>...</para>
   </sect1>
 </article>

    13.3.4.2. ************

   ****** itemizedlist
   ***********************************************************************************************._*********************************._

   ************** para *** term
   ****************************************************************************************************************************************._

   **************************************************************._

   *******************************************************************._

   *****************************************************************************************************._********************************************************._

   *****************************************************************************._

  13.3.5. ************

   *****************************************************************************._

   ************************************************************************************************************************************************************._

   **********************************************************************************************
   80 ******************** commmit
   ******._**************************************************** commit
   ***._*************** commit ********************************
   whitespace-only (******************)
   ************************************************************* commit ***
   ._

  13.3.6. ***************

   ********************************************************,_************************************._************************************************************._***************************************
   HTML
   **************************************************************************

 Data capacity ranges from 40 MB to 15
 GB.  Hardware compression ...

   ********* &nbsp;
   ****************************************************************************

     * **************************

 57600&nbsp;bps

     * ********************************

 &os;&nbsp;9.2

     * *************************** (*************** "The FreeBSD Brazilian
       Portuguese Documentation Project"
       ******************************************************)**

 Sun&nbsp;Microsystems

13.4. *********

   ****************************** FreeBSD
   *********************************._**************************************
   FreeBSD documentation project mailing list ._

  ******               XML *********                               ******                    
CD-ROM     <acronym>CD-ROM</acronym>                                                         
DoS                                                                                          
(Denial of <acronym>DoS</acronym>                 
Service)   
email                                                                                        
file                                                                                         
system     
IPsec                                                                                        
Internet                                                                                     
manual                                                                                       
page       
mail                                                                                         
server     
name                                                                                         
server     
Ports                                                                                        
Collection 
read-only                                                                                    
Soft                                                                                         
Updates    
stdin      <varname>stdin</varname>                                                          
stdout     <varname>stdout</varname>                                                         
stderr     <varname>stderr</varname>                                                         
                                                 *************** SVN ********* Subversion    
Subversion <application>Subversion</application> ************._***************************** 
                                                 <command>svn</command>._                    
UNIX(R)    &unix;                                                                            
userland                                         ************************************ (User  
                                                 space) *********************._              
web server                                                                                   

                            *** 14. ***************

   ************

   14.1. Vim

   14.2. Emacs

   14.3. nano

   Adjusting text editor configuration can make working on document files
   quicker and easier, and help documents conform to FDP guidelines.

14.1. Vim

   Install from editors/vim or editors/vim-lite, then follow the
   configuration instructions in *** 14.1.2, "******".

  14.1.1. ******

   Press P to reformat paragraphs or text that has been selected in Visual
   mode. Press T to replace groups of eight spaces with a tab.

  14.1.2. ******

   Edit ~/.vimrc, adding these lines to the end of the file:

 if has("autocmd")
     au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()
     au BufNewFile,BufRead *.[1-9] call ShowSpecial()
 endif " has(autocmd)

 function Set_Highlights()
     "match ExtraWhitespace /^\s* \s*\|\s\+$/
     highlight default link OverLength ErrorMsg
     match OverLength /\%71v.\+/
     return 0
 endfunction

 function ShowSpecial()
     setlocal list listchars=tab:>>,trail:*,eol:$
     hi def link nontext ErrorMsg
     return 0
 endfunction " ShowSpecial()

 function Set_SGML()
     setlocal number
     syn match sgmlSpecial "&[^;]*;"
     setlocal syntax=sgml
     setlocal filetype=xml
     setlocal shiftwidth=2
     setlocal textwidth=70
     setlocal tabstop=8
     setlocal softtabstop=2
     setlocal formatprg="fmt -p"
     setlocal autoindent
     setlocal smartindent
     " Rewrap paragraphs
     noremap P gqj
     " Replace spaces with tabs
     noremap T :s/        /\t/<CR>
     call ShowSpecial()
     call Set_Highlights()
     return 0
 endfunction " Set_SGML()

14.2. Emacs

   Install from editors/emacs or editors/emacs-devel.

  14.2.1. ******

   Emacs's nxml-mode uses compact relax NG schemas for validating XML. A
   compact relax NG schema for FreeBSD's extension to DocBook 5.0 is included
   in the documentation repository. To configure nxml-mode to validate using
   this schema, create ~/.emacs.d/schema/schemas.xml and add these lines to
   the file:

 <locatingRules xmlns="http://thaiopensource.com/ns/locating-rules/1.0">
   <documentElement localName="section" typeId="DocBook">
   <documentElement localName="chapter" typeId="DocBook">
   <documentElement localName="article" typeId="DocBook">
   <documentElement localName="book" typeId="DocBook">
   <typeId id="DocBook" uri="/usr/local/share/xml/docbook/5.0/rng/docbook.rnc">
 </locatingRules>

  14.2.2. ****** Flycheck *** Igor ***************

   The Flycheck package is available from Milkypostman's Emacs Lisp Package
   Archive (MELPA). If MELPA is not already in Emacs's packages-archives, it
   can be added by evaluating

 (add-to-list 'package-archives '("melpa" . "http://stable.melpa.org/packages/") t)

   Add the line to Emacs's initialization file (one of ~/.emacs, ~/.emacs.el,
   or ~.emacs.d/init.el) to make this change permanent.

   To install Flycheck, evaluate

 (package-install 'flycheck)

   Create a Flycheck checker for textproc/igor by evaluating

 (flycheck-define-checker igor
   "FreeBSD Documentation Project sanity checker.

 See URLs http://www.freebsd.org/docproj/ and
 http://www.freshports.org/textproc/igor/."
   :command ("igor" "-X" source-inplace)
   :error-parser flycheck-parse-checkstyle
   :modes (nxml-mode)
   :standard-input t)

   (add-to-list 'flycheck-checkers 'igor 'append)

   Again, add these lines to Emacs's initialization file to make the changes
   permanent.

  14.2.3. FreeBSD ***************************

   To apply settings specific to the FreeBSD documentation project, create
   .dir-locals.el in the root directory of the documentation repository and
   add these lines to the file:

 ;;; Directory Local Variables
 ;;; For more information see (info "(emacs) Directory Variables")

 ((nxml-mode
   (eval . (turn-on-auto-fill))
   (fill-column . 70)
   (eval . (require 'flycheck))
   (eval . (flycheck-mode 1))
   (flycheck-checker . igor)
   (eval . (add-to-list 'rng-schema-locating-files "~/.emacs.d/schema/schemas.xml"))))

14.3. nano

   Install from editors/nano or editors/nano-devel.

  14.3.1. ******

   Copy the sample XML syntax highlight file to the user's home directory:

 % cp /usr/local/share/nano/xml.nanorc ~/.nanorc

   Add these lines to the new ~/.nanorc.

 syntax "xml" "\.([jrs]html?|xml|xslt?)$"
 # trailing whitespace
 color ,blue "[[:space:]]+$"
 # multiples of eight spaces at the start a line
 # (after zero or more tabs) should be a tab
 color ,blue "^([TAB]*[ ]{8})+"
 # tabs after spaces
 color ,yellow "( )+TAB"
 # highlight indents that have an odd number of spaces
 color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}"
 # lines longer than 70 characters
 color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"

   Process the file to create embedded tabs:

 % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc

  14.3.2. ******

   Specify additional helpful options when running the editor:

 % nano -AKipwz -r 70 -T8 chapter.xml

   Users of csh(1) can define an alias in ~/.cshrc to automate these options:

 alias nano "nano -AKipwz -r 70 -T8"

   After the alias is defined, the options will be added automatically:

 % nano chapter.xml

                              *** 15. ************

   ************

   15.1. FreeBSD ******************

   15.2. XML

   15.3. HTML

   15.4. DocBook

   This document is deliberately not an exhaustive discussion of XML, the
   DTDs listed, and the FreeBSD Documentation Project. For more information
   about these, you are encouraged to see the following web sites.

15.1. FreeBSD ******************

     * FreeBSD ************************

     * FreeBSD ************

15.2. XML

     * W3C's XML ****** SGML/XML ******

15.3. HTML

     * *********************

     * The HTML 4.0 *********

15.4. DocBook

     * The DocBook *****************DocBook DTD************

     * DocBook**The Definitive Guide**DocBook DTD *********************._

     * The DocBook Open Repository contains DSSSL stylesheets and other
       resources for people using DocBook

                                ****** A. ******

   ************

   A.1. DocBook book

   A.2. DocBook article

   These examples are not exhaustive-they do not contain all the elements
   that might be desirable to use, particularly in a document's front matter.
   For more examples of DocBook markup, examine the XML source for this and
   other documents available in the Subversion doc repository, or available
   online starting at http://svnweb.FreeBSD.org/doc/.

A.1. DocBook book

   ****** A.1. DocBook book

 <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
         "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

 <book xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:lang="en">

   <info>
     <title>An Example Book</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>foo@example.com</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>

     <abstract>
       <para>If your book has an abstract then it should go here.</para>
     </abstract>
   </info>

   <preface>
     <title>Preface</title>

     <para>Your book may have a preface, in which case it should be placed
       here.</para>
   </preface>

   <chapter>
     <title>My First Chapter</title>

     <para>This is the first chapter in my book.</para>

     <sect1>
       <title>My First Section</title>

       <para>This is the first section in my book.</para>
     </sect1>
   </chapter>
 </book>

A.2. DocBook article

   ****** A.2. DocBook article

 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
         "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">

 <article xmlns="http://docbook.org/ns/docbook"
   xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
   xml:lang="en">

   <info>
     <title>An Example Article</title>

     <author>
       <personname>
         <firstname>Your first name</firstname>
         <surname>Your surname</surname>
       </personname>

       <affiliation>
         <address>
           <email>foo@example.com</email>
         </address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>Copyright string here</holder>
     </copyright>

     <abstract>
       <para>If your article has an abstract then it should go here.</para>
     </abstract>
   </info>

   <sect1>
     <title>My First Section</title>

     <para>This is the first section in my article.</para>

     <sect2>
       <title>My First Sub-Section</title>

       <para>This is the first sub-section in my article.</para>
     </sect2>
   </sect1>
 </article>

                                     ******

  F

   Formal Public Identifier, DOCTYPE ******, ********************* (FPI)
