                    FreeBSD CURaaYENopueCURJ-au(R)N

  FreeBSD CURaaYENop^1-o

   Copyright (c) 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005,
   2006, 2007 DocEng

   .PAA+-zDEGN>>P FreeBSD CURaaYENop^1-o(A^2-oU!GFDP, FreeBSD
   Documentation Project)!A+-z-a-oAI-owDEG^A:m!A^3-L-NOTU.iA:_P:Q!C

   YEN>>CURJCURa(R)NCUR-o(R)eYEN]NOTA!G|p|oP:}(c)luUCURaA
   1/2A:P:-a-o|UP:u^2O,`!AYENHCURI.|YENI"`i-a-oCUR@"C,|nYENICURu"a(YEN]NOTA!GYEN^2^3AECURu"a!B>>^2S:UCURu"a)
   !AYENHCURICURaaYENopue-a-o(c)v|(R)!C

   YEN>>CURaaYENoAU|b-o 1/2Z!A(c)|YEN 1/4S:^1 1/2Z!CYEN
   1/4S:^1|"-a-o^3^1,`!AS:UI.||b^3^1,`|W-oU(R)C,Aa:YEN[uu!y*
   !zYENHS:@ANS:O!C

   Redistribution and use in source (SGML DocBook) and 'compiled'
   forms (SGML, 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 (SGML 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.

     Important: THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD
     DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED
     WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 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.

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

   Table of Contents

   S:C,"YEN

                Shell '-L-YENU:^2AA,^1(Prompts)

                (R)NCURCUR(c)OYENI-a-o 1/2s+-AE.(R)ae

                !yNote!BTip!BImportant!BWarning!BExample!z-a-o^1BYENI

                .PAA

   1 .S: 1/2 *

                1.1 FreeBSD CURaaYENo-a-o^2O|"^3!CURA

                1.2 |bP:}CURuCURS:<<e...

                1.3 S:O:^3tCURWCURa 1/2g

   2 CURu"a

                2.1 YEN^2^3AECURu"a

                             2.1.1 ^3nAAe

                             2.1.2 DTD CURI Entity

                             2.1.3  1/4E|!-ai(Stylesheets)

                2.2 >>^2S:UCURu"a

                             2.2.1 ^3nAAe

   3 SGML Primer

                3.1 A^2CURP:

                3.2 Elements, tags, and attributes

                             3.2.1 For you to do...

                3.3 The DOCTYPE declaration

                             3.3.1 Formal Public Identifiers (FPIs)

                             3.3.2 Alternatives to FPIs

                3.4 Escaping back to SGML

                3.5 uu,N

                             3.5.1 For you to do...

                3.6 Entities

                             3.6.1 General Entities

                             3.6.2 Parameter entities

                             3.6.3 For you to do...

                3.7 Using entities to include files

                             3.7.1 Using general entities to include
                             files

                             3.7.2 Using parameter entities to
                             include files

                             3.7.3 For you to do...

                3.8 Marked sections

                             3.8.1 Marked section keywords

                             3.8.2 For you to do...

                3.9 Conclusion

   4 SGML Markup

                4.1 HTML

                             4.1.1 Formal Public Identifier (FPI)

                             4.1.2 Sectional elements

                             4.1.3 Block elements

                             4.1.4 In-line elements

                             4.1.5 Links

                4.2 DocBook

                             4.2.1 FreeBSD extensions

                             4.2.2 Formal Public Identifier (FPI)

                             4.2.3 Document structure

                             4.2.4 Block elements

                             4.2.5 In-line elements

                             4.2.6 Images

                             4.2.7 Links

   5 * Stylesheets

                5.1 * DSSSL

                5.2 CSS

                             5.2.1 The Web site (HTML documents)

                             5.2.2 The DocBook documents

   6 Structuring documents under doc/

                6.1 The top level, doc/

                6.2 The lang.encoding/ directories

                6.3 Document specific information

                             6.3.1 The Handbook

   7 The Documentation Build Process

                7.1 The FreeBSD Documentation Build Toolset

                7.2 Understanding Makefiles in the Documentation tree

                             7.2.1 Subdirectory Makefiles

                             7.2.2 Documentation Makefiles

                7.3 FreeBSD Documentation Project make includes

                             7.3.1 doc.project.mk

                             7.3.2 doc.subdir.mk

   8 <<O/-oc Website

                8.1 "AE<<e.C,^3AE

                8.2 Build the web pages from scratch

                8.3 |bS:A-a-o-ooP:|o/-aA 3/4^1CURW|w,E-ooP:

                8.4 Ao^1OAAU: 1/4AE

   9 A 1/2A:P:(R)E-a-o+-`"-L-DEGYAD

   10 CURaaYENo-a-o 1/4P: 1/4g.(R)ae

                10.1 Style guide

                             10.1.1 CURjCURp 1/4g

                             10.1.2 AY 1/4g|r

                             10.1.3 AY+-AE

                             10.1.4 Tag .(R)ae

                             10.1.5 -aAAYENO-a-oS:oS:i

                             10.1.6 Nonbreaking space

                10.2 uu:.J-ai

   11 Using sgml-mode with Emacs

   12 YENLCURsCURS:YENU

                12.1 The FreeBSD Documentation Project

                12.2 SGML

                12.3 HTML

                12.4 DocBook

                12.5 The Linux Documentation Project

   A.  1/2d"O

                A.1 DocBook <book>

                A.2 DocBook <article>

                A.3 Producing formatted output

                             A.3.1 "IYENI Jade

   List of Examples

   1. ^3oNOTOA|"O>>!(c)u

   3-1. Using an element (start and end tags)

   3-2. Using an element (start tag only)

   3-3. Elements within elements; <em>

   3-4. Using an element with an attribute

   3-5. Single quotes around attributes

   3-6. .profile, for sh(1) and bash(1) users

   3-7. .cshrc, for csh(1) and tcsh(1) users

   3-8. SGML generic comment

   3-9. Erroneous SGML comments

   3-10. Defining general entities

   3-11. Defining parameter entities

   3-12. Using general entities to include files

   3-13. Using parameter entities to include files

   3-14. Structure of a marked section

   3-15. Using a CDATA marked section

   3-16. Using INCLUDE and IGNORE in marked sections

   3-17. Using a parameter entity to control a marked section

   4-1. Normal HTML document structure

   4-2. <h1>, <h2>, etc.

   4-3. Bad ordering of <hn> elements

   4-4. <p>

   4-5. <blockquote>

   4-6. <ul> and <ol>

   4-7. Definition lists with <dl>

   4-8. <pre>

   4-9. Simple use of <table>

   4-10. Using rowspan

   4-11. Using colspan

   4-12. Using rowspan and colspan together

   4-13. <em> and <strong>

   4-14. <b> and <i>

   4-15. <tt>

   4-16. <big>, <small>, and <font>

   4-17. Using <a href="...">

   4-18. Using <a name="...">

   4-19. Linking to a named part of another document

   4-20. Linking to a named part of the same document

   4-21. Boilerplate <book> with <bookinfo>

   4-22. Boilerplate <article> with <articleinfo>

   4-23. A simple chapter

   4-24. Empty chapters

   4-25. Sections in chapters

   4-26. <para>

   4-27. <blockquote>

   4-28. <warning>

   4-29. <itemizedlist>, <orderedlist>, and <procedure>

   4-30. <programlisting>

   4-31. <co> and <calloutlist>

   4-32. <informaltable>

   4-33. Tables where frame="none"

   4-34. <screen>, <prompt>, and <userinput>

   4-35. <emphasis>

   4-36. Quotations

   4-37. Keys, mouse buttons, and combinations

   4-38. Applications, commands, and options.

   4-39. <filename>

   4-40. <filename> tag with package role

   4-41. <devicename>

   4-42. <hostid> and roles

   4-43. <username>

   4-44. <maketarget> and <makevar>

   4-45. <literal>

   4-46. <replaceable>

   4-47. <errorname>

   4-48. id on chapters and sections

   4-49. <anchor>

   4-50. Using <xref>

   4-51. Using <link>

   4-52. <ulink>

   A-1. DocBook <book>

   A-2. DocBook <article>

   A-3. A`a'<< DocBook NOTDEG HTML (S:^1 3/4a 1/4O|!)

   A-4. A`a'<< DocBook NOTDEG HTML (^3^1,` 1/4O|!)

   A-5. A`a'<< DocBook NOTDEG Postscript(PS) (R)ae|!

   A-6. A`a'<< DocBook NOTDEG PDF (R)ae|!

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

                                S:C,"YEN

Shell '-L-YENU:^2AA,^1(Prompts)

   CURU-aiAAaYENU:YENXCUR@-e+-b,^1>>P root
   -a-o'-L-YENU:^2AA,^1!A|b(c)O|^3-a-oCURaaYENo"OCURlCURCUR.|YENI'-L-YENU:^2AA,^1(prompt)
   !A"O'-L-?o+-z,OYENIth-oO/+-b,^1CUR~^1i!C

             +-b,^1                   '-L-YENU:^2AA,^1(Prompt)        
   'P:^3q+-b,^1                %                                      
   root                        #                                      

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

(R)NCURCUR(c)OYENI-a-o 1/2s+-AE.(R)ae

   CURU-aiNOTDEGYEN>>(R)NCURCUR(c)O"IYENI 1/2s+-AE.(R)aeCURe|!!G

                       YENN-ai.N,q                                           A|"O                   
<<u:YENO                                                   "IYENI ls -a "O|CYENX(c)O|^3-a-oAE(R)    
                                                           *!C                                      
AE|W                                                       *S:i .login AE!C                         
?A^1oCURW.|YENX^2{-a-oDEGT(R)S:                            You have mail.                           
?eCURJ<<u:YENO<<a!A?A^1oCURW.|YENX^2{-a-o^1iA^3CUR-o(R)e!C % su                                     
                                                           Password:                                
nDEGN|O-a-o 1/2uCURWCURaYENU(manual)                       YENH su(1) "OCURA'<<+-b,^1!C             
|bA?"`i+-b,^1(user)!B,s^2O(group)-a-o|W-oU-a-o(R)EO...     YENu|^3 root                             
                                                           CUR~YENiYENHDEGu^3oYENo"AE!C             
>>y(R)d--a-o+-j 1/2O                                       S:A!yYEN^2P:.!z^3o>>oDEGuCUR~|ae!C       
YEN'<<u:YENO(R)E!AYENi'A'<<-a-o^3!YEN-:                    nS:RDEG-L-AE(R) *-a-o,U:!A 1/2D-YEN' rm  
                                                           nS:RDEG-L--a-oAE|W                       
Ao^1OAAU: 1/4AE^3](c)w                                     $HOME                                    
                                                           NOTO<<u:+-b,^1-a-o(R)aYENO/?y(c)O|b^3B!C 

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

!yNote!BTip!BImportant!BWarning!BExample!z-a-o^1BYENI

   YENHCURUCURaa|rNOTO!y-a`.N!z!B!yS:THYEN(c)!z!B!y<<nDEGT(R)S:!z!B!yA:uS:i!z!B!y
   1/2d"O!z-a-o^1BYENI!C

     Note:
     -aiYENU:>>Yn-a`.N-a-o"AEP:u!A"a:CURCURYEN]NOTA+-z>>Yn-a`.N-a-o"AE+-!!A|]NOTDEG^3o"C,"AE+-!YENi-`a.|
     1/4vAAT"`i 3/4THS:@u^2-aG!C

     Tip: '-L-"NYENi-`a^1i+-z|^3YENI(c)IA^2CURAE
     3/4THS:@CURe|!-a-oS:THYEN(c)>>!(c)u!C

     Important:
     -aiYENU:n-SS:O-a`.N-a-o"AE+-!!CCUR@-e"O>>!!AYEN|I.|YEN]NOTA
     3/4THS:@<<u:YENO(R)E>>YnYEN[-a-oABYEN~DEGN 1/4AE!C

     Warning:
     -aiYENU:A:uS:i"AEP:u!ACURn|p|p-aG+-zCUR-L--a`.N<<hYENi-`a
     3/4EP-a-o.lYEN-c-!C^3o"C,.lYEN-c-YENi-`aNOTO^1i+-z(c)IuwAAe^3y|"^1e>>UP:E(R)`!A
     CUR]YENi-`aNOTOuL-ak|op-a-o.l(R)`!A"O|pCUR@(R)E^2"(c)?|OS:RDEG-L-<<nAE(R)
     *...!C

   Example 1. ^3oNOTOA|"O>>!(c)u

   ^3oNOTOA|"O>>!(c)u|OCURw!A^3q+-`YEN]S:tA^3?i'`-a-o<<u:YENO
   1/2d"O!A(c)IAAaYENU:NOTY"C,-S(c)wDEGES:@(c)OYENi-`auoYENI-a-ou^2-aG!C

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

.PAA

   |b|^1n.PAA Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn,
   Christopher Maden ^3o"C,CURH-a-o"oS:U>>P 3/4\AA-a-a`i'A-o
   1/2Z!A"A'-L-"N^3\|hA:_P:Q-a-o 1/4i 1/2Z.N"-L->>Puu 1/2 *!C

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

                          Chapter 1 .S: 1/2 *

   AAw-aiDEGN>>P FreeBSD CURaaYENop^1-o!C-ou<<uAu"q
   1/2eP:q-a-oCURaaYENo^1i FreeBSD -a-o|"YEN\"O>>!CURQCURA<<n!A |O
   FreeBSD CURaaYENop^1-o(YENHCURUNOTOYENH FDP "OYENN-ai FreeBSD
   Documentation Project -a-oAY 1/4g) <<h>>P^3o"C,CURaaYENo 1/4P:
   1/4g!BS:o.s(R)S:(R)S:NOTUAo:!A|]|^1+-z-a-oAI-owDEG^A:m^3-L-NOTOCURQCURAA:_P:Q-a-o!C

   YEN>>CURaaYENo^3IYENDn-a-oYENO/-a-o!A'NNOTO^2M.!S:iP:D+-z!G!yFDP
   -a-oNOT[-oc|^3th"C,!z!B!y|p|o 1/4P: 1/4g"A'-L-YENaeCURaaYENou^1
   FDP!z!B !y|p|o|^3(R)A:^1BYENICURu"a"O"oS:U 1/4P: 1/2Z!z!C

   
 S:UIAAw-ai"CO 1/4o:CURss-a-oS:OCURh"OYEN[CURJ FDP |ae|C!CFDP
   "ACUR-L-(c)w"CCUReYEN^2P:.YENaeYENX|hCURO:
   1/2ZP:q!ACUR~-`aYEN[CURJ!C +-zDEGssCUR@P:.nS:@-a-o'NNOTOq 3/4\
   FreeBSD documentation project P:l>> 1/4 1/2 * 3/4A !C

   AA-aS:^1YEN>>YEN-:CURaaYENo!A+-z+-N.|!G

     * AA,N|^3th"C,CURaaYENoNOTOYENN FDP (c)O-ouAA@-a-o!C

     * YENiYENHNOTYA' FDP (c)O-ouAA@-a-o SGML `i(c)lCURaaYENo!C

     * -a 3/4^1D|p|o"O^1iCURaaYENoS:@ *S:i!C

     * -a 3/4^1D|p|oS:e 1/2Z|UCURv-a-o
       *S:i^3!YEN-:!A"A^3I<<aYEN?|!P:iCURJ FreeBSD CURaaYENoCUR-o!C

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

1.1 FreeBSD CURaaYENo-a-o^2O|"^3!CURA

   FDP A`|@t^3d FreeBSD -a-o 4 -oO/AthS:O-a-oCURaaYENo!G

   1/2uCURWCURaYENU(manual)

           ^CURaa-a(c)-a-o"t^2I manual "ACUR-L-NOTOYENN FDP (c)O
           1/4P: 1/4g-a-o!A|]NOTDEGYEN|INOTOA:Y(c)o base system
           -a-o^3!YEN-:!C uM|O!AFDP YENiYENH(CUR]'?^3o>>oDEGu^1L)
           *S:i^3o"C,CURaaYENo!A"OAAy^3o"C,CURaaYENo
           1/4g+-oS:o^2M.!!ANOTAE|U:NOTODEGEYEN??u>>~-a-o|aCURe!C

           A 1/2A:P:^1IP:CURt^3d+-N"t^2I-a-o 1/2uCURWCURaYENUA
           1/2A:P:NOTDEGCUR-L-|P-a-o>>y"YEN!C
           ^3o"C,A:P:YEN>>^3-L-YENN FDP -ouAA@!C

   FAQ

           FAQ YENDnNOTO|NOTP:DEG|b|U 1/2 * 3/4A(c)I newsgroup
           .|+-`DEGY"`i(c)I|^3YENi-`a.|DEGY"`i-a-o FreeBSD
           NOTUAo:DEGYAD>>Pu-a(R) * !C
           (A^2^3aeA?!A'NNOTO!yDEGYu-aP:DEG!z(R)ae|!)
           ^3q+-`.|A\|b^3o,I+--a-oDEGYu-a(R)ae|!!ACUR-L-.|(c)nCURO-ao/-a-o,O^2OCUR-o(R)e!C

   "IYENICURaYENU(Handbook)

           "IYENICURaYENUYENDnNOTOu^1 FreeBSD
           "IYENI-aI'-L-"N,O-oE-a-o 1/2uCURWDEGN|O,e(R)AE!C

   Web site

           FreeBSD YENDn|UP:uCURP:^2D-CURe+--a-o WWW
           ^3!YEN-:!AAAw-ai^3}^3} http://www.FreeBSD.org/
           YENHCURI^3\|h"a:YENL mirror
           -,!C^3o-oo-,NOTO^3\|hCURH^2A:CUR@|,+-uA:^2 FreeBSD
           -a-o|aCURe!C

   ^3oYEN|OCURaaYENo^2O|"^3!CURA^3-L-YENi^3z^1L FreeBSD CVS tree
   "O"u+-o!CCUR]'NNOTO>>!!A^3o"C,CURaaYENo-a-o
   *S:iDEGO?y^1i(c)oYENo|oCURH^3-L-NOTOCUR 1/2P:}-a-o!A |OYENBuL 1/2
   *NOTO 1/2O:^3-L-YENiYENHYENI^1^3NOTO CSup, CVSup (c)I CTM
   +-NCURaaYENo"uYENX"O(checkout)"A(c)n|b|UCURv 3/4-:
   3/4^1CURWDEGu^3AEYEN-:(c)IDEGAEYEN>>DEGN|OuYENYENI^3~!C

   |^1YEN~!A^3\|hCURH.| 1/4g"C,+-D- 3/4C,CURaaYENo(c)I-ouAA@|^3Ao:
   FreeBSD
   CUR-o(R)e-a-o-oo-,!C(YS:@-aI|P.N-a-o,U:)"a:CURCUR|^3"C,,e(R)AE.|<<O|s|b
   FreeBSD YEN?|! CVS repository
   CUR-o!C|O"a:YENL-a-oCURaaYENo!AYENi-`aS:@-aICUR-L-S:AE+-ae^3Q(c)n|b
   FreeBSD repository CUR-o|OYENt|sYENL^3B!C A`CURS:!AFDP
   .|-oECURO'-L-"N^3o"C,CURaaYENo-a-o^3su^2!C

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

1.2 |bP:}CURuCURS:<<e...

   YEN>>CURaaDEG^2^3]+-zCURw,gAA,N!G

     * |p|o+-q FreeBSD CVS repository S:o.s|UCURv^1q,-L-CURW-a-o
       FreeBSD CURaaYENo^3!YEN-:(YENH CVS (c)I CSup (c)I CVSup
       (c)INOTO CTM) (c)INOTOYENI CVSup "OCURU,u: checked-out
       -a-oDEGAEYEN>>

     * |p|oYENI FreeBSD Ports (R)MYENo-oTH^2z 3/4-:"i(c)I pkg_add(1)
       "OCURU,u:!B|w,E^3nAAe!C

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

1.3 S:O:^3tCURWCURa 1/2g

   Y.QYENy|U|ae,O,ONOTY!A"A|^3<<HCURssYENiYENHS:@+-o"`i!A"-o>>o'N.OCURU+-"BAEJS:a!C

    1. |w,E textproc/docproj ^3oO^2O|X<<NOT port(meta-port)!C

 # cd /usr/ports/textproc/docproj
 # make JADETEX=no install

    2. CURU,u: FreeBSD doc tree "`iYEN>> 3/4-:CURW!G uL 1/2 *NOTOYENI
       CSup (c)I CVSup -a-o checkout  1/4O|!!A (c)INOTO 1/2AE>>sS:^1
       3/4a-a-o CVS repository "`iYEN>> 3/4-:CURW^3-L-YENiYENH!C

       Y.Q|bYEN>> 3/4-:CURWYENuP:]^3IS:C<< *-a-o CVS repository
       'N|n!A"-o>>oYEN^2P:.n checkout YENX doc/share YENHCURI
       doc/en_US.ISO8859-1/share ^3o"aOYENO/?yCUR~|ae!C

 % cvs checkout doc/share
 % cvs checkout doc/en_US.ISO8859-1/share

       Yuw-oD--aAAP:!AU-oaYENiYENH-a-o,U:!A"-oYENiYENHS:a(c)O|^3>>y"t-a-o
       doc ^3-L- check out YENX"O!G

 % cvs checkout doc

    3. YENi"I>>Yn+-q repository CURCUR checkout YENX"OS:A.Q
       *S:iNOTYYEN-:^2{|^3-a-o(R)NA:y(c)ICURaa^3^1CUR-o(R)e!C
       YYEN'-oa 1/4P:
       1/4g.s(R)N(c)I.sCURaa^3^1-a-o,U:!AYENiYENHDEGN|O^2{|^3-a-o^3!CURAS:@NOTDEG^1e"O"ODEGu!C

       A|"O"O>>!!AY.Q 1/4g 1/2g.sCURaa^3^1!ACUR-o(R)eNOTO|^3Ao:|b
       FreeBSD >>P Windows 2000 CURS:P:!<<O/YENss VPN ^3s 1/2u!A
       "-o>>oYENiYENH.OAth|u:CURU+-^3o 1/4E-a-oS:@-ak!G

         1. Check out articles YENO/?y!G

 % cvs checkout doc/en_US.ISO8859-1/articles

         2. 1/2AE>>s^2{|^3-a-oCURaa^3^1S:@NOTDEG
            1/2dYEN>>!C|b^3oO"OCURlCURCUR!A+-zYEN'-oa"M(c)wS:a.sCURaa^3^1(c)n|b
            vpn-w2k -a-oYENO/?yCURU!C

 % cd doc/en_US.ISO8859-1/articles
 % cp -R committers-guide vpn-w2k

       YNOTOn *S:i^2{|^3CURaa^3^1!A^1^3NOTO FAQ(A\|b
       doc/en_US.ISO8859-1/books/faq) !A"-o>>on+-q repository
       CURCUR"uYENX"O(check out)!G

 % cvs checkout doc/en_US.ISO8859-1/books/faq

    4. YENH 1/2s?e 3/4^1"O 1/2s 1/4g .sgml AE!C

    5. YENH lint .i>>^2S:UDEGN
       1/4AE!A"OS:O:^3tAE'uCURaaYENou^2-ocCURI^3su^2|^3uL?u>>~!A
       YENHCURU^3oO<<u:YENO!A^1e>>UCURWCUR-L-.|P:i|ae-O(R)E-a-o
       1/2s(R)N^1Lu{!AYENuNOTOYENy'u,OCURaaYENo|^3uL?u>>~!C

 % make lint

       .i 1/2s(R)N-a-oCUR@CURA^3-L-'N-ou:(R)E!A^3o(R)ES:AYENiYENHYENI
       FORMATS AAU:
       1/4AE"O<<u:(c)w^2-L-YENI-a-o(R)ae|!NOTDEGthCUR@-oO/!C
       YENO/<<eCURa:'(c)-a-o(R)ae|!|@|^3!G html, html-split, txt, ps,
       pdf, rtf !C
       (c)OCURa:'(c)-a-o(R)ae|!|C-ai^3I.s-a(c)!AYENiDEGN|O
       doc/share/mk/doc.docbook.mk AE!C  1/2D-DEGO+-o!G
       |b^3aeCUR@<<u:YENOCURCUR!AYn|P(R)E^2-L-YENI|h-oO/(R)ae|!-a-o,U:!AA^3"IYENICURTH,^1(quotes)"O+-N^3o"C,(R)ae|!NOTADEG_"O!C

       A|"O"O>>!!AYYENun^2-L-YENI html (R)ae|!'N|n!A"-o>>o'NYEN'!G

 % make FORMATS=html

       |yYS:AE+-ae|^3 html CURI txt (R)ae|!-a-o,U:!A
       S:AYENi-`anYEN'"a|, make(1) <<u:YENOCUR~-`aS:^1|"!G

 % make FORMATS=html
 % make FORMATS=txt

       "a:^1e!ACUR]YENiYENHYENI^3aeCUR@<<u:YENO"OS:^1|"!G

 % make FORMATS="html txt"

    6. ^3I<<a!AYENH send-pr(1) "O'-L-YENae *S:i-a-o^3!YEN-:!C

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

                            Chapter 2 CURu"a

   FDP "IYENICUR@DEGiCURu"a"O"oS:U-oTH^2z FreeBSD
   CURaaYENo!BA`a'<<CURaaYENo(R)ae|!uYENuYEN!C |]|^1!AYnP:i|ae FDP
   CURuS:@-a-o,U:!AYEN^2P:.n 3/4C,.|^3o"C,CURu"aCUR~|ae!C

   ^3o"C,CURu"a^3-L-YENiYENHYENI Ports (c)I Packages
   "O|w,E!AYENH,`NOTU^3\|h|w,E-a-oCURuCURO!C

   +-zYEN^2P:.|w,E^3o"C,CURu"a!ACUR~-`a"IYENI+-uCURU"O|U^3^1,`.|CURP:^2D-"`i-a-o"OCURl!C
   ^3o"C,CURu"a-a-oYENI-ak!A.||b<<aA:oNOTUAo:^3^1,` 1/2I"`i!C

     <<O/A:^3|w,E textproc/docproj: ,ECURF textproc/docproj
     YENiYENHS:oNOTU(R)ENOTUCURO!AYEN|NOTOO ^2O|X<<NOT-a-o
     port(meta-port)!AYEN>>""A<<D^3nAAe!AYENuNOTO+-NCUR@"C,+-`YENICURu"a^2O|XDEG_"O|OCURw!C
     ,ECURF^3oO port
     CURS:<<a!A!yA^3,O!z'N.||UDEGECURU,u:!B|w,EYEN>>^3^1(c)O.|CURP:^2D-"`i-a-oCURu"aCURF!C
     Yn^3B^2zCURCURCURaa-a-o,U:!A<<O/A:^3|A,E chinese/docproj
     .|CURn,u|n!C

     |b^3o"C, packages .iCURCUR!AS:AYENi-`a.|>>Yn"IYENI JadeTeX ^3oO
     macro ^3](c)w!A CUR@YEN^1?i 3/4U:"IYENI,O macro
     -a-o,U:!AYEN|.|+-uuUYENh,E TeX!CYENN(c)o TeX
     -oaNOTOOAEZCURj-a-o(R)MYENo!A DEG-L-<<DS:A>>Yn?eYENX Postscript
     (c)I PDF (R)ae|!!AS:_<<h'NCUR-L-YEN^2,ECURF!C

     (c)OYENH 1/2D-|O 1/4{NOTOS:_n,`NOTU
     1/2sA:P:(R)EP:!!Buw-oD--aAAP:!!AYENHS:P(c)wnCUR-L-n,E JadeTeX
     (YENHCURI TeX) CURF!CYnCUR@"O:,EDEG_"O-a-o,U:!G

 # make JADETEX=yes install

     (c)INOTO!ACUR-L-,E-a-o,U:!G

 # make JADETEX=no install

     (c)I-aI!ACUR]YENiYENH?i 3/4U: textproc/docproj-jadetex (c)INOTO
     textproc/docproj-nojadetex ^3o"aOCURS:CUR@"O,E!A
     YEN|I^3-L-NOTOCURw"AEYENy^3](c)w JADETEX AAU: 1/4AE-a-o slave
     ports!A ^3-L-CUR@ 1/4E.|,E docproj (R)tS:OP:E|b(c)o|^3"S|^3
     JadeTeX |OCURw!C  1/2D--a`.N!GYYENun?eYENX HTML (c)I ASCII
     (R)ae|!CURaaYENo!A"-o'NCUR-L-YENI,E JadeTeX!A |OYn?eYENX
     PostScript!BPDF (R)ae|!!A'N>>Yn,E TeX CUR~|ae!C

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

2.1 YEN^2^3AECURu"a

  2.1.1 ^3nAAe

   ^3o"C,^3-L-NOTO|bP:i|ae FreeeBSD
   CURaaYENop^1-o(R)E(c)O.|>>YnYENICURW-a-oCURu"au{|!!A
   |OYENBYENiYENHYENI"OA`a'<<CURaaYENoNOTDEG HTML!Bplain textYENHCURI
   RTF (R)ae|!!C^3o"C,NOTUAo:(R)MYENo|b textproc/docproj
   ^3-L-CURw,gYENth^3!|NOT?yCURF!C

   Jade (textproc/jade)

           DSSSL ^3W(R)ae-a-o^1eS:@u{|!!AYENiYENI"OS:a
           1/4D-DEGO>>y"YEN-a-oCURaaYENo(marked
           up)A`a'<<NOTDEG"a:YENL(R)ae|!!A^1^3NOTO!GHTML CURI TeX!C

   Tidy (www/tidy)

           HTML !S:pretty printer!"!AYENiYENI"OS:a|UDEGE^2-L-YENI-a-o
           HTML CUR-o(R)e 3/4a^2z+-oS:o(c)o:
           3/4\AA-a!BYENH<<KCURe<<a-ouAA@!C

   Links (www/links)

           CURaa|r 3/4THS:@ 1/4O|!-a-o WWW AsA:y
           3/4^1(browser)YENiYENHS:a HTML AEA`aNOTDEG plain text
           (R)ae|!!C

   peps (graphics/peps)

           CURaaYENoCURCUR|^3"C,^1INOTO|s|" EPS
           (R)ae|!-a-o!A^3o"C,YEN^2P:.nA`aNOTDEG PNG (R)ae|!!A
           CUR~-`aAAyCUR@-eAsA:y 3/4^1YENiYENHYEN?+-`AE[NOTY!C

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

  2.1.2 DTD CURI Entity

   YENN(c)o FDP |^3YENI"`i^3\|h DTD ,o
   Entity!A|]|^1|bP:}CURu<<e!An,ECURW^3o"C,CUR~|ae!C

   HTML DTD (textproc/html)

           HTML NOTOYENI(c)o WWW -a-o 1/4D-DEGO>>y"YEN!AYENBCUR]NOTO
           FreeBSD -ooP:(c)O"IYENI-a-o(R)ae|!!C

   DocBook DTD (textproc/docbook)

           DocBook NOTO+-M-auYENI"O>>sS:@S:TH^3NCURaaYENo-a-o
           1/4D-YENU:>>y"YEN-a(c)YEN>>!A FreeBSD
           YENth^3!CURaaYENo^3-L-NOTOYENH DocBook (c)O 1/4g|"-a-o!C

   ISO 8879 entities (textproc/iso8879)

           |b ISO 8879:1986 CURS:CURCUR|^3 19 O entity ^3Q^3\|h DTD
           (c)OCURjP:q"IYENI!A YEN]NOTACURF 1/4AE
           3/4C,^2AA,^1!B(c)OCURB|rYENA^2AA,^1(|y<<uuYENu,`^2AA,^1CUR]NOTO)YENHCURIS:AEA
           3/4^2AA,^1!C

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

  2.1.3  1/4E|!-ai(Stylesheets)

   ^3o"C,
   1/4E|!-ai^3-L-NOTOYENI"OA`a'<<!B<<+-AECURaaYENo-a-o?A^1oAAaYENU:!B|C|LuYEN(R)A:-aG^3B^2z

   Modular DocBook  1/4E|!-ai (textproc/dsssl-docbook-modular)

           Modular DocBook  1/4E|!-ai!ANOTOYENI"OS:a DocBook -a-o
           1/4D-DEGO>>y"YENCURaaYENoA`a'<<NOTDEG"a:YENL(R)ae|!!A^1^3NOTO!G
           HTML (c)I RTF!C

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

2.2 >>^2S:UCURu"a

   CUR-L-CUR@(c)w+-o,ECURU|C-a-oCURu"aCUR~|ae!A|yNOTO!A,ECURFCURS:<<a.|S:o(R)e(c)o:P:i|ae|UP:uCURuS:@!A
   |OYENBYENi?eYENX-a-o(R)ae|!CUR]S:o"a 1/4u(c)E!C

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

  2.2.1 ^3nAAe

   JadeTeX CURI teTeX (print/jadetex CURI print/teTeX)

           Jade >>P teTeX YENiYENI"OS:a DocBook
           (R)ae|!CURaaYENoA`aNOTDEG DVI, Postscript CURI PDF
           (R)ae|!!C|w,E(R)E 1/2D-DEGO+-oYEN[CURW JadeTeX ^3oO
           macro!A^3o 1/4ECUR~.|P:P:<<K,ECURW^3o"aO(R)MYENo!C

           YuL.NS:aCURaaYENoA`a'<<S:o|h(R)ae|!-a-o,U:(A|"O!GYENun
           HTML, plain text, RTF ^3o"C,(R)ae|!'NDEG-:-a-o,U:)
           !A"-o>>o'NCUR-L-YENI,E JadeTeX >>P teTeX!C
           |p|^1CUR@"OYENiNOTUCURUCUR@"C,-a-o
           1/2sA:P:(R)EP:!!B|w,E-aAAP:!!A |]NOTDEG teTeX
           CURjNOTun|U:CURO: 30MB -aAAP:!!C

             Important: Y"M(c)wn,E JadeTeX YENHCURI teTeX
             -a-o,U:!A"-o>>o|b,ES:^1 JadeTeX CURS:<<a!A
             nDEGO+-o^3](c)w teTeX CUR~|ae!C
             print/jadetex/pkg-message
             CUR-o|^3,O^2OCURP:^2D-NOTUAo:"BAEJ!C

   Emacs (c)I XEmacs (editors/emacs (c)I editors/xemacs)

           ^3o"a-aI 1/2s?e 3/4^1^3-L-"a|^3^3B^2z SGML DTD 
           1/4D-DEGOCURaaYENo-a-o-S(R)i 1/4O|!!C ,O
           1/4O|!'-L-"NCUR@"C,<<u:YENO!A"OA^2CURAE(c)O>>Y-a-oYEN'|r|,
           1/4AE!A|OYENBYENiYENH'iCURO:YENi-`auoYENI-a-o?u>>~!C

           CUR-L-^1L!A^3o"C, 1/2s?e
           3/4^1"ACUR-L-NOTOYEN^2^3AE-a-o!FYENo|oCURaa|r 1/2s?e
           3/4^1^3-L-YENiYENHYENI"O 1/2s?e
           1/4D-DEGO>>y"YENCURaaYENo!C
           CUR-L-^1L!AS:AYENiYENH^3z^1LAth|u:CURWz^3o 1/4E-a-o 1/2s?e
           3/4^1!A"OAAy^3o"C,Ac-o 3/4S:@.~S:o>>'AP|^3(R)A:^2v"C,!C

   Y|^3+-AAE"a:YENL|nYENI-a-o^3B^2z SGML CURaaYENou{|!!A
   1/2D-"O<<HAAy Documentation Engineering Team <doceng@FreeBSD.org>
   -a 3/4^1D!A |p|^1CUR@"O!A,O^3nAAe'N.||CCURJ^3o,ICURP:^2D-CURF!C

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

                         Chapter 3 SGML Primer

   FDP CURaaYENo'XYENG^3-L-NOTOYENH SGML NOTUAo:u{|!
   1/4g-a-o!CYEN>>^3^1.|CURP:^2D- SGML NOTOCURDEG>>o!B |p|o
   3/4\AA-a!B^2z,N^3o"C, SGML `i
   1/2Z!AYENHCURIYEN>>CURaaYENoCURCUR(c)O^1BYENI-a-o|UP:u SGML
   S:THYEN(c)!C

   YEN>>,`^3!CURAAEF.P+-Ouo"O|U Mark Galassi -a-o^3o 1/2g Get Going
   With DocBook!C

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

3.1 A^2CURP:

   Way back when, electronic text was simple to deal with.
   Admittedly, you had to know which character set your document was
   written in (ASCII, EBCDIC, or one of a number of others) 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. Once you have text in a
   machine-usable format, you expect machines to be able to use it
   and manipulate it intelligently. You would like to indicate that
   certain phrases should be emphasized, or added to a glossary, or
   be hyperlinks. You might want filenames to be shown in a
   !S:typewriter!" style font for viewing on screen, but as
   !S: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. Your computer would read in 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 our computers require
   some assistance before they can meaningfully process our text.

   More precisely, they need help identifying what is what. You or I
   can look at

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

 % rm /tmp/foo

   and easily 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.

   !S:Markup!" is commonly used to describe !S:adding value!" or
   !S: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!X!Xafter 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 (i.e., 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>

   As you can see, the markup is clearly separate from the content.

   Obviously, if you are going to use markup you need to define what
   your markup means, and how it should be interpreted. You will need
   a markup language that you can follow when marking up your
   documents.

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

   This is exactly what the Standard Generalized Markup Language
   (SGML) is. Many markup languages have been written in SGML,
   including the two most used by the FDP, HTML and DocBook.

   Each language definition is more properly called a Document Type
   Definition (DTD). The DTD specifies the name of the elements that
   can be used, what order they appear in (and whether some markup
   can be used inside other markup) and related information. A DTD is
   sometimes referred to as an application of SGML.

   A DTD 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 SGML parser which reads in both the
   DTD and a document which claims to conform to the DTD. The parser
   can then confirm whether or not all the elements required by the
   DTD are in the document in the right order, and whether there are
   any errors in the markup. This is normally referred to as
   !S:validating the document!".

     Note: This processing simply confirms that the choice of
     elements, their ordering, and so on, conforms to that listed in
     the DTD. It does not check that you have used appropriate markup
     for the content. If you tried to mark up all the filenames in
     your document as function names, the parser would not flag this
     as an error (assuming, of course, that your DTD defines elements
     for filenames and functions, and that they are allowed to appear
     in the same place).

   It is likely that most of your contributions to the Documentation
   Project will consist of content marked up in either HTML or
   DocBook, rather than alterations to the DTDs. For this reason this
   book will not touch on how to write a DTD.

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

3.2 Elements, tags, and attributes

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

   Your 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 !S: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.

   You might like to think of this as !S:chunking!" content. At the
   very top level you have one chunk, the book. Look a little deeper,
   and you have more chunks, the individual chapters. These are
   chunked further into paragraphs, footnotes, character names, and
   so on.

   Notice how you can make this differentiation between different
   elements of the content without resorting to any SGML terms. It
   really is surprisingly straightforward. You could do this 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 SGML (HTML, 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 DTD 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>.

   Example 3-1. Using an element (start and end tags)

   HTML has an element for indicating that the content enclosed by
   the element is a paragraph, called p. This element has both start
   and end tags.

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

   Not all elements require an end tag. Some elements have no
   content. For example, in HTML you can indicate that you want a
   horizontal line to appear in the document. Obviously, this line
   has no content, so just the start tag is required for this
   element.

   Example 3-2. Using an element (start tag only)

   HTML has an element for indicating a horizontal rule, called hr.
   This element does not wrap content, so only has a start tag.

 <p>This is a paragraph.</p>

 <hr>

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

   If it is not obvious by now, 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.

   Example 3-3. Elements within elements; <em>

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

   The DTD will specify the rules detailing which elements can
   contain other elements, and exactly what they can contain.

     Important: 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 end.

     When this document (or anyone else knowledgeable about SGML)
     refers to !S:the <p> tag!" they mean the literal text consisting
     of the three characters <, p, and >. But the phrase !S: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 sufficiently recent versions of HTML, the <p> element has an
   attribute called align, which suggests an alignment
   (justification) for the paragraph to the program displaying the
   HTML.

   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.

   Example 3-4. Using an element with an attribute

 <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 will only take specific values, such as left or
   justify. Others will allow you to enter anything you want. If you
   need to include quotes (") within an attribute then use single
   quotes around the attribute value.

   Example 3-5. Single quotes around attributes

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

   Sometimes you do not need to use quotes around attribute values at
   all. However, the rules for doing this are subtle, and it is far
   simpler just to always quote your attribute values.

   The information on attributes, elements, and tags is stored in
   SGML catalogs. The various Documentation Project tools use these
   catalog files to validate your work. The tools in textproc/docproj
   include a variety of SGML catalog files. The FreeBSD Documentation
   Project includes its own set of catalog files. Your tools need to
   know about both sorts of catalog files.

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

  3.2.1 For you to do...

   In order to run the examples in this document you will need to
   install some software on your system and ensure that an
   environment variable is set correctly.

    1. Download and install textproc/docproj from the FreeBSD ports
       system. This is a meta-port that should download and install
       all of the programs and supporting files that are used by the
       Documentation Project.

    2. Add lines to your shell startup files to set
       SGML_CATALOG_FILES. (If you are not working on the English
       version of the documentation, you will want to substitute the
       correct directory for your language.)

       Example 3-6. .profile, for sh(1) and bash(1) users

 SGML_ROOT=/usr/local/share/sgml    
 SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
 SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES
 export SGML_CATALOG_FILES

       Example 3-7. .cshrc, for csh(1) and tcsh(1) users

 setenv SGML_ROOT /usr/local/share/sgml
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/share/sgml/catalog:$SGML_CATALOG_FILES
 setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/sgml/catalog:$SGML_CATALOG_FILES

       Then either log out, and log back in again, or run those
       commands from the command line to set the variable values.

    1. Create example.sgml, and enter the following text:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

 <html>
   <head>            
     <title>An example HTML 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 SGML parser.

       Part of textproc/docproj is the nsgmls validating parser.
       Normally, nsgmls reads in a document marked up according to an
       SGML DTD and returns a copy of the document's Element
       Structure Information Set (ESIS, but that is not important
       right now).

       However, when nsgmls is given the -s parameter, nsgmls will
       suppress its normal output, and just print error messages.
       This makes it a useful way to check to see if your document is
       valid or not.

       Use nsgmls to check that your document is valid:

 % nsgmls -s example.sgml

       As you will see, nsgmls returns without displaying any output.
       This means that your document validated successfully.

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

 % nsgmls -s example.sgml
 nsgmls:example.sgml:5:4:E: character data is not allowed here
 nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished

       The error output from nsgmls is organized into colon-separated
       groups, or columns.

       Column                         Meaning                         
       1      The name of the program generating the error. This will 
              always be nsgmls.                                       
       2      The name of the file that contains the error.           
       3      Line number where the error appears.                    
       4      Column number where the error appears.                  
              A one letter code indicating the nature of the message. 
              I indicates an informational message, W is for          
       5      warnings, and E is for errors[a], and X is for          
              cross-references. As you can see, these messages are    
              errors.                                                 
       6      The text of the error message.                          
       Notes: 
       a. It is not always the fifth column either. nsgmls -sv
       displays nsgmls:I: SP version "1.3" (depending on the
       installed version). As you can see, this is an informational
       message.

       Simply omitting the <title> tags has generated 2 different
       errors.

       The first error indicates that content (in this case,
       characters, rather than the start tag for an element) has
       occurred where the SGML parser was expecting something else.
       In this case, the parser was expecting to see one of the start
       tags for elements that are valid inside <head> (such as
       <title>).

       The second error is because <head> elements must contain a
       <title> element. Because it does not nsgmls considers that the
       element has not been properly finished. However, the closing
       tag indicates that the element has been closed before it has
       been finished.

    4. Put the title element back in.

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

3.3 The DOCTYPE declaration

   The beginning of each document that you write must specify the
   name of the DTD that the document conforms to. This is so that
   SGML parsers can determine the DTD and ensure that the document
   does conform to it.

   This information is generally expressed on one line, in the
   DOCTYPE declaration.

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

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">

   That line contains a number of different components.

   <!

           Is the indicator that indicates that this is an SGML
           declaration. This line is declaring the document type.

   DOCTYPE

           Shows that this is an SGML declaration for the document
           type.

   html

           Names the first element that will appear in the document.

   PUBLIC "-//W3C//DTD HTML 4.0//EN"

           Lists the Formal Public Identifier (FPI) for the DTD that
           this document conforms to. Your SGML parser will use this
           to find the correct DTD when processing this document.

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

   >

           Returns to the document.

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

  3.3.1 Formal Public Identifiers (FPIs)

     Note: You do not need to know this, but it is useful background,
     and might help you debug problems when your SGML processor can
     not locate the DTD you are using.

   FPIs must follow a specific syntax. This syntax is as follows:

 "Owner//Keyword Description//Language"

   Owner

           This indicates the owner of the FPI.

           If this string starts with !S:ISO!" then this is an ISO
           owned 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 ISO number for the SGML standard.

           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 + it identifies it as being
           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. In addition, 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. And as you can see, 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 SGML content (text and tags).

   Description

           Any description you want to supply for the contents of
           this file. This may include version numbers or any short
           text that is meaningful to you and unique for the SGML
           system.

   Language

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

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

    3.3.1.1 catalog files

   If you use the syntax above and process this document using an
   SGML processor, the processor will need to have some way of
   turning the FPI into the name of the file on your computer that
   contains the DTD.

   In order to do this it can use a catalog file. 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 HTML 4.0//EN"             "4.0/strict.dtd"

   The SGML processor would know to look up the DTD from strict.dtd
   in the 4.0 subdirectory of whichever directory held the catalog
   file that contained that line.

   Look at the contents of /usr/local/share/sgml/html/catalog. This
   is the catalog file for the HTML DTDs that will have been
   installed as part of the textproc/docproj port.

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

    3.3.1.2 SGML_CATALOG_FILES

   In order to locate a catalog file, your SGML processor will need
   to know where to look. Many of them feature command line
   parameters for specifying the path to one or more catalogs.

   In addition, you can set SGML_CATALOG_FILES to point to the files.
   This environment variable should consist of a colon-separated list
   of catalog files (including their full path).

   Typically, you will want to include the following files:

     * /usr/local/share/sgml/docbook/4.1/catalog

     * /usr/local/share/sgml/html/catalog

     * /usr/local/share/sgml/iso8879/catalog

     * /usr/local/share/sgml/jade/catalog

   You should already have done this.

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

  3.3.2 Alternatives to FPIs

   Instead of using an FPI to indicate the DTD that the document
   conforms to (and therefore, which file on the system contains the
   DTD) you can explicitly specify the name of the file.

   The syntax for this is slightly different:

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

   The SYSTEM keyword indicates that the SGML 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. You do not
   want to have to ship a copy of the DTD around with your document,
   and if you used the SYSTEM identifier then everyone would need to
   keep their DTDs in the same place.

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

3.4 Escaping back to SGML

   Earlier in this primer I said that SGML is only used when writing
   a DTD. This is not strictly true. There is certain SGML syntax
   that you will want to be able to use within your documents. For
   example, comments can be included in your document, and will be
   ignored by the parser. Comments are entered using SGML syntax.
   Other uses for SGML syntax in your document will be shown later
   too.

   Obviously, you need some way of indicating to the SGML processor
   that the following content is not elements within the document,
   but is SGML that the parser should act upon.

   These sections are marked by <! ... > in your document. Everything
   between these delimiters is SGML syntax as you might find within a
   DTD.

   As you may just have realized, the DOCTYPE declaration is an
   example of SGML syntax that you need to include in your
   document...

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

3.5 uu,N

   Comments are an SGML construction, and are normally only valid
   inside a DTD. However, as Section 3.4 shows, it is possible to use
   SGML syntax within your document.

   The delimiter for SGML comments is the string !S:--!". The first
   occurrence of this string opens a comment, and the second closes
   it.

   Example 3-8. SGML generic comment

 <!-- 'u,Ouu,N -->

 <!-- ^3oNOTOuu,N -->

 <!-- ^3oCUR]NOTOuu,N    -->

 <!-- n 1/4g|h|aeuu,N-a-o,U:!A
      ^3oNOTO"a:CURCURCURS:CUR@-a-oCURe|! -->

 <!-- n 1/4g|h|aeuu,N!A   --
   -- CUR]YENiYENH^3o 1/4ECURlYENI -->

   If you have used HTML before you may have been shown different
   rules for comments. In particular, you may think that the string
   <!-- opens a comment, and it is only closed by -->.

   This is not the case. A lot of web browsers have broken HTML
   parsers, and will accept that as valid. However, the SGML parsers
   used by the Documentation Project are much stricter, and will
   reject documents that make that error.

   Example 3-9. Erroneous SGML comments

 <!-- This is in the comment --

      THIS IS OUTSIDE THE COMMENT!

   -- back inside the comment -->

   The SGML parser will treat this as though it were actually:

 <!THIS IS OUTSIDE THE COMMENT>

   This is not valid SGML, and may give confusing error messages.

 <!--------------- This is a very bad idea --------------->

   As the example suggests, do not write comments like that.

 <!--===================================================-->

   That is a (slightly) better approach, but it still potentially
   confusing to people new to SGML.

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

  3.5.1 For you to do...

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

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

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

3.6 Entities

   Entities are a mechanism for assigning names to chunks of content.
   As an SGML parser processes your 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 your SGML documents. It is also the only way to include
   one marked up file inside another using SGML.

   There are two types of entities which can be used in two different
   situations; general entities and parameter entities.

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

  3.6.1 General Entities

   You cannot use general entities in an SGML context (although you
   define them in one). They can only be used in your document.
   Contrast this with parameter entities.

   Each general entity has a name. When you want to reference a
   general entity (and therefore include whatever text it represents
   in your document), you write &entity-name;. For example, suppose
   you had an entity called current.version which expanded to the
   current version number of your product. You could write:

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

   When the version number changes you can simply change the
   definition of the value of the general entity and reprocess your
   document.

   You can also use general entities to enter characters that you
   could not otherwise include in an SGML document. For example, <
   and & cannot normally appear in an SGML document. When the SGML
   parser sees the < symbol it assumes that a tag (either a start tag
   or an end tag) is about to appear, and when it sees the & symbol
   it assumes the next text will be the name of an entity.

   Fortunately, you can use the two general entities &lt; and &amp;
   whenever you need to include one or other of these.

   A general entity can only be defined within an SGML context.
   Typically, this is done immediately after the DOCTYPE declaration.

   Example 3-10. Defining general entities

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY current.version    "3.0-RELEASE">
 <!ENTITY last.version       "2.2.7-RELEASE">
 ]>

   Notice how 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, before the square bracket is
   closed, and then the DOCTYPE declaration is closed.

   The square brackets are necessary to indicate that we are
   extending the DTD indicated by the DOCTYPE declaration.

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

  3.6.2 Parameter entities

   Like general entities, parameter entities are used to assign names
   to reusable chunks of text. However, where as general entities can
   only be used within your document, parameter entities can only be
   used within an SGML context.

   Parameter entities are defined in a similar way to general
   entities. However, instead of using &entity-name; to refer to
   them, use %entity-name;[1]. The definition also includes the %
   between the ENTITY keyword and the name of the entity.

   Example 3-11. Defining parameter entities

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % param.some "some">
 <!ENTITY % param.text "text">
 <!ENTITY % param.new  "%param.some more %param.text">

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

   This may not seem particularly useful. It will be.

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

  3.6.3 For you to do...

    1. Add a general entity to example.sgml.

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
 <!ENTITY version "1.1">
 ]>   

 <html>
   <head>            
     <title>An example HTML file</title>
   </head>

   <!-- You might well have 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 nsgmls.

    3. Load example.sgml into your web browser (you may need to copy
       it to example.html before your browser recognizes it as an
       HTML document).

       Unless your browser is very advanced, you will not see the
       entity reference &version; replaced with the version number.
       Most web browsers have very simplistic parsers which do not
       handle proper SGML[2].

    4. The solution is to normalize your document using an SGML
       normalizer. The normalizer reads in valid SGML and outputs
       equally valid SGML which has been transformed in some way. One
       of the ways in which the normalizer transforms the SGML is to
       expand all the entity references in the document, replacing
       the entities with the text that they represent.

       You can use sgmlnorm to do this.

 % sgmlnorm example.sgml > example.html

       You should find a normalized (i.e., entity references
       expanded) copy of your document in example.html, ready to load
       into your web browser.

    5. If you look at the output from sgmlnorm you will see that it
       does not include a DOCTYPE declaration at the start. To
       include this you need to use the -d option:

 % sgmlnorm -d example.sgml > example.html

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

3.7 Using entities to include files

   Entities (both general and parameter) are particularly useful when
   used to include one file inside another.

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

  3.7.1 Using general entities to include files

   Suppose you have some content for an SGML book organized into
   files, one file per chapter, called chapter1.sgml, chapter2.sgml,
   and so forth, with a book.sgml file that will contain these
   chapters.

   In order to use the contents of these files as the values for your
   entities, you declare them with the SYSTEM keyword. This directs
   the SGML parser to use the contents of the named file as the value
   of the entity.

   Example 3-12. Using general entities to include files

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY chapter.1 SYSTEM "chapter1.sgml">
 <!ENTITY chapter.2 SYSTEM "chapter2.sgml">
 <!ENTITY chapter.3 SYSTEM "chapter3.sgml">
 <!-- And so forth -->
 ]>

 <html>
   <!-- Use the entities to load in the chapters -->

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

     Warning: When using general entities to include other files
     within a document, the files being included (chapter1.sgml,
     chapter2.sgml, and so on) must not start with a DOCTYPE
     declaration. This is a syntax error.

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

  3.7.2 Using parameter entities to include files

   Recall that parameter entities can only be used inside an SGML
   context. Why then would you want to include a file within an SGML
   context?

   You can use this to ensure that you can reuse your general
   entities.

   Suppose that you had many chapters in your document, and you
   reused these chapters in two different books, each book organizing
   the chapters in a different fashion.

   You could list the entities at the top of each book, but this
   quickly becomes cumbersome to manage.

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

   Example 3-13. Using parameter entities to include files

   First, place your entity definitions in a separate file, called
   chapters.ent. This file contains the following:

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

   Now 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 HTML 4.0//EN" [
 <!-- 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>
   &chapter.1;
   &chapter.2;
   &chapter.3;
 </html>

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

  3.7.3 For you to do...

    3.7.3.1 Use general entities to include files

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

       Put content similar to the following in each file:

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

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

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY version "1.1">
 <!ENTITY para1 SYSTEM "para1.sgml">
 <!ENTITY para2 SYSTEM "para2.sgml">
 <!ENTITY para3 SYSTEM "para3.sgml">
 ]>

 <html>
   <head>
     <title>An example HTML 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.sgml.

 % sgmlnorm -d example.sgml > example.html

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

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

    3.7.3.2 Use parameter entities to include files

     Note: You must have taken the previous steps first.

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

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
 ]>

 <html>
   <head>
     <title>An example HTML file</title>
   </head>

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

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

    2. Create a new file, entities.sgml, with this content:

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

    3. Produce example.html by normalizing example.sgml.

 % sgmlnorm -d example.sgml > example.html

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

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

3.8 Marked sections

   SGML provides a mechanism to indicate that particular pieces of
   the document should be processed in a special way. These are
   termed !S:marked sections!".

   Example 3-14. Structure of a marked section

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

   As you would expect, being an SGML construct, a marked section
   starts with <!.

   The first square bracket begins to delimit the marked section.

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

   The second square bracket indicates that the content of the marked
   section starts here.

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

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

  3.8.1 Marked section keywords

    3.8.1.1 CDATA, RCDATA

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

   When an SGML parser is processing a document it keeps track of
   what is called the !S:content model!".

   Briefly, the content model describes what sort of content the
   parser is expecting to see, and what it will do with it when it
   finds it.

   The two content models you will probably find most useful are
   CDATA and RCDATA.

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

   RCDATA is for !S:Entity references and character data!" If the
   parser is in this content model then it is expecting to see
   characters and entities. < loses its special status, but & will
   still be treated as starting the beginning of a general entity.

   This is particularly useful if you are including some verbatim
   text that contains lots of < and & characters. While you could go
   through the text ensuring that every < is converted to a &lt; and
   every & is converted to a &amp;, it can be easier to mark the
   section as only containing CDATA. When the SGML parser encounters
   this it will ignore the < and & symbols embedded in the content.

     Note: When you use CDATA or RCDATA in examples of text marked up
     in SGML, keep in mind that the content of CDATA is not
     validated. You have to check the included SGML text using other
     means. You could, for example, write the example in another
     document, validate the example code, and then paste it to your
     CDATA content.

   Example 3-15. Using a CDATA marked section

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

 <programlisting>
   <![ CDATA [ 
     <p>This is a sample that shows you some of the elements within
       HTML.  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>

   If you look at the source for this document you will see this
   technique used throughout.

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

    3.8.1.2 INCLUDE and IGNORE

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

   Example 3-16. Using INCLUDE and IGNORE in marked sections

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

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

   By itself, this is not too useful. If you wanted to remove text
   from your document you could cut it out, or wrap it in comments.

   It becomes more useful when you realize you can use parameter
   entities to control this. Remember that parameter entities can
   only be used in SGML contexts, and the keyword of a marked section
   is an SGML context.

   For example, suppose that you produced a hard-copy version of some
   documentation and an electronic version. In the electronic version
   you wanted to include some extra content that was not to appear in
   the hard-copy.

   Create a parameter entity, and set its value to INCLUDE. Write
   your document, using marked sections to delimit content that
   should only appear in the electronic version. In these marked
   sections use the parameter entity in place of the keyword.

   When you want to produce the hard-copy version of the document,
   change the parameter entity's value to IGNORE and reprocess the
   document.

   Example 3-17. Using a parameter entity to control a marked section

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % electronic.copy "INCLUDE">        
 ]]>

 ...

 <![ %electronic.copy [
   This content should only appear in the electronic
   version of the document.
 ]]>

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

 <!ENTITY % electronic.copy "IGNORE">

   On reprocessing the document, the marked sections that use
   %electronic.copy as their keyword will be ignored.

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

  3.8.2 For you to do...

    1. Create a new file, section.sgml, that contains the following:

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
 <!ENTITY % text.output "INCLUDE">
 ]>

 <html>
   <head>
     <title>An example using marked sections</title>
   </head>

   <body>    
     <p>This paragraph <![ CDATA [contains many <
       characters (< < < < <) so it is easier
       to wrap it in a CDATA marked section ]]></p>

     <![ IGNORE [
     <p>This paragraph will definitely not be included in the
       output.</p>
     ]]>

     <![ %text.output [
     <p>This paragraph might appear in the output, or it
       might not.</p>

     <p>Its appearance is controlled by the %text.output
       parameter entity.</p>         
     ]]>
   </body>
 </html>

    2. Normalize this file using sgmlnorm(1) and examine the output.
       Notice which paragraphs have appeared, which have disappeared,
       and what has happened to the content of the CDATA marked
       section.

    3. Change the definition of the text.output entity from INCLUDE
       to IGNORE. Re-normalize the file, and examine the output to
       see what has changed.

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

3.9 Conclusion

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

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

                         Chapter 4 SGML Markup

   This chapter describes the two markup languages you will encounter
   when you contribute to the FreeBSD documentation project. Each
   section describes the markup language, and details the markup that
   you are likely to want to use, or that is already in use.

   These markup languages contain a large number of elements, and it
   can be confusing sometimes to know which element to use for a
   particular situation. This section goes through the elements you
   are most likely to need, and gives examples of how you would use
   them.

   This is not an exhaustive list of elements, since that would just
   reiterate the documentation for each language. The aim of this
   section is to list those elements more likely to be useful to you.
   If you have a question about how best to markup a particular piece
   of content, please post it to the FreeBSD documentation project
   P:l>> 1/4 1/2 * 3/4A.

     Inline vs. 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.

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

4.1 HTML

   HTML, the HyperText Markup Language, is the markup language of
   choice on the World Wide Web. More information can be found at
   <URL:http://www.w3.org/>.

   HTML is used to markup pages on the FreeBSD web site. It should
   not (generally) be used to mark up other documentation, since
   DocBook offers a far richer set of elements to choose from.
   Consequently, you will normally only encounter HTML pages if you
   are writing for the web site.

   HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and
   the latest, 4.0 (available in both strict and loose variants).

   The HTML DTDs are available from the ports collection in the
   textproc/html port. They are automatically installed as part of
   the textproc/docproj port.

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

  4.1.1 Formal Public Identifier (FPI)

   There are a number of HTML FPIs, depending upon the version (also
   known as the level) of HTML that you want to declare your document
   to be compliant with.

   The majority of HTML documents on the FreeBSD web site comply with
   the loose version of HTML 4.0.

 PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"

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

  4.1.2 Sectional elements

   An HTML 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 the
   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.

   Example 4-1. Normal HTML document structure

 <html>
   <head>
           <title>The document's title</title>
   </head>

   <body>

     ...

   </body>
 </html>

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

  4.1.3 Block elements

    4.1.3.1 Headings

   HTML allows you to denote headings in your 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.

   Example 4-2. <h1>, <h2>, etc.

   Use:

 <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 HTML 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. Each <hn> element
   should have the same element, but one further up the hierarchy,
   preceding it. Leaving gaps in the numbering is to be avoided.

   Example 4-3. Bad ordering of <hn> elements

   Use:

 <h1>First section</h1>

 <!-- Document introduction -->

 <h3>Sub-section</h3>

 <!-- This is bad, <h2> has been left out -->

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

    4.1.3.2 Paragraphs

   HTML supports a single paragraph element, <p>.

   Example 4-4. <p>

   Use:

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

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

    4.1.3.3 Block quotations

   A block quotation is an extended quotation from another document
   that should not appear within the current paragraph.

   Example 4-5. <blockquote>

   Use:

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

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

    4.1.3.4 Lists

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

   Typically, each entry in an ordered list will be numbered, while
   each entry in an unordered list will be preceded by a bullet
   point. Definition lists are composed of two sections for each
   entry. The first section is the term being defined, and the second
   section is the definition of the term.

   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.

   Example 4-6. <ul> and <ol>

   Use:

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

   Example 4-7. Definition lists with <dl>

   Use:

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

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

    4.1.3.5 Pre-formatted text

   You can indicate that text should be shown to the user exactly as
   it is in the file. Typically, this means that the text is shown in
   a fixed font, multiple spaces are not merged into one, and line
   breaks in the text are significant.

   In order to do this, wrap the content in the <pre> element.

   Example 4-8. <pre>

   You could use <pre> 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, e.g., an email
   message or program code.

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

    4.1.3.6 Tables

     Note: Most text-mode browsers (such as Lynx) do not render
     tables particularly effectively. If you are relying on the
     tabular display of your content, you should consider using
     alternative markup to prevent confusion.

   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 you do not need to include the <p>
   element.

   Example 4-9. Simple use of <table>

   Use:

 <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. To indicate this, add
   the rowspan and/or colspan attributes, with values indicating the
   number of rows of columns that should be spanned.

   Example 4-10. Using rowspan

   Use:

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

   Example 4-11. Using colspan

   Use:

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

   Example 4-12. Using rowspan and colspan together

   Use:

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

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

  4.1.4 In-line elements

    4.1.4.1 Emphasizing information

   You have two levels of emphasis available in HTML, <em> and
   <strong>. <em> is for a normal level of emphasis and <strong>
   indicates stronger emphasis.

   Typically, <em> is rendered in italic and <strong> is rendered in
   bold. This is not always the case, however, and you should not
   rely on it.

   Example 4-13. <em> and <strong>

   Use:

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

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

    4.1.4.2 Bold and italics

   Because HTML includes presentational markup, you can also indicate
   that particular content should be rendered in bold or italic. The
   elements are <b> and <i> respectively.

   Example 4-14. <b> and <i>

 <p><b>This</b> is in bold, while <i>this</i> is
   in italics.</p>

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

    4.1.4.3 Indicating fixed pitch text

   If you have content that should be rendered in a fixed pitch
   (typewriter) typeface, use <tt> (for !S:teletype!").

   Example 4-15. <tt>

   Use:

 <p>This document was originally written by
   Nik Clayton, who can be reached by email as
   <tt>nik@FreeBSD.org</tt>.</p>

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

    4.1.4.4 Content size

   You can indicate that content should be shown in a larger or
   smaller font. There are three ways of doing this.

    1. Use <big> and <small> around the content you wish to change
       size. These tags can be nested, so <big><big>This is much
       bigger</big></big> is possible.

    2. Use <font> with the size attribute set to +1 or -1
       respectively. This has the same effect as using <big> or
       <small>. However, the use of this approach is deprecated.

    3. Use <font> with the size attribute set to a number between 1
       and 7. The default font size is 3. This approach is
       deprecated.

   Example 4-16. <big>, <small>, and <font>

   The following fragments all do the same thing.

 <p>This text is <small>slightly smaller</small>.  But
   this text is <big>slightly bigger</big>.</p>

 <p>This text is <font size="-1">slightly smaller</font>.  But
   this text is <font size="+1">slightly bigger</font.</p>

 <p>This text is <font size="2">slightly smaller</font>.  But
   this text is <font size="4">slightly bigger</font>.</p>

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

  4.1.5 Links

     Note: Links are also in-line elements.

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

    4.1.5.1 Linking to other documents on the WWW

   In order to include a link to another document on the WWW you must
   know the URL of the document you want to link to.

   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, and is normally indicated to the user in some way
   (underlining, change of color, different mouse cursor when over
   the link, and so on).

   Example 4-17. Using <a href="...">

   Use:

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

   These links will take the user to the top of the chosen document.

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

    4.1.5.2 Linking to other parts of documents

   Linking to a point within another document (or within the same
   document) requires that the document author include anchors that
   you can link to.

   Anchors are indicated with <a> and the name attribute instead of
   href.

   Example 4-18. Using <a name="...">

   Use:

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

   To link to a named part of a document, write a normal link to that
   document, but include the name of the anchor after a # symbol.

   Example 4-19. Linking to a named part of another document

   Assume that the para1 example resides in a document called
   foo.html.

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

   If you are linking to a named anchor within the same document then
   you can omit the document's URL, and just include the name of the
   anchor (with the preceding #).

   Example 4-20. Linking to a named part of the same document

   Assume that the para1 example resides in this document:

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

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

4.2 DocBook

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

     formal vs. 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.

   The DocBook DTD is available from the ports collection in the
   textproc/docbook port. It is automatically installed as part of
   the textproc/docproj port.

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

  4.2.1 FreeBSD extensions

   The FreeBSD Documentation Project has extended the DocBook DTD by
   adding some new elements. These elements serve to make some of the
   markup more precise.

   Where a FreeBSD specific element is listed below it is clearly
   marked.

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

     Note: There is nothing about these extensions that is FreeBSD
     specific, 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 get in
     touch with Documentation Engineering Team <doceng@FreeBSD.org>.

   The FreeBSD extensions are not (currently) in the ports
   collection. They are stored in the FreeBSD CVS tree, as
   doc/share/sgml/freebsd.dtd.

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

  4.2.2 Formal Public Identifier (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.1-Based Extension//EN"

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

  4.2.3 Document structure

   DocBook allows you to structure your documentation in several
   ways. In the FreeBSD Documentation Project we are using two
   primary types of DocBook document: the book and the article.

   A book is organized into <chapter>s. This is a mandatory
   requirement. There may be <part>s between the book and the chapter
   to provide another layer of organization. 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.

   Obviously, you should consider the nature of the documentation you
   are writing in order to decide 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 FreeBSD FAQ, and the FreeBSD Handbook are all marked
   up as books.

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

    4.2.3.1 Starting a book

   The content of the 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 should be contained within <bookinfo>.

   Example 4-21. Boilerplate <book> with <bookinfo>

 <book>
   <bookinfo>
     <title>Your title here</title>
    
     <author>
       <firstname>Your first name</firstname>
       <surname>Your surname</surname>
       <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>
   </bookinfo>

   ...

 </book>

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

    4.2.3.2 Starting an article

   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 should be contained within
   <articleinfo>.

   Example 4-22. Boilerplate <article> with <articleinfo>

 <article>
   <articleinfo>
     <title>Your title here</title>
    
     <author>
       <firstname>Your first name</firstname>
       <surname>Your surname</surname>
       <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 article's contents here.</para>
     </abstract>
   </articleinfo>

   ...

 </article>

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

    4.2.3.3 Indicating chapters

   Use <chapter> to mark up your chapters. Each chapter has a
   mandatory <title>. Articles do not contain chapters, they are
   reserved for books.

   Example 4-23. A simple chapter

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

   Example 4-24. Empty chapters

 <chapter>
   <title>This is an empty chapter</title>

   <para></para>
 </chapter>

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

    4.2.3.4 Sections below chapters

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

   Example 4-25. Sections in chapters

 <chapter>
   <title>A sample chapter</title>

   <para>Some text in the chapter.</para>

   <sect1>
     <title>First section (1.1)</title>

     ...
   </sect1>

   <sect1>
     <title>Second section (1.2)</title>

     <sect2>
       <title>First sub-section (1.2.1)</title>

       <sect3>
         <title>First sub-sub-section (1.2.1.1)</title>

         ...
       </sect3>
     </sect2>

     <sect2>
       <title>Second sub-section (1.2.2)</title>

       ...
     </sect2>
   </sect1>
 </chapter>

     Note: This example includes section numbers in the section
     titles. You should not do this in your documents. Adding the
     section numbers is carried out by the stylesheets (of which more
     later), and you do not need to manage them yourself.

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

    4.2.3.5 Subdividing using <part>s

   You can introduce another layer of organization between <book> and
   <chapter> with one or more <part>s. 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>

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

  4.2.4 Block elements

    4.2.4.1 Paragraphs

   DocBook supports three types of paragraphs: <formalpara>, <para>,
   and <simpara>.

   Most of the time you will only need to use <para>. <formalpara>
   includes a <title> element, and <simpara> disallows some elements
   from within <para>. Stick with <para>.

   Example 4-26. <para>

   Use:

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

   Appearance:

   This is a paragraph. It can contain just about any other element.

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

    4.2.4.2 Block quotations

   A block quotation is an extended quotation from another document
   that should not appear within the current paragraph. You will
   probably only need it infrequently.

   Blockquotes can optionally contain a title and an attribution (or
   they can be left untitled and unattributed).

   Example 4-27. <blockquote>

   Use:

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

   Appearance:

     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   

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

    4.2.4.3 Tips, notes, warnings, cautions, important information and
    sidebars.

   You may need to include extra information separate from the main
   body of the text. Typically this is !S:meta!" information that the
   user should be aware of.

   Depending on the nature of the information, one of <tip>, <note>,
   <warning>, <caution>, and <important> should be used.
   Alternatively, if the information is related to the main text but
   is not one of the above, use <sidebar>.

   The circumstances in which to choose one of these elements over
   another is unclear. The DocBook documentation suggests:

     * A Note is for information that should be heeded by all
       readers.

     * An Important element is a variation on Note.

     * A Caution is for information regarding possible data loss or
       software damage.

     * A Warning is for information regarding possible hardware
       damage or injury to life or limb.

   Example 4-28. <warning>

   Use:

 <warning>
   <para>Installing FreeBSD may make you want to delete Windows from your
     hard disk.</para>
 </warning>

     Warning: Installing FreeBSD may make you want to delete Windows
     from your hard disk.

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

    4.2.4.4 Lists and procedures

   You will often need to list pieces of information to the user, or
   present them with a number of steps that must be carried out in
   order to accomplish a particular goal.

   In order to do this, use <itemizedlist>, <orderedlist>, or
   <procedure>[4]

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

   <procedure> is slightly different. It consists of <step>s, which
   may in turn consists of more <step>s or <substep>s. Each <step>
   contains block elements.

   Example 4-29. <itemizedlist>, <orderedlist>, and <procedure>

   Use:

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

 <procedure>
   <step>
     <para>Do this.</para>
   </step>

   <step>
     <para>Then do this.</para>
   </step>

   <step>
     <para>And now do this.</para>
   </step>
 </procedure>

   Appearance:

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

    1. Do this.

    2. Then do this.

    3. And now do this.

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

    4.2.4.5 Showing file samples

   If you want to show a fragment of a file (or perhaps a complete
   file) to the user, wrap it 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.

   Example 4-30. <programlisting>

   Use:

 <para>When you have finished, your program should 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.

   Appearance:

   When you have finished, your program should look like this:

 #include <stdio.h>

 int
 main(void)
 {
     printf("hello, world\n");
 }

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

    4.2.4.6 Callouts

   A callout is a mechanism for referring back to an earlier piece of
   text or specific position within an earlier example without
   linking to it within the text.

   To do this, mark areas of interest in your example
   (<programlisting>, <literallayout>, or whatever) with the <co>
   element. Each element must have a unique id assigned to it. After
   the example include a <calloutlist> that refers back to the
   example and provides additional commentary.

   Example 4-31. <co> and <calloutlist>

 <para>When you have finished, your program should look like
   this:</para>

 <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">

 int <co id="co-ex-return">
 main(void)
 {
     printf("hello, world\n"); <co 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>

   Appearance:

   When you have finished, your program should 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.

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

    4.2.4.7 Tables

   Unlike HTML, you do not need to use tables for layout purposes, as
   the stylesheet handles those issues for you. 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 you can then have 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.

   Example 4-32. <informaltable>

   Use:

 <informaltable frame="none" 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>

   Appearance:

         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.

   If you do not want a border around the table the frame attribute
   can be added to the <informaltable> element with a value of none
   (i.e., <informaltable frame="none">).

   Example 4-33. Tables where frame="none"

   Appearance:

         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                  

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

    4.2.4.8 Examples for the user to follow

   A lot of the time you need to show examples for the user to
   follow. Typically, these will consist of dialogs with the
   computer; the user types in a command, the user gets a response
   back, they type in 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.
           Every time you want 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>.

             Note: &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 probably be displayed
           differently to the user.

   Example 4-34. <screen>, <prompt>, and <userinput>

   Use:

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

   Appearance:

 % ls -1
 foo1
 foo2
 foo3
 % ls -1 | grep foo2
 foo2
 % su
 Password:
 # cat foo2
 This is the file called 'foo2'

     Note: 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.

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

  4.2.5 In-line elements

    4.2.5.1 Emphasizing information

   When you want 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
   your document, no equivalent of HTML's <b> and <i>. If the
   information you are presenting is important then consider
   presenting it in <important> rather than <emphasis>.

   Example 4-35. <emphasis>

   Use:

 <para>FreeBSD is without doubt <emphasis>the</emphasis>
   premiere Unix like operating system for the Intel architecture.</para>

   Appearance:

   FreeBSD is without doubt the premiere Unix like operating system
   for the Intel architecture.

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

    4.2.5.2 Quotations

   To quote text from another document or source, or to denote a
   phrase that is used figuratively, use <quote>. Within a <quote>
   tag, you may use most of the markup tags available for normal
   text.

   Example 4-36. Quotations

   Use:

 <para>However, make sure that the search does not go beyond the
   <quote>boundary between local and public administration</quote>,
   as RFC 1535 calls it.</para>

   Appearance:

   However, make sure that the search does not go beyond the
   !S:boundary between local and public administration!", as RFC 1535
   calls it.

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

    4.2.5.3 Keys, mouse buttons, and combinations

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

   Example 4-37. Keys, mouse buttons, and combinations

   Use:

 <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 your work, 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>

   Appearance:

   To switch to the second virtual terminal, press Alt+F1.

   To exit vi without saving your work, type Esc : q !.

   My window manager is configured so that Alt+right mouse button is
   used to move windows.

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

    4.2.5.4 Applications, commands, options, and cites

   You will frequently want to refer to both applications and
   commands when writing for the Handbook. The distinction between
   them is simple: an application is the name for a suite (or
   possibly just 1) of programs that fulfil a particular task. A
   command is the name of a program that the user can run.

   In addition, you will occasionally need to list one or more of the
   options that a command might take.

   Finally, you will often want to list a command with its manual
   section number, in the !S:command(number)!" format so common in
   Unix manuals.

   Mark up application names with <application>.

   When you want 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/sgml/man-refs.ent, and can be referred to using this
   FPI:

 PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"

   Therefore, the introduction to your documentation will probably
   look like 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> when you want to include a command name !S:in-line!"
   but present it as something the user should type in.

   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.

   This can be confusing, and sometimes the choice is not always
   clear. Hopefully this example makes it clearer.

   Example 4-38. Applications, commands, and options.

   Use:

 <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.8;, and &man.newaliases.8;
   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>

   Appearance:

   Sendmail is the most widely used Unix mail application.

   Sendmail includes the sendmail(8), mailq(8), and newaliases(8)
   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.

     Note: Notice how the &man.command.section; notation is easier to
     follow.

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

    4.2.5.5 Files, directories, extensions

   Whenever you wish to refer to the name of a file, a directory, or
   a file extension, use <filename>.

   Example 4-39. <filename>

   Use:

 <para>The SGML source for the Handbook in English can be
   found in <filename>/usr/doc/en/handbook/</filename>.  The first
   file is called <filename>handbook.sgml</filename> in that
   directory.  You should also see a <filename>Makefile</filename>
   and a number of files with a <filename>.ent</filename>
   extension.</para>

   Appearance:

   The SGML source for the Handbook in English can be found in
   /usr/doc/en/handbook/. The first file is called handbook.sgml in
   that directory. You should also see a Makefile and a number of
   files with a .ent extension.

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

    4.2.5.6 The name of ports

     FreeBSD extension: These elements are part of the FreeBSD
     extension to DocBook, and do not exist in the original DocBook
     DTD.

   You might need to include the name of a program from the FreeBSD
   Ports Collection in the documentation. Use the <filename> tag with
   the role attribute set to package to identify these. Since ports
   can be installed in any number of locations, only include the
   category and the port name; do not include /usr/ports.

   Example 4-40. <filename> tag with package role

   Use:

 <para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>

   Appearance:

   Install the net/ethereal port to view network traffic.

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

    4.2.5.7 Devices

     FreeBSD extension: These elements are part of the FreeBSD
     extension to DocBook, and do not exist in the original DocBook
     DTD.

   When referring to devices you have two choices. You can either
   refer to the device as it appears in /dev, or you can use the name
   of the device as it appears in the kernel. For this latter course,
   use <devicename>.

   Sometimes you will not have a choice. Some devices, such as
   networking cards, do not have entries in /dev, or the entries are
   markedly different from those entries.

   Example 4-41. <devicename>

   Use:

 <para><devicename>sio</devicename> is used for serial
   communication in FreeBSD.  <devicename>sio</devicename> manifests
   through a number of entries in <filename>/dev</filename>, including
   <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para>

 <para>By contrast, the networking devices, such as
   <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para>

 <para>In MS-DOS, the first floppy drive is referred to as
   <devicename>a:</devicename>.  In FreeBSD it is
   <filename>/dev/fd0</filename>.</para>

   Appearance:

   sio is used for serial communication in FreeBSD. sio manifests
   through a number of entries in /dev, including /dev/ttyd0 and
   /dev/cuaa0.

   By contrast, the networking devices, such as ed0 do not appear in
   /dev.

   In MS-DOS, the first floppy drive is referred to as a:. In FreeBSD
   it is /dev/fd0.

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

    4.2.5.8 Hosts, domains, IP addresses, and so forth

     FreeBSD extension: These elements are part of the FreeBSD
     extension to DocBook, and do not exist in the original DocBook
     DTD.

   You can markup identification information for networked computers
   (hosts) in several ways, depending on the nature of the
   information. All of them use <hostid> as the element, with the
   role attribute selecting the type of the marked up information.

   No role attribute, or role="hostname"

           With no role attribute (i.e., <hostid>...</hostid>) the
           marked up information is the simple hostname, such as
           freefall or wcarchive. You can explicitly specify this
           with role="hostname".

   role="domainname"

           The text is a domain name, such as FreeBSD.org or
           ngo.org.uk. There is no hostname component.

   role="fqdn"

           The text is a Fully Qualified Domain Name, with both
           hostname and domain name parts.

   role="ipaddr"

           The text is an IP address, probably expressed as a dotted
           quad.

   role="ip6addr"

           The text is an IPv6 address.

   role="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.

   role="mac"

           The text is an Ethernet MAC address, expressed as a series
           of 2 digit hexadecimal numbers separated by colons.

   Example 4-42. <hostid> and roles

   Use:

 <para>The local machine can always be referred to by the
   name <hostid>localhost</hostid>, which will have the IP address
   <hostid role="ipaddr">127.0.0.1</hostid>.</para>

 <para>The <hostid role="domainname">FreeBSD.org</hostid> domain
   contains a number of different hosts, including
   <hostid role="fqdn">freefall.FreeBSD.org</hostid> and
   <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para>

 <para>When adding an IP alias to an interface (using
   <command>ifconfig</command>) <emphasis>always</emphasis> use a
   netmask of <hostid role="netmask">255.255.255.255</hostid>
   (which can also be expressed as <hostid
     role="netmask">0xffffffff</hostid>.</para>

 <para>The MAC address uniquely identifies every network card
   in existence.  A typical MAC address looks like <hostid
     role="mac">08:00:20:87:ef:d0</hostid>.</para>

   Appearance:

   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.

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

    4.2.5.9 Usernames

     FreeBSD extension: These elements are part of the FreeBSD
     extension to DocBook, and do not exist in the original DocBook
     DTD.

   When you need to refer to a specific username, such as root or
   bin, use <username>.

   Example 4-43. <username>

   Use:

 <para>To carry out most system administration functions you
   will need to be <username>root</username>.</para>

   Appearance:

   To carry out most system administration functions you will need to
   be root.

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

    4.2.5.10 Describing Makefiles

     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, <maketarget>
   and <makevar>.

   <maketarget> identifies a build target exported by a Makefile that
   can be given as a parameter to make. <makevar> identifies a
   variable that can be set (in the environment, on the make command
   line, or within the Makefile) to influence the process.

   Example 4-44. <maketarget> and <makevar>

   Use:

 <para>Two common targets in a <filename>Makefile</filename>
   are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para>

 <para>Typically, invoking <maketarget>all</maketarget> will rebuild the
   application, and invoking <maketarget>clean</maketarget> will remove
   the temporary files (<filename>.o</filename> for example) created by
   the build process.</para>

 <para><maketarget>clean</maketarget> may be controlled by a number of
   variables, including <makevar>CLOBBER</makevar> and
   <makevar>RECURSE</makevar>.</para>

   Appearance:

   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.

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

    4.2.5.11 Literal text

   You will often need to include !S:literal!" text in the Handbook.
   This is text that is excerpted from another file, or which should
   be copied from the Handbook into another file verbatim.

   Some of the time, <programlisting> will be sufficient to denote
   this text. <programlisting> is not always appropriate,
   particularly when you want to include a portion of a file
   !S:in-line!" with the rest of the paragraph.

   On these occasions, use <literal>.

   Example 4-45. <literal>

   Use:

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

   Appearance:

   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.

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

    4.2.5.12 Showing items that the user must fill in

   There will often be times when you want to show the user what to
   do, or refer to a file, or command line, or similar, where the
   user cannot simply copy the examples that you provide, but must
   instead include 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.

   Example 4-46. <replaceable>

   Use:

 <informalexample>
   <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>
 </informalexample>

   Appearance:

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

   Use:

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

   Appearance:

   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.

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

    4.2.5.13 Quoting system errors

   You might want to show errors generated by FreeBSD. Mark these
   with <errorname>. This indicates the exact error that appears.

   Example 4-47. <errorname>

   Use:

 
 <screen><errorname>Panic: cannot mount root</errorname></screen>

   Appearance:

 !S:Panic: cannot mount root!"

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

  4.2.6 Images

     Important: Image support in the documentation is currently
     extremely experimental. I think the mechanisms described here
     are unlikely to change, but that is not guaranteed.

     You will also need to install the graphics/ImageMagick port,
     which is used to convert between the different image formats.
     This is a big port, and most of it is not required. However,
     while we are working on the Makefiles and other infrastructure
     it makes things easier. This port is not in the textproc/docproj
     meta port, you must install it by hand.

     The best example of what follows in practice is the
     doc/en_US.ISO8859-1/articles/vm-design/ document. If you are
     unsure of the description that follows, take a look at the files
     in that directory to see how everything hangs together.
     Experiment with creating different formatted versions of the
     document to see how the image markup appears in the formatted
     output.

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

    4.2.6.1 Image formats

   We currently support two formats for images. The format you should
   use will depend on the nature of your image.

   For images that are primarily vector based, such as network
   diagrams, time lines, and similar, use Encapsulated Postscript,
   and make sure that your images have the .eps extension.

   For bitmaps, such as screen captures, use the Portable Network
   Graphic format, and make sure that your images have the .png
   extension.

   These are the only formats in which images should be committed to
   the CVS repository.

   Use the right format for the right image. It is to be expected
   that your documentation will have a mix of EPS and PNG images. The
   Makefiles ensure that the correct format image is chosen depending
   on the output format that you use for your documentation. Do not
   commit the same image to the repository in two different formats.

     Important: It is anticipated that the Documentation Project will
     switch to using the Scalable Vector Graphic (SVG) format for
     vector images. However, the current state of SVG capable editing
     tools makes this impractical.

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

    4.2.6.2 Markup

   The markup for an image is relatively simple. First, markup a
   <mediaobject>. The <mediaobject> can contain other, more specific
   objects. We are concerned with two, the <imageobject> and the
   <textobject>.

   You should include one <imageobject>, and two <textobject>
   elements. The <imageobject> will point to the name of the image
   file that will be used (without the extension). The <textobject>
   elements contain information that will be presented to the user as
   well as, or instead of, the image.

   There are two circumstances where this can happen.

     * When the reader is viewing the documentation in HTML. In this
       case, each image will need to have associated alternate text
       to show the user, typically whilst the image is loading, or if
       they hover the mouse pointer over the image.

     * When the reader is viewing the documentation in plain text. In
       this case, each image should have an ASCII art equivalent to
       show the user.

   An example will probably make things easier to understand. Suppose
   you have an image, called fig1, that you want to include in the
   document. This image is of a rectangle with an A inside it. The
   markup for this would be as follows.

 <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> should contain a <literallayout>
           element, where the class attribute is set to monospaced.
           This is your opportunity to demonstrate your 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> should contain a single <phrase>
           element. The contents of this will become the alt
           attribute for the image when this document is converted to
           HTML.

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

    4.2.6.3 Makefile entries

   Your images must be listed in the Makefile in the IMAGES variable.
   This variable should contain the name of all your source images.
   For example, if you have created three figures, fig1.eps,
   fig2.png, fig3.png, then your 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 your source document, you only need to list the
   image files you provided.

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

    4.2.6.4 Images and chapters in subdirectories

   You must be careful when you separate your documentation into
   smaller files (see Section 3.7.1) in different directories.

   Suppose you have a book with three chapters, and the chapters are
   stored in their own directories, called chapter1/chapter.sgml,
   chapter2/chapter.sgml, and chapter3/chapter.sgml. If each chapter
   has images associated with it, I suggest you place those images in
   each chapter's subdirectory (chapter1/, chapter2/, and chapter3/).

   However, if you do this you must include the directory names in
   the IMAGES variable in the Makefile, and you must include the
   directory name in the <imagedata> element in your document.

   For example, if you have chapter1/fig1.png, then
   chapter1/chapter.sgml 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
 ...

   Then everything should just work.

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

  4.2.7 Links

     Note: Links are also in-line elements.

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

    4.2.7.1 Linking to other parts of the same document

   Linking within the same document requires you to specify where you
   are linking from (i.e., the text the user will click, or otherwise
   indicate, as the source of the link) and where you are linking to
   (the link's destination).

   Each element within DocBook has an attribute called id. You can
   place text in this attribute to uniquely name the element it is
   attached to.

   This value will be used when you specify the link source.

   Normally, you will only be linking to chapters or sections, so you
   would add the id attribute to these elements.

   Example 4-48. id on chapters and sections

 <chapter id="chapter1">
   <title>Introduction</title>

   <para>This is the introduction.  It contains a subsection,
     which is identified as well.</para>

   <sect1 id="chapter1-sect1">
     <title>Sub-sect 1</title>

     <para>This is the subsection.</para>
   </sect1>
 </chapter>

   Obviously, you should use more descriptive values. The values must
   be unique within the document (i.e., not just the file, but the
   document the file might be included in as well). Notice how the id
   for the subsection is constructed by appending text to the id of
   the chapter. This helps to ensure that they are unique.

   If you want to allow the user to jump into a specific portion of
   the document (possibly in the middle of a paragraph or an
   example), use <anchor>. This element has no content, but takes an
   id attribute.

   Example 4-49. <anchor>

 <para>This paragraph has an embedded
   <anchor id="para1">link target in it.  It will not show up in
   the document.</para>

   When you want to provide the user with a link they can activate
   (probably by clicking) to go to a section of the document that has
   an id attribute, you can use either <xref> or <link>.

   Both of these elements have a linkend attribute. The value of this
   attribute should be the value that you have used in a id attribute
   (it does not matter if that value has not yet occurred in your
   document; this will work for forward links as well as backward
   links).

   If you use <xref> then you have no control over the text of the
   link. It will be generated for you.

   Example 4-50. Using <xref>

   Assume that this fragment appears somewhere in a document that
   includes the id example:

 <para>More information can be found
   in <xref linkend="chapter1">.</para>

 <para>More specific information can be found
   in <xref linkend="chapter1-sect1">.</para>

   The text of the link will be generated automatically, and will
   look like (emphasized text indicates the text that will be the
   link):

     More information can be found in Chapter One.

     More specific information can be found in the section called
     Sub-sect 1.

   Notice how the text from the link is derived from the section
   title or the chapter number.

     Note: This means that you cannot use <xref> to link to an id
     attribute on an <anchor> element. The <anchor> has no content,
     so the <xref> cannot generate the text for the link.

   If you want to control the text of the link then use <link>. This
   element wraps content, and the content will be used for the link.

   Example 4-51. Using <link>

   Assume that this fragment appears somewhere in a document that
   includes the id example.

 <para>More information can be found in
   <link linkend="chapter1">the first chapter</link>.</para>

 <para>More specific information can be found in
   <link linkend="chapter1-sect1">this</link> section.</para>

   This will generate the following (emphasized text indicates the
   text that will be the link):

     More information can be found in the first chapter.

     More specific information can be found in this section.

     Note: That last one is a bad example. Never use words like
     !S:this!" or !S:here!" as the source for the link. The reader
     will need to hunt around the surrounding context to see where
     the link is actually taking them.

     Note: You can use <link> to include a link to an id on an
     <anchor> element, since the <link> content defines the text that
     will be used for the link.

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

    4.2.7.2 Linking to documents on the WWW

   Linking to external documents is much simpler, as long as you know
   the URL of the document you want to link to. Use <ulink>. The url
   attribute is the URL of the page that the link points to, and the
   content of the element is the text that will be displayed for the
   user to activate.

   Example 4-52. <ulink>

   Use:

 <para>Of course, you could stop reading this document and
   go to the <ulink url="&url.base;/index.html">FreeBSD
   home page</ulink> instead.</para>

   Appearance:

   Of course, you could stop reading this document and go to the
   FreeBSD home page instead.

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

                        Chapter 5 * Stylesheets

   SGML says nothing about how a document should be displayed to the
   user, or rendered on paper. To do that, various languages have
   been developed to describe stylesheets, including DynaText,
   Panorama, SPICE, JSSS, FOSI, CSS, and DSSSL.

   For DocBook, we are using stylesheets written in DSSSL. For HTML
   we are using CSS.

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

5.1 * DSSSL

   The Documentation Project uses a slightly customized version of
   Norm Walsh's modular DocBook stylesheets.

   These can be found in textproc/dsssl-docbook-modular.

   The modified stylesheets are not in the ports system. Instead they
   are part of the Documentation Project source repository, and can
   be found in doc/share/sgml/freebsd.dsl. It is well commented, and
   pending completion of this section you are encouraged to examine
   that file to see how some of the available options in the standard
   stylesheets have been configured in order to customize the output
   for the FreeBSD Documentation Project. That file also contains
   examples showing how to extend the elements that the stylesheet
   understands, which is how the FreeBSD specific elements have been
   formatted.

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

5.2 CSS

   Cascading Stylesheets (CSS) are a mechanism for attaching style
   information (font, weight, size, color, and so forth) to elements
   in an HTML document without abusing HTML to do so.

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

  5.2.1 The Web site (HTML documents)

   The FreeBSD web site does not currently use CSS. Unfortunately,
   the look and feel is constructed using abuses of HTML of varying
   degrees. This should be fixed, and would be a good project for
   someone looking to contribute to the documentation project.

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

  5.2.2 The DocBook documents

   The FreeBSD DSSSL stylesheets include a reference to a stylesheet,
   docbook.css, which is expected to appear in the same directory as
   the HTML files. The project-wide CSS file is copied from
   doc/share/misc/docbook.css when documents are converted to HTML,
   and is installed automatically.

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

               Chapter 6 Structuring documents under doc/

   The doc/ tree is organized in a particular fashion, and the
   documents that are part of the FDP are in turn organized in a
   particular fashion. The aim is to make it simple to add new
   documentation into the tree and:

    1. make it easy to automate converting the document to other
       formats;

    2. promote consistency between the different documentation
       organizations, to make it easier to switch between working on
       different documents;

    3. make it easy to decide where in the tree new documentation
       should be placed.

   In addition, the documentation tree has to accommodate
   documentation that could be in many different languages and in
   many different encodings. It is important that the structure of
   the documentation tree does not enforce any particular defaults or
   cultural preferences.

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

6.1 The top level, doc/

   There are two types of directory under doc/, each with very
   specific directory names and meanings.

   Directory: share/

   Meaning: Contains files that are not specific to the various
   translations and encodings of the documentation. Contains
   subdirectories to further categorize the information. For example,
   the files that comprise the make(1) infrastructure are in
   share/mk, while the additional SGML support files (such as the
   FreeBSD extended DocBook DTD) are in share/sgml.

   Directory: lang.encoding/

   Meaning: One directory exists for each available translation and
   encoding of the documentation, for example en_US.ISO8859-1/ and
   zh_TW.Big5/. The names are long, but by fully specifying the
   language and encoding we prevent any future headaches should a
   translation team want to provide the documentation in the same
   language but in more than one encoding. This also completely
   isolates us from any problems that might be caused by a switch to
   Unicode.

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

6.2 The lang.encoding/ directories

   These directories contain the documents themselves. The
   documentation is split into up to three more categories at this
   level, indicated by the different directory names.

   Directory: articles

   Contents: Documentation marked up as a DocBook <article> (or
   equivalent). Reasonably short, and broken up into sections.
   Normally only available as one HTML file.

   Directory: books

   Contents: Documentation marked up as a DocBook <book> (or
   equivalent). Book length, and broken up into chapters. Normally
   available as both one large HTML file (for people with fast
   connections, or who want to print it easily from a browser) and as
   a collection of linked, smaller files.

   Directory: man

   Contents: For translations of the system manual pages. This
   directory will contain one or more mann directories, corresponding
   to the sections that have been translated.

   Not every lang.encoding directory will contain all of these
   directories. It depends on how much translation has been
   accomplished by that translation team.

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

6.3 Document specific information

   This section contains specific notes about particular documents
   managed by the FDP.

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

  6.3.1 The Handbook

   books/handbook/

   The Handbook is written to comply with the FreeBSD DocBook
   extended DTD.

   The Handbook is organized as a DocBook <book>. It is then divided
   into <part>s, each of which may contain several <chapter>s.
   <chapter>s are further subdivided into sections (<sect1>) and
   subsections (<sect2>, <sect3>) and so on.

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

    6.3.1.1 Physical organization

   There are a number of files and directories within the handbook
   directory.

     Note: The Handbook's organization may change over time, and this
     document may lag in detailing the organizational changes. If you
     have any questions about how the Handbook is organized, please
     contact the FreeBSD documentation project P:l>> 1/4 1/2 * 3/4A.

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

      6.3.1.1.1 Makefile

   The Makefile defines some variables that affect how the SGML
   source is converted to other formats, and lists the various source
   files that make up the Handbook. It then includes the standard
   doc.project.mk file, to bring in the rest of the code that handles
   converting documents from one format to another.

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

      6.3.1.1.2 book.sgml

   This is the top level document in the Handbook. It contains the
   Handbook's DOCTYPE declaration, as well as the elements that
   describe the Handbook's structure.

   book.sgml uses parameter entities to load in the files with the
   .ent extension. These files (described later) then define general
   entities that are used throughout the rest of the Handbook.

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

      6.3.1.1.3 directory/chapter.sgml

   Each chapter in the Handbook is stored in a file called
   chapter.sgml in a separate directory from the other chapters. Each
   directory is named after the value of the id attribute on the
   <chapter> element.

   For example, if one of the chapter files contains:

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

   then it will be called chapter.sgml in the kernelconfiguration
   directory. In general, the entire contents of the chapter will be
   held in this file.

   When the HTML version of the Handbook is produced, this will yield
   kernelconfiguration.html. This is because of the id value, and is
   not related to the name of the directory.

   In earlier versions of the Handbook the files were stored in the
   same directory as book.sgml, and named after the value of the id
   attribute on the file's <chapter> element. Moving them into
   separate directories prepares for future plans for the Handbook.
   Specifically, it will soon be possible to include images in each
   chapter. It makes more sense for each image to be stored in a
   directory with the text for the chapter than to try to keep the
   text for all the chapters, and all the images, in one large
   directory. Namespace collisions would be inevitable, and it is
   easier to work with several directories with a few files in them
   than it is to work with one directory that has many files in it.

   A brief look will show that there are many directories with
   individual chapter.sgml files, including basics/chapter.sgml,
   introduction/chapter.sgml, and printing/chapter.sgml.

     Important: Chapters and/or directories should not be named in a
     fashion that reflects their ordering within the Handbook. This
     ordering might change as the content within the Handbook is
     reorganized; this sort of reorganization should not (generally)
     include the need to rename files (unless entire chapters are
     being promoted or demoted within the hierarchy).

   Each chapter.sgml file will not be a complete SGML document. In
   particular, they will not have their own DOCTYPE lines at the
   start of the files.

   This is unfortunate as it makes it impossible to treat these as
   generic SGML files and simply convert them to HTML, RTF, PS, and
   other formats in the same way the main Handbook is generated. This
   would force you to rebuild the Handbook every time you want to see
   the effect a change has had on just one chapter.

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

               Chapter 7 The Documentation Build Process

   This chapter's main purpose is to clearly explain how the
   documentation build process is organized, and how to affect
   modifications to this process.

   After you have finished reading this chapter you should:

     * Know what you need to build the FDP documentation, in addition
       to those mentioned in the SGML tools chapter.

     * Be able to read and understand the make instructions that are
       present in each document's Makefiles, as well as an overview
       of the doc.project.mk includes.

     * Be able to customize the build process by using make variables
       and make targets.

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

7.1 The FreeBSD Documentation Build Toolset

   Here are your tools. Use them every way you can.

     * The primary build tool you will need is make, but specifically
       Berkeley Make.

     * Package building is handled by FreeBSD's pkg_create. If you
       are not using FreeBSD, you will either have to live without
       packages, or compile the source yourself.

     * gzip is needed to create compressed versions of the document.
       bzip2 compression and zip archives are also supported. tar is
       supported, but package building demands it.

     * install is the default method to install the documentation.
       There are alternatives, however.

     Note: It is unlikely you will have any trouble finding these
     last two, they are mentioned for completeness only.

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

7.2 Understanding Makefiles in the Documentation tree

   There are three main types of Makefiles in the FreeBSD
   Documentation Project tree.

     * Subdirectory Makefiles simply pass commands to those
       directories below them.

     * Documentation Makefiles describe the document(s) that should
       be produced from this directory.

     * Make includes are the glue that perform the document
       production, and are usually of the form doc.xxx.mk.

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

  7.2.1 Subdirectory Makefiles

   These Makefiles usually take the form of:

 SUBDIR =articles
 SUBDIR+=books

 COMPAT_SYMLINK = en

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

   In quick summary, the first four non-empty lines define the make
   variables, SUBDIR, COMPAT_SYMLINK, and DOC_PREFIX.

   The first SUBDIR statement, as well as the COMPAT_SYMLINK
   statement, shows how to assign a value to a variable, overriding
   any previous value.

   The second SUBDIR statement shows how a value is appended to the
   current value of a variable. The SUBDIR variable is now articles
   books.

   The DOC_PREFIX assignment shows how a value is assigned to the
   variable, but only if it is not already defined. This is useful if
   DOC_PREFIX is not where this Makefile thinks it is - the user can
   override this and provide the correct value.

   Now what does it all mean? SUBDIR mentions which subdirectories
   below this one the build process should pass any work on to.

   COMPAT_SYMLINK is specific to compatibility symlinks (amazingly
   enough) for languages to their official encoding (doc/en would
   point to en_US.ISO-8859-1).

   DOC_PREFIX is the path to the root of the FreeBSD Document Project
   tree. This is not always that easy to find, and is also easily
   overridden, to allow for flexibility. .CURDIR is a make builtin
   variable with the path to the current directory.

   The final line includes the FreeBSD Documentation Project's
   project-wide make system file doc.project.mk which is the glue
   which converts these variables into build instructions.

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

  7.2.2 Documentation Makefiles

   These Makefiles set a bunch of make variables that describe how to
   build the documentation contained in that directory.

   Here is an example:

 MAINTAINER=nik@FreeBSD.org

 DOC?= book

 FORMATS?= html-split html

 INSTALL_COMPRESSED?= gz
 INSTALL_ONLY_COMPRESSED?=

 # SGML content
 SRCS=  book.sgml

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

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

   The MAINTAINER variable is a very important one. This variable
   provides the ability to claim ownership over a document in the
   FreeBSD Documentation Project, whereby you gain the responsibility
   for maintaining it.

   DOC is the name (sans the .sgml extension) of the main document
   created by this directory. SRCS lists all the individual files
   that make up the document. This should also include important
   files in which a change should result in a rebuild.

   FORMATS indicates the default formats that should be built for
   this document. INSTALL_COMPRESSED is the default list of
   compression techniques that should be used in the document build.
   INSTALL_ONLY_COMPRESS, empty by default, should be non-empty if
   only compressed documents are desired in the build.

     Note: We covered optional variable assignments in the previous
     section.

   The DOC_PREFIX and include statements should be familiar already.

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

7.3 FreeBSD Documentation Project make includes

   This is 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.

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

  7.3.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"

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

    7.3.1.1 Variables

   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.

     Note: PRI_LANG in no way affects what documents can, or even
     will, be built. Its main use is creating links to commonly
     referenced documents into the FreeBSD documentation install
     root.

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

    7.3.1.2 Conditionals

   The .if defined(DOC) line is an example of a make 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.

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

  7.3.2 doc.subdir.mk

   This is too long to explain by inspection, you should be able to
   work it out with the knowledge gained from the previous chapters,
   and a little help given here.

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

    7.3.2.1 Variables

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

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

    7.3.2.2 Targets and macros

   Dependencies are described by target: dependency1 dependency2 ...
   tuples, where to build target, you need to build the given
   dependencies 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.

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

      7.3.2.2.1 Provided targets

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

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

    7.3.2.3 More on conditionals

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

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

    7.3.2.4 Looping constructs in 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.

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

                       Chapter 8 <<O/-oc Website

8.1 "AE<<e.C,^3AE

   1/2D-YENy.C,^3AENOTu 200MB -aAAP:!!A^3o"C,NOTOnYENI"O(c)n SGML
   CURu"au{|!!BCVS tree!B A{(R)E 1/2sA:P:YENI-a-o-aAAP:!!AYENHCURI
   1/2sA:P:|n-a-o-ooP:|s(c)n-aAAP:!!CY"AEYENyCURw|^3,E SGML
   CURu"au{|!!B CVS tree -a-o,U:!A"-o>>oYENu>>Y^3>>|hNOTu 100MB
   -aAAP:!S:YYENi!C

     Note:  1/2D-
     1/2T>>{CUR@CURUS:A-a-oNOTUAo:CURaaYENo>>sS:@(c)O.|YENI"`i-a-o
     ports ^3-L-NOTO^3I.s-a(c)!I
     YCUR-L-^2M.!(c)O,E-a-o-a(c)YEN>>NOTDEG|o!A"-o>>o'NYENyYENH
     pkg_delete(1) <<u:YENO"O^2 3/4DEG-L-AA-a(c)!A +-uuUCUR~YENh,E
     port!C A|"O"O>>!!AYCURw,E-a-oNOTO jade-1.1!A
     |yNOTOS:UIYENO/<<e>>Yn-a-o<<oNOTO
     jade-1.2!A"-o>>oYENyYENICURU|CCURe|!"O^2 3/4DEG-L-AA-a(c)!G

 # pkg_delete jade-1.1

   +-uuU!A'NNOTO^3](c)w CVS repository!C>>Yn|U:CURO: www, doc, ports
   ^3oCURT 1/4E CVS tree(.iuMAUnYEN[CURW CVSROOT)!C  1/2D-DEGN 3/4\
   CVSup A^2CURP: YENHAA,N|p|o"O mirror a CVS tree (c)I^3!CURA CVS
   tree!C

   ^3IS:C>>Y"D-a-o cvsup collections NOTDEG!Gwww, doc-all, cvs-base
   YENHCURI ports-base!C

   eA?-a-o^3o"C,>>YnNOTu 105MB -aAAP:!!C

   |OS:^1 3/4a-a-o CVS tree - YEN]NOTA src, doc, www YENHCURI ports -
   YENO/<<eNOTuNOTDEG 940MB!C

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

8.2 Build the web pages from scratch

    1. YENy<<O/YENssn 1/2sA:P:-a-oYENO/?y(|U:CURO:n|^3 60MB
       -aAAP:!)!A"ACURA'<<"`i,OYENO/?y!C

 # mkdir /var/tmp/webbuild
 # cd /var/tmp/webbuild

    2. +-q CVS tree CUR-o checkout NOTUAo:-a-o SGML AE!C

 # cvs -R co www doc

    3. CURA"`i www/en YENO/?y!AuM<<aYEN' make(1) all
       "O^2-L-YENI-ooP:!C

 # cd en
 # make all

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

8.3 |bS:A-a-o-ooP:|o/-aA 3/4^1CURW|w,E-ooP:

    1. |p-aGS:ACURw,gA-:P:} en ^3oOYENO/?y!A
       1/2D-CURA'<<|^^3oOYENO/?yCURCUR!C

 # cd path/www/en

    2. DEGo|ae make(1) install !A "A+-N DESTDIR
       ^3](c)wNOTDEGS:A.Q|w,EAE(R) *-a-oYENO/?y|W-oU!C

 # make DESTDIR=/usr/local/www install

    3. |p-aGS:ACURS:<<eCURw,g|bNOTU|P-a-oYENO/?yCURCUR|w,ECURF^3o"C,-ooP:!A
       |w,E^1Lu{"ACUR-L-.|S:RDEG-L-YENo|oNOTJ|^3(c)I^1L'A-a-o-ooP:!C
       A|"O"O>>!!A|p-aGS:A"CCURe<<O/-oc(c)M|w,E.s-a-o-ooP:DEGAEYEN>>!A
       ^3oO<<u:YENO+-N.|.j'M"AS:RDEG-L-|bCURTCURNCUR-o"S|^3S:o.s-a-oAE(R)
       *!C

 # find /usr/local/www -ctime 3 -print0 | xargs -0 rm

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

8.4 Ao^1OAAU: 1/4AE

   CVSROOT

           ^3](c)w CVS tree -a-o|`i,m!A|^1NOTDEGYEN^2^3AE+-o/YENo!C

 # CVSROOT=/home/ncvs; export CVSROOT

   ENGLISH_ONLY

           |p-aG^3](c)w^3oOAo^1OAAU:
           1/4AE!A|OYENBECUR-L-NOTDEG-aAAYENO!A makefiles
           +-NYENu.|<<O/-oc(c)M|w,E^CURaaCURaaYENo!C
           (c)OYENH+-N.|^2CUR^1L"a:YENL-a-o|UDEGeA 1/2A:P:!C"O|p!G

 # make ENGLISH_ONLY=YES all install

           |p-aGS:A.Qn"u(R)o/AAU: 1/4AE ENGLISH_ONLY
           YENHCURI<<O/-oc(c)O|^3-a-oP:+-"AYEN]NOTAA
           1/2A:P:!AYENun+-NAAU: 1/4AE ENGLISH_ONLY
           -a-oE^3](c)w|"-aAAYENOS:YYENi!C

 # make ENGLISH_ONLY="" all install clean

   WEB_ONLY

           |p-aG|^3^3](c)w^3oOAAU: 1/4AE-a-o,U:!A makefiles
           +-NYENu.|+-q www YENO/?y<<O/-ocCURI|w,E HTML P:+-!C
           (c)O|^3+-q doc
           YENO/?yCURU-a-oCURaaYENoYENth^3!^3-L-.|^3Q(c)?^2CUR
           (Handbook, FAQ, Tutorials)!C "O|p!G

 # make WEB_ONLY=YES all install

   NOPORTSCVS

           |p-aG^3]CURF^3oOAAU: 1/4AE!Amakefiles 'NCUR-L-.|+-q ports
           cvs repository "uYENXAE(R) *!C "u|OYENNCURS:.|+-q
           /usr/ports ((c)INOTO PORTSBASE (c)O^3](c)w-a-oE) CUR-o
           1/2AE>>sAE(R) *!C

   CVSROOT NOTOAo^1OAAU: 1/4AE!C S:AYEN^2P:.-a
   1/2+-u"IYENI<<u:YENO(c)INOTO|b dot files (|p!G ~/.profile) CURCUR
   ^3](c)w^3oOAo^1OAAU: 1/4AE!C

   WEB_ONLY!BENGLISH_ONLY CURI NOPORTSCVS ^3-L-NOTO makefile AAU:
   1/4AE!C S:AYENiYENH|b /etc/make.conf!BMakefile.inc
   CURCUR^3](c)w^3o"C,AAU:
   1/4AE!AS:@-ak'N^1^3NOTOYENI(c)RYENO|C(c)I"IYENI dot files
   "O^3](c)wAo^1OAAU: 1/4AECUR@-e!C

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

                Chapter 9 A 1/2A:P:(R)E-a-o+-`"-L-DEGYAD

   YEN>>^3^1NOTOA 1/2A:P: FreeBSD CURaaYENo(YEN]S:t!GFAQ, Handbook,
   tutorials, manual pagesuYEN)-a-o+-`"-L-DEGYAD(FAQ)!C

   YEN>>CURaaYENo YENDn NOTOYENH FreeBSD  1/4wCURaaA
   1/2A:P:p^1-o-a-oA 1/2A:P: FAQ NOTDEGYENAYEN>>|O"O-a-o!A `i(c)l
   1/4P: 1/2Z-aINOTDEG Frank Gru:nder <elwood@mc5sys.in-berlin.de>
   !A"AYENN Bernd Warken <bwarken@mayn.de> |AA 1/2A:P:|^^CURaa-a(c)!C

   The FAQ is maintained by the Documentation Engineering Team
   <doceng@FreeBSD.org>.

   9.1. FAQ -a-oYENO/-a-oNOTO?

   9.2. i18n ,o l10n NOTOCURDEG>>o(c)O!H

   9.3. |^3+-M-auu^1A:P:-aIDEGN>>PDEGQ 1/2 *-a-o mailing list P:U:!H

   9.4. >>YnS:o|hCURHCUR@DEG_DEGN>>PA 1/2A:P:P:U:!H

   9.5. |^3n"Dth"C,>>y"YEN-`aCURO(c)O!H

   9.6. ,O 3/4C,.|th"C,u{|!-a-o"IYENI(c)O!H

   9.7. n<<c,>>oS:a:YENX"OAU|^3 1/2O:n,oS:UCUR@DEG_A
   1/2A:P:-a-o(c)O!H

   9.8. ^3-L-"SCURHA
   1/2A:P:NOTDEGS:U(c)O"IYENI-a-o>>y"YEN!A,O<<c,>>o?`i!H

   9.9. CURw,gA 1/2|nCUR@"C,CURaaYENoCURF!A,O+-H"`ith(c)O!H

   9.10. S:UNOTO,O>>y"t-a-oDEGssCUR@A 1/2A:P:-aI!A,O<<c,>>oS:aA
   1/2A:P:|"-aG+-HYENXYENh(c)O!H

   9.11.
   YENiYENHYEN[CURJNOTY>>y"t(c)INOTYDEGe(R)aCUR~|^3-a-o-aF|e"`iA
   1/2A:P:CUR-o(R)eCUR-oP:U:!H

   9.12. n<<c,>>oS:a,O>>y"t-S|^3-a-o|rCUR, 1/4gP:iYENhA
   1/2A:P:CUR-o(R)e(c)O!H

   9.13. |p|o-oU(c)IAA-a-aI(c)O!H

   9.14. A
   1/2A:P:|"-aGCUR-onCUR-L-n-athCURWCUR@"C,"a:YENLDEGT(R)S:(c)O!H

   9.1. FAQ -a-oYENO/-a-oNOTO?

   AHuUP:V"OP:V|hCURHDEGN>>P freebsd-doc P:l>> 1/4 1/2 *
   3/4A!A|OYENBS:AE+-ae+-N FreeBSD CURaaYENoA
   1/2A:P:NOTDEG|U-oO/>>y"YEN-a(c)YEN>>!C S:UIS:AE+-ae^3oYEN-: FAQ
   -`a 3/4"YENi-`aNOTDEG^3o"C,DEGN>>PA
   1/2A:P:-aI'-L-"NS:O:^3t-a-o,N'b!C

   9.2. i18n ,o l10n NOTOCURDEG>>o(c)O!H

   i18n NOTO internationalization -a-oA^2 1/4g!A|O l10n <<hNOTO
   localization -a-oA^2 1/4g!C^3o"C,^3-L-NOTONOTDEGCURF(R)N
   1/4gCURe<<K|OYENI-a-oA^2 1/4g!C

   i18n 'NNOTOP:}AYNOTDEG !S:i!" <<a+-|^3 18 O|rYENA!A^3I<<a+-u
   !S:n!"!C |P^2z!A l10n <<hNOTOP:}AYNOTDEG !S:l!" <<a+-|^3 10
   O|rYENA!A^3I<<a+-u !S:n!"!C

   9.3. |^3+-M-auu^1A:P:-aIDEGN>>PDEGQ 1/2 *-a-o mailing list P:U:!H

   |^3DEGU!ACUR-L-|P-a-o>>y"tA 1/2A:P:-aI^3-L-|U|U|^3|UA:Y-a-o
   mailing lists!C^3oYEN-: A 1/2A:P:p^1-o^2M^3ae |^3|CYENX|UA
   1/2A:P:p^1-o-a-o,O^2O mailing lists CURINOTUAo:-oo-,!C

   9.4. >>YnS:o|hCURHCUR@DEG_DEGN>>PA 1/2A:P:P:U:!H

   .iuMAAo!AP:V|hCURHDEGN>>PA 1/2A:P:!A"-o>>o'N-`aDEG-:P:VS:O:A
   1/2S:^1!A|OYENB^CURaa-a(c)CURaaYENoY|^3 1/4W'i!BS:o.s-a-o,U:!A |UA
   1/2A:P:-a(c)CUR]YENiYENH 3/4"S:O:|P"BAAo!C

   CUR-L-CUR@(c)w+-oNOTO+-M.~A:P:-aI!ACUR~-`aDEGN>>PA 1/2A:P:-a-o!C

   9.5. |^3n"Dth"C,>>y"YEN-`aCURO(c)O!H

   ^2z 1/2 *CURW!AYEN^2P:.n^1i^CURaa<<D+-`
   1/4o,Z!A|OYENB<<U:(c)uAAa|a!A^1i.QA
   1/2A:P:-a-o>>y"YENYEN^2P:.n-`a^1BYENI|U|p!C

   ^CURaa"A<<DCUR@(c)wn.|-a-o!CCURn|p>>!!AYENiYENHS:a|e-ZCURuCURaa(Spanish)-a-o
   FAQ A 1/2A:P:NOTDEG|ICURuS:QCURaa(Hungarian)!C

   9.6. ,O 3/4C,.|th"C,u{|!-a-o"IYENI(c)O!H

   +-j-P<<O/A:^3|b|UCURv 3/4-: 3/4^1CURWCUR]<<O/YENss FreeBSD CVS
   repository -a-o^3AEYEN-:(|U:CURO:CURaaYENo^3!CURA)!AYENiYENHYENI
   CTM (c)I CVSup ^3-L-YENiYENH!CHandbook CURCUR-a-o "S:o.s!BCURE-AA
   FreeBSD" CUR@^3^1CUR-o|^3'-L-"`i|p|o"IYENI^3o"C,u{|!!C

   |^1YEN~!A>>Yn 1/4o+-x CVS YENI-ak!C |p|^1CUR@"O!AS:AYENiYENHNOTd
   3/4\CUR-L-|P-a(c)YEN>>CURS:P:!-a-o(R)t^2S:^3B!C

   [XXX To Do((c)|YEN 1/4 1/4P: 1/2Z!ACUR'<<Y,EYENR) -- 
   1/4gYEN-:CURWCURa>>!(c)u(tutorial)"OCURP:^2D-|p|oYENH CVSup
   "u+-oCURaaYENo^3!CURA!AYENHCURI^1iNOTYCUR-L-|P-a(c)YEN>>CURS:P:!-a-o(R)t^2S:!C]

   9.7. n<<c,>>oS:a:YENX"OAU|^3 1/2O:n,oS:UCUR@DEG_A
   1/2A:P:-a-o(c)O!H

   CURaaYENop^1-o-a-oA 1/2A:P: ^3o|CCURFYENO/<<eCURw-a 3/4-a-o|UA
   1/2A:P:-aI|"-aG !A|p-aGCURw,g|^3"a:YENLCURHCUR]|bDEGu,oS:ACUR@
   1/4E-a-oA 1/2A:P:CURuS:@!A"-o>>o 1/2D-CUR-L-n<<
   1/2AE(R)o:P:OCURHCURO!A 
   1/2D->>PYENLIApA'NOTYNOTYAU|^3th"C,|aCUReYENiYENHADEGCURW|-L--a-o!C

   YCURW+-"AYEN 1/4|CYENXS:AYENA>>y-a-oA
   1/2A:P:!A(c)INOTOCUR]|^3CURHnA 1/2A:P:|yAUYEN 1/4CUR
   1/2P:}<<AAYENNOT-a-o,U:!A"-o>>o'N+-H<<H"`i FreeBSD documentation
   project P:l>> 1/4 1/2 * 3/4A S:a!C

   9.8. ^3-L-"SCURHA
   1/2A:P:NOTDEGS:U(c)O"IYENI-a-o>>y"YEN!A,O<<c,>>o?`i!H

   (R)YEN^3ssDEGU!AS:Ae|n 1/2nCURW !S:FreeBSD S:A-a-oYENA>>y
   CURaaYENoA 1/2A:P:p^1-o!" -a-o+-Ou{CURS:,o!AAAw-aiCURW^2i!C

   -oYENy(c)O!AYENyS:PA_NOTOS:_|^3S:'u
   1/2^3W^1-o(R)EP:!!A|]NOTDEGS:AYENu|^3CUR@OCURH|bA 1/2|OCURw!A
   |]|^1!ANOTUAo:A 1/2A:P:|"-aG-a-oCUR
   1/2YENNOT!B>>P"a:YENLYENi-`a.|ADEG|-L--a-oS:OCURuIApA'^3o"C,CURuS:@^3-L-NOTOS:A-a-oA
   3/4^3d(c)O|b!C

   1/4g<<H"`i FreeBSD documentation project P:l>> 1/4 1/2 * 3/4A
   |VCURj(R)a<<AAYENNOTS:AYEN?.C,^3AEnA
   1/2A:P:!AuM<<aCURaaYENop^1-o-a-oA
   1/2A:P:^3!CURA'N.|S:o.sNOTUAo:,e(R)AE

   YS:A-a-oDEGe(R)aCURw,g|^3CURH'-L-"N FreeBSD -a-o mirror(NOTM^3])
   -aADEGE-a-o,U:!A"-o>>o'NYENy,oYENLIApA'!A
   "A,ssDEGYS:ANOTOS:_|bCURW+-YENiYENH|^3-ooP:-aAAP:!"O(c)nNOTUAo:p^1-o,e(R)AE!A
   YENHCURINOTOS:_YENiYENH|^3'-L-"N email +-b,^1(c)I mailing list
   -aADEGE!C

   uM<<a!A'NP:}(c)lA 1/2CURaaYENoAAo!ACUR@P:}(c)lA
   1/2A:P:-a-o(R)EO!AYENyS:a:"C,
   1/2g'T,uuu-a-oCURaaYENo.|CURn,u(R)e(c)o:"C, !X!X ^1^3NOTO FAQ
   DEGO!A(c)INOTO|p|oCURWCURaCURS:Ath-a-o>>!(c)uCURaa^3^1!C

   9.9. CURw,gA 1/2|nCUR@"C,CURaaYENoCURF!A,O+-H"`ith(c)O!H

   ^3onNOTY+-!-ap|O(c)w!C YS:ANOTO|bA
   1/2A:P:^1IP:CURCUR-oDEGu-a-o,U:(^1^3NOTOCUReYEN>>!B 1/4wDEGe)!A
   YENLI.||^3|UCURvCUR-o^3!NOTyu{"O"M(c)wA
   1/2A:P:CURaaYENo<<c,>>oDEGe!A^3o"C,CURjPNOTyu{.||bYENLI-ooP:CURW+-|^3
   1/4g!C

   YS:ANOTONOTY>>y"t-a-oDEGssCUR@A 1/2A:P:-aI((c)IS:ANOTOt^3dNOTYA
   1/2A:P:p^1-o!A"A.QS:a|"-aG|^oXu^1 FreeBSD p^1-o)
   !A"-o>>oS:A'NA^3,OS:a|UCURv-a-oA 1/2A:P:|"-aG+-Hu^1 FreeBSD
   p^1-o!C(^2O,` 1/2D-NOTYCURUODEGYAD)

   9.10. S:UNOTO,O>>y"t-a-oDEGssCUR@A 1/2A:P:-aI!A,O<<c,>>oS:aA
   1/2A:P:|"-aG+-HYENXYENh(c)O!H

   (c)I-aI

   S:UINOTOA 1/2A:P:^1IP:CUR!A,O<<c,>>oS:aS:UI|"uA
   1/2A:P:|"-aG+-HYENXYENh(c)O!H

   -oYENy!A 1/2D-YENy 1/2T(c)wS:A-a-oA
   1/2A:P:|"-aG^2OA'+-o/^2zCURA(c)u!A"AYENiYEN? 1/2T
   1/2sA:P:!ACUR]'NNOTO>>!!G
   S:aYEN|A\"`i^2{|^3CURaaYENoNOT[-ocCUR-oNOTOYENiYENHYEN? 1/2T
   1/2sA:P:|"YEN\-a-o!C

   YENO/<<e!AFreeBSD CURaaYENo^3-L-NOTO(c)n|b^3ICURW 1/4h-a-o doc/
   YENO/?yCUR-o!C
   |O,OYENO/?yCURU-a-o<<h"I"a:>>y"t"ODEGuCURAAth(c)R|W-a-o!A"I.O
   ISO639 (c)w,q(/usr/share/misc/iso639 -a-o^3oO FreeBSD
   -a(c)YEN>>CURn 1999/01/20 AU.s)!C

   YS:A^3oO>>y"tYENi-`a.||^3CUR-L-|P 1/2s
   1/2XCURe|!(^1^3NOTO!GCURCURCURaa) "-o>>o'NA^3,O.|^1^3CURU+-^3o
   1/4E!A"O"IS:A(c)O"IYENI-a-o 1/2s 1/2XCURe|!^2OCURA!C

   ^3I<<a!AS:AA^3,O<<O/YENss|n|UCURaaYENo-a-oYENO/?yCURF!C

   A|"O"O>>!!ADEG^2^3]|^3.c,"aaCURaa(Swedish)-a(c)-a-oA
   1/2A:P:!A"-o>>oA^3,O.|-ao/^1^3!G

 doc/
     sv_SE.ISO8859-1/
                      Makefile
                      books/
                            faq/
                                Makefile
                                book.sgml

   sv_SE.ISO8859-1 NOTO"I.O >>y"t(lang). 1/2s 1/2X(encoding)
   -a-o^3W<<h"O<<O/YENss-a-oA:P:|W!C  1/2D--a`.N!G"a:CURCUR|^3"aO
   Makefiles AE!AYEN|INOTOYENI"O 1/2s(R)N-a-o!C

   uM<<a 1/2D-YENI tar(1) >>P gzip(1) "OS:aS:A-a-oA
   1/2A:P:CURaaYENoA-L-AYDEG_"O!A"A+-H"`iYEN>>p^1-o"O!C

 % cd doc
 % tar cf swedish-docs.tar sv_SE.ISO8859-1
 % gzip -9 swedish-docs.tar

   +-uuU!AS:a swedish-docs.tar.gz
   (c)n"`i-ooP:-aAAP:!CURW!AYS:A"S|^3|UCURv-ooP:-aAAP:!-a-o,U:(ISPCUR-L-'-L-"N)
   !A"-o>>oYENiYENH,OAE+-H"`i Documentation Engineering Team
   <doceng@FreeBSD.org> "O!C

   AU|^3!ADEGO+-oYENI send-pr(1) YENHYEN?|!^3q-a
   3/4CURj(R)a!FS:ACURw,g+-HYENXA 1/2A:P:CURaaYENoCURF!A
   AU|^3!AY|^3CURHYENiYENHADEG|-L-AE 3/4\!B 1/2AE
   1/4fCURaaYENo-a-o,U:!A^1iA 1/2A:P:<<~ 1/2e,u|n!A
   |]NOTDEG^3oCUR]|^3S:U(c)o'-L-CUREA 1/2A:P:<<~ 1/2e-a-oNOTy-oZ<<
   *!C

   ^3I<<a!A.||^3CURH(YENi-`aNOTOCURaaYENop^1-oA`-oTH!A(c)INOTO
   Documentation Engineering Team <doceng@FreeBSD.org> |"u) .|AE
   3/4\S:A-a-oA 1/2A:P:CURaaYENo!A"A 1/2T>>{NOTOS:_YENiYEN?+-`
   1/2sA:P:!C|^1YEN~!AYENLI.|-SS:O-a`.NCURU|C'XAI!G

    1. S:A-a-oAE(R) *NOTOS:_^3-L-|^3YENI RCS tag (^1^3NOTO "ID"
       CURS:Ath-a-o)!H

    2. sv_SE.ISO8859-1 NOTOS:_YENiYENHP:P:S:Q make all 
       1/2sA:P:(c)O!H

    3. make install NOTOS:_u^2-aG|^3YEN? 1/2T!H

   Y|^3DEGYAD-a-o,U:!A"-o>>oAE 3/4\-aI.|YENmA{S:A!A"OAAy^3o"C,A
   1/2A:P:|"-aGYENiYENHYEN? 1/2T"IYENI!C

   Y"SDEGYAD-a-o,U:!A"-o>>o'N.|<<U:S:O:S:aS:A-a-oA 1/2A:P:|"-aG
   commit P:iYENhCURF!C

   9.11.
   YENiYENHYEN[CURJNOTY>>y"t(c)INOTYDEGe(R)aCUR~|^3-a-o-aF|e"`iA
   1/2A:P:CUR-o(R)eCUR-oP:U:!H

   S:UIS:AE+-aeCUR-L-n^3o>>oDEGu!C

   A|"O"O>>!!ADEG^2^3]S:AYEN?.C,^3AES:a Handbook A
   1/2A:P:NOTDEGAuCURaa-a(c)!A
   "AS:AE+-aeS:aAuDEGe^1sDEGa^3BCUR]YEN["`iS:AA 1/2A:P:-a-o Handbook
   AuCURaa-a(c)CUR-o!C

   S:UI.QCUR-L-YENX"O|^3O-L-`i|]!ANOTDEGCURDEG>>oCUR-L-S:a^3o"C,,eDEGT'-L-"Nu^1^CURaa-a(c)(c)O!H((c)INOTO
   1/4wCURaa!B|e-ZCURuCURaa!BCUReCURaauYEN ...)
   |]NOTDEG!A|^3YENi-`a^>>yAA-a-aIP:]YENhAuDEGe(R)E!A.|.QP:R FreeBSD
   NOTUAo:^2-L-<<~!C |^1YEN~!A^3oCUR]YENiYENH'-L-CURE FreeBSD
   -a-oYENi"-L-<< *!A<<U:AAauM-a-o!A^3o"ACUR-L-NOTOYENoAa"AEDEGU!C

   YS:A|^3NOTYDEGeCUR~|^3-a-o,e(R)AE!A 1/2D-(YENI send-pr(1)
   )'-L-"Nu^1^CURaa-a(c) Handbook YENHS:@NOTDEG *q
   !AuM<<a|AS:a^CURaa-a(c)-a-o *q^3!CURA!AA 1/2NOTDEGS:AnA
   1/2A:P:-a-o Handbook S:a!C

   .P(R)|!AAAAA!C

   9.12. n<<c,>>oS:a,O>>y"t-S|^3-a-o|rCUR, 1/4gP:iYENhA
   1/2A:P:CUR-o(R)e(c)O!H

   CURaaYENoCUR-o(c)O|^3-a-o<<D ASCII(Non-ASCII) |rCUR,!A^3-L-n"IYENI
   SGML entities CUR~-`a 1/4gP:iYENh!C

   A^2^3ae"O>>!!A-ao/NOTUCUR@P:}AY.|NOTO & ^2AA,^1(&)!AuM<<aNOTO,O
   entity |W-oU!A^3I<<a+-uCURWCURA,^1(;)!C

   ^3o"C, entity |W-oU^3-L-NOTO ISO8879 (c)O"iq-a-o!A|O port tree
   CUR-o<<h|b textproc/iso8879!C

   YENHCURUA|CUR@"C,"OCURl!G

   Entity|W-oU: &eacute;

   ^1e>>U 1/4ECURl: e

   CURP:^2D-: CURp !S:e!"!A"A+-a|y!B<<u(acute accent)

   Entity|W-oU: &Eacute;

   ^1e>>U 1/4ECURl: E

   CURP:^2D-: CURj !S:E!"!A"A+-a|y!B<<u(acute accent)

   Entity|W-oU: &uuml;

   ^1e>>U 1/4ECURl: u:

   CURP:^2D-: CURp
   !S:u!"!A"A+-aCURe|ODEGO>>y"tCURCUR-a-oYENAuAAU:CURAE(umlaut)

   |b,ECURF iso8879 ^3oO port CURS:<<a!A'NYENiYENH|b
   /usr/local/share/sgml/iso8879 S:a:"`i^3o"C,-a-o,O^2O|C-ai!C

   9.13. |p|o-oU(c)IAA-a-aI(c)O!H

   |b^CURaaCURaaYENoCUR-o!AAA-a-aI^3-L-NOTOYENH !S:you!"
   "O-oU(c)I!A|O|^3"C,>>y"YEN"A"S|^3YEN?|!/<<DYEN?|!-a-oDEGI^1j!C

   YS:A(c)OnA 1/2-a-o>>y"YENYENiYENHDEGIS:O^3o"C,(R)t^2S:!A"-o>>o
   1/2D-YENI,O>>y"t|bCUR@-eS:TH^3NCURaaYENoCURW(c)O"IYENI-a-o-oU(c)IS:a!C
   |p-aG(R)e(c)o:^3y|"S:x'b-a-o,U:!A"-o>>o
   1/2D-S:iYENI,uCURCUR(c)E-a-o-oU(c)I"O"uYENN!C

   9.14. A
   1/2A:P:|"-aGCUR-onCUR-L-n-athCURWCUR@"C,"a:YENLDEGT(R)S:(c)O!H

   .iuMn!C

   "CYEN-:^CURaa-a(c)`i
   1/2Z-a-oP:}AY!A^3q+-`.||^3^1^3CURU+--a-oCUR-o(R)e!G

 <!--
      The FreeBSD Documentation Project

      $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $
 -->

   ^1e>>UCURW-a-oCUR-o(R)eYENi-`auy|^3CUR-L-|P!A|y"CYEN-:`i
   1/2Z^3-L-.|-athCURW $FreeBSD$ ^3oCUR@|aeYENHCURI The FreeBSD
   Documentation Project <<AAS:i!C  1/2D--a`.N!G$FreeBSD
   P:}AY-a-o^3o|aeNOTO.|YENN CVS AHuU"C|,^2S:DEGE|O|UDEGES:oS:i-a-o!A
   (c)OYENH!A.sAE(R) *-a-o,U: 1/2D-<<O<<u`i-aNOT(CUR]'NNOTOYENun 1/4g
   $FreeBSD$ 'N|nCURF)!C

   A 1/2A:P:CURaaYENoCURCUR!AYEN^2P:.^3-L-n|^3 $FreeBSD$
   ^3o|ae!A"AYENBS:a FreeBSD Documentation Project ^3o|aeS:iNOTDEG
   The FreeBSD S:A-a-o>>y"t Documentation Project!C

   |^1YEN~!AAUYEN^2P:.YEN[CURW^2A:CURT|ae"O<<u:YENXS:A(c)OA
   1/2A:P:-a-o!A"`i(c)^3NOTOYENH^CURaa-a(c)`i
   1/2Z-a-othCUR@-a(c)YEN>>NOTDEGYENAYEN>>(c)ODEGu-a-oA 1/2A:P:!C

   |]|^1(c)O!A|e-ZCURuCURaa-a(c)(Spanish)-a-oAE(R)
   *P:}AYA^3,ONOTO-ao/^1^3^3o 1/4E!G

 <!--
      The FreeBSD Spanish Documentation Project

      $FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.sgml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
      Original revision: 1.11
 -->

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

               Chapter 10 CURaaYENo-a-o 1/4P: 1/4g.(R)ae

   YENN(c)o FreeBSD
   CURaaYENoNOTOYENN^2^3|hS:@-aI(c)O-ouAA@-a-o!ANOTDEGCURF<<O<<u
   1/4gS:@.(R)ae-a-oCUR@^3e(c)E!A (c)oNOTO'N^2-L-YENI,u|^3|@AN-a-o
   1/4gS:@^3W<<h!A 1/2D-|U|`iDEGO+-on?i|u!C

   "IYENINOTu:|!^>>y

           |PCUR@O|r|bCUR-L-|P-oO/Ath-a-o^>>y.||^3uUCUR-L-|P-a-o<<-:-ak!C
           ^1J"`i<<-:|rCUR-L-|P-a-o+-!-ap!A
           1/2D-+-A:YENINOTu:|!^>>y<<-:-ak!C ^1^3NOTO!G  1/2D-S:iYENI
           !S:color!"!A|O<<D !S:colour!"!C  1/2D-S:iYENI
           !S:rationalize!"!A|O<<D !S:rationalise!"
           uYENuYENAth|u:|r.J!C

             Note:
             YCURaa^3^1+-A:YENI^|!^>>yCUR]YENiYENH+-u"u:!A|yYEN^2P:.YENth
             1/2gCURaa^3^1^3-L-+-A:YENI|PCUR@<<-:-akCUR~|ae !C
             |OCURaaYENo-a-o"a:YENL^3!YEN-:!A^1^3NOTO(R)N!B-ooP:!B
             manual >>!(c)uuYEN<<hYEN^2P:.+-A:YENINOTu:|!^>>y!C

   CUR-L-nYENIA^2 1/4g

           1/2D-CUR-L-nA^2 1/4g(contraction)!C  1/2D-DEGEYEN^2+-NS:^1
           3/4a-a-o|r 1/4gYENX"O!C CURn|p!G !S:Don't use
           contractions!" ^3oYENy|^3YENI"`iA^2 1/4g!A'NnA *S:K!C

           YEN?|!(R)N+- 1/4g-akA *S:KA^2
           1/4g-a-o`i|]!ACURDNOTO|]NOTDEG|p|^1CUR@"O|rYENy.N<<a:,u-oe.C,!A
           YENB^1iA:P:-aI.|CURn,u>>'AP"C,!C

   YEN? 1/2T"IYENI serial comma YENHCURI^1y,^1

           ^CURaaNOTq,"^3q+-`.|^3r,^1(,)S:@NOTDEG,OYENy(c)O'-L-"`i-a-o|UP:uYENO/-a-o>>y(R)d-DEGI^1j!C
           "AYENB.||b^3I<<aCUR@O'-L-"`i-a-oP:uYENO/(R)E!AYENyYEN[CURW^3r,^1|A+-uCURW
           !S:and!"!A ^3I<<aCUR~NOTO^3I<<a-a-oP:uYENO/!C

           A|O"OCURl!ANOTYNOTYCURU+-^3oYENy!G

             This is a list of one, two and three items.

           "-o>>o^3oCUR@YENy"`i(c)^3NOTO|^3CURTOP:uYENO/(!S:one!"!B!S:two!"
           !B!S:three!")(c)O!H(c)I-aINOTOYENu|^3"aOP:uYENO/(!S:one!"!B
           !S:two and three!")(c)O!H

           |]|^1,uS:'-a-oCURe|!NOTOYENH serial comma
           -a-oCURe|!!ACUR~-`aYEN? 1/2T-ai^1F>>y.N!G

             This is a list of one, two, and three items.

           uM|O!A|bA
           1/2A:P:^1Lu{CURCUR!A<<O/A:^3S:a^3r,^1(,)^3!YEN-:S:iNOTDEG^1y,^1(!B)!A"AYENB
           !S:and!" -a-o^3!YEN-:YENi^2CUR|OCUR-L-A
           1/2!AYENHS:K>>y.N^1yP:e!C

   A *S:K"IYENIAO/uu:

           1/2D-,OuUA *S:K"IYENIAO/uu:(redundant phrase)!C CUR
           *"a:NOTO !S:^3oO<<u:YENO!"!B!S:^3oOAE(R) *!"!B!S:man
           <<u:YENO!" ^3o'XO^3q+-`^3-L-NOTOCUR-L-YEN^2n-a-oAO/uu:!C

           YENH<<u:YENO(command)CURe+-A|"O!ACURn,uS:'.i-a-oYENI-akNOTO^2A:CURGYENy-a-o"OCURl!G

           "IYENI cvsup <<u:YENO"OS:o.s`i(c)l 1/2X!C

           "IYENI cvsup "OS:o.s`i(c)l 1/2X!C

           YENHAE(R)
           *(filename)CURe+-A|"O!ACURn,uS:'.i-a-oYENI-akNOTO^2A:CURGYENy-a-o"OCURl!G

           ... |b^3oO /etc/rc.local AE(R) * ...

           ... |b /etc/rc.local AE ...

           YENH
           man(manual)CURe+-A|"O!ACURn,uS:'.i-a-oYENI-akNOTO^2A:CURGYENy(|^3YENI"`i
           SGML <citerefentry>  1/4D-AAO)!G

           1/2D-YEN' man csh <<u:YENOYENHDEGN 3/4\,O+-!>>!(c)u!C

           ,O+-! 1/2D-DEGN 3/4\ csh(1)!C

   "CYENy<<a+-YEN[CURW"aO-aAAYENO

           NOTDEGCURF"ICURaa^3^1S:o(c)o: 3/4\AA-a!AYENHCURIAAy Emacs
           CURS:Ath-a-oCURu"a(R)e(c)o:^1BYENI!A 1/2D-|b"CCUR@S:^1
           3/4aYENyCURl<<a+-YEN[CURW"aO-aAAYENO!C

           CUR-L-^1L!AYENy,^1(.)<<a+-|^3+-uCURj 1/4g|rYENA!A
           "ACUR-L-CUR@(c)w-aiYENU:<<eCUR@OYENyAI(c)O|b^3B'NNOTOS:^1
           3/4aYENyCURl!A CUR
           *"a:NOTO|W|r^3!YEN-:+-`+-`.||^3^3o^2{P:H!C ^1^3NOTO
           !S:Jordan K. Hubbard!"
           ^3oCURH|W'NNOTO<<U:|n-a-o"OAO!GYENy,^1<<a+-+-u-aAAYENO!AuM<<aNOTOCURj
           1/4g-a-o H!AuM|O^3o-aO:(c)w"ACUR-L-NOTO"aNOTqYENyCURl!C

   1/4P: 1/4g.(R)ae-a-oNOTUAo:^2O,`!AYENiDEGN 3/4\ William Strunk
   (c)O 1/4g-a-o Elements of Style!C

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

10.1 Style guide

   YENN(c)o Handbook NOTOYENN^2^3|hS:@-aI(c)O-ouAA@!ANOTDEGCURF<<O<<u
   1/4gS:@.(R)ae-a-oCUR@^3e(c)E!A  1/2D-?i|uCURU|C 1/4P: 1/4g.(R)ae!C

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

  10.1.1 CURjCURp 1/4g

   Tag -a-o^3!YEN-:^3-L-NOTOYENICURp 1/4g|rYENA!AA:'|pNOTOYENI <para>
   !A|O<<D <PARA>!C

   |O SGML CUR-oCURaa<<hNOTOYENICURj 1/4g|rYENA-aiYENU:!A^1^3NOTO!G
   <!ENTITY...> CURI <!DOCTYPE...>!A |OCUR-L-NOTO <!entity...> CURI
   <!doctype...>!C

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

  10.1.2 AY 1/4g|r

   AY
   1/4g|r(acronym)^3q+-`|b(R)NCURCUR^2A:CUR@|,'-L-"`i(R)E!AYEN^2P:.|P(R)E|CYENXS:^1
   3/4a<<-:-ak!A CURn|p!G"Network Time Protocol (NTP)"!C (c)w,qAY
   1/4g|rCURS:<<a!AA^3,O 3/4"P:qYENu"IYENI,OAY 1/4g|r(|O<<DS:^1
   3/4auu:.J!A DEG-L-<<D"IYENIS:^1
   3/4auu:.JYENiYENHS:o-`a-ai^1F>>y.N)"O-ai^1FS:YYENi!C
   ^3q+-`"CYEN>>(R)NYENu.|^2A:CUR@|,'-L-"`i(R)E!ACUR~.||CYENXS:^1
   3/4auu:.J!A
   |yY+-zDEG-a?^3CUR]YENiYENH|b"C^3^1^2A:CUR@|,'-L-"`i(R)ECURS|CYENXS:^1
   3/4auu:.J!C

   |^1YEN~!A|PCUR@AY 1/4g|r|b<<eCURT|,"IYENI(R)E!AP:."IYENI <acronym>
    1/4D-AAO!A "AS:aS:^1 3/4auu:.J-ath|b role
   A:Y(c)ECUR-oDEGu>>!(c)u!C
   |p|^1CUR@"O'N.|<<O/YENssuu:.J-ai!A"AYENB.i.AE^1<<^2 3/4|U:,OAY
   1/4g|rCURWCURe(R)E!A 'N.|AAaYENU:S:^1 3/4auu:.J!C

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

  10.1.3 AY+-AE

   uL 1/2 * AE(R) *AY+-AE^3](c)wNOTDEG|o!A "COAE(R)
   *CUR@P:}(c)l-a-oAY+-AE(indentation)^3-L-NOTO+-q 0 Aa|CP:}(c)l

   YEN 1/4S:^1-a-o 1/4D-AAO.|YENH|h"aO-aAAYENO"O 1/4WYEN[AY+-AE!A
   u^2S:A-a-o 1/4D-AAO<<hCURO:"aO-aAAYENO"OAY'iAY+-AE!C YCURw^1F 8
   O-aAAYENO!A<<hYENH tab "uYENNCURS:!C |^1YEN~!A|b tab
   <<e+-CUR-L-n|AYENI-aAAYENO!ACUR]CUR-L-n|b"C|ae<<a+-YEN[CURW-aAAYENO!C
   "CO tag
   -a-oCUR-oCURaaYP:W^1LCUR@|ae-a-o,U:!A<<h+-uCURU"O-a-o'N|h"aO-aAAYENOYENHDEGuAY+-AE!C

   A|O"OCURl!A^3o,`(c)OYENI-a-o 1/4g-akCURjPNOTOCURU+-^3o 1/4E!G

 +--- ^3oNOTO 0 Aa|C
 V
 <chapter>
   <title>...</title>

   <sect1>
     <title>...</title>

     <sect2>
       <title>AY+-AE</title>

       <para><emphasis>uL 1/2 *</emphasis> AE(R) *AY+-AE^3](c)wNOTDEG|o!A
         "COAE(R) *CUR@P:}(c)l-a-oAY+-AE(indentation)^3-L-NOTO+-q 0 Aa|CP:}(c)l!C</para>

       ...      
     </sect2>
   </sect1>
 </chapter>

   YYENI Emacs (c)I XEmacs "O 1/2s?e^3oAE!A"-o>>o.||UDEGEP:iCURJ
   sgml-mode  1/4O|!!A uM<<a'N.|+-j"i"IYENI"COAE(R)
   *^3ICURUCURe-a-oAo^1O^3](c)w!C

   Vim .RYENI-aICUR]YENiYENHYENICURU|C^3](c)w"O 1/2O 3/4a!G

 augroup sgmledit
   autocmd FileType sgml set formatoptions=cq2l " -S(R)i(R)ae|!?iP:u
   autocmd FileType sgml set textwidth=70       " |b 70 Aa|C^3BS:Y|UDEGE'<<|ae
   autocmd FileType sgml set shiftwidth=2       " |UDEGEAY+-AE 2 O-aAAYENO
   autocmd FileType sgml set softtabstop=2      " <<o: Tab .||UDEGEA`aNOTDEG"aO-aAAYENOAY+-AE
   autocmd FileType sgml set tabstop=8          " S:a 8 O-aAAYENOA`aNOTDEG tab
   autocmd FileType sgml set autoindent         " |UDEGEAY+-AE
 augroup END

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

  10.1.4 Tag .(R)ae

    10.1.4.1 Tag -aAA|ae

   |PCUR@AY+-AEuYEN-AA-a-o
   1/4D-AAOnYENH-aAACUR@|ae"ODEGuDEGI^1j!A|OCUR-L-|PAY+-AEuYEN-AA-a-o<<hCUR-L-YEN^2!C
   CURn|p!G

 <article>
   <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>

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

    10.1.4.2  1/4D-AAO-a-oCURA|ae

   ^1^3NOTO <itemizedlist> ^3oAth-a-o
   1/4D-AAO"AE^1eCURWYEN>>"CUR-L-S:tYENo|oCURaa|r,e(R)AE!AYEN^2P:.+-oYENN"a:YENL
   1/4D-AAO"O,EYENRCUR-oCURaa!C ^3oAth-a-o 1/4D-AAO.|?WYENICUR@
   3/4a|ae!C

   YENtYEN~!A^1^3NOTO <para> CURI <term> ^3oAth-a-o
   1/4D-AAO"ACUR-L->>Y.fDEGt"a:YENL 1/4D-AAO!A
   'NYENi-athCURWCURaa|r,e(R)AE!A"AYENB|b 1/4D-AAO<<a+--a-o|PCUR@|ae
   CUR-oS:YYENiYENssS:Y 1/4gCURW^3o"C,CUR-oCURaa!C

   .iuM!A^3o"aAth-a-o
   1/4D-AAOu^2S:A(R)ECUR]NOTO,oCURW+-^1D^2zNOTU|P!C

   CUR-L-^1L!A.iCURWz^3o"a-oO/
   1/4D-AAO^2VYENI(R)E!A.||^3<<U:(c)uAAa-a-oS:xAZ!C

   .i^2A:CUR@Ath 1/4D-AAO-a-o<<a+-+-uCURW^2A:CURGAth
   1/4D-AAO-a-o,U:!A "-o>>onS:a^3o"aAth 1/4D-AAO|U|UCURA|ae"O 1/4g!C
   <<a-aI 1/4D-AAO-a-oNOTq,"!A CUR]NOTO>>YnDEGu 3/4A.iAY+-AE 1/2O
   3/4a!C

   |O^2A:CURGAth 1/4D-AAOu^2S:A(R)E!AYENiYENH>>P^2A:CUR@Ath
   1/4D-AAO-a-ou^2S:A(c)n|b|PCUR@|ae!C

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

  10.1.5 -aAAYENO-a-oS:oS:i

   |b commit  *S:i(R)E!A 1/2D-S:O|b *S:iCUR-o(R)e-a-o|P(R)E!A
   CUR]CUR@DEG_S:oS:i 1/2s+-AE(R)ae|!!C

   |p|^1CUR@"O!A^1^3NOTO Handbook A
   1/2A:P:^1IP:CURCUR~-`a"^3^3tS:a:YENXS:AS:iCURFth"C,CUR-o(R)e!A
   |OCUR-L-YENIP:OCURss<<a:YENhS:PA_,O|ae-a-oS:iAAU:!ANOTOYENN(c)o(R)ae|!<<+-AE(c)I-aICUR-o(R)e^2S:DEGE!C

   A|"O>>!(c)u!AYn|bNOTYNOTqYEN[CURW"aOYENyCURl!A|p|^1CUR@"O,ONOTq,"-a-oNOTY|aeP:OYEN^2.|P:WYENX
   80 Aa|C!A^3o(R)E 1/2D-YENy commmit  *S:i!C +-uuU!A|A
   *^1-c-^1L-ao/|ae,"-a-o'<<|ae!AuM<<a|A|, commit CURS:!C
   |O^2A:CURG|,-a-o commit NOTo:?y!A 1/2D-(c)u 1/2T>>!(c)u^3oYENuNOTO
   whitespace-only ( *S:i-aAAYENO|OCURw) -a-oS:oS:i!A|p|^1CUR@"O!AA
   1/2A:P:^1IP:CUR'NYENiYENH(c)?^2CUR^2A:CURG|, commit CURF !C

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

  10.1.6 Nonbreaking space

   1/2D-A
   *S:KCUR@"C,+-!-apCURU-a-oA_|ae!G^3y|"-a(c)+-A`aA`a-a-o!B(c)INOTOP:.^3s^3e-ai^1F-a-o|PCUR@YENyCURl!C
   A_|ae-a-o+-!-ap.|AH(c)O
   3/4\AA-a-a-oCURu"aCUR-L-|P|O|^3(c)OCUR-L-|P!C CUR
   *"a:NOTO^3z^1L-ACURaa|rAsA:y 3/4^1"ONOTY HTML
   (R)E.|S:o(c)uAAaNOTY"`iAth|u:CURU+-^3o 1/4ECUR-L-|n-a-o
   1/2s+-AENOTq,"!G

 Data capacity ranges from 40 MB to 15
 GB.  Hardware compression ...

   1/2D-"IYENI &nbsp; YENHA *S:K|PYENyCURlCURS:P:!-a-oA_|ae!A
   YENHCURUYENU: 1/2d|p|o"IYENI nonbreaking spaces!G

     * |b 1/4AE|r>>P^3ae|`iCURS:P:!!G

 57600&nbsp;bps

     * |bu{|!|W-oU>>P-a(c),^1CURS:P:!!G

 FreeBSD&nbsp;4.7

     * multiword CURS:P:! ("IYENI(R)E 1/2D-CURpCURss!A^1^3NOTO !S:The
       FreeBSD Brazilian Portuguese Documentation Project!"
       ^3oAthYENNCURT"`iYEN|O|r(c)O^2O|"-a-o!A <<hCUR-L-YENIYEN[!C)!G

 Sun&nbsp;Microsystems

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

10.2 uu:.J-ai

   YENHCURUNOTDEG FreeBSD CURaaYENop^1-o
   1/2s+-AE(R)E(c)O+-A:YENI-a-oCURp<<NOTuu:.J-ai!C
   YS:a:CUR-L-"`inS:a:-a-ouu:.J!A 1/2D-DEGN 3/4\ O'Reilly word list!C

     * 2.2.X

     * 4.X-STABLE

     * CD-ROM

     * DoS (Denial of Service)

     * Ports Collection

     * IPsec

     * Internet

     * MHz

     * Soft Updates

     * Unix

     * disk label

     * email

     * file system

     * manual page

     * mail server

     * name server

     * null-modem

     * web server

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

                 Chapter 11 Using sgml-mode with Emacs

   Recent versions of Emacs or XEmacs (available from the ports
   collection) contain a very useful package called PSGML.
   Automatically invoked when a file with the .sgml extension is
   loaded, or by typing M-x sgml-mode, it is a major mode for dealing
   with SGML files, elements and attributes.

   An understanding of some of the commands provided by this mode can
   make working with SGML documents such as the Handbook much easier.

   C-c C-e

           Runs sgml-insert-element. You will be prompted for the
           name of the element to insert at the current point. You
           can use the TAB key to complete the element. Elements that
           are not valid at the current point will be disallowed.

           The start and end tags for the element will be inserted.
           If the element contains other, mandatory, elements then
           these will be inserted as well.

   C-c =

           Runs sgml-change-element-name. Place the point within an
           element and run this command. You will be prompted for the
           name of the element to change to. Both the start and end
           tags of the current element will be changed to the new
           element.

   C-c C-r

           Runs sgml-tag-region. Select some text (move to start of
           text, C-space, move to end of text, C-space) and then run
           this command. You will be prompted for the element to use.
           This element will then be inserted immediately before and
           after your marked region.

   C-c -

           Runs sgml-untag-element. Place the point within the start
           or end tag of an element you want to remove, and run this
           command. The element's start and end tags will be removed.

   C-c C-q

           Runs sgml-fill-element. Will recursively fill (i.e.,
           reformat) content from the current element in. The filling
           will affect content in which whitespace is significant,
           such as within <programlisting> elements, so run this
           command with care.

   C-c C-a

           Runs sgml-edit-attributes. Opens a second buffer
           containing a list of all the attributes for the closest
           enclosing element, and their current values. Use TAB to
           navigate between attributes, C-k to remove an existing
           value and replace it with a new one, C-c C-c to close this
           buffer and return to the main document.

   C-c C-v

           Runs sgml-validate. Prompts you to save the current
           document (if necessary) and then runs an SGML validator.
           The output from the validator is captured into a new
           buffer, and you can then navigate from one troublespot to
           the next, fixing markup errors as you go.

   C-c /

           Runs sgml-insert-end-tag. Inserts the end tag for the
           current open element.

   Doubtless there are other useful functions of this mode, but those
   are the ones I use most often.

   You can also use the following entries in .emacs to set proper
   spacing, indentation, and column width for working with the
   Documentation Project.

     (defun local-sgml-mode-hook
       (setq fill-column 70
             indent-tabs-mode nil
             next-line-add-newlines nil
             standard-indent 4
             sgml-indent-data t)
       (auto-fill-mode t)
       (setq sgml-catalog-files '("/usr/local/share/sgml/catalog")))
     (add-hook 'psgml-mode-hook
       '(lambda () (local-psgml-mode-hook)))
  

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

                      Chapter 12 YENLCURsCURS:YENU

   This document is deliberately not an exhaustive discussion of
   SGML, the DTDs listed, and the FreeBSD Documentation Project. For
   more information about these, you are encouraged to see the
   following web sites.

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

12.1 The FreeBSD Documentation Project

     * The FreeBSD Documentation Project web pages

     * The FreeBSD Handbook

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

12.2 SGML

     * The SGML/XML web page, a comprehensive SGML resource

     * Gentle introduction to SGML

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

12.3 HTML

     * The World Wide Web Consortium

     * The HTML 4.0 specification

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

12.4 DocBook

     * The DocBook Technical Committee, maintainers of the DocBook
       DTD

     * DocBook: The Definitive Guide, the online documentation for
       the DocBook DTD.

     * The DocBook Open Repository contains DSSSL stylesheets and
       other resources for people using DocBook.

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

12.5 The Linux Documentation Project

     * The Linux Documentation Project web pages

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

                          Appendix A.  1/2d"O

   YEN>>-ath?y|NOT?yCUR@"C, SGML AE
   1/2d"O!AYENHCURIYENI"OA`a'<<(R)ae|!-a-oNOTUAo:<<u:YENO!C
   YCURw|"YEN\|w,ECURaaYENopueCURu"aYEN]-a-o,U:!A"-o>>o'NYENiYENH-a
   1/2+-u.OCURU+- 1/2d"O"O"IYENI!C

   ^3o"C,"OCURl"ACUR-L-NOTO<<U:,O^2O !X!X "AYEN
   1/4YEN]NOTAS:AYENi-`a.QYENI-a-oCUR,YENo!A CUR
   *"a:^1^3NOTOS:ACURaaYENo-a-o<<eP:(YEN?CURaa<<e-a-o(R)NP:!AYEN]NOTA'vP:!BS:C,"YEN!BYENO/?yuYEN)
   Y>>YDEGN|OS:o|h DocBook 
   1/4D-DEGO>>y"YENCURaaYENo-a-o,U:!A"-o>>oYENiYENH^3z^1L CSup!BCVSup
   u{|!"OS:`i doc tree
   ^3!CURA!AYENH^1iNOTYYEN>>CURaaYENo(c)I"a:YENLCURaaYENo-a-o SGML `i
   1/2Z!C (c)I-aI!ACUR]YENiYENH 1/2uCURWAsA:y
   http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/!C

   NOTDEGCURFA *S:KCUR-L-YEN^2n-a-oS:xAZ!A^3o"C,"OCURl+-A:YENI
   1/4D-.C,-a-o DocBook 4.1 DTD |O<<D FreeBSD ABYEN~-a-o DTD!C
   |P(R)E"A+-A:YENI Norm Walsh CURo-a-o 1/4E|!-ai(stylesheets)!A|O<<D
   FreeBSD CURaaYENop^1-o|^3|U|aeS:i^1L-a-o 1/4E|!-ai!C
   |bCUR@-e"IYENI DocBook -a-o"OCURl!A^3o
   1/4ECURl.|CURn,uA^2CURAEAo^1O!A|OCUR-L-.|^3y|"ABYEN~S:xAZ!C

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

A.1 DocBook <book>

   Example A-1. DocBook <book>

 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <book>
   <bookinfo>
     <title> 1/4EYEN>>(R)N-a-o"OCURl</title>
    
     <author>
       <firstname>|W(first name)</firstname>
       <surname>(c)m(surname)</surname>
       <affiliation>
         <address><email>foo@example.com</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>NOTUAo:-a(c)AAv|r 1/4E</holder>
     </copyright>

     <abstract>
       <para>,O(R)NY|^3-oKn!A'N 1/4g|b^3oAa:!C</para>
     </abstract>
   </bookinfo>

   <preface>
     <title>S:C,"YEN</title>

     <para>,O(R)NY|^3S:C,"YEN!A'N(c)n|b^3oAa:!C</para>
   </preface>
      
   <chapter>
     <title>^2A:CUR@^3^1</title>

     <para>^3oNOTO^3oYEN>>(R)N-a-o^2A:CUR@^3^1!C</para>

     <sect1>
       <title>^2A:CUR@,`</title>

       <para>^3oYEN>>(R)N-a-o^2A:CUR@,`!C</para>
     </sect1>
   </chapter>
 </book>

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

A.2 DocBook <article>

   Example A-2. DocBook <article>

 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

 <article>
   <articleinfo>
     <title>CURaa^3^1 1/4EYEN>></title>

     <author>
       <firstname>|W(first name)</firstname>
       <surname>(c)m(surname)</surname>
       <affiliation>
         <address><email>foo@example.com</email></address>
       </affiliation>
     </author>

     <copyright>
       <year>2000</year>
       <holder>NOTUAo:-a(c)AAv|r 1/4E</holder>
     </copyright>

     <abstract>
       <para>,OCURaa^3^1Y|^3-oKn!A'N 1/4g|b^3oAa:!C</para>
     </abstract>
   </articleinfo>

   <sect1>
     <title>^2A:CUR@,`</title>

     <para>,OCURaa^3^1-a-o^2A:CUR@,`!C</para>

     <sect2>
       <title>^2A:CUR@CURp,`(sub-section)</title>

       <para>,OCURaa^3^1-a-o^2A:CUR@CURp,`(sub-section)</para>
     </sect2>   
   </sect1>
 </article>

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

A.3 Producing formatted output

   YEN>>,`|^3"C,<<e'-L-!ADEG^2^3]!GCURw,g|^3,E textproc/docproj
   CURW+-(c)O|w,E|U^3nAAe!AuL 1/2 *YEN|INOTOYENI port
   CURe|!|w,E(c)INOTOCURaDEGE|w,E!C
   |^1YEN~!ADEG^2^3](c)O,E-a-o^3nAAe^3-L-(c)n|b /usr/local/
   CURU-a-oCURlYENO/?y!A
   "AYENB(c)O|w,E-a-oNOTUAo:DEGo|aeAE!A^3-L-|^3,E|bS:A-a-o PATH
   Ao^1OAAU: 1/4AECUR-o-a-oYENO/?y!C |p|^3YEN^2n-a-o,U:!A
   1/2D-"IS:A-a-o"t^2IAo^1O|O 1/2O 3/4aNOTUAo:,o(R)|!C

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

  A.3.1 "IYENI Jade

   Example A-3. A`a'<< DocBook NOTDEG HTML (S:^1 3/4a 1/4O|!)

 % jade -V nochunks \  (1)
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ (2)
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \(3)
     -t sgml (4) file.sgml > file.html (5)

   (1)
           Specifies the nochunks parameter to the stylesheets,
           forcing all output to be written to STDOUT (using Norm
           Walsh's stylesheets).
   (2)
           Specifies the catalogs that Jade will need to process.
           Three catalogs are required. The first is a catalog that
           contains information about the DSSSL stylesheets. The
           second contains information about the DocBook DTD. The
           third contains information specific to Jade.
   (3)
           Specifies the full path to the DSSSL stylesheet that Jade
           will use when processing the document.
   (4)
           Instructs Jade to perform a transformation from one DTD to
           another. In this case, the input is being transformed from
           the DocBook DTD to the HTML DTD.
   (5)
           Specifies the file that Jade should process, and redirects
           output to the specified .html file.

   Example A-4. A`a'<< DocBook NOTDEG HTML (^3^1,` 1/4O|!)

 % jade \
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ (1)
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/html/docbook.dsl \(2)
     -t sgml (3) file.sgml (4)

   (1)
           Specifies the catalogs that Jade will need to process.
           Three catalogs are required. The first is a catalog that
           contains information about the DSSSL stylesheets. The
           second contains information about the DocBook DTD. The
           third contains information specific to Jade.
   (2)
           Specifies the full path to the DSSSL stylesheet that Jade
           will use when processing the document.
   (3)
           Instructs Jade to perform a transformation from one DTD to
           another. In this case, the input is being transformed from
           the DocBook DTD to the HTML DTD.
   (4)
           Specifies the file that Jade should process. The
           stylesheets determine how the individual HTML files will
           be named, and the name of the !S:root!" file (i.e., the
           one that contains the start of the document.

   This example may still only generate one HTML file, depending on
   the structure of the document you are processing, and the
   stylesheet's rules for splitting output.

   Example A-5. A`a'<< DocBook NOTDEG Postscript(PS) (R)ae|!

   The source SGML file must be converted to a TeX file.

 % jade -Vtex-backend \ (1)
     -c /usr/local/share/sgml/docbook/dsssl/modular/catalog \ (2)
     -c /usr/local/share/sgml/docbook/catalog \
     -c /usr/local/share/sgml/jade/catalog \
     -d /usr/local/share/sgml/docbook/dsssl/modular/print/docbook.dsl \(3)
     -t tex (4) file.sgml

   (1)
           Customizes the stylesheets to use various options specific
           to producing output for TeX.
   (2)
           Specifies the catalogs that Jade will need to process.
           Three catalogs are required. The first is a catalog that
           contains information about the DSSSL stylesheets. The
           second contains information about the DocBook DTD. The
           third contains information specific to Jade.
   (3)
           Specifies the full path to the DSSSL stylesheet that Jade
           will use when processing the document.
   (4)
           Instructs Jade to convert the output to TeX.

   The generated .tex file must now be run through tex, specifying
   the &jadetex macro package.

 % tex "&jadetex" file.tex

   You have to run tex at least three times. The first run processes
   the document, and determines areas of the document which are
   referenced from other parts of the document, for use in indexing,
   and so on.

   Do not be alarmed if you see warning messages such as LaTeX
   Warning: Reference `136' on page 5 undefined on input line 728. at
   this point.

   The second run reprocesses the document now that certain pieces of
   information are known (such as the document's page length). This
   allows index entries and other cross-references to be fixed up.

   The third pass performs any final cleanup necessary.

   The output from this stage will be file.dvi.

   Finally, run dvips to convert the .dvi file to Postscript.

 % dvips -o file.ps file.dvi

   Example A-6. A`a'<< DocBook NOTDEG PDF (R)ae|!

   The first part of this process is identical to that when
   converting DocBook to Postscript, using the same jade command line
   (Example A-5).

   When the .tex file has been generated you run pdfTeX. However, use
   the &pdfjadetex macro package instead.

 % pdftex "&pdfjadetex" file.tex

   Again, run this command three times.

   This will generate file.pdf, which does not need to be processed
   any further.

  Notes

   [1] Parameter entities use the Percent symbol.                     
   [2] This is a shame. Imagine all the problems and hacks (such as   
       Server Side Includes) that could be avoided if they did.       
   [3] A short history can be found under                             
       http://www.oasis-open.org/committees/docbook/intro.shtml.      
   [4] There are other types of list element in DocBook, but we are   
       not concerned with those at the moment.                        

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

YEN>>CURaaCURI"a:YENLCURaaYENo!AYENiYENN|^1CURU,u:!Gftp://ftp.FreeBSD.org/pub/FreeBSD/doc/!C

        Y|^3 FreeBSD CURe+--oADEGY!A 1/2D-YENy 3/4\AA-a FreeBSD
         NOTUAo:CURaaYENo!A|pCUR-L--`a,N"M-a-o,U:!A|ANOT-c-,ss
                       <questions@FreeBSD.org>!C
  Ao:(c)oYEN>>CURaaYENo-a-oDEGYAD!A 1/2D-NOT-c-,ss <doc@FreeBSD.org>!C
