diff options
43 files changed, 15417 insertions, 0 deletions
diff --git a/en/tutorials/docproj-primer/Makefile b/en/tutorials/docproj-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en/tutorials/docproj-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en/tutorials/docproj-primer/book.sgml b/en/tutorials/docproj-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en/tutorials/docproj-primer/book.sgml @@ -0,0 +1,278 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +]> + +<book> + <bookinfo> + <title>FreeBSD Documentation Project Primer for New Contributors</title> + + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + <affiliation> + <address><email>nik@FreeBSD.ORG</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <year>1999</year> + <holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder> + </copyright> + + <pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate> + + <releaseinfo>$ID$</releaseinfo> + + <legalnotice> + <para>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:</para> + + <orderedlist> + <listitem> + <para>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.</para> + </listitem> + + <listitem> + <para>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.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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.</para> + </important> + </legalnotice> + + <abstract> + <para>Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable.</para> + + <para>This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project.</para> + + <para>This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + <literal>*</literal> in their name.</para> + </abstract> + </bookinfo> + + <preface> + <title>Preface</title> + + <sect1> + <title>Shell Prompts</title> + + <para>The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>User</entry> + <entry>Prompt</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Normal user</entry> + <entry>&prompt.user;</entry> + </row> + + <row> + <entry><username>root</username></entry> + <entry>&prompt.root;</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Typographic Conventions</title> + + <para>The following table describes the typographic conventions used in + this book.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Meaning</entry> + <entry>Examples</entry> + </row> + </thead> + + <tbody> + <row> + <entry>The name of commands, files, and directories. On screen + computer output.</entry> + <entry><para>Edit your <filename>.login</filename> + file.</para><para>Use <command>ls -a</command> to list all + files.</para><para><screen>You have mail.</screen> + </para></entry> + </row> + + <row> + <entry>What you type, when contrasted with on-screen computer + output.</entry> + + <entry><screen>&prompt.user; <userinput>su</userinput> +Password:</screen></entry> + </row> + + <row> + <entry>Manual page references.</entry> + + <entry>Use <citerefentry> + <refentrytitle>su</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> to change user names.</entry> + </row> + + <row> + <entry>User and group names</entry> + + <entry>Only <username>root</username> can do this.</entry> + </row> + + <row> + <entry>Emphasis</entry> + + <entry>You <emphasis>must</emphasis> do this.</entry> + </row> + + <row> + <entry>Command line variables; replace with the real name or + variable.</entry> + + <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> + </row> + + <row> + <entry>Environment variables</entry> + + <entry><envar>$HOME</envar> is your home directory.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Notes, warnings, and examples</title> + + <para>Within the text appear notes, warnings, and examples.</para> + + <note> + <para>Notes are represented like this, and contain information that + you should take note of, as it may affect what you do.</para> + </note> + + <warning> + <para>Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files.</para> + </warning> + + <example> + <title>A sample example</title> + + <para>Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be.</para> + </example> + </sect1> + + <sect1> + <title>Acknowledgments</title> + + <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms.</para> + </sect1> + </preface> + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/en/tutorials/docproj-primer/chapter.decl b/en/tutorials/docproj-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en/tutorials/docproj-primer/chapter.decl @@ -0,0 +1 @@ +<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"> diff --git a/en/tutorials/docproj-primer/chapters.ent b/en/tutorials/docproj-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en/tutorials/docproj-primer/chapters.ent @@ -0,0 +1,22 @@ +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .sgml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $Id: chapters.ent,v 1.1 1999-04-20 20:59:49 nik Exp $ +--> + +<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> +<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> +<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> +<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml"> +<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> +<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> diff --git a/en/tutorials/docproj-primer/overview/chapter.sgml b/en/tutorials/docproj-primer/overview/chapter.sgml new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en/tutorials/docproj-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="overview"> + <title>Overview</title> + + <para>Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success.</para> + + <para>After you have read this primer you should;</para> + + <itemizedlist> + <listitem> + <para>Have an understanding of the text formats used by the + Documentation Project, and why they were chosen.</para> + </listitem> + + <listitem> + <para>Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats.</para> + </listitem> + + <listitem> + <para>Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them.</para> + </listitem> + </itemizedlist> + + <para>This primer assumes that you already understand;</para> + + <itemizedlist> + <listitem> + <para>How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files.</para> + + <para>Alternatively, how to retrieve versions of files using the + <application>CVSWeb</application> interface.</para> + </listitem> + + <listitem> + <para>How to use the ports system to download and install new + software.</para> + </listitem> + </itemizedlist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/psgml-mode/chapter.sgml b/en/tutorials/docproj-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en/tutorials/docproj-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="psgml-mode"> + <title>Using <literal>sgml-mode</literal> with + <application>Emacs</application></title> + + <para>Recent versions of Emacs or Xemacs (available from the ports + collection) contain a very useful package called PSGML. Automatically + invoked when a file with <filename>.sgml</filename> extension is loaded, + or by typing <command>M-x sgml-mode</command>, it is a major mode for + dealing with SGML files, elements and attributes.</para> + + <para>An understanding of some of the commands provided by this mode can + make working with SGML documents such as the Handbook much easier.</para> + + <variablelist> + <varlistentry> + <term><command>C-c C-e</command></term> + + <listitem> + <para>Runs <literal>sgml-insert-element</literal>. 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.</para> + + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c =</command></term> + + <listitem> + <para>Runs <literal>sgml-change-element-name</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-r</command></term> + + <listitem> + <para>Runs <literal>sgml-tag-region</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c -</command></term> + + <listitem> + <para>Runs <literal>sgml-untag-element</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-q</command></term> + + <listitem> + <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill + (i.e., reformat) content from the current element in. The filling + <emphasis>will</emphasis> affect content in which whitespace is + significant, such as within <sgmltag>programlisting</sgmltag> + elements, so run this command with care.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-a</command></term> + + <listitem> + <para>Runs <literal>sgml-edit-attributes</literal>. 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, <command>C-k</command> to remove an existing + value and replace it with a new one, <command>C-c</command> to close + this buffer and return to the main document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-v</command></term> + + <listitem> + <para>Runs <literal>sgml-validate</literal>. 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.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Doubtless there are other useful functions of this mode, but those are + the ones I use most often.</para> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/see-also/chapter.sgml b/en/tutorials/docproj-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en/tutorials/docproj-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="see-also"> + <title>See Also</title> + + <para>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.</para> + + <sect1> + <title>The FreeBSD Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD + Documentation Project web pages</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>SGML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web + page</ulink>, a comprehensive SGML resource</para> + </listitem> + + <listitem> + <para><ulink + url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.w3.org/">The World Wide Web + organisation</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 + specification</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oreilly.com/davenport/">The Davenport + Group</ulink>, maintainers of the DocBook DTD</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>The Linux Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation + Project web pages</ulink></para> + </listitem> + </itemizedlist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/sgml-markup/chapter.sgml b/en/tutorials/docproj-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en/tutorials/docproj-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-markup"> + <title>SGML Markup</title> + + <para>This chapter describes the three 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.</para> + + <para>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.</para> + + <para>This is <emphasis>not</emphasis> 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 mailing list + <email>freebsd-doc@freebsd.org</email>.</para> + + <note> + <title>Inline vs. block</title> + + <para>In the remainder of this document, when describing elements, + <emphasis>inline</emphasis> means that the element can occur within a + block element, and does not cause a line break. A + <emphasis>block</emphasis> element, by comparison, will cause a line + break (and other processing) when it is encountered.</para> + </note> + + <sect1> + <title>HTML</title> + + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML is used to markup pages on the FreeBSD web site. It should not + (generally) be used to mark up other documention, 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.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the + latest, 4.0 (available in both <emphasis>strict</emphasis> and + <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> port. They are automatically + installed as part of the <filename>textproc/docproj</filename> port.</para> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>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.</para> + + <para>The majority of HTML documents on the FreeBSD web site comply with + the loose version of HTML 4.0.</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>An HTML document is normally split in to two sections. The first + section, called the <emphasis>head</emphasis>, 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 + <emphasis>body</emphasis>, contains the content that will be displayed + to the user.</para> + + <para>These sections are indicated with <sgmltag>head</sgmltag> and + <sgmltag>body</sgmltag> elements respectively. These elements are + contained within the top-level <sgmltag>html</sgmltag> element.</para> + + <example> + <title>Normal HTML document structure</title> + + <programlisting> +<html> + <head> + <title><replaceable>The document's title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Headings</title> + + <para>HTML allows you to denote headings in your document, at up to + six different levels.</para> + + <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, + then <sgmltag>h2</sgmltag>, continuing down to + <sgmltag>h6</sgmltag>.</para> + + <para>The element's content is the text of the heading.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 -->]]></programlisting> + </example> + + <para>Generally, an HTML page should have one first level heading + (<sgmltag>h1</sgmltag>). This can contain many second level headings + (<sgmltag>h2</sgmltag>), which can in turn contain many third level + headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> + element should have the same element, but one further up the + hierarchy, preceeding it. Leaving gaps in the numbering is to be + avoided.</para> + + <example> + <title>Bad ordering of + <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<h1>First section</h1> + +<!-- Document introduction --> + +<h3>Sub-section</h3> + +<!-- This is bad, <h2> has been left out -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Paragraphs</title> + + <para>HTML supports a single paragraph element, + <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>A block quotation is an extended quotation from another document + that should not appear within the current paragraph.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Lists</title> + + <para>You can present the user with three types of lists, ordered, + unordered, and definition.</para> + + <para>Typically, each entry in an ordered list will be numbered, while + each entry in an unordered list will be proceeded 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.</para> + + <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> + element, unordered lists by the <sgmltag>ul</sgmltag> element, and + definition lists by the <sgmltag>dl</sgmltag> element.</para> + + <para>Ordered and unordered lists contain listitems, indicated by the + <sgmltag>li</sgmltag> element. A listitem can contain textual + content, or it may be further wrapped in one or more + <sgmltag>p</sgmltag> elements.</para> + + <para>Definition lists contain definition terms + (<sgmltag>dt</sgmltag>) and definition descriptions + (<sgmltag>dd</sgmltag>). A definition term can only contain inline + elements. A definition description can contain other block + elements.</para> + + <example> + <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>An unordered list. Listitems will probably be + preceeded 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>]]></programlisting> + </example> + + <example> + <title>Definition lists with <sgmltag>dl</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p></dd> + + <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>Paragraph 1 of definition 3. Note that the <p> + element is not required in the single paragraph case.</dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Pre-formatted text</title> + + <para>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 in to one, and line + breaks in the text are significant.</para> + + <para>In order to do this, wrap the content in the + <sgmltag>pre</sgmltag> element.</para> + + <example> + <title><sgmltag>pre</sgmltag></title> + + <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail + message;</para> + + <programlisting> +<![ CDATA [<pre> + From: nik@freebsd.org + To: freebsd-doc@freebsd.org + Subject: New documentation available + + There's a new copy of my primer for contributers to the FreeBSD + Documentation Project available at + + <URL:http://www.freebsd.org/~nik/primer/index.html> + + Comments appreciated. + + N +</pre>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Tables</title> + + <note> + <para>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.</para> + </note> + + <para>Mark up tabular information using the <sgmltag>table</sgmltag> + element. A table consists of one or more table rows + (<sgmltag>tr</sgmltag>), each containing one or more cells of table + data (<sgmltag>td</sgmltag>). 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 + <sgmltag>p</sgmltag> element.</para> + + <example> + <title>Simple use of <sgmltag>table</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting></example> + + <para>A cell can span multiple rows and columns. To indicate this, add + the <literal>rowspan</literal> and/or <literal>colspan</literal> + attributes, with values indicating the number of rows of columns + that should be spanned.</para> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>colspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>rowspan</literal> and + <literal>colspan</literal> together</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged in to 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 in to + 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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>You have two levels of emphasis available in HTML, + <sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal + level of emphasis and <sgmltag>strong</sgmltag> indicates stronger + emphasis.</para> + + <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and + <sgmltag>strong</sgmltag> is rendered in bold. This is not always + the case however, and you should not rely on it.</para> + + <example> + <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><em>This</em> has been emphasised, while + <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Bold and italics</title> + + <para>Because HTML includes presentational markup, you can also + indicate that particular content should be rendered in bold or + italic. The elements are <sgmltag>b</sgmltag> and + <sgmltag>i</sgmltag> respectively.</para> + + <example> + <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> + + <programlisting> +<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + in italics.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating fixed pitch text</title> + + <para>If you have content that should be rendered in a fixed pitch + (typewriter) typeface, use <sgmltag>tt</sgmltag> (for + “teletype”).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This document was originally written by + Nik Clayton, who can be reached by e-mail as + <tt>nik@freebsd.org</tt>.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Content size</title> + + <para>You can indicate that content should be shown in a larger or + smaller font. There are three ways of doing this.</para> + + <orderedlist> + <listitem> + <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> + around the content you wish to change size. These tags can be + nested, so <literal><big><big>This is much + bigger</big></big></literal> is possible.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to <literal>+1</literal> or <literal>-1</literal> + respectively. This has the same effect as using + <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the + use of this approach is deprecated.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to a number between 1 and 7. The default font size + is <literal>3</literal>. This approach is deprecated.</para> + </listitem> + </orderedlist> + + <example> + <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and + <sgmltag>font</sgmltag></title> + + <para>The following fragments all do the same thing.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other documents on the WWW</title> + + <para>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.</para> + + <para>The link is indicated with <sgmltag>a</sgmltag>, and the + <literal>href</literal> 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 + colour, different mouse cursor when over the link, and so on).</para> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>More information is available at the + <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting> + </example> + + <para>These links will take the user to the top of the chosen + document.</para> + </sect3> + + <sect3> + <title>Linking to other parts of documents</title> + + <para>Linking to a point within another document (or within the same + document) requires that the document author include anchors that you + can link to.</para> + + <para>Anchors are indicated with <sgmltag>a</sgmltag> and the + <literal>name</literal> attribute instead of + <literal>href</literal>.</para> + + <example> + <title>Using <literal><a name="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + in other links with the name <tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>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 + <literal>#</literal> symbol.</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in a + document called <filename>foo.html</filename>.</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="foo.html#para1">first paragraph</a> of + <tt>foo.html</tt>.</p>]]></programlisting> + </example> + + <para>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 preceeding <literal>#</literal>).</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in + this document</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="#para1">first paragraph</a> of this + document.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>DocBook</title> + + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be + a DTD for writing technical documentation. As such, and unlike LinuxDoc + and HTML, DocBook is very heavily orientated towards markup that + describes <emphasis>what</emphasis> something is, rather than describing + <emphasis>how</emphasis> it should be presented.</para> + + <note> + <title><literal>formal</literal> vs. <literal>informal</literal></title> + + <para>Some elements may exist in two forms, <emphasis>formal</emphasis> + and <emphasis>informal</emphasis>. Typically, the formal version of + the element will consist of a title followed by the information + version of the element. The informal version will not have a + title.</para> + </note> + + <para>The DocBook DTD is available from the ports collection in the + <filename>textproc/docbook</filename> port. It is automatically + installed as part of the <filename>textproc/docproj</filename> + port.</para> + + <sect2> + <title>FreeBSD extensions</title> + + <para>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.</para> + + <para>Where a FreeBSD specific element is listed below it is clearly + marked.</para> + + <para>Throughout the rest of this document, the term + “DocBook” is used to mean the FreeBSD extended DocBook + DTD.</para> + + <note> + <para>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 Nik Clayton <email>nik@freebsd.org</email>.</para> + </note> + </sect2> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing FPIs for + DocBook customisations, the FPI for the FreeBSD extended DocBook DTD + is;</para> + + <programlisting> +PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>DocBook contains a number of elements for marking up the structure + of a book.</para> + + <para>Generally, the top level (first) element will be + <sgmltag>book</sgmltag>.</para> + + <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a + mandatory requirement. There may be <sgmltag>part</sgmltag>s between + the book and the chapter to provide another layer of organisation. The + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. These are + indicated with the <sgmltag>sect1</sgmltag> element. If a section + contains another section then use the <sgmltag>sect2</sgmltag> + element, and so on, up to <sgmltag>sect5</sgmltag>.</para> + + <para>Chapters and sections contain the remainder of the content.</para> + + <sect3> + <title>Starting a book</title> + + <para>The content of the book is contained within the + <sgmltag>book</sgmltag> 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.</para> + + <para>This additional information should be contained within + <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting> +<book> + <bookinfo> + <title><replaceable>Your title here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating chapters</title> + + <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each + chapter has a mandatory <sgmltag>title</sgmltag>.</para> + + <example> + <title>A simple chapter</title> + + <programlisting> +<![ CDATA [<chapter> + <title>The chapter's title</title> + + ... +</chapter>]]></programlisting> + </example> + + <para>A chapter can not be empty, it must contain elements in addition + to <sgmltag>title</sgmltag>. If you need to include an empty chapter + then just use an empty paragraph.</para> + + <example> + <title>Empty chapters</title> + + <programlisting> +<![ CDATA [<chapter> + <title>This is an empty chapter</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sections below chapters</title> + + <para>Chapters can be broken up into sections, subsections, and so + on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> + element. The <replaceable>n</replaceable> indicates the section + number, which identifies the section level.</para> + + <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is + <sgmltag>sect1</sgmltag>. You can have one or more of these in a + chapter. They can contain one or more <sgmltag>sect2</sgmltag> + elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> + + <example> + <title>Sections in chapters</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Subdividing using <sgmltag>part</sgmltag>s</title> + + <para>You can introduce another layer of organisation between + <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or + more <sgmltag>part</sgmltag>s.</para> + + <programlisting> +<![ CDATA [<part> + <title>Introduction</title> + + <chapter> + <title>Overview</title> + + ... + </chapter> + + <chapter> + <title>What is FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>History</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs; + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and + <sgmltag>simpara</sgmltag>.</para> + + <para>Most of the time you will only need to use + <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a + <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> + disallows some elements from within <sgmltag>para</sgmltag>. Stick + with <sgmltag>para</sgmltag>.</para> + + <example> + <title><sgmltag>para</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>This is a paragraph. It can contain just about any + other element.</para> ]]></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any other + element.</para> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>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.</para> + + <para>Blockquotes can optionally contain a title and an attribution + (or they can be left untitled and unattributed).</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>A small excerpt from the US Constitution;</para> + +<blockquote> + <title>Preamble to the Constitution of the United States</para> + + <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>]]></programlisting> + + <para>Appearance:</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> + </example> + </sect3> + + <sect3> + <title>Tips, notes, warnings, cautions, important information and + sidebars.</title> + + <para>You may need to include extra information separate from the + main body of the text. Typically this is “meta” + information that the user should be aware of.</para> + + <para>Depending on the nature of the information, one of + <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, + <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and + <sgmltag>important</sgmltag> should be used. Alternatively, if the + information is related to the main text but is not one of the above, + use <sgmltag>sidebar</sgmltag>.</para> + + <para>The circumstances in which to choose one of these elements over + another is unclear. The DocBook documentation suggests;</para> + + <itemizedlist> + <listitem> + <para>A Note is for information that should be heeded by all + readers.</para> + </listitem> + + <listitem> + <para>An Important element is a variation on Note.</para> + </listitem> + + <listitem> + <para>A Caution is for information regarding possible data loss + or software damage.</para> + </listitem> + + <listitem> + <para>A Warning is for information regarding possible hardware + damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + harddisk.</para> +</warning>]]></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows from + your harddisk.</para> + </warning> + </sect3> + + <sect3> + <title>Lists and procedures</title> + + <para>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.</para> + + <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, or + <sgmltag>procedure</sgmltag><footnote><para>There are other types of + list element in DocBook, but we're not concerned with those at + the moment.</para> + </footnote> + </para> + + <para><sgmltag>itemizedlist</sgmltag> and + <sgmltag>orderedlist</sgmltag> are similar to the counterparts in + HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one + consists of one or more <sgmltag>listentry</sgmltag> elements, and + each <sgmltag>listentry</sgmltag> contains one or more block + elements. The <sgmltag>listentry</sgmltag> elements are analagous to + HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are + required.</para> + + <para><sgmltag>procedure</sgmltag> is slightly different. It consists + of <sgmltag>step</sgmltag>s, which may in turn consists of more + <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each + <sgmltag>step</sgmltag> contains block elements.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing file samples</title> + + <para>If you want to show a fragment of a file (or perhaps a complete + file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> + element.</para> + + <para>White space and line breaks within + <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> + significant. In particular, this means that the closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will be included.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA[<para>When you have finished, your program should look like + this;</para> + +<programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by their + entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this;</para> + + <programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + + <note> + <para>There is a mechanism within DocBook for referring to sections + of a previously occuring <sgmltag>programlisting</sgmltag>, called + callouts (see <sgmltag>programlistingco</sgmltag> for more + information). I don't fully understand (i.e., have never used) + this feature, so can't document it here. For the mean time, you + can include line numbers within the content, and then refer to + them later on in your description. That will change, as soon as I + find the time to understand and document callouts.</para> + </note> + </sect3> + + <sect3> + <title>Tables</title> + + <para>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.</para> + + <para>In general terms (and see the DocBook documentation for more + detail) a table (which can be either formal or informal) consists of + a <sgmltag>table</sgmltag> element. This contains at least one + <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) + the number of columns in this table group. Within the tablegroup you + can then have one <sgmltag>thead</sgmltag> element, which contains + elements for the table headings (column headings), and one + <sgmltag>tbody</sgmltag> which contains the body of the + table.</para> + + <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> + contain <sgmltag>row</sgmltag> elements, which in turn contain + <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> + element specifies one cell in the table.</para> + + <example> + <title><sgmltag>informaltable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informaltable> + <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>]]></programlisting> + + <para>Appearance:</para> + + <informaltable> + <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> + </example> + + <para>If you don't want a border around the table the + <literal>frame</literal> attribute can be added to the + <sgmltag>informaltable</sgmltag> element with a value of + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + <example> + <title>Tables where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none"> + <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> + </example> + </sect3> + + <sect3> + <title>Examples for the user to follow</title> + + <para>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.</para> + + <para>A number of distinct elements and entities come in to play + here.</para> + + <variablelist> + <varlistentry> + <term><sgmltag>informalexample</sgmltag></term> + + <listitem> + <para>Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be <sgmltag>informalexample</sgmltag>. For those times + when you do need to include a title on the example, use + <sgmltag>example</sgmltag>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Everything the user sees in this example will be on the + computer screen, so the next element is + <sgmltag>screen</sgmltag>.</para> + + <para>Within <sgmltag>screen</sgmltag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the screen + are prompts from the computer (either from the OS, command + shell, or application. These should be marked up using + <sgmltag>prompt</sgmltag>.</para> + + <para>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 <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. They do not + need to be inside <sgmltag>prompt</sgmltag>.</para> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the original + DTD.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>When displaying text that the user should type in, wrap it + in <sgmltag>userinput</sgmltag> tags. It will probably be + displayed differently to the user.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>informalexample</sgmltag>, + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <sgmltag>userinput</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <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> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <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> + </informalexample> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> marked + up as <sgmltag>programlisting</sgmltag>. Reserve + <sgmltag>programlisting</sgmltag> for showing fragments of files + outside the context of user actions.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>When you want to emphasise a particular word or phrase, use + <sgmltag>emphasis</sgmltag>. This may be presented as italic, or + bold, or might be spoken differently with a text-to-speech + system.</para> + + <para>There is no way to change the presentation of the emphasis + within your document, no equivalent of HTML's <sgmltag>b</sgmltag> + and <sgmltag>i</sgmltag>. If the information you are presenting is + important then consider presenting it in + <sgmltag>important</sgmltag> rather than + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix + like operating system for the Intel architecture.</para> + </example> + </sect3> + + <sect3> + <title>Applications, commands, options, and cites</title> + + <para>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.</para> + + <para>In addition, you will occasionally need to list one or more of + the options that a command might take.</para> + + <para>Finally, you will often want to list a command with it's manual + section number, in the “command(number)” format so + common in Unix manuals.</para> + + <para>Mark up application names with + <sgmltag>application</sgmltag>.</para> + + <para>When you want to list a command with it's manual section number + (which should be most of the time) the DocBook element is + <sgmltag>citerefentry</sgmltag>. This will contain a further two + elements, <sgmltag>refentrytitle</sgmltag> and + <sgmltag>manvolnum</sgmltag>. The content of + <sgmltag>refentrytitle</sgmltag> is the name of the command, and the + content of <sgmltag>manvolnum</sgmltag> is the manual page + section.</para> + + <para>This can be cumbersome to write, and so a series of <link + linkend="general-entities">general entities</link> have been + created to make this easier. Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/sgml/man-refs.ent</filename>, and can be + referred to using this FPI;</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to your documentation will probably + look like this;</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]]></programlisting> + + <para>Use <sgmltag>command</sgmltag> when you want to include a + command name “in-line” but present it as something the + user should type in.</para> + + <para>Use <sgmltag>option</sgmltag> to mark up a command's + options.</para> + + <para>This can be confusing, and sometimes the choice is not always + clear. Hopefully this example makes it clearer.</para> + + <example> + <title>Applications, commands, and options.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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.sendmail.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>]]></programlisting> + + <para>Appearance:</para> + + <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>, <citerefentry> + <refentrytitle>mailq</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, and <citerefentry> + <refentrytitle>newaliases</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> 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> + </example> + + <note> + <para>Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> + </note> + </sect3> + + <sect3> + <title>Files, directories, extensions</title> + + <para>Whenever you wish to refer to the name of a file, a directory, + or a file extension, use <sgmltag>filename</sgmltag>.</para> + + <example> + <title><sgmltag>filename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Devices</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When referring to devices you have two choices. You can either + refer to the device as it appears in <filename>/dev</filename>, or + you can use the name of the device as it appears in the kernel. For + this latter course, use <sgmltag>devicename</sgmltag>.</para> + + <para>Sometimes you will not have a choice. Some devices, such as + networking cards, do not have entries in <filename>/dev</filename>, + or the entries are markedly different from those entries.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Hosts, domains, IP addresses, and so forth</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>You can markup identification information for networked + computers (hosts) in several ways, depending on the nature of the + information. All of them use <sgmltag>hostid</sgmltag> as the + element, with the <literal>role</literal> attribute selecting the + type of the marked up information.</para> + + <variablelist> + <varlistentry> + <term>No role attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no role attribute (i.e., + <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the + marked up information is the simple hostname, such as + <literal>freefall</literal> or <literal>wcarchive</literal>. + You can explicitly specify this with + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>freebsd.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with both + hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>The text is an IP address, probably expressed as a dotted + quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be expressed as a + dotted quad, a hexadecimal string, or as a + <literal>/</literal> followed by a number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an ethernet MAC address, expressed as a series + of 2 digit hexadecimal numbers seperated by colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>hostid</sgmltag> and roles</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 + in existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When you need to refer to a specific username, such as + <literal>root</literal> or <literal>bin</literal>, use + <sgmltag>username</sgmltag>.</para> + + <example> + <title><sgmltag>username</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>To carry out most system administration functions you + will need to be <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions you will + need to be <username>root</username>.</para> + </example> + </sect3> + + <sect3> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag>.</para> + + <para><sgmltag>maketarget</sgmltag> identifies a build target exported + by a <filename>Makefile</filename> that can be given as a parameter + to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a + variable that can be set (in the environment, on the + <command>make</command> command line, or within the + <filename>Makefile</filename>) to influence the process.</para> + + <example> + <title><sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Literal text</title> + + <para>You will often need to include “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.</para> + + <para>Some of the time, <sgmltag>programlisting</sgmltag> will be + sufficient to denote this text. <sgmltag>programlisting</sgmltag> is + not always appropriate, particularly when you want to include a + portion of a file “in-line” with the rest of the + paragraph.</para> + + <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing items that the user <emphasis>must</emphasis> fill + in</title> + + <para>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 + can not simply copy the examples that you provide, but must instead + include some information themselves.</para> + + <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. + Use it <emphasis>inside</emphasis> other elements to indicate parts + of that element's content that the user must replace.</para> + + <example> + <title><sgmltag>replaceable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><sgmltag>replaceable</sgmltag> can be used in many different + elements, including <sgmltag>literal</sgmltag>. This example also + shows that <sgmltag>replaceable</sgmltag> should only be wrapped + around the content that the user <emphasis>is</emphasis> meant to + provide. The other content should be left alone.</para> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other parts of the same document</title> + + <para>Linking within the same document requires you to 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).</para> + + <para>Each element within DocBook has an attribute called + <literal>id</literal>. You can place text in this attribute to + uniquely name the element it is attached to.</para> + + <para>This value will be used when you specify the link + source.</para> + + <para>Normally, you will only be linking to chapters or sections, so + you would add the <literal>id</literal> attribute to these + elements.</para> + + <example> + <title><literal>id on chapters and sections</literal></title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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 + <literal>id</literal> for the subsection is constructed by appending + text to the <literal>id</literal> of the chapter. This helps to + ensure that they are unique.</para> + + <para>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 <sgmltag>anchor</sgmltag>. This element has no content, but + takes an <literal>id</literal> attribute.</para> + + <example> + <title><sgmltag>anchor</sgmltag></title> + + <programlisting> +<![ CDATA [<para>This paragraph has an embedded + <anchor id="para1">link target in it. It won't show up in + the document.</para>]]></programlisting> + </example> + + <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 <literal>id</literal> attribute, you can use either + <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> + + <para>Both of these elements have a <literal>linkend</literal> + attribute. The value of this attribute should be the value that you + have used in a <literal>id</literal> attribute (it does not matter + if that value has not yet occured in your document, this will work + for forward links as well as backward links).</para> + + <para>If you use <sgmltag>xref</sgmltag> then you have no control over + the text of the link. It will be generated for you.</para> + + <example> + <title>Using <sgmltag>xref</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example;</para> + + <programlisting> +<![ CDATA [<para>More information can be found + in <xref linkend="chapter1">.</para> + +<para>More specific information can be found + in <xref linkend="chapter1-sect1">.</para>]]></programlisting> + + <para>The text of the link will be generated automatically, and will + look like (<emphasis>emphasised</emphasis> text indicates the text + that will be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + One</emphasis>.</para> + + <para>More specific information can be found in <emphasis>the + section called Sub-sect 1</emphasis>.</para> + </blockquote> + </example> + + <para>Notice how the text from the link is derived from the section + title or the chapter number.</para> + + <note> + <para>This means that you <emphasis>can not</emphasis> use + <sgmltag>xref</sgmltag> to link to an <literal>id</literal> + attribute on an <sgmltag>anchor</sgmltag> element. The + <sgmltag>anchor</sgmltag> has no content, so the + <sgmltag>xref</sgmltag> can not generate the text for the + link.</para> + </note> + + <para>If you want to control the text of the link then use + <sgmltag>link</sgmltag>. This element wraps content, and the content + will be used for the link.</para> + + <example> + <title>Using <sgmltag>link</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>This will generate the following + (<emphasis>emphasised</emphasis> text indicates the text that will + be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>the first + chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>this</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para>That last one is a bad example. Never use words like + “this” or “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.</para> + </note> + + <note> + <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to + include a link to an <literal>id</literal> on an + <sgmltag>anchor</sgmltag> element, since the + <sgmltag>link</sgmltag> content defines the text that will be used + for the link.</para> + </note> + </sect3> + + <sect3> + <title>Linking to documents on the WWW</title> + + <para>Linking to external documents is much simpler, as long as you + know the URL of the document you want to link to. Use + <sgmltag>ulink</sgmltag>. The <literal>url</literal> 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.</para> + + <example> + <title><sgmltag>ulink</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>Of course, you could stop reading this document and + go to the <ulink url="http://www.freebsd.org/">FreeBSD + home page</ulink> instead.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go to the + <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink> + instead.</para> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>* LinuxDoc</title> + + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the + <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD Documentation + Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup rather + than content related markup (i.e., it describes what something looks + like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux Documentation + Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + </sect1> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/sgml-primer/chapter.sgml b/en/tutorials/docproj-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en/tutorials/docproj-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-primer"> + <title>SGML Primer</title> + + <para>The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website.</para> + + <para>Portions of this section were inspired by Mark Galassi's <ulink + url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> + + <sect1> + <title>Overview</title> + + <para>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.</para> + + <para>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 emphasised, or added to a glossary, or be hyperlinks. + You might want filenames to be shown in a “typewriter” style + font for viewing on screen, but as “italics” when printed, + or any of a myriad of other options for presentation.</para> + + <para>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 the can + meaningfully process our text.</para> + + <para>More precisely, they need help identifying what is what. You or I + can look at + + <blockquote> + <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + + <para><command>rm /tmp/foo</command></para> + </blockquote> + + 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 can not. For this we need + markup.</para> + + <para>“Markup” is commonly used to describe “adding + value” or “increasing cost”. The term takes on both + these meanings when applied to text. Markup is additional text included + in the document, distinguished from the document's content in some way, + so that programs that process the document can read the markup and use + it when making decisions about the document. Editors can hide the + markup from the user, so they are not distracted by it.</para> + + <para>The extra information stored in the markup <emphasis>adds + value</emphasis> to the document. Adding the markup to the document + must typically be done by a person—after all, if computers could + recognise the text sufficiently well to add the markup then there would + be no need to add it in the first place. This <emphasis>increases the + cost</emphasis> of the document.</para> + + <para>The previous example is actually represented in this document like + this;</para> + + <programlisting><![ CDATA [ +<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + +<para><command>rm /tmp/foo</command></para>]]></programlisting> + + <para>As you can see, the markup is clearly separate from the + content.</para> + + <para>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.</para> + + <para>SGML is <emphasis>not</emphasis> a markup langugage. Instead, SGML + is <emphasis>the language in which you write markup + languages</emphasis>. There have been many markup languages written + using SGML. HTML and DocBook are two of these.</para> + + <para>This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML.</para> + + <para>Each language definition (which is written in SGML) 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.</para> + + <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> + 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 a + <emphasis>parser</emphasis> which reads in 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 <quote>validating the document</quote>.</para> + + <note> + <para>This processing simply confirms that the choice of elements, their + ordering, and so on, conforms to that listed in the DTD. It does + <emphasis>not</emphasis> check that you have used + <emphasis>appropriate</emphasis> markup for the content. If you were + to try and 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).</para> + </note> + + <para>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.</para> + </sect1> + + <sect1 id="elements"> + <title>Elements, tags, and attributes</title> + + <para>All the DTDs written in SGML share certain characteristics. This is + hardly surprising, as the philisophy behind SGML will inevitably show + through. One of the most obvious manifestations of this philisophy is + that of <emphasis>content</emphasis> and + <emphasis>elements</emphasis>.</para> + + <para>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.</para> + + <para>For example, consider a typical book. At the very top level, the + book is itself an element. This “book” element obviously + contains chapters, which can be considered to be elements in their own + right. Each chapter will contain more elements, such as paragraphs, + quotations, and footnotes. Each paragraph might contain further + elements, identifying content that was direct speech, or the name of a + character in the story.</para> + + <para>You might like to think of this as “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.</para> + + <para>Notice how you can make this differentation 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 colours to indicate + different types of content.</para> + + <para>Of course, we don't 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 <emphasis>tags</emphasis>.</para> + + <para>A tag is used to identify where a particular element starts, and + where the ends. <emphasis>The tag is not part of the element + itself</emphasis>. Because each DTD was normally written to mark up + specific types of information, each one will recognise different + elements, and will therefore have different names for the tags.</para> + + <para>For an element called <replaceable>element-name</replaceable> the + start tag will normally look like + <literal><<replaceable>element-name</replaceable>></literal>. The + corresponding closing tag for this element is + <literal></<replaceable>element-name</replaceable>></literal>.</para> + + <example> + <title>Using an element (start and end tags)</title> + + <para>HTML has an element for indicating that the content enclosed by + the element is a paragraph, called <literal>p</literal>. This + element has both start and end tags.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Using an element (start tag only)</title> + + <para>HTML has an element for indicating a horizontal rule, called + <literal>hr</literal>. This element does not wrap content, so only has + a start tag.</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph.</p> + +<hr> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Elements within elements; <sgmltag>em</sgmltag></title> + + <programlisting> +<![ CDATA [<p>This is a simple <em>paragraph</em> where some + of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> + </example> + + <para>The DTD will specify the rules detailing which elements can contain + other elements, and exactly what they can contain.</para> + + <important> + <para>People often confuse the terms tags and elements, and use the terms + as if they were interchangeable. They are not.</para> + + <para>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.</para> + + <para>When this document (or anyone else knowledgable about SGML) refers + to “the <p> tag” they mean the literal text + consisting of the three characters <literal><</literal>, + <literal>p</literal>, and <literal>></literal>. But the phrase + “the <p> element” refers to the whole element.</para> + + <para>This distinction <emphasis>is</emphasis> very subtle. But keep it + in mind.</para> + </important> + + <para>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 occurence of the element, or + it might be something else.</para> + + <para>An element's attributes are written <emphasis>inside</emphasis> the + start tag for that element, and take the form + <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> + + <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> + element has an attribute called <literal>align</literal>, which suggests + an alignment (justification) for the paragraph to the program displaying + the HTML.</para> + + <para>The <literal>align</literal> attribute can take one of four defined + values, <literal>left</literal>, <literal>center</literal>, + <literal>right</literal> and <literal>justify</literal>. If the + attribute is not specified then the default is + <literal>left</literal>.</para> + + <example> + <title>Using an element with an attribute</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>Some attributes will only take specific values, such as + <literal>left</literal> or <literal>justify</literal>. Others will + allow you to enter anything you want. If you need to include quotes + (<literal>"</literal>) within an attribute then use single quotes around + the attribute value.</para> + + <example> + <title>Single quotes around attributes</title> + + <programlisting> +<![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> + </example> + + <para>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 <emphasis>always</emphasis> quote your attribute values.</para> + + <sect2> + <title>For you to do…</title> + + <para>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.</para> + + <procedure> + <step> + <para>Download and install <filename>textproc/docproj</filename> + from the FreeBSD ports system. This is a + <emphasis>meta-port</emphasis> that should download and install + all of the programs and supporting files that are used by the + Documentation Project.</para> + </step> + + <step> + <para>Add lines to your shell startup files to set + <envar>SGML_CATALOG_FILES</envar>.</para> + + <example id="sgml-primer-envars"> + <title><filename>.profile</filename>, for &man.sh.1; and + &man.bash.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES</programlisting> + </example> + + <example> + <title><filename>.login</filename>, for &man.csh.1; and + &man.tcsh.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES</programlisting> + </example> + + <para>Then either log out, and log back in again, or run those + commands from the command line to set the variable values.</para> + </step> + </procedure> + + <procedure> + <step> + <para>Create <filename>example.sgml</filename>, and enter the + following text;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Try and validate this file using an SGML parser.</para> + + <para>Part of <filename>textproc/docproj</filename> is the + &man.nsgmls.1; <link linkend="sgml-primer-validating">validating + parser</link>. Normally, &man.nsgmls.1; 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).</para> + + <para>However, when <option>-s</option> is passed as a parameter to + it, &man.nsgmls.1; 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.</para> + + <para>Use &man.nsgmls.1; to check that your document is + valid;</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> + + <para>As you will see, &man.nsgmls.1; returns without displaying any + output. This means that your document validated + successfully.</para> + </step> + + <step> + <para>See what happens when required elements are omitted. Try + removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> + tags, and re-run the validation.</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> +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</screen> + + <para>The error output from &man.nsgmls.1; is organised into + colon-separated groups, or columns.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Column</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>The name of the program generating the error. This + will always be <literal>nsgmls</literal>.</entry> + </row> + + <row> + <entry>2</entry> + <entry>The name of the file that contains the error.</entry> + </row> + + <row> + <entry>3</entry> + <entry>Line number where the error appears.</entry> + </row> + + <row> + <entry>4</entry> + <entry>Column number where the error appears.</entry> + </row> + + <row> + <entry>5</entry> + <entry>A one letter code indicating the nature of the + message. <literal>I</literal> indicates an informational + message, <literal>W</literal> is for warnings, and + <literal>E</literal> is for errors<footnote> + <para>It is not always the fifth column either. + <command>nsgmls -sv</command> displays + <literal>nsgmls:I: SP version "1.3"</literal> + (depending on the installed version). As you can see, + this is an informational message.</para> + </footnote>, and <literal>X</literal> is for + cross-references. As you can see, these messages are + errors.</entry> + </row> + + <row> + <entry>6</entry> + <entry>The text of the error message.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Simply omitting the <sgmltag>title</sgmltag> tags has generated + 2 different errors.</para> + + <para>The first error indicates that content (in this case, + characters, rather than the start tag for an element) has occured + 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 <sgmltag>head</sgmltag> (such as + <sgmltag>title</sgmltag>).</para> + + <para>The second error is because <sgmltag>head</sgmltag> elements + <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> + element. Because it does not &man.nsgmls.1; 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.</para> + </step> + + <step> + <para>Put the <literal>title</literal> element back in.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="doctype-declaration"> + <title>The DOCTYPE declaration</title> + + <para>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 the + it.</para> + + <para>This information is generally expressed on one line, in the DOCTYPE + declaration.</para> + + <para>A typical declaration for document written to conform with version + 4.0 of the HTML DTD looks like this;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> + + <para>That line contains a number of different components.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>Is the <emphasis>indicator</emphasis> that indicates that this + is an SGML declaration. This line is declaring the document type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Shows that this is an SGML declaration for the document + type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>Names the first <link linkend="elements">element</link> that + will appear in the document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> + + <listitem> + <para>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.</para> + + <para><literal>PUBLIC</literal> 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 <link linkend="fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Returns to the document.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title>Formal Public Identifiers (FPIs)</title> + + <note> + <para>You don't need to know this, but it's useful background, and + might help you debug problems when your SGML processor can't locate + the DTD you are using.</para> + </note> + + <para>FPIs must follow a specific syntax. This syntax is as + follows;</para> + + <programlisting> +"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Owner</replaceable></term> + + <listitem> + <para>This indicates the owner of the FPI.</para> + + <para>If this string starts with “ISO” then this is an + ISO owned FPI. For example, the FPI <literal>"ISO + 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists + <literal>ISO 8879:1986</literal> as being the owner for the set + of entities for greek symbols. ISO 8879:1986 is the ISO number + for the SGML standard.</para> + + <para>Otherwise, this string will either look like + <literal>-//<replaceable>Owner</replaceable></literal> or + <literal>+//<replaceable>Owner</replaceable></literal> (notice + the only difference is the leading <literal>+</literal> or + <literal>-</literal>).</para> + + <para>If the string starts with <literal>-</literal> then the + owner information is unregistered, with a <literal>+</literal> + it identifies it as being registered.</para> + + <para>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 organisation 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).</para> + + <para>Because the FreeBSD Project hasn't been registered the + owner string is <literal>-//FreeBSD</literal>. And as you can + see, the W3C are not a registered owner either.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Keyword</replaceable></term> + + <listitem> + <para>There are several keywords that indicate the type of + information in the file. Some of the most common keywords are + <literal>DTD</literal>, <literal>ELEMENT</literal>, + <literal>ENTITIES</literal>, and <literal>TEXT</literal>. + <literal>DTD</literal> is used only for DTD files, + <literal>ELEMENT</literal> is usually used for DTD fragments + that contain only entity or element declarations. + <literal>TEXT</literal> is used for SGML content (text and + tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Description</replaceable></term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Language</replaceable></term> + + <listitem> + <para>This is an ISO two-character code that identifies the native + language for the file. <literal>EN</literal> is used for + English.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title><filename>catalog</filename> files</title> + + <para>If you use the syntax above and try 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.</para> + + <para>In order to do this it can use a catalog file. A catalog file + (typically called <filename>catalog</filename>) contains lines that + map FPIs to filenames. For example, if the catalog file contained the + line;</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> + + <para>The SGML processor would know to look up the DTD from + <filename>strict.dtd</filename> in the <filename>4.0</filename> + subdirectory of whichever directory held the + <filename>catalog</filename> file that contained that line.</para> + + <para>Look at the contents of + <filename>/usr/local/share/sgml/html/catalog</filename>. This is the + catalog file for the HTML DTDs that will have been installed as part + of the <filename>textproc/docproj</filename> port.</para> + </sect3> + + <sect3> + <title><envar>SGML_CATALOG_FILES</envar></title> + + <para>In order to locate a <filename>catalog</filename> 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.</para> + + <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to + point to the files. This environment variable should consist of a + colon-separated list of catalog files (including their full + path).</para> + + <para>Typically, you will want to include the following files;</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/share/sgml/docbook/3.0/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/html/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> + </listitem> + </itemizedlist> + + <para>You should <link linkend="sgml-primer-envars">already have done + this</link>.</para> + </sect3> + </sect2> + + <sect2 id="fpi-alternatives"> + <title>Alternatives to FPIs</title> + + <para>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.</para> + + <para>The syntax for this is slightly different;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + + <para>The <literal>SYSTEM</literal> 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.</para> + + <para>Using FPIs is preferred for reasons of portability. You don't want + to have to ship a copy of the DTD around with your document, and if + you used the <literal>SYSTEM</literal> identifier then everyone would + need to keep their DTDs in the same place.</para> + </sect2> + </sect1> + + <sect1 id="sgml-escape"> + <title>Escaping back to SGML</title> + + <para>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.</para> + + <para>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.</para> + + <para>These sections are marked by <literal><! ... ></literal> in + your document. Everything between these delimiters is SGML syntax as you + might find within a DTD.</para> + + <para>As you may just have realised, the <link + linkend="doctype-declaration">DOCTYPE declaration</link> is an example + of SGML syntax that you need to include in your document…</para> + </sect1> + + <sect1> + <title>Comments</title> + + <para>Comments are an SGML construction, and are normally only valid + inside a DTD. However, as <xref linkend="sgml-escape"> shows, it is + possible to use SGML syntax within your document.</para> + + <para>The delimiters for SGML comments is the string + “<literal>--</literal>”. The first occurence of this string + opens a comment, and the second closes it.</para> + + <example> + <title>SGML generic comment</title> + + <programlisting> +<!-- test comment --></programlisting> + + <programlisting><![ CDATA [ +<!-- This is inside the comment --> + +<!-- This is another comment --> + +<!-- This is one way + of doing multiline comments --> + +<!-- This is another way of -- + -- doing multiline comments -->]]></programlisting> + </example> + + <![ %output.print; [ + <important> + <title>Use 2 dashes</title> + + <para>There is a problem with producing the Postscript and PDF versions + of this document. The above example probably shows just one hyphen + symbol, <literal>-</literal> after the <literal><!</literal> and + before the <literal>></literal>.</para> + + <para>You <emphasis>must</emphasis> use two <literal>-</literal>, + <emphasis>not</emphasis> one. The Postscript and PDF versions have + translated the two <literal>-</literal> in the original to a longer, + more professional <emphasis>em-dash</emphasis>, and broken this + example in the process.</para> + + <para>The HTML, plain text, and RTF versions of this document are not + affected.</para> + </important> + ]]> + + <para>If you have used HTML before you may have been shown different rules + for comments. In particular, you may think that the string + <literal><!--</literal> opens a comment, and it is only closed by + <literal>--></literal>.</para> + + <para>This is <emphasis>not</emphasis> 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.</para> + + <example> + <title>Errorneous SGML comments</title> + + <programlisting><![ CDATA [ +<!-- This is in the comment -- + + THIS IS OUTSIDE THE COMMENT! + + -- back inside the comment -->]]></programlisting> + + <para>The SGML parser will treat this as though it were actually;</para> + + <programlisting> +<!THIS IS OUTSIDE THE COMMENT></programlisting> + + <para>This is not valid SGML, and may give confusing error + messages.</para> + + <programlisting> +<![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> + + <para>As the example suggests, <emphasis>do not</emphasis> write + comments like that.</para> + + <programlisting> +<![ CDATA [<!--===================================================-->]]></programlisting> + + <para>That is a (slightly) better approach, but it still potentially + confusing to people new to SGML.</para> + </example> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add some comments to <filename>example.sgml</filename>, and + check that the file still validates using &man.nsgmls.1;</para> + </step> + + <step> + <para>Add some invalid comments to + <filename>example.sgml</filename>, and see the error messages that + &man.nsgmls.1; gives when it encounters an invalid comment.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Entities</title> + + <para>Entities are an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities.</para> + + <sect2 id="general-entities"> + <title>General Entities</title> + + <para>General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document.</para> + + <para>You can not use general entities in an SGML context (although you + define them in one). They can only be used in your document. Contrast + this with <link linkend="parameter-entities">parameter + entities</link>.</para> + + <para>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 + <literal>&<replaceable>entity-name</replaceable>;</literal>. For + example, suppose you had an entity called + <literal>current.version</literal> which expanded to the current + version number of your product. You could write;</para> + + <programlisting> +<![ CDATA [<para>The current version of our product is + ¤t.version;.</para>]]></programlisting> + + <para>When the version number changes you can simply change the + definition of the value of the general entity and reprocess your + document.</para> + + <para>You can also use general entities to enter characters that you + could not normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & symbol + it assumes the next text will be the name of an entity.</para> + + <para>Fortunately, you can use the two general entities &lt; and + &amp; whenever you need to include one or other of these </para> + + <para>A general entity can only be defined within an SGML context. + Typically, this is done immediately after the DOCTYPE + declaration.</para> + + <example> + <title>Defining general entities</title> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]>]]></programlisting> + + <para>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.</para> + + <para>The square brackets are necessary to indicate that we are + extending the DTD indicated by the DOCTYPE declaration.</para> + </example> + </sect2> + + <sect2 id="parameter-entities"> + <title>Parameter entities</title> + + <para>Like <link linkend="general-entities">general entities</link>, + 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 <link + linkend="sgml-escape">SGML context</link>.</para> + + <para>Parameter entities are defined in a similar way to general + entities. However, instead of using + <literal>&<replaceable>entity-name</replaceable>;</literal> to + refer to them, use + <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> + <para><emphasis>P</emphasis>arameter entities use the + <emphasis>P</emphasis>ercent symbol.</para> + </footnote>. The definition also includes the <literal>%</literal> + between the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <example> + <title>Defining parameter entities</title> + + <programlisting> +<![ CDATA [<!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" --> +]>]]></programlisting> + </example> + + <para>This may not seem particularly useful. It will be.</para> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add a general entity to + <filename>example.sgml</filename>.</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Validate the document using &man.nsgmls.1;</para> + </step> + + <step> + <para>Load <filename>example.sgml</filename> into your web browser + (you may need to copy it to <filename>example.html</filename> + before your browser recognises it as an HTML document).</para> + + <para>Unless your browser is very advanced, you won't see the entity + reference <literal>&version;</literal> replaced with the + version number. Most web browsers have very simplistic parsers + which don't do proper SGML<footnote> + <para>This is a shame. Imagine all the problems and hacks (such + as Server Side Includes) that could be avoided if they + did.</para> + </footnote>.</para> + </step> + + <step> + <para>The solution is to <emphasis>normalise</emphasis> your + document. Normalising it involves converting all the entity + references to the values of those entities.</para> + + <para>You can use &man.sgmlnorm.1; to do this.</para> + + <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> + + <para>You should find a normalised (i.e., entity references + expanded) copy of your document in + <filename>example.html</filename>, ready to load into your web + browser.</para> + </step> + + <step> + <para>If you look at the output from &man.sgmlnorm.1; you will see + that it does not include a DOCTYPE declaration at the start. To + include this you need to use the <option>-d</option> + option;</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Using entities to include files</title> + + <para>Entities (both <link linkend="general-entities">general</link> and + <link linkend="parameter-entities">parameter</link>) come into their own + when you realise they can be used to include other files.</para> + + <sect2 id="include-using-gen-entities"> + <title>Using general entities to include files</title> + + <para>Suppose you have some content for an SGML book organised into + files, one file per chapter, called + <filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so forth, with a + <filename>book.sgml</filename> file that will contain these + chapters.</para> + + <para>In order to use the contents of these files as the values for your + entities, you declare them with the <literal>SYSTEM</literal> keyword. + This directs the SGML parser to use the contents of the named file as + the value of the entity.</para> + + <example> + <title>Using general entities to include files</title> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + + <warning> + <para>When using general entities to include other files within a + document, the files being included + (<filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so on) <emphasis>must + not</emphasis> start with a DOCTYPE declaration. This is a syntax + error.</para> + </warning> + </sect2> + + <sect2> + <title>Using parameter entities to include files</title> + + <para>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?</para> + + <para>You can use this to ensure that you can reuse your general + entities.</para> + + <para>Suppose that you had many chapters in your document, and you + reused these chapters in two different books, each book organising the + chapters in a different fashion.</para> + + <para>You could list the entities at the top of each book, but this + quickly becomes cumbersome to manage.</para> + + <para>Instead, place the general entity definitions inside one file, + and use a parameter entity to include that file within your + document.</para> + + <example> + <title>Using parameter entities to include files</title> + + <para>First, place your entity definitions in a separate file, called + <filename>chapters.ent</filename>. This file contains the + following;</para> + + <programlisting> +<![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> +<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> +<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> + + <para>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;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + </sect2> + + <sect2> + <title>For you to do…</title> + + <sect3> + <title>Use general entities to include files</title> + + <procedure> + <step> + <para>Create three files, <filename>para1.sgml</filename>, + <filename>para2.sgml</filename>, and + <filename>para3.sgml</filename>.</para> + + <para>Put content similar to the following in each file;</para> + + <programlisting> +<![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> + </step> + + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Use parameter entities to include files</title> + + <note> + <para>You must have taken the previous steps first.</para> + </note> + + <procedure> + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Create a new file, <filename>entities.sgml</filename>, with + this content;</para> + + <programlisting> +<![ CDATA [<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.sgml"> +<!ENTITY para2 SYSTEM "para2.sgml"> +<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>Marked sections</title> + + <para>SGML provides a mechanism to indicate that particular pieces of the + document should be processed in a special way. These are termed + “marked sections”.</para> + + <example> + <title>Structure of a marked section</title> + + <programlisting> +<![ <replaceable>KEYWORD</replaceable> [ + Contents of marked section +]]></programlisting> + </example> + + <para>As you would expect, being an SGML construct, a marked section + starts <literal><!</literal>.</para> + + <para>The first square bracket begins to delimit the marked + section.</para> + + <para><replaceable>KEYWORD</replaceable> describes how this marked + section should be processed by the parser.</para> + + <para>The second square bracket indicates that the content of the marked + section starts here.</para> + + <para>The marked section is finished by closing the two square brackets, + and then returning to the document context from the SGML context with + <literal>></literal></para> + + <sect2> + <title>Marked section keywords</title> + + <sect3> + <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> + + <para>These keywords denote the marked sections <emphasis>content + model</emphasis>, and allow you to change it from the + default.</para> + + <para>When an SGML processor is processing a document, it keeps track + of what is called the “content model”.</para> + + <para>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.</para> + + <para>The two content models you will probably find most useful are + <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> + + <para><literal>CDATA</literal> is for “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.</para> + + <para><literal>RCDATA</literal> is for “Entity references and + character data” If the parser is in this content model then it + is expecting to see characters <emphasis>and</emphasis> entities. + < loses its special status, but & will still be treated as + starting the beginning of a general entity.</para> + + <para>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.</para> + + <!-- The nesting of CDATA within the next example is disgusting --> + + <example> + <title>Using a CDATA marked section</title> + + <programlisting> +<para>Here is an example of how you would include some text + that contained many &lt; and &amp; symbols. The sample + text is a fragment of HTML. The surrounding text (<para> and + <programlisting>) are from DocBook.</para> + +<programlisting> + <![ CDATA [ <![ 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's + 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></programlisting> + + <para>If you look at the source for this document you will see this + technique used throughout.</para> + </example> + </sect3> + + <sect3> + <title><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para>If the keyword is <literal>INCLUDE</literal> then the contents + of the marked section will be processed. If the keyword is + <literal>IGNORE</literal> then the marked section is ignored and + will not be processed. It will not appear in the output.</para> + + <example> + <title>Using <literal>INCLUDE</literal> and + <literal>IGNORE</literal> in marked sections</title> + + <programlisting> +<![ INCLUDE [ + This text will be processed and included. +]]> + +<![ IGNORE [ + This text will not be processed or included. +]]></programlisting> + </example> + + <para>By itself, this isn't too useful. If you wanted to remove text + from your document you could cut it out, or wrap it in + comments.</para> + + <para>It becomes more useful when you realise you can use <link + linkend="parameter-entities">parameter entities</link> to control + this. Remember that parameter entities can only be used in SGML + contexts, and the keyword of a marked section + <emphasis>is</emphasis> an SGML context.</para> + + <para>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 wasn't to + appear in the hard-copy.</para> + + <para>Create a parameter entity, and set it's value to + <literal>INCLUDE</literal>. 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.</para> + + <para>When you want to produce the hard-copy version of the document, + change the parameter entity's value to <literal>IGNORE</literal> and + reprocess the document.</para> + + <example> + <title>Using a parameter entity to control a marked + section</title> + + <programlisting> +<!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. +]]></programlisting> + + <para>When producing the hard-copy version, change the entity's + definition to;</para> + + <programlisting> +<!ENTITY % electronic.copy "IGNORE"></programlisting> + + <para>On reprocessing the document, the marked sections that use + <literal>%electronic.copy</literal> as their keyword will be + ignored.</para> + </example> + </sect3> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Create a new file, <filename>section.sgml</filename>, that + contains the following;</para> + + <programlisting> +<!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> + ]]> + + <![ <![ CDATA [%text.output]]> [ + <p>This paragraph might appear in the output, or it + might not.</p> + + <p>Its appearance is controlled by the <![CDATA[%text.output]]> + parameter entity.</p> + ]]> + </body> +</html></programlisting> + </step> + + <step> + <para>Normalise this file using &man.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.</para> + </step> + + <step> + <para>Change the definition of the <literal>text.output</literal> + entity from <literal>INCLUDE</literal> to + <literal>IGNORE</literal>. Re-normalise the file, and examine the + output to see what has changed. </para> + </step> + </procedure> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en/tutorials/docproj-primer/stylesheets/chapter.sgml b/en/tutorials/docproj-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en/tutorials/docproj-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="stylesheets"> + <title>* Stylesheets</title> + + <para>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.</para> + + <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS.</para> + + <sect1> + <title>* DSSSL</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + </sect1> + + <sect1> + <title>* CSS</title> + + <para></para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en/tutorials/docproj-primer/the-faq/chapter.sgml b/en/tutorials/docproj-primer/the-faq/chapter.sgml new file mode 100644 index 0000000000..24cc68a30a --- /dev/null +++ b/en/tutorials/docproj-primer/the-faq/chapter.sgml @@ -0,0 +1,47 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-faq"> + <title>* The FAQ</title> + + <para></para> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/the-handbook/chapter.sgml b/en/tutorials/docproj-primer/the-handbook/chapter.sgml new file mode 100644 index 0000000000..9b860d2e7f --- /dev/null +++ b/en/tutorials/docproj-primer/the-handbook/chapter.sgml @@ -0,0 +1,280 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-handbook"> + <title>* The Handbook</title> + + <sect1> + <title>Logical structure</title> + + <para>The Handbook is written to comply with the FreeBSD DocBook extended + DTD.</para> + + <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. It + is then divided into <sgmltag>part</sgmltag>s, each of which may contain + several <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are + further subdivided into sections (<sgmltag>sect1</sgmltag>) and + subsections (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) and so + on.</para> + </sect1> + + <sect1> + <title>Physical organisation</title> + + <para>The Handbook (and its translations) are in the + <filename>doc/<replaceable>language</replaceable>/handbook</filename> + subdirectory of the main CVS + repository. <replaceable>language</replaceable> corresponds to the ISO + language code for that translation, <literal>en</literal> for English, + <literal>ja</literal> for Japanese, and so on.</para> + + <para>There are a number of files and directories within the + <filename>handbook</filename> directory.</para> + + <note> + <para>The Handbook's organisation may change over time, and this + document may lag in detailing the organisational changes. If you have + any questions about how the Handbook is organised, please contact the + FreeBSD Documentation Project, <email>doc@FreeBSD.ORG</email>.</para> + </note> + + <sect2> + <title><filename>Makefile</filename></title> + + <para>The <filename>Makefile</filename> defines the rules that are used + to convert the Handbook from its source form (DocBook) to a number of + other target formats (including HTML, PostScript, and plain + text).</para> + + <para>A more detailed description of the <filename>Makefile</filename> + is in <xref linkend="the-handbook-converting">.</para> + </sect2> + + <sect2> + <title><filename>handbook.sgml</filename></title> + + <para>This is the top level document in the Handbook. It contains the + Handbook's <link linkend="doctype-declaration">DOCTYPE + declaration</link>, as well as the elements that describe the + Handbook's structure.</para> + + <para><filename>handbook.sgml</filename> uses <link + linkend="parameter-entities">parameter entities</link> to load in + the files with the <filename>.ent</filename> extension. These files + (described later) then define <link linkend="general-entities">general + entities</link> that are used throughout the rest of the + Handbook.</para> + </sect2> + + <sect2> + <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> + + <para>Each chapter in the Handbook is stored in a file called + <filename>chapter.sgml</filename> in a separate directory from the + other chapters. Each directory is named after the value of the + <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> + element.</para> + + <para>For example, if one of the chapter files contains:</para> + + <programlisting><![ CDATA [ +<chapter id="kernelconfiguration"> +... +</chapter>]]></programlisting> + + <para>then it will be called <filename>chapter.sgml</filename> in the + <filename>kernelconfiguration</filename> directory. In general, the + entire contents of the chapter will be held in this file.</para> + + <para>When the HTML version of the Handbook is produced, this will yield + <filename>kernelconfiguration.html</filename>. This is because of the + <literal>id</literal> value, and is not related to the name of the + directory.</para> + + <para>In earlier versions of the Handbook the files were stored in the + same directory as <filename>handbook.sgml</filename>, and named after + the value of the <literal>id</literal> attribute on the file's + <sgmltag>chapter</sgmltag> element. Moving them in to 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 and 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.</para> + + <para>A brief look will show that there are many directories with + individual <filename>chapter.sgml</filename> files, including + <filename>basics/chapter.sgml</filename>, + <filename>introduction/chapter.sgml</filename>, and + <filename>printing/chapter.sgml</filename>.</para> + + <important> + <para>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 reorganised; this + sort of reorganistion should not (generally) include the need to + rename files (unless entire chapters are being promoted or demoted + within the hierarchy).</para> + </important> + + <para>Each <filename>chapter.sgml</filename> file will not be a complete + SGML document. In particular, they will not have their own DOCTYPE + line at the start of the file.</para> + + <para>This is unfortunate for two reasons;</para> + + <itemizedlist> + <listitem> + <para>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 + <emphasis>would</emphasis> force you to rebuild the Handbook every + time you want to see the effect a change as had on just one + chapter.</para> + </listitem> + + <listitem> + <para>Emacs' <literal>sgml-mode</literal> can not use it to + determine the DTD to use, losing useful benefits of + <literal>sgml-mode</literal> (element completion, automatic + validation, and so on).</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1> + <title>Style guide</title> + + <para>To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions.</para> + + <sect2> + <title>Letter case</title> + + <para>Tags are entered in lower case, <literal><para></literal>, + <emphasis>not</emphasis> <literal><PARA></literal>.</para> + + <para>Text that appears in SGML contexts is generally written in upper + case, <literal><!ENTITY…></literal>, and + <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> + <literal><!entity…></literal> and + <literal><!doctype…></literal>.</para> + </sect2> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + + <para>Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line.</para> + + <para>For example, the source for this section looks something + like;</para> + + <programlisting> +<![ CDATA [+--- This is column 0 +V +<chapter> + <title>...</title> + + <sect1> + <title>...</title> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + + <para>Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line.</para> + + ... + </sect2> + </sect1> +</chapter>]]></programlisting> + + <para>If you use <application>Emacs</application> or + <application>Xemacs</application> to edit the files then + <literal>sgml-mode</literal> should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles.</para> + </sect2> + + <sect2> + <title>White space changes</title> + + <para>When committing changes, <emphasis>do not commit changes to the + content at the same time as changes to the + formatting</emphasis>.</para> + + <para>This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled.</para> + + <para>For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for the + second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it.</para> + </sect2> + </sect1> + + <sect1 id="the-handbook-converting"> + <title>Converting the Handbook to other formats</title> + + <para></para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/the-website/chapter.sgml b/en/tutorials/docproj-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en/tutorials/docproj-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-website"> + <title>* The Website</title> + + <para></para> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en/tutorials/docproj-primer/tools/chapter.sgml b/en/tutorials/docproj-primer/tools/chapter.sgml new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en/tutorials/docproj-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ +<chapter id="tools"> + <title>* Tools</title> + + <para>The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes.</para> + + <important> + <title>Use <filename>textproc/docproj</filename> if possible</title> + + <para>You can save yourself a lot of time if you install the + <filename>textproc/docproj</filename> port. This is a + <emphasis>meta-port</emphasis> which does not contain any software + itself. Instead, it depends on various other ports being installed + correctly. Installing this port <emphasis>should</emphasis> + automatically download and install all of the packages listed in this + chapter that you need that are missing from your system.</para> + + <para>One of the packages that you might need is the JadeTeX macro set. + In turn, this macro set requires that TeX is installed. TeX is a large + package, and you only need it if you want to produce Postscript or PDF + output.</para> + + <para>To save yourself time and space you must specify whether or not you + want JadeTeX (and therefore TeX) installed when you install this port. + Either do; + + <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> + + or + + <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + + as necessary.</para> + </important> + + <sect1> + <title>Software</title> + + <para>The project uses the following applications;</para> + + <variablelist> + <varlistentry> + <term><application>Jade</application> and + <application>SP</application></term> + + <listitem> + <para>These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + <application>Jade</application> is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + <application>SP</application> contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents.</para> + + <para>Don't be concerned if these terms are unfamliar to you.</para> + + <para>They can be found in the ports system as + <filename>textproc/jade</filename> and + <filename>textproc/sp</filename> respectively.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>teTeX</application></term> + + <listitem> + <para><application>teTeX</application> is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats.</para> + + <para>v0.9 of <application>teTeX</application> is required, which is + currently in the ports collection as + <filename>print/teTeX-beta</filename>.</para> + + <note> + <para>Might be installed as part of + <filename>textproc/docproj</filename>, depending on the + <makevar>JADETEX</makevar> setting.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> or + <application>Xemacs</application></term> + + <listitem> + <para>Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors.</para> + + <para>They can be found in <filename>editor/emacs20</filename> and + <filename>editor/xemacs20</filename>.</para> + + <note> + <para>Not installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>Document Type Definitions (DTDs)</title> + + <para>The project uses the following DTDs;</para> + + <variablelist> + <varlistentry> + <term>HTML</term> + + <listitem> + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, + and the latest, 4.0 (available in both <emphasis>strict</emphasis> + and <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>LinuxDoc</term> + + <listitem> + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD + Documentation Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup + rather than content related markup (i.e., it describes what + something looks like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux + Documentation Project are migrating from the LinuxDoc DTD to the + DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook</term> + + <listitem> + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> + to be a DTD for writing technical documentation. As such, it + contains XXX</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>DSSSL Stylesheets</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + + <note> + <para>Installed as part of <filename>textproc/docproj</filename>.</para> + </note> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en/tutorials/docproj-primer/writing-style/chapter.sgml b/en/tutorials/docproj-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en/tutorials/docproj-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="writing-style"> + <title>Writing style</title> + + <para>In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow.</para> + + <variablelist> + <varlistentry> + <term>Do not use contractions</term> + + <listitem> + <para>Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong.</para> + + <para>Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Use the serial comma</term> + + <listitem> + <para>In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”.</para> + + <para>For example, look at the following quote;</para> + + <blockquote> + <para>This is a list of one, two and three items.</para> + </blockquote> + + <para>Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”?</para> + + <para>It is better to be explicit and include a serial comma;</para> + + <blockquote> + <para>This is a list of one, two, and three items.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Avoid redundant phrases</term> + + <listitem> + <para>Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant.</para> + + <para>These two examples show this for commands. The second example + is preferred.</para> + + <informalexample> + <para>Use the command <command>cvsup</command> to update your + sources</para> + </informalexample> + + <informalexample> + <para>Use <command>cvsup</command> to update your sources</para> + </informalexample> + + <para>These two examples show this for filenames. The second example + is preferred.</para> + + <informalexample> + <para>… in the filename + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>… in + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>These two examples show this for manual references. The second + example is preferred (the second example uses + <sgmltag>citerefentry</sgmltag>).</para> + + <informalexample> + <para>See <command>man csh</command> for more + information.</para> + </informalexample> + + <informalexample> + <para>See &man.csh.1;</para> + </informalexample> + </listitem> + </varlistentry> + </variablelist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,278 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +]> + +<book> + <bookinfo> + <title>FreeBSD Documentation Project Primer for New Contributors</title> + + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + <affiliation> + <address><email>nik@FreeBSD.ORG</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <year>1999</year> + <holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder> + </copyright> + + <pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate> + + <releaseinfo>$ID$</releaseinfo> + + <legalnotice> + <para>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:</para> + + <orderedlist> + <listitem> + <para>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.</para> + </listitem> + + <listitem> + <para>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.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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.</para> + </important> + </legalnotice> + + <abstract> + <para>Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable.</para> + + <para>This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project.</para> + + <para>This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + <literal>*</literal> in their name.</para> + </abstract> + </bookinfo> + + <preface> + <title>Preface</title> + + <sect1> + <title>Shell Prompts</title> + + <para>The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>User</entry> + <entry>Prompt</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Normal user</entry> + <entry>&prompt.user;</entry> + </row> + + <row> + <entry><username>root</username></entry> + <entry>&prompt.root;</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Typographic Conventions</title> + + <para>The following table describes the typographic conventions used in + this book.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Meaning</entry> + <entry>Examples</entry> + </row> + </thead> + + <tbody> + <row> + <entry>The name of commands, files, and directories. On screen + computer output.</entry> + <entry><para>Edit your <filename>.login</filename> + file.</para><para>Use <command>ls -a</command> to list all + files.</para><para><screen>You have mail.</screen> + </para></entry> + </row> + + <row> + <entry>What you type, when contrasted with on-screen computer + output.</entry> + + <entry><screen>&prompt.user; <userinput>su</userinput> +Password:</screen></entry> + </row> + + <row> + <entry>Manual page references.</entry> + + <entry>Use <citerefentry> + <refentrytitle>su</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> to change user names.</entry> + </row> + + <row> + <entry>User and group names</entry> + + <entry>Only <username>root</username> can do this.</entry> + </row> + + <row> + <entry>Emphasis</entry> + + <entry>You <emphasis>must</emphasis> do this.</entry> + </row> + + <row> + <entry>Command line variables; replace with the real name or + variable.</entry> + + <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> + </row> + + <row> + <entry>Environment variables</entry> + + <entry><envar>$HOME</envar> is your home directory.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Notes, warnings, and examples</title> + + <para>Within the text appear notes, warnings, and examples.</para> + + <note> + <para>Notes are represented like this, and contain information that + you should take note of, as it may affect what you do.</para> + </note> + + <warning> + <para>Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files.</para> + </warning> + + <example> + <title>A sample example</title> + + <para>Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be.</para> + </example> + </sect1> + + <sect1> + <title>Acknowledgments</title> + + <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms.</para> + </sect1> + </preface> + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/en_US.ISO8859-1/books/fdp-primer/chapter.decl b/en_US.ISO8859-1/books/fdp-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/chapter.decl @@ -0,0 +1 @@ +<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"> diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,22 @@ +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .sgml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $Id: chapters.ent,v 1.1 1999-04-20 20:59:49 nik Exp $ +--> + +<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> +<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> +<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> +<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml"> +<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> +<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="overview"> + <title>Overview</title> + + <para>Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success.</para> + + <para>After you have read this primer you should;</para> + + <itemizedlist> + <listitem> + <para>Have an understanding of the text formats used by the + Documentation Project, and why they were chosen.</para> + </listitem> + + <listitem> + <para>Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats.</para> + </listitem> + + <listitem> + <para>Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them.</para> + </listitem> + </itemizedlist> + + <para>This primer assumes that you already understand;</para> + + <itemizedlist> + <listitem> + <para>How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files.</para> + + <para>Alternatively, how to retrieve versions of files using the + <application>CVSWeb</application> interface.</para> + </listitem> + + <listitem> + <para>How to use the ports system to download and install new + software.</para> + </listitem> + </itemizedlist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="psgml-mode"> + <title>Using <literal>sgml-mode</literal> with + <application>Emacs</application></title> + + <para>Recent versions of Emacs or Xemacs (available from the ports + collection) contain a very useful package called PSGML. Automatically + invoked when a file with <filename>.sgml</filename> extension is loaded, + or by typing <command>M-x sgml-mode</command>, it is a major mode for + dealing with SGML files, elements and attributes.</para> + + <para>An understanding of some of the commands provided by this mode can + make working with SGML documents such as the Handbook much easier.</para> + + <variablelist> + <varlistentry> + <term><command>C-c C-e</command></term> + + <listitem> + <para>Runs <literal>sgml-insert-element</literal>. 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.</para> + + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c =</command></term> + + <listitem> + <para>Runs <literal>sgml-change-element-name</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-r</command></term> + + <listitem> + <para>Runs <literal>sgml-tag-region</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c -</command></term> + + <listitem> + <para>Runs <literal>sgml-untag-element</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-q</command></term> + + <listitem> + <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill + (i.e., reformat) content from the current element in. The filling + <emphasis>will</emphasis> affect content in which whitespace is + significant, such as within <sgmltag>programlisting</sgmltag> + elements, so run this command with care.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-a</command></term> + + <listitem> + <para>Runs <literal>sgml-edit-attributes</literal>. 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, <command>C-k</command> to remove an existing + value and replace it with a new one, <command>C-c</command> to close + this buffer and return to the main document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-v</command></term> + + <listitem> + <para>Runs <literal>sgml-validate</literal>. 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.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Doubtless there are other useful functions of this mode, but those are + the ones I use most often.</para> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="see-also"> + <title>See Also</title> + + <para>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.</para> + + <sect1> + <title>The FreeBSD Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD + Documentation Project web pages</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>SGML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web + page</ulink>, a comprehensive SGML resource</para> + </listitem> + + <listitem> + <para><ulink + url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.w3.org/">The World Wide Web + organisation</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 + specification</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oreilly.com/davenport/">The Davenport + Group</ulink>, maintainers of the DocBook DTD</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>The Linux Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation + Project web pages</ulink></para> + </listitem> + </itemizedlist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-markup"> + <title>SGML Markup</title> + + <para>This chapter describes the three 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.</para> + + <para>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.</para> + + <para>This is <emphasis>not</emphasis> 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 mailing list + <email>freebsd-doc@freebsd.org</email>.</para> + + <note> + <title>Inline vs. block</title> + + <para>In the remainder of this document, when describing elements, + <emphasis>inline</emphasis> means that the element can occur within a + block element, and does not cause a line break. A + <emphasis>block</emphasis> element, by comparison, will cause a line + break (and other processing) when it is encountered.</para> + </note> + + <sect1> + <title>HTML</title> + + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML is used to markup pages on the FreeBSD web site. It should not + (generally) be used to mark up other documention, 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.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the + latest, 4.0 (available in both <emphasis>strict</emphasis> and + <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> port. They are automatically + installed as part of the <filename>textproc/docproj</filename> port.</para> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>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.</para> + + <para>The majority of HTML documents on the FreeBSD web site comply with + the loose version of HTML 4.0.</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>An HTML document is normally split in to two sections. The first + section, called the <emphasis>head</emphasis>, 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 + <emphasis>body</emphasis>, contains the content that will be displayed + to the user.</para> + + <para>These sections are indicated with <sgmltag>head</sgmltag> and + <sgmltag>body</sgmltag> elements respectively. These elements are + contained within the top-level <sgmltag>html</sgmltag> element.</para> + + <example> + <title>Normal HTML document structure</title> + + <programlisting> +<html> + <head> + <title><replaceable>The document's title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Headings</title> + + <para>HTML allows you to denote headings in your document, at up to + six different levels.</para> + + <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, + then <sgmltag>h2</sgmltag>, continuing down to + <sgmltag>h6</sgmltag>.</para> + + <para>The element's content is the text of the heading.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 -->]]></programlisting> + </example> + + <para>Generally, an HTML page should have one first level heading + (<sgmltag>h1</sgmltag>). This can contain many second level headings + (<sgmltag>h2</sgmltag>), which can in turn contain many third level + headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> + element should have the same element, but one further up the + hierarchy, preceeding it. Leaving gaps in the numbering is to be + avoided.</para> + + <example> + <title>Bad ordering of + <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<h1>First section</h1> + +<!-- Document introduction --> + +<h3>Sub-section</h3> + +<!-- This is bad, <h2> has been left out -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Paragraphs</title> + + <para>HTML supports a single paragraph element, + <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>A block quotation is an extended quotation from another document + that should not appear within the current paragraph.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Lists</title> + + <para>You can present the user with three types of lists, ordered, + unordered, and definition.</para> + + <para>Typically, each entry in an ordered list will be numbered, while + each entry in an unordered list will be proceeded 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.</para> + + <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> + element, unordered lists by the <sgmltag>ul</sgmltag> element, and + definition lists by the <sgmltag>dl</sgmltag> element.</para> + + <para>Ordered and unordered lists contain listitems, indicated by the + <sgmltag>li</sgmltag> element. A listitem can contain textual + content, or it may be further wrapped in one or more + <sgmltag>p</sgmltag> elements.</para> + + <para>Definition lists contain definition terms + (<sgmltag>dt</sgmltag>) and definition descriptions + (<sgmltag>dd</sgmltag>). A definition term can only contain inline + elements. A definition description can contain other block + elements.</para> + + <example> + <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>An unordered list. Listitems will probably be + preceeded 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>]]></programlisting> + </example> + + <example> + <title>Definition lists with <sgmltag>dl</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p></dd> + + <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>Paragraph 1 of definition 3. Note that the <p> + element is not required in the single paragraph case.</dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Pre-formatted text</title> + + <para>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 in to one, and line + breaks in the text are significant.</para> + + <para>In order to do this, wrap the content in the + <sgmltag>pre</sgmltag> element.</para> + + <example> + <title><sgmltag>pre</sgmltag></title> + + <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail + message;</para> + + <programlisting> +<![ CDATA [<pre> + From: nik@freebsd.org + To: freebsd-doc@freebsd.org + Subject: New documentation available + + There's a new copy of my primer for contributers to the FreeBSD + Documentation Project available at + + <URL:http://www.freebsd.org/~nik/primer/index.html> + + Comments appreciated. + + N +</pre>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Tables</title> + + <note> + <para>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.</para> + </note> + + <para>Mark up tabular information using the <sgmltag>table</sgmltag> + element. A table consists of one or more table rows + (<sgmltag>tr</sgmltag>), each containing one or more cells of table + data (<sgmltag>td</sgmltag>). 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 + <sgmltag>p</sgmltag> element.</para> + + <example> + <title>Simple use of <sgmltag>table</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting></example> + + <para>A cell can span multiple rows and columns. To indicate this, add + the <literal>rowspan</literal> and/or <literal>colspan</literal> + attributes, with values indicating the number of rows of columns + that should be spanned.</para> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>colspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>rowspan</literal> and + <literal>colspan</literal> together</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged in to 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 in to + 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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>You have two levels of emphasis available in HTML, + <sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal + level of emphasis and <sgmltag>strong</sgmltag> indicates stronger + emphasis.</para> + + <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and + <sgmltag>strong</sgmltag> is rendered in bold. This is not always + the case however, and you should not rely on it.</para> + + <example> + <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><em>This</em> has been emphasised, while + <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Bold and italics</title> + + <para>Because HTML includes presentational markup, you can also + indicate that particular content should be rendered in bold or + italic. The elements are <sgmltag>b</sgmltag> and + <sgmltag>i</sgmltag> respectively.</para> + + <example> + <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> + + <programlisting> +<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + in italics.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating fixed pitch text</title> + + <para>If you have content that should be rendered in a fixed pitch + (typewriter) typeface, use <sgmltag>tt</sgmltag> (for + “teletype”).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This document was originally written by + Nik Clayton, who can be reached by e-mail as + <tt>nik@freebsd.org</tt>.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Content size</title> + + <para>You can indicate that content should be shown in a larger or + smaller font. There are three ways of doing this.</para> + + <orderedlist> + <listitem> + <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> + around the content you wish to change size. These tags can be + nested, so <literal><big><big>This is much + bigger</big></big></literal> is possible.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to <literal>+1</literal> or <literal>-1</literal> + respectively. This has the same effect as using + <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the + use of this approach is deprecated.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to a number between 1 and 7. The default font size + is <literal>3</literal>. This approach is deprecated.</para> + </listitem> + </orderedlist> + + <example> + <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and + <sgmltag>font</sgmltag></title> + + <para>The following fragments all do the same thing.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other documents on the WWW</title> + + <para>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.</para> + + <para>The link is indicated with <sgmltag>a</sgmltag>, and the + <literal>href</literal> 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 + colour, different mouse cursor when over the link, and so on).</para> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>More information is available at the + <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting> + </example> + + <para>These links will take the user to the top of the chosen + document.</para> + </sect3> + + <sect3> + <title>Linking to other parts of documents</title> + + <para>Linking to a point within another document (or within the same + document) requires that the document author include anchors that you + can link to.</para> + + <para>Anchors are indicated with <sgmltag>a</sgmltag> and the + <literal>name</literal> attribute instead of + <literal>href</literal>.</para> + + <example> + <title>Using <literal><a name="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + in other links with the name <tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>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 + <literal>#</literal> symbol.</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in a + document called <filename>foo.html</filename>.</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="foo.html#para1">first paragraph</a> of + <tt>foo.html</tt>.</p>]]></programlisting> + </example> + + <para>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 preceeding <literal>#</literal>).</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in + this document</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="#para1">first paragraph</a> of this + document.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>DocBook</title> + + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be + a DTD for writing technical documentation. As such, and unlike LinuxDoc + and HTML, DocBook is very heavily orientated towards markup that + describes <emphasis>what</emphasis> something is, rather than describing + <emphasis>how</emphasis> it should be presented.</para> + + <note> + <title><literal>formal</literal> vs. <literal>informal</literal></title> + + <para>Some elements may exist in two forms, <emphasis>formal</emphasis> + and <emphasis>informal</emphasis>. Typically, the formal version of + the element will consist of a title followed by the information + version of the element. The informal version will not have a + title.</para> + </note> + + <para>The DocBook DTD is available from the ports collection in the + <filename>textproc/docbook</filename> port. It is automatically + installed as part of the <filename>textproc/docproj</filename> + port.</para> + + <sect2> + <title>FreeBSD extensions</title> + + <para>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.</para> + + <para>Where a FreeBSD specific element is listed below it is clearly + marked.</para> + + <para>Throughout the rest of this document, the term + “DocBook” is used to mean the FreeBSD extended DocBook + DTD.</para> + + <note> + <para>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 Nik Clayton <email>nik@freebsd.org</email>.</para> + </note> + </sect2> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing FPIs for + DocBook customisations, the FPI for the FreeBSD extended DocBook DTD + is;</para> + + <programlisting> +PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>DocBook contains a number of elements for marking up the structure + of a book.</para> + + <para>Generally, the top level (first) element will be + <sgmltag>book</sgmltag>.</para> + + <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a + mandatory requirement. There may be <sgmltag>part</sgmltag>s between + the book and the chapter to provide another layer of organisation. The + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. These are + indicated with the <sgmltag>sect1</sgmltag> element. If a section + contains another section then use the <sgmltag>sect2</sgmltag> + element, and so on, up to <sgmltag>sect5</sgmltag>.</para> + + <para>Chapters and sections contain the remainder of the content.</para> + + <sect3> + <title>Starting a book</title> + + <para>The content of the book is contained within the + <sgmltag>book</sgmltag> 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.</para> + + <para>This additional information should be contained within + <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting> +<book> + <bookinfo> + <title><replaceable>Your title here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating chapters</title> + + <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each + chapter has a mandatory <sgmltag>title</sgmltag>.</para> + + <example> + <title>A simple chapter</title> + + <programlisting> +<![ CDATA [<chapter> + <title>The chapter's title</title> + + ... +</chapter>]]></programlisting> + </example> + + <para>A chapter can not be empty, it must contain elements in addition + to <sgmltag>title</sgmltag>. If you need to include an empty chapter + then just use an empty paragraph.</para> + + <example> + <title>Empty chapters</title> + + <programlisting> +<![ CDATA [<chapter> + <title>This is an empty chapter</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sections below chapters</title> + + <para>Chapters can be broken up into sections, subsections, and so + on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> + element. The <replaceable>n</replaceable> indicates the section + number, which identifies the section level.</para> + + <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is + <sgmltag>sect1</sgmltag>. You can have one or more of these in a + chapter. They can contain one or more <sgmltag>sect2</sgmltag> + elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> + + <example> + <title>Sections in chapters</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Subdividing using <sgmltag>part</sgmltag>s</title> + + <para>You can introduce another layer of organisation between + <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or + more <sgmltag>part</sgmltag>s.</para> + + <programlisting> +<![ CDATA [<part> + <title>Introduction</title> + + <chapter> + <title>Overview</title> + + ... + </chapter> + + <chapter> + <title>What is FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>History</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs; + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and + <sgmltag>simpara</sgmltag>.</para> + + <para>Most of the time you will only need to use + <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a + <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> + disallows some elements from within <sgmltag>para</sgmltag>. Stick + with <sgmltag>para</sgmltag>.</para> + + <example> + <title><sgmltag>para</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>This is a paragraph. It can contain just about any + other element.</para> ]]></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any other + element.</para> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>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.</para> + + <para>Blockquotes can optionally contain a title and an attribution + (or they can be left untitled and unattributed).</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>A small excerpt from the US Constitution;</para> + +<blockquote> + <title>Preamble to the Constitution of the United States</para> + + <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>]]></programlisting> + + <para>Appearance:</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> + </example> + </sect3> + + <sect3> + <title>Tips, notes, warnings, cautions, important information and + sidebars.</title> + + <para>You may need to include extra information separate from the + main body of the text. Typically this is “meta” + information that the user should be aware of.</para> + + <para>Depending on the nature of the information, one of + <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, + <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and + <sgmltag>important</sgmltag> should be used. Alternatively, if the + information is related to the main text but is not one of the above, + use <sgmltag>sidebar</sgmltag>.</para> + + <para>The circumstances in which to choose one of these elements over + another is unclear. The DocBook documentation suggests;</para> + + <itemizedlist> + <listitem> + <para>A Note is for information that should be heeded by all + readers.</para> + </listitem> + + <listitem> + <para>An Important element is a variation on Note.</para> + </listitem> + + <listitem> + <para>A Caution is for information regarding possible data loss + or software damage.</para> + </listitem> + + <listitem> + <para>A Warning is for information regarding possible hardware + damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + harddisk.</para> +</warning>]]></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows from + your harddisk.</para> + </warning> + </sect3> + + <sect3> + <title>Lists and procedures</title> + + <para>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.</para> + + <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, or + <sgmltag>procedure</sgmltag><footnote><para>There are other types of + list element in DocBook, but we're not concerned with those at + the moment.</para> + </footnote> + </para> + + <para><sgmltag>itemizedlist</sgmltag> and + <sgmltag>orderedlist</sgmltag> are similar to the counterparts in + HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one + consists of one or more <sgmltag>listentry</sgmltag> elements, and + each <sgmltag>listentry</sgmltag> contains one or more block + elements. The <sgmltag>listentry</sgmltag> elements are analagous to + HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are + required.</para> + + <para><sgmltag>procedure</sgmltag> is slightly different. It consists + of <sgmltag>step</sgmltag>s, which may in turn consists of more + <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each + <sgmltag>step</sgmltag> contains block elements.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing file samples</title> + + <para>If you want to show a fragment of a file (or perhaps a complete + file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> + element.</para> + + <para>White space and line breaks within + <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> + significant. In particular, this means that the closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will be included.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA[<para>When you have finished, your program should look like + this;</para> + +<programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by their + entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this;</para> + + <programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + + <note> + <para>There is a mechanism within DocBook for referring to sections + of a previously occuring <sgmltag>programlisting</sgmltag>, called + callouts (see <sgmltag>programlistingco</sgmltag> for more + information). I don't fully understand (i.e., have never used) + this feature, so can't document it here. For the mean time, you + can include line numbers within the content, and then refer to + them later on in your description. That will change, as soon as I + find the time to understand and document callouts.</para> + </note> + </sect3> + + <sect3> + <title>Tables</title> + + <para>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.</para> + + <para>In general terms (and see the DocBook documentation for more + detail) a table (which can be either formal or informal) consists of + a <sgmltag>table</sgmltag> element. This contains at least one + <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) + the number of columns in this table group. Within the tablegroup you + can then have one <sgmltag>thead</sgmltag> element, which contains + elements for the table headings (column headings), and one + <sgmltag>tbody</sgmltag> which contains the body of the + table.</para> + + <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> + contain <sgmltag>row</sgmltag> elements, which in turn contain + <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> + element specifies one cell in the table.</para> + + <example> + <title><sgmltag>informaltable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informaltable> + <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>]]></programlisting> + + <para>Appearance:</para> + + <informaltable> + <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> + </example> + + <para>If you don't want a border around the table the + <literal>frame</literal> attribute can be added to the + <sgmltag>informaltable</sgmltag> element with a value of + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + <example> + <title>Tables where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none"> + <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> + </example> + </sect3> + + <sect3> + <title>Examples for the user to follow</title> + + <para>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.</para> + + <para>A number of distinct elements and entities come in to play + here.</para> + + <variablelist> + <varlistentry> + <term><sgmltag>informalexample</sgmltag></term> + + <listitem> + <para>Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be <sgmltag>informalexample</sgmltag>. For those times + when you do need to include a title on the example, use + <sgmltag>example</sgmltag>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Everything the user sees in this example will be on the + computer screen, so the next element is + <sgmltag>screen</sgmltag>.</para> + + <para>Within <sgmltag>screen</sgmltag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the screen + are prompts from the computer (either from the OS, command + shell, or application. These should be marked up using + <sgmltag>prompt</sgmltag>.</para> + + <para>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 <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. They do not + need to be inside <sgmltag>prompt</sgmltag>.</para> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the original + DTD.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>When displaying text that the user should type in, wrap it + in <sgmltag>userinput</sgmltag> tags. It will probably be + displayed differently to the user.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>informalexample</sgmltag>, + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <sgmltag>userinput</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <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> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <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> + </informalexample> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> marked + up as <sgmltag>programlisting</sgmltag>. Reserve + <sgmltag>programlisting</sgmltag> for showing fragments of files + outside the context of user actions.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>When you want to emphasise a particular word or phrase, use + <sgmltag>emphasis</sgmltag>. This may be presented as italic, or + bold, or might be spoken differently with a text-to-speech + system.</para> + + <para>There is no way to change the presentation of the emphasis + within your document, no equivalent of HTML's <sgmltag>b</sgmltag> + and <sgmltag>i</sgmltag>. If the information you are presenting is + important then consider presenting it in + <sgmltag>important</sgmltag> rather than + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix + like operating system for the Intel architecture.</para> + </example> + </sect3> + + <sect3> + <title>Applications, commands, options, and cites</title> + + <para>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.</para> + + <para>In addition, you will occasionally need to list one or more of + the options that a command might take.</para> + + <para>Finally, you will often want to list a command with it's manual + section number, in the “command(number)” format so + common in Unix manuals.</para> + + <para>Mark up application names with + <sgmltag>application</sgmltag>.</para> + + <para>When you want to list a command with it's manual section number + (which should be most of the time) the DocBook element is + <sgmltag>citerefentry</sgmltag>. This will contain a further two + elements, <sgmltag>refentrytitle</sgmltag> and + <sgmltag>manvolnum</sgmltag>. The content of + <sgmltag>refentrytitle</sgmltag> is the name of the command, and the + content of <sgmltag>manvolnum</sgmltag> is the manual page + section.</para> + + <para>This can be cumbersome to write, and so a series of <link + linkend="general-entities">general entities</link> have been + created to make this easier. Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/sgml/man-refs.ent</filename>, and can be + referred to using this FPI;</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to your documentation will probably + look like this;</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]]></programlisting> + + <para>Use <sgmltag>command</sgmltag> when you want to include a + command name “in-line” but present it as something the + user should type in.</para> + + <para>Use <sgmltag>option</sgmltag> to mark up a command's + options.</para> + + <para>This can be confusing, and sometimes the choice is not always + clear. Hopefully this example makes it clearer.</para> + + <example> + <title>Applications, commands, and options.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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.sendmail.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>]]></programlisting> + + <para>Appearance:</para> + + <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>, <citerefentry> + <refentrytitle>mailq</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, and <citerefentry> + <refentrytitle>newaliases</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> 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> + </example> + + <note> + <para>Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> + </note> + </sect3> + + <sect3> + <title>Files, directories, extensions</title> + + <para>Whenever you wish to refer to the name of a file, a directory, + or a file extension, use <sgmltag>filename</sgmltag>.</para> + + <example> + <title><sgmltag>filename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Devices</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When referring to devices you have two choices. You can either + refer to the device as it appears in <filename>/dev</filename>, or + you can use the name of the device as it appears in the kernel. For + this latter course, use <sgmltag>devicename</sgmltag>.</para> + + <para>Sometimes you will not have a choice. Some devices, such as + networking cards, do not have entries in <filename>/dev</filename>, + or the entries are markedly different from those entries.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Hosts, domains, IP addresses, and so forth</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>You can markup identification information for networked + computers (hosts) in several ways, depending on the nature of the + information. All of them use <sgmltag>hostid</sgmltag> as the + element, with the <literal>role</literal> attribute selecting the + type of the marked up information.</para> + + <variablelist> + <varlistentry> + <term>No role attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no role attribute (i.e., + <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the + marked up information is the simple hostname, such as + <literal>freefall</literal> or <literal>wcarchive</literal>. + You can explicitly specify this with + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>freebsd.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with both + hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>The text is an IP address, probably expressed as a dotted + quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be expressed as a + dotted quad, a hexadecimal string, or as a + <literal>/</literal> followed by a number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an ethernet MAC address, expressed as a series + of 2 digit hexadecimal numbers seperated by colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>hostid</sgmltag> and roles</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 + in existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When you need to refer to a specific username, such as + <literal>root</literal> or <literal>bin</literal>, use + <sgmltag>username</sgmltag>.</para> + + <example> + <title><sgmltag>username</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>To carry out most system administration functions you + will need to be <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions you will + need to be <username>root</username>.</para> + </example> + </sect3> + + <sect3> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag>.</para> + + <para><sgmltag>maketarget</sgmltag> identifies a build target exported + by a <filename>Makefile</filename> that can be given as a parameter + to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a + variable that can be set (in the environment, on the + <command>make</command> command line, or within the + <filename>Makefile</filename>) to influence the process.</para> + + <example> + <title><sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Literal text</title> + + <para>You will often need to include “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.</para> + + <para>Some of the time, <sgmltag>programlisting</sgmltag> will be + sufficient to denote this text. <sgmltag>programlisting</sgmltag> is + not always appropriate, particularly when you want to include a + portion of a file “in-line” with the rest of the + paragraph.</para> + + <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing items that the user <emphasis>must</emphasis> fill + in</title> + + <para>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 + can not simply copy the examples that you provide, but must instead + include some information themselves.</para> + + <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. + Use it <emphasis>inside</emphasis> other elements to indicate parts + of that element's content that the user must replace.</para> + + <example> + <title><sgmltag>replaceable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><sgmltag>replaceable</sgmltag> can be used in many different + elements, including <sgmltag>literal</sgmltag>. This example also + shows that <sgmltag>replaceable</sgmltag> should only be wrapped + around the content that the user <emphasis>is</emphasis> meant to + provide. The other content should be left alone.</para> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other parts of the same document</title> + + <para>Linking within the same document requires you to 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).</para> + + <para>Each element within DocBook has an attribute called + <literal>id</literal>. You can place text in this attribute to + uniquely name the element it is attached to.</para> + + <para>This value will be used when you specify the link + source.</para> + + <para>Normally, you will only be linking to chapters or sections, so + you would add the <literal>id</literal> attribute to these + elements.</para> + + <example> + <title><literal>id on chapters and sections</literal></title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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 + <literal>id</literal> for the subsection is constructed by appending + text to the <literal>id</literal> of the chapter. This helps to + ensure that they are unique.</para> + + <para>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 <sgmltag>anchor</sgmltag>. This element has no content, but + takes an <literal>id</literal> attribute.</para> + + <example> + <title><sgmltag>anchor</sgmltag></title> + + <programlisting> +<![ CDATA [<para>This paragraph has an embedded + <anchor id="para1">link target in it. It won't show up in + the document.</para>]]></programlisting> + </example> + + <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 <literal>id</literal> attribute, you can use either + <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> + + <para>Both of these elements have a <literal>linkend</literal> + attribute. The value of this attribute should be the value that you + have used in a <literal>id</literal> attribute (it does not matter + if that value has not yet occured in your document, this will work + for forward links as well as backward links).</para> + + <para>If you use <sgmltag>xref</sgmltag> then you have no control over + the text of the link. It will be generated for you.</para> + + <example> + <title>Using <sgmltag>xref</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example;</para> + + <programlisting> +<![ CDATA [<para>More information can be found + in <xref linkend="chapter1">.</para> + +<para>More specific information can be found + in <xref linkend="chapter1-sect1">.</para>]]></programlisting> + + <para>The text of the link will be generated automatically, and will + look like (<emphasis>emphasised</emphasis> text indicates the text + that will be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + One</emphasis>.</para> + + <para>More specific information can be found in <emphasis>the + section called Sub-sect 1</emphasis>.</para> + </blockquote> + </example> + + <para>Notice how the text from the link is derived from the section + title or the chapter number.</para> + + <note> + <para>This means that you <emphasis>can not</emphasis> use + <sgmltag>xref</sgmltag> to link to an <literal>id</literal> + attribute on an <sgmltag>anchor</sgmltag> element. The + <sgmltag>anchor</sgmltag> has no content, so the + <sgmltag>xref</sgmltag> can not generate the text for the + link.</para> + </note> + + <para>If you want to control the text of the link then use + <sgmltag>link</sgmltag>. This element wraps content, and the content + will be used for the link.</para> + + <example> + <title>Using <sgmltag>link</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>This will generate the following + (<emphasis>emphasised</emphasis> text indicates the text that will + be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>the first + chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>this</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para>That last one is a bad example. Never use words like + “this” or “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.</para> + </note> + + <note> + <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to + include a link to an <literal>id</literal> on an + <sgmltag>anchor</sgmltag> element, since the + <sgmltag>link</sgmltag> content defines the text that will be used + for the link.</para> + </note> + </sect3> + + <sect3> + <title>Linking to documents on the WWW</title> + + <para>Linking to external documents is much simpler, as long as you + know the URL of the document you want to link to. Use + <sgmltag>ulink</sgmltag>. The <literal>url</literal> 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.</para> + + <example> + <title><sgmltag>ulink</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>Of course, you could stop reading this document and + go to the <ulink url="http://www.freebsd.org/">FreeBSD + home page</ulink> instead.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go to the + <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink> + instead.</para> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>* LinuxDoc</title> + + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the + <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD Documentation + Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup rather + than content related markup (i.e., it describes what something looks + like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux Documentation + Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + </sect1> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-primer"> + <title>SGML Primer</title> + + <para>The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website.</para> + + <para>Portions of this section were inspired by Mark Galassi's <ulink + url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> + + <sect1> + <title>Overview</title> + + <para>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.</para> + + <para>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 emphasised, or added to a glossary, or be hyperlinks. + You might want filenames to be shown in a “typewriter” style + font for viewing on screen, but as “italics” when printed, + or any of a myriad of other options for presentation.</para> + + <para>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 the can + meaningfully process our text.</para> + + <para>More precisely, they need help identifying what is what. You or I + can look at + + <blockquote> + <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + + <para><command>rm /tmp/foo</command></para> + </blockquote> + + 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 can not. For this we need + markup.</para> + + <para>“Markup” is commonly used to describe “adding + value” or “increasing cost”. The term takes on both + these meanings when applied to text. Markup is additional text included + in the document, distinguished from the document's content in some way, + so that programs that process the document can read the markup and use + it when making decisions about the document. Editors can hide the + markup from the user, so they are not distracted by it.</para> + + <para>The extra information stored in the markup <emphasis>adds + value</emphasis> to the document. Adding the markup to the document + must typically be done by a person—after all, if computers could + recognise the text sufficiently well to add the markup then there would + be no need to add it in the first place. This <emphasis>increases the + cost</emphasis> of the document.</para> + + <para>The previous example is actually represented in this document like + this;</para> + + <programlisting><![ CDATA [ +<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + +<para><command>rm /tmp/foo</command></para>]]></programlisting> + + <para>As you can see, the markup is clearly separate from the + content.</para> + + <para>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.</para> + + <para>SGML is <emphasis>not</emphasis> a markup langugage. Instead, SGML + is <emphasis>the language in which you write markup + languages</emphasis>. There have been many markup languages written + using SGML. HTML and DocBook are two of these.</para> + + <para>This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML.</para> + + <para>Each language definition (which is written in SGML) 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.</para> + + <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> + 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 a + <emphasis>parser</emphasis> which reads in 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 <quote>validating the document</quote>.</para> + + <note> + <para>This processing simply confirms that the choice of elements, their + ordering, and so on, conforms to that listed in the DTD. It does + <emphasis>not</emphasis> check that you have used + <emphasis>appropriate</emphasis> markup for the content. If you were + to try and 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).</para> + </note> + + <para>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.</para> + </sect1> + + <sect1 id="elements"> + <title>Elements, tags, and attributes</title> + + <para>All the DTDs written in SGML share certain characteristics. This is + hardly surprising, as the philisophy behind SGML will inevitably show + through. One of the most obvious manifestations of this philisophy is + that of <emphasis>content</emphasis> and + <emphasis>elements</emphasis>.</para> + + <para>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.</para> + + <para>For example, consider a typical book. At the very top level, the + book is itself an element. This “book” element obviously + contains chapters, which can be considered to be elements in their own + right. Each chapter will contain more elements, such as paragraphs, + quotations, and footnotes. Each paragraph might contain further + elements, identifying content that was direct speech, or the name of a + character in the story.</para> + + <para>You might like to think of this as “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.</para> + + <para>Notice how you can make this differentation 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 colours to indicate + different types of content.</para> + + <para>Of course, we don't 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 <emphasis>tags</emphasis>.</para> + + <para>A tag is used to identify where a particular element starts, and + where the ends. <emphasis>The tag is not part of the element + itself</emphasis>. Because each DTD was normally written to mark up + specific types of information, each one will recognise different + elements, and will therefore have different names for the tags.</para> + + <para>For an element called <replaceable>element-name</replaceable> the + start tag will normally look like + <literal><<replaceable>element-name</replaceable>></literal>. The + corresponding closing tag for this element is + <literal></<replaceable>element-name</replaceable>></literal>.</para> + + <example> + <title>Using an element (start and end tags)</title> + + <para>HTML has an element for indicating that the content enclosed by + the element is a paragraph, called <literal>p</literal>. This + element has both start and end tags.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Using an element (start tag only)</title> + + <para>HTML has an element for indicating a horizontal rule, called + <literal>hr</literal>. This element does not wrap content, so only has + a start tag.</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph.</p> + +<hr> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Elements within elements; <sgmltag>em</sgmltag></title> + + <programlisting> +<![ CDATA [<p>This is a simple <em>paragraph</em> where some + of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> + </example> + + <para>The DTD will specify the rules detailing which elements can contain + other elements, and exactly what they can contain.</para> + + <important> + <para>People often confuse the terms tags and elements, and use the terms + as if they were interchangeable. They are not.</para> + + <para>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.</para> + + <para>When this document (or anyone else knowledgable about SGML) refers + to “the <p> tag” they mean the literal text + consisting of the three characters <literal><</literal>, + <literal>p</literal>, and <literal>></literal>. But the phrase + “the <p> element” refers to the whole element.</para> + + <para>This distinction <emphasis>is</emphasis> very subtle. But keep it + in mind.</para> + </important> + + <para>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 occurence of the element, or + it might be something else.</para> + + <para>An element's attributes are written <emphasis>inside</emphasis> the + start tag for that element, and take the form + <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> + + <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> + element has an attribute called <literal>align</literal>, which suggests + an alignment (justification) for the paragraph to the program displaying + the HTML.</para> + + <para>The <literal>align</literal> attribute can take one of four defined + values, <literal>left</literal>, <literal>center</literal>, + <literal>right</literal> and <literal>justify</literal>. If the + attribute is not specified then the default is + <literal>left</literal>.</para> + + <example> + <title>Using an element with an attribute</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>Some attributes will only take specific values, such as + <literal>left</literal> or <literal>justify</literal>. Others will + allow you to enter anything you want. If you need to include quotes + (<literal>"</literal>) within an attribute then use single quotes around + the attribute value.</para> + + <example> + <title>Single quotes around attributes</title> + + <programlisting> +<![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> + </example> + + <para>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 <emphasis>always</emphasis> quote your attribute values.</para> + + <sect2> + <title>For you to do…</title> + + <para>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.</para> + + <procedure> + <step> + <para>Download and install <filename>textproc/docproj</filename> + from the FreeBSD ports system. This is a + <emphasis>meta-port</emphasis> that should download and install + all of the programs and supporting files that are used by the + Documentation Project.</para> + </step> + + <step> + <para>Add lines to your shell startup files to set + <envar>SGML_CATALOG_FILES</envar>.</para> + + <example id="sgml-primer-envars"> + <title><filename>.profile</filename>, for &man.sh.1; and + &man.bash.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES</programlisting> + </example> + + <example> + <title><filename>.login</filename>, for &man.csh.1; and + &man.tcsh.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES</programlisting> + </example> + + <para>Then either log out, and log back in again, or run those + commands from the command line to set the variable values.</para> + </step> + </procedure> + + <procedure> + <step> + <para>Create <filename>example.sgml</filename>, and enter the + following text;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Try and validate this file using an SGML parser.</para> + + <para>Part of <filename>textproc/docproj</filename> is the + &man.nsgmls.1; <link linkend="sgml-primer-validating">validating + parser</link>. Normally, &man.nsgmls.1; 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).</para> + + <para>However, when <option>-s</option> is passed as a parameter to + it, &man.nsgmls.1; 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.</para> + + <para>Use &man.nsgmls.1; to check that your document is + valid;</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> + + <para>As you will see, &man.nsgmls.1; returns without displaying any + output. This means that your document validated + successfully.</para> + </step> + + <step> + <para>See what happens when required elements are omitted. Try + removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> + tags, and re-run the validation.</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> +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</screen> + + <para>The error output from &man.nsgmls.1; is organised into + colon-separated groups, or columns.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Column</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>The name of the program generating the error. This + will always be <literal>nsgmls</literal>.</entry> + </row> + + <row> + <entry>2</entry> + <entry>The name of the file that contains the error.</entry> + </row> + + <row> + <entry>3</entry> + <entry>Line number where the error appears.</entry> + </row> + + <row> + <entry>4</entry> + <entry>Column number where the error appears.</entry> + </row> + + <row> + <entry>5</entry> + <entry>A one letter code indicating the nature of the + message. <literal>I</literal> indicates an informational + message, <literal>W</literal> is for warnings, and + <literal>E</literal> is for errors<footnote> + <para>It is not always the fifth column either. + <command>nsgmls -sv</command> displays + <literal>nsgmls:I: SP version "1.3"</literal> + (depending on the installed version). As you can see, + this is an informational message.</para> + </footnote>, and <literal>X</literal> is for + cross-references. As you can see, these messages are + errors.</entry> + </row> + + <row> + <entry>6</entry> + <entry>The text of the error message.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Simply omitting the <sgmltag>title</sgmltag> tags has generated + 2 different errors.</para> + + <para>The first error indicates that content (in this case, + characters, rather than the start tag for an element) has occured + 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 <sgmltag>head</sgmltag> (such as + <sgmltag>title</sgmltag>).</para> + + <para>The second error is because <sgmltag>head</sgmltag> elements + <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> + element. Because it does not &man.nsgmls.1; 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.</para> + </step> + + <step> + <para>Put the <literal>title</literal> element back in.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="doctype-declaration"> + <title>The DOCTYPE declaration</title> + + <para>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 the + it.</para> + + <para>This information is generally expressed on one line, in the DOCTYPE + declaration.</para> + + <para>A typical declaration for document written to conform with version + 4.0 of the HTML DTD looks like this;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> + + <para>That line contains a number of different components.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>Is the <emphasis>indicator</emphasis> that indicates that this + is an SGML declaration. This line is declaring the document type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Shows that this is an SGML declaration for the document + type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>Names the first <link linkend="elements">element</link> that + will appear in the document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> + + <listitem> + <para>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.</para> + + <para><literal>PUBLIC</literal> 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 <link linkend="fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Returns to the document.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title>Formal Public Identifiers (FPIs)</title> + + <note> + <para>You don't need to know this, but it's useful background, and + might help you debug problems when your SGML processor can't locate + the DTD you are using.</para> + </note> + + <para>FPIs must follow a specific syntax. This syntax is as + follows;</para> + + <programlisting> +"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Owner</replaceable></term> + + <listitem> + <para>This indicates the owner of the FPI.</para> + + <para>If this string starts with “ISO” then this is an + ISO owned FPI. For example, the FPI <literal>"ISO + 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists + <literal>ISO 8879:1986</literal> as being the owner for the set + of entities for greek symbols. ISO 8879:1986 is the ISO number + for the SGML standard.</para> + + <para>Otherwise, this string will either look like + <literal>-//<replaceable>Owner</replaceable></literal> or + <literal>+//<replaceable>Owner</replaceable></literal> (notice + the only difference is the leading <literal>+</literal> or + <literal>-</literal>).</para> + + <para>If the string starts with <literal>-</literal> then the + owner information is unregistered, with a <literal>+</literal> + it identifies it as being registered.</para> + + <para>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 organisation 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).</para> + + <para>Because the FreeBSD Project hasn't been registered the + owner string is <literal>-//FreeBSD</literal>. And as you can + see, the W3C are not a registered owner either.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Keyword</replaceable></term> + + <listitem> + <para>There are several keywords that indicate the type of + information in the file. Some of the most common keywords are + <literal>DTD</literal>, <literal>ELEMENT</literal>, + <literal>ENTITIES</literal>, and <literal>TEXT</literal>. + <literal>DTD</literal> is used only for DTD files, + <literal>ELEMENT</literal> is usually used for DTD fragments + that contain only entity or element declarations. + <literal>TEXT</literal> is used for SGML content (text and + tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Description</replaceable></term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Language</replaceable></term> + + <listitem> + <para>This is an ISO two-character code that identifies the native + language for the file. <literal>EN</literal> is used for + English.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title><filename>catalog</filename> files</title> + + <para>If you use the syntax above and try 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.</para> + + <para>In order to do this it can use a catalog file. A catalog file + (typically called <filename>catalog</filename>) contains lines that + map FPIs to filenames. For example, if the catalog file contained the + line;</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> + + <para>The SGML processor would know to look up the DTD from + <filename>strict.dtd</filename> in the <filename>4.0</filename> + subdirectory of whichever directory held the + <filename>catalog</filename> file that contained that line.</para> + + <para>Look at the contents of + <filename>/usr/local/share/sgml/html/catalog</filename>. This is the + catalog file for the HTML DTDs that will have been installed as part + of the <filename>textproc/docproj</filename> port.</para> + </sect3> + + <sect3> + <title><envar>SGML_CATALOG_FILES</envar></title> + + <para>In order to locate a <filename>catalog</filename> 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.</para> + + <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to + point to the files. This environment variable should consist of a + colon-separated list of catalog files (including their full + path).</para> + + <para>Typically, you will want to include the following files;</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/share/sgml/docbook/3.0/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/html/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> + </listitem> + </itemizedlist> + + <para>You should <link linkend="sgml-primer-envars">already have done + this</link>.</para> + </sect3> + </sect2> + + <sect2 id="fpi-alternatives"> + <title>Alternatives to FPIs</title> + + <para>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.</para> + + <para>The syntax for this is slightly different;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + + <para>The <literal>SYSTEM</literal> 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.</para> + + <para>Using FPIs is preferred for reasons of portability. You don't want + to have to ship a copy of the DTD around with your document, and if + you used the <literal>SYSTEM</literal> identifier then everyone would + need to keep their DTDs in the same place.</para> + </sect2> + </sect1> + + <sect1 id="sgml-escape"> + <title>Escaping back to SGML</title> + + <para>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.</para> + + <para>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.</para> + + <para>These sections are marked by <literal><! ... ></literal> in + your document. Everything between these delimiters is SGML syntax as you + might find within a DTD.</para> + + <para>As you may just have realised, the <link + linkend="doctype-declaration">DOCTYPE declaration</link> is an example + of SGML syntax that you need to include in your document…</para> + </sect1> + + <sect1> + <title>Comments</title> + + <para>Comments are an SGML construction, and are normally only valid + inside a DTD. However, as <xref linkend="sgml-escape"> shows, it is + possible to use SGML syntax within your document.</para> + + <para>The delimiters for SGML comments is the string + “<literal>--</literal>”. The first occurence of this string + opens a comment, and the second closes it.</para> + + <example> + <title>SGML generic comment</title> + + <programlisting> +<!-- test comment --></programlisting> + + <programlisting><![ CDATA [ +<!-- This is inside the comment --> + +<!-- This is another comment --> + +<!-- This is one way + of doing multiline comments --> + +<!-- This is another way of -- + -- doing multiline comments -->]]></programlisting> + </example> + + <![ %output.print; [ + <important> + <title>Use 2 dashes</title> + + <para>There is a problem with producing the Postscript and PDF versions + of this document. The above example probably shows just one hyphen + symbol, <literal>-</literal> after the <literal><!</literal> and + before the <literal>></literal>.</para> + + <para>You <emphasis>must</emphasis> use two <literal>-</literal>, + <emphasis>not</emphasis> one. The Postscript and PDF versions have + translated the two <literal>-</literal> in the original to a longer, + more professional <emphasis>em-dash</emphasis>, and broken this + example in the process.</para> + + <para>The HTML, plain text, and RTF versions of this document are not + affected.</para> + </important> + ]]> + + <para>If you have used HTML before you may have been shown different rules + for comments. In particular, you may think that the string + <literal><!--</literal> opens a comment, and it is only closed by + <literal>--></literal>.</para> + + <para>This is <emphasis>not</emphasis> 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.</para> + + <example> + <title>Errorneous SGML comments</title> + + <programlisting><![ CDATA [ +<!-- This is in the comment -- + + THIS IS OUTSIDE THE COMMENT! + + -- back inside the comment -->]]></programlisting> + + <para>The SGML parser will treat this as though it were actually;</para> + + <programlisting> +<!THIS IS OUTSIDE THE COMMENT></programlisting> + + <para>This is not valid SGML, and may give confusing error + messages.</para> + + <programlisting> +<![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> + + <para>As the example suggests, <emphasis>do not</emphasis> write + comments like that.</para> + + <programlisting> +<![ CDATA [<!--===================================================-->]]></programlisting> + + <para>That is a (slightly) better approach, but it still potentially + confusing to people new to SGML.</para> + </example> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add some comments to <filename>example.sgml</filename>, and + check that the file still validates using &man.nsgmls.1;</para> + </step> + + <step> + <para>Add some invalid comments to + <filename>example.sgml</filename>, and see the error messages that + &man.nsgmls.1; gives when it encounters an invalid comment.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Entities</title> + + <para>Entities are an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities.</para> + + <sect2 id="general-entities"> + <title>General Entities</title> + + <para>General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document.</para> + + <para>You can not use general entities in an SGML context (although you + define them in one). They can only be used in your document. Contrast + this with <link linkend="parameter-entities">parameter + entities</link>.</para> + + <para>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 + <literal>&<replaceable>entity-name</replaceable>;</literal>. For + example, suppose you had an entity called + <literal>current.version</literal> which expanded to the current + version number of your product. You could write;</para> + + <programlisting> +<![ CDATA [<para>The current version of our product is + ¤t.version;.</para>]]></programlisting> + + <para>When the version number changes you can simply change the + definition of the value of the general entity and reprocess your + document.</para> + + <para>You can also use general entities to enter characters that you + could not normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & symbol + it assumes the next text will be the name of an entity.</para> + + <para>Fortunately, you can use the two general entities &lt; and + &amp; whenever you need to include one or other of these </para> + + <para>A general entity can only be defined within an SGML context. + Typically, this is done immediately after the DOCTYPE + declaration.</para> + + <example> + <title>Defining general entities</title> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]>]]></programlisting> + + <para>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.</para> + + <para>The square brackets are necessary to indicate that we are + extending the DTD indicated by the DOCTYPE declaration.</para> + </example> + </sect2> + + <sect2 id="parameter-entities"> + <title>Parameter entities</title> + + <para>Like <link linkend="general-entities">general entities</link>, + 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 <link + linkend="sgml-escape">SGML context</link>.</para> + + <para>Parameter entities are defined in a similar way to general + entities. However, instead of using + <literal>&<replaceable>entity-name</replaceable>;</literal> to + refer to them, use + <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> + <para><emphasis>P</emphasis>arameter entities use the + <emphasis>P</emphasis>ercent symbol.</para> + </footnote>. The definition also includes the <literal>%</literal> + between the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <example> + <title>Defining parameter entities</title> + + <programlisting> +<![ CDATA [<!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" --> +]>]]></programlisting> + </example> + + <para>This may not seem particularly useful. It will be.</para> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add a general entity to + <filename>example.sgml</filename>.</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Validate the document using &man.nsgmls.1;</para> + </step> + + <step> + <para>Load <filename>example.sgml</filename> into your web browser + (you may need to copy it to <filename>example.html</filename> + before your browser recognises it as an HTML document).</para> + + <para>Unless your browser is very advanced, you won't see the entity + reference <literal>&version;</literal> replaced with the + version number. Most web browsers have very simplistic parsers + which don't do proper SGML<footnote> + <para>This is a shame. Imagine all the problems and hacks (such + as Server Side Includes) that could be avoided if they + did.</para> + </footnote>.</para> + </step> + + <step> + <para>The solution is to <emphasis>normalise</emphasis> your + document. Normalising it involves converting all the entity + references to the values of those entities.</para> + + <para>You can use &man.sgmlnorm.1; to do this.</para> + + <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> + + <para>You should find a normalised (i.e., entity references + expanded) copy of your document in + <filename>example.html</filename>, ready to load into your web + browser.</para> + </step> + + <step> + <para>If you look at the output from &man.sgmlnorm.1; you will see + that it does not include a DOCTYPE declaration at the start. To + include this you need to use the <option>-d</option> + option;</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Using entities to include files</title> + + <para>Entities (both <link linkend="general-entities">general</link> and + <link linkend="parameter-entities">parameter</link>) come into their own + when you realise they can be used to include other files.</para> + + <sect2 id="include-using-gen-entities"> + <title>Using general entities to include files</title> + + <para>Suppose you have some content for an SGML book organised into + files, one file per chapter, called + <filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so forth, with a + <filename>book.sgml</filename> file that will contain these + chapters.</para> + + <para>In order to use the contents of these files as the values for your + entities, you declare them with the <literal>SYSTEM</literal> keyword. + This directs the SGML parser to use the contents of the named file as + the value of the entity.</para> + + <example> + <title>Using general entities to include files</title> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + + <warning> + <para>When using general entities to include other files within a + document, the files being included + (<filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so on) <emphasis>must + not</emphasis> start with a DOCTYPE declaration. This is a syntax + error.</para> + </warning> + </sect2> + + <sect2> + <title>Using parameter entities to include files</title> + + <para>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?</para> + + <para>You can use this to ensure that you can reuse your general + entities.</para> + + <para>Suppose that you had many chapters in your document, and you + reused these chapters in two different books, each book organising the + chapters in a different fashion.</para> + + <para>You could list the entities at the top of each book, but this + quickly becomes cumbersome to manage.</para> + + <para>Instead, place the general entity definitions inside one file, + and use a parameter entity to include that file within your + document.</para> + + <example> + <title>Using parameter entities to include files</title> + + <para>First, place your entity definitions in a separate file, called + <filename>chapters.ent</filename>. This file contains the + following;</para> + + <programlisting> +<![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> +<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> +<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> + + <para>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;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + </sect2> + + <sect2> + <title>For you to do…</title> + + <sect3> + <title>Use general entities to include files</title> + + <procedure> + <step> + <para>Create three files, <filename>para1.sgml</filename>, + <filename>para2.sgml</filename>, and + <filename>para3.sgml</filename>.</para> + + <para>Put content similar to the following in each file;</para> + + <programlisting> +<![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> + </step> + + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Use parameter entities to include files</title> + + <note> + <para>You must have taken the previous steps first.</para> + </note> + + <procedure> + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Create a new file, <filename>entities.sgml</filename>, with + this content;</para> + + <programlisting> +<![ CDATA [<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.sgml"> +<!ENTITY para2 SYSTEM "para2.sgml"> +<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>Marked sections</title> + + <para>SGML provides a mechanism to indicate that particular pieces of the + document should be processed in a special way. These are termed + “marked sections”.</para> + + <example> + <title>Structure of a marked section</title> + + <programlisting> +<![ <replaceable>KEYWORD</replaceable> [ + Contents of marked section +]]></programlisting> + </example> + + <para>As you would expect, being an SGML construct, a marked section + starts <literal><!</literal>.</para> + + <para>The first square bracket begins to delimit the marked + section.</para> + + <para><replaceable>KEYWORD</replaceable> describes how this marked + section should be processed by the parser.</para> + + <para>The second square bracket indicates that the content of the marked + section starts here.</para> + + <para>The marked section is finished by closing the two square brackets, + and then returning to the document context from the SGML context with + <literal>></literal></para> + + <sect2> + <title>Marked section keywords</title> + + <sect3> + <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> + + <para>These keywords denote the marked sections <emphasis>content + model</emphasis>, and allow you to change it from the + default.</para> + + <para>When an SGML processor is processing a document, it keeps track + of what is called the “content model”.</para> + + <para>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.</para> + + <para>The two content models you will probably find most useful are + <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> + + <para><literal>CDATA</literal> is for “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.</para> + + <para><literal>RCDATA</literal> is for “Entity references and + character data” If the parser is in this content model then it + is expecting to see characters <emphasis>and</emphasis> entities. + < loses its special status, but & will still be treated as + starting the beginning of a general entity.</para> + + <para>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.</para> + + <!-- The nesting of CDATA within the next example is disgusting --> + + <example> + <title>Using a CDATA marked section</title> + + <programlisting> +<para>Here is an example of how you would include some text + that contained many &lt; and &amp; symbols. The sample + text is a fragment of HTML. The surrounding text (<para> and + <programlisting>) are from DocBook.</para> + +<programlisting> + <![ CDATA [ <![ 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's + 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></programlisting> + + <para>If you look at the source for this document you will see this + technique used throughout.</para> + </example> + </sect3> + + <sect3> + <title><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para>If the keyword is <literal>INCLUDE</literal> then the contents + of the marked section will be processed. If the keyword is + <literal>IGNORE</literal> then the marked section is ignored and + will not be processed. It will not appear in the output.</para> + + <example> + <title>Using <literal>INCLUDE</literal> and + <literal>IGNORE</literal> in marked sections</title> + + <programlisting> +<![ INCLUDE [ + This text will be processed and included. +]]> + +<![ IGNORE [ + This text will not be processed or included. +]]></programlisting> + </example> + + <para>By itself, this isn't too useful. If you wanted to remove text + from your document you could cut it out, or wrap it in + comments.</para> + + <para>It becomes more useful when you realise you can use <link + linkend="parameter-entities">parameter entities</link> to control + this. Remember that parameter entities can only be used in SGML + contexts, and the keyword of a marked section + <emphasis>is</emphasis> an SGML context.</para> + + <para>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 wasn't to + appear in the hard-copy.</para> + + <para>Create a parameter entity, and set it's value to + <literal>INCLUDE</literal>. 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.</para> + + <para>When you want to produce the hard-copy version of the document, + change the parameter entity's value to <literal>IGNORE</literal> and + reprocess the document.</para> + + <example> + <title>Using a parameter entity to control a marked + section</title> + + <programlisting> +<!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. +]]></programlisting> + + <para>When producing the hard-copy version, change the entity's + definition to;</para> + + <programlisting> +<!ENTITY % electronic.copy "IGNORE"></programlisting> + + <para>On reprocessing the document, the marked sections that use + <literal>%electronic.copy</literal> as their keyword will be + ignored.</para> + </example> + </sect3> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Create a new file, <filename>section.sgml</filename>, that + contains the following;</para> + + <programlisting> +<!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> + ]]> + + <![ <![ CDATA [%text.output]]> [ + <p>This paragraph might appear in the output, or it + might not.</p> + + <p>Its appearance is controlled by the <![CDATA[%text.output]]> + parameter entity.</p> + ]]> + </body> +</html></programlisting> + </step> + + <step> + <para>Normalise this file using &man.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.</para> + </step> + + <step> + <para>Change the definition of the <literal>text.output</literal> + entity from <literal>INCLUDE</literal> to + <literal>IGNORE</literal>. Re-normalise the file, and examine the + output to see what has changed. </para> + </step> + </procedure> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="stylesheets"> + <title>* Stylesheets</title> + + <para>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.</para> + + <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS.</para> + + <sect1> + <title>* DSSSL</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + </sect1> + + <sect1> + <title>* CSS</title> + + <para></para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-website"> + <title>* The Website</title> + + <para></para> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ +<chapter id="tools"> + <title>* Tools</title> + + <para>The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes.</para> + + <important> + <title>Use <filename>textproc/docproj</filename> if possible</title> + + <para>You can save yourself a lot of time if you install the + <filename>textproc/docproj</filename> port. This is a + <emphasis>meta-port</emphasis> which does not contain any software + itself. Instead, it depends on various other ports being installed + correctly. Installing this port <emphasis>should</emphasis> + automatically download and install all of the packages listed in this + chapter that you need that are missing from your system.</para> + + <para>One of the packages that you might need is the JadeTeX macro set. + In turn, this macro set requires that TeX is installed. TeX is a large + package, and you only need it if you want to produce Postscript or PDF + output.</para> + + <para>To save yourself time and space you must specify whether or not you + want JadeTeX (and therefore TeX) installed when you install this port. + Either do; + + <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> + + or + + <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + + as necessary.</para> + </important> + + <sect1> + <title>Software</title> + + <para>The project uses the following applications;</para> + + <variablelist> + <varlistentry> + <term><application>Jade</application> and + <application>SP</application></term> + + <listitem> + <para>These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + <application>Jade</application> is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + <application>SP</application> contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents.</para> + + <para>Don't be concerned if these terms are unfamliar to you.</para> + + <para>They can be found in the ports system as + <filename>textproc/jade</filename> and + <filename>textproc/sp</filename> respectively.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>teTeX</application></term> + + <listitem> + <para><application>teTeX</application> is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats.</para> + + <para>v0.9 of <application>teTeX</application> is required, which is + currently in the ports collection as + <filename>print/teTeX-beta</filename>.</para> + + <note> + <para>Might be installed as part of + <filename>textproc/docproj</filename>, depending on the + <makevar>JADETEX</makevar> setting.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> or + <application>Xemacs</application></term> + + <listitem> + <para>Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors.</para> + + <para>They can be found in <filename>editor/emacs20</filename> and + <filename>editor/xemacs20</filename>.</para> + + <note> + <para>Not installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>Document Type Definitions (DTDs)</title> + + <para>The project uses the following DTDs;</para> + + <variablelist> + <varlistentry> + <term>HTML</term> + + <listitem> + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, + and the latest, 4.0 (available in both <emphasis>strict</emphasis> + and <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>LinuxDoc</term> + + <listitem> + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD + Documentation Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup + rather than content related markup (i.e., it describes what + something looks like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux + Documentation Project are migrating from the LinuxDoc DTD to the + DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook</term> + + <listitem> + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> + to be a DTD for writing technical documentation. As such, it + contains XXX</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>DSSSL Stylesheets</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + + <note> + <para>Installed as part of <filename>textproc/docproj</filename>.</para> + </note> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="writing-style"> + <title>Writing style</title> + + <para>In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow.</para> + + <variablelist> + <varlistentry> + <term>Do not use contractions</term> + + <listitem> + <para>Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong.</para> + + <para>Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Use the serial comma</term> + + <listitem> + <para>In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”.</para> + + <para>For example, look at the following quote;</para> + + <blockquote> + <para>This is a list of one, two and three items.</para> + </blockquote> + + <para>Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”?</para> + + <para>It is better to be explicit and include a serial comma;</para> + + <blockquote> + <para>This is a list of one, two, and three items.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Avoid redundant phrases</term> + + <listitem> + <para>Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant.</para> + + <para>These two examples show this for commands. The second example + is preferred.</para> + + <informalexample> + <para>Use the command <command>cvsup</command> to update your + sources</para> + </informalexample> + + <informalexample> + <para>Use <command>cvsup</command> to update your sources</para> + </informalexample> + + <para>These two examples show this for filenames. The second example + is preferred.</para> + + <informalexample> + <para>… in the filename + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>… in + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>These two examples show this for manual references. The second + example is preferred (the second example uses + <sgmltag>citerefentry</sgmltag>).</para> + + <informalexample> + <para>See <command>man csh</command> for more + information.</para> + </informalexample> + + <informalexample> + <para>See &man.csh.1;</para> + </informalexample> + </listitem> + </varlistentry> + </variablelist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/Makefile b/en_US.ISO_8859-1/books/fdp-primer/Makefile new file mode 100644 index 0000000000..6321390a6d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/Makefile @@ -0,0 +1,38 @@ +# +# $Id: Makefile,v 1.1 1999-04-20 20:59:49 nik Exp $ +# +# Build the FreeBSD Documentation Project Primer. +# + +MAINTAINER=nik@FreeBSD.ORG + +DOC?= book + +FORMATS?= html-split + +INSTALL_COMPRESSED?= gz +INSTALL_ONLY_COMPRESSED?= + +# +# SRCS lists the individual SGML files that make up the document. Changes +# to any of these files will force a rebuild +# + +# SGML content +SRCS= book.sgml +SRCS+= overview/chapter.sgml +SRCS+= psgml-mode/chapter.sgml +SRCS+= see-also/chapter.sgml +SRCS+= sgml-markup/chapter.sgml +SRCS+= sgml-primer/chapter.sgml +SRCS+= stylesheets/chapter.sgml +SRCS+= the-faq/chapter.sgml +SRCS+= the-handbook/chapter.sgml +SRCS+= the-website/chapter.sgml +SRCS+= tools/chapter.sgml +SRCS+= writing-style/chapter.sgml + +# Entities +SRCS+= chapters.ent + +.include "../../../share/mk/docproj.docbook.mk" diff --git a/en_US.ISO_8859-1/books/fdp-primer/book.sgml b/en_US.ISO_8859-1/books/fdp-primer/book.sgml new file mode 100644 index 0000000000..2355b1683d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/book.sgml @@ -0,0 +1,278 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; +]> + +<book> + <bookinfo> + <title>FreeBSD Documentation Project Primer for New Contributors</title> + + <author> + <firstname>Nik</firstname> + <surname>Clayton</surname> + <affiliation> + <address><email>nik@FreeBSD.ORG</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <year>1999</year> + <holder role="mailto:nik@FreeBSD.ORG">Nik Clayton</holder> + </copyright> + + <pubdate role="rcs">$Date: 1999-04-20 20:59:49 $</pubdate> + + <releaseinfo>$ID$</releaseinfo> + + <legalnotice> + <para>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:</para> + + <orderedlist> + <listitem> + <para>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.</para> + </listitem> + + <listitem> + <para>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.</para> + </listitem> + </orderedlist> + + <important> + <para>THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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.</para> + </important> + </legalnotice> + + <abstract> + <para>Thank you for becoming a part of the FreeBSD Documentation + Project. Your contribution is extremely valuable.</para> + + <para>This primer covers everything you will need to know in order + to start contributing to the FreeBSD Documentation Project, from + the tools and software you will be using (both mandatory and + recommended) to the philosophy behind the Documentation + Project.</para> + + <para>This document is a work in progress, and is not complete. Sections + that are known to be incomplete are indicated with a + <literal>*</literal> in their name.</para> + </abstract> + </bookinfo> + + <preface> + <title>Preface</title> + + <sect1> + <title>Shell Prompts</title> + + <para>The following table shows the default system prompt and superuser + prompt. The examples will use this prompt to indicate which user you + should be running the example as.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>User</entry> + <entry>Prompt</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Normal user</entry> + <entry>&prompt.user;</entry> + </row> + + <row> + <entry><username>root</username></entry> + <entry>&prompt.root;</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Typographic Conventions</title> + + <para>The following table describes the typographic conventions used in + this book.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Meaning</entry> + <entry>Examples</entry> + </row> + </thead> + + <tbody> + <row> + <entry>The name of commands, files, and directories. On screen + computer output.</entry> + <entry><para>Edit your <filename>.login</filename> + file.</para><para>Use <command>ls -a</command> to list all + files.</para><para><screen>You have mail.</screen> + </para></entry> + </row> + + <row> + <entry>What you type, when contrasted with on-screen computer + output.</entry> + + <entry><screen>&prompt.user; <userinput>su</userinput> +Password:</screen></entry> + </row> + + <row> + <entry>Manual page references.</entry> + + <entry>Use <citerefentry> + <refentrytitle>su</refentrytitle> + <manvolnum>1</manvolnum> + </citerefentry> to change user names.</entry> + </row> + + <row> + <entry>User and group names</entry> + + <entry>Only <username>root</username> can do this.</entry> + </row> + + <row> + <entry>Emphasis</entry> + + <entry>You <emphasis>must</emphasis> do this.</entry> + </row> + + <row> + <entry>Command line variables; replace with the real name or + variable.</entry> + + <entry>To delete a file, type <command>rm <filename><replaceable>filename</replaceable></filename></command></entry> + </row> + + <row> + <entry>Environment variables</entry> + + <entry><envar>$HOME</envar> is your home directory.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect1> + + <sect1> + <title>Notes, warnings, and examples</title> + + <para>Within the text appear notes, warnings, and examples.</para> + + <note> + <para>Notes are represented like this, and contain information that + you should take note of, as it may affect what you do.</para> + </note> + + <warning> + <para>Warnings are represented like this, and contain information + warning you about possible damage if you do not follow the + instructions. This damage may be physical, to your hardware or to + you, or it may be non-physical, such as the inadvertant deletion of + important files.</para> + </warning> + + <example> + <title>A sample example</title> + + <para>Examples are represented like this, and typically contain + examples you should walk through, or show you what the results of a + particular action should be.</para> + </example> + </sect1> + + <sect1> + <title>Acknowledgments</title> + + <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter + Flynn, and Christopher Maden, who took the time to read early drafts + of this document and offer many valuable comments and + criticisms.</para> + </sect1> + </preface> + + &chap.overview; + &chap.sgml-primer; + &chap.tools; + &chap.sgml-markup; + &chap.stylesheets; + &chap.the-faq; + &chap.the-handbook; + &chap.the-website; + &chap.writing-style; + &chap.psgml-mode; + &chap.see-also; + +</book> + +<!-- + Local Variables: + mode: sgml + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + End: +--> diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapter.decl b/en_US.ISO_8859-1/books/fdp-primer/chapter.decl new file mode 100644 index 0000000000..494cb2946d --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/chapter.decl @@ -0,0 +1 @@ +<!DOCTYPE chapter PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"> diff --git a/en_US.ISO_8859-1/books/fdp-primer/chapters.ent b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent new file mode 100644 index 0000000000..974039f391 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/chapters.ent @@ -0,0 +1,22 @@ +<!-- + Creates entities for each chapter in the Documentation Project Primer. + Each entity is named chap.foo, where foo is the value of the id + attribute on that chapter, and corresponds to the name of the + directory in which that chapter's .sgml file is stored. + + Chapters should be listed in the order in which they are referenced. + + $Id: chapters.ent,v 1.1 1999-04-20 20:59:49 nik Exp $ +--> + +<!ENTITY chap.overview SYSTEM "overview/chapter.sgml"> +<!ENTITY chap.sgml-primer SYSTEM "sgml-primer/chapter.sgml"> +<!ENTITY chap.tools SYSTEM "tools/chapter.sgml"> +<!ENTITY chap.sgml-markup SYSTEM "sgml-markup/chapter.sgml"> +<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.sgml"> +<!ENTITY chap.the-faq SYSTEM "the-faq/chapter.sgml"> +<!ENTITY chap.the-handbook SYSTEM "the-handbook/chapter.sgml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.sgml"> +<!ENTITY chap.writing-style SYSTEM "writing-style/chapter.sgml"> +<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.sgml"> +<!ENTITY chap.see-also SYSTEM "see-also/chapter.sgml"> diff --git a/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml new file mode 100644 index 0000000000..84fef1dc71 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/overview/chapter.sgml @@ -0,0 +1,89 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="overview"> + <title>Overview</title> + + <para>Welcome to the FreeBSD Documentation Project, and thank you for + volunteering. One of the keys to the success of a project such as FreeBSD + is the availability of good quality documentation, and your contribution + will help that success.</para> + + <para>After you have read this primer you should;</para> + + <itemizedlist> + <listitem> + <para>Have an understanding of the text formats used by the + Documentation Project, and why they were chosen.</para> + </listitem> + + <listitem> + <para>Be able to read and understand the source code for the Handbook, + FAQ, and website, and follow how they are converted into HTML, + PostScript, and other formats.</para> + </listitem> + + <listitem> + <para>Be able to make changes to the documentation, test them, and + either contribute them back to the project or (if you have commit + privileges) commit them.</para> + </listitem> + </itemizedlist> + + <para>This primer assumes that you already understand;</para> + + <itemizedlist> + <listitem> + <para>How to maintain an up-to-date copy of the FreeBSD CVS tree using + CVS and one of CVSup or CTM, and how to check out particular versions + of files.</para> + + <para>Alternatively, how to retrieve versions of files using the + <application>CVSWeb</application> interface.</para> + </listitem> + + <listitem> + <para>How to use the ports system to download and install new + software.</para> + </listitem> + </itemizedlist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml new file mode 100644 index 0000000000..5208c5f016 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/psgml-mode/chapter.sgml @@ -0,0 +1,148 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="psgml-mode"> + <title>Using <literal>sgml-mode</literal> with + <application>Emacs</application></title> + + <para>Recent versions of Emacs or Xemacs (available from the ports + collection) contain a very useful package called PSGML. Automatically + invoked when a file with <filename>.sgml</filename> extension is loaded, + or by typing <command>M-x sgml-mode</command>, it is a major mode for + dealing with SGML files, elements and attributes.</para> + + <para>An understanding of some of the commands provided by this mode can + make working with SGML documents such as the Handbook much easier.</para> + + <variablelist> + <varlistentry> + <term><command>C-c C-e</command></term> + + <listitem> + <para>Runs <literal>sgml-insert-element</literal>. 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.</para> + + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c =</command></term> + + <listitem> + <para>Runs <literal>sgml-change-element-name</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-r</command></term> + + <listitem> + <para>Runs <literal>sgml-tag-region</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c -</command></term> + + <listitem> + <para>Runs <literal>sgml-untag-element</literal>. 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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-q</command></term> + + <listitem> + <para>Runs <literal>sgml-fill-element</literal>. Will recursively fill + (i.e., reformat) content from the current element in. The filling + <emphasis>will</emphasis> affect content in which whitespace is + significant, such as within <sgmltag>programlisting</sgmltag> + elements, so run this command with care.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-a</command></term> + + <listitem> + <para>Runs <literal>sgml-edit-attributes</literal>. 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, <command>C-k</command> to remove an existing + value and replace it with a new one, <command>C-c</command> to close + this buffer and return to the main document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-v</command></term> + + <listitem> + <para>Runs <literal>sgml-validate</literal>. 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.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Doubtless there are other useful functions of this mode, but those are + the ones I use most often.</para> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml new file mode 100644 index 0000000000..eaecab8f99 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/see-also/chapter.sgml @@ -0,0 +1,119 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="see-also"> + <title>See Also</title> + + <para>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.</para> + + <sect1> + <title>The FreeBSD Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.freebsd.org/docproj/">The FreeBSD + Documentation Project web pages</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.freebsd.org/handbook/">The FreeBSD Handbook</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>SGML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web + page</ulink>, a comprehensive SGML resource</para> + </listitem> + + <listitem> + <para><ulink + url='http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG">http://etext.virginia.edu/bin/tei-tocs?div=DIV1&id=SG'>Gentle introduction to SGML</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>HTML</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.w3.org/">The World Wide Web + organisation</ulink></para> + </listitem> + + <listitem> + <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0 + specification</ulink></para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>DocBook</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://www.oreilly.com/davenport/">The Davenport + Group</ulink>, maintainers of the DocBook DTD</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1> + <title>The Linux Documentation Project</title> + + <itemizedlist> + <listitem> + <para><ulink url="http://metalab.unc.edu/LDP/">The Linux Documentation + Project web pages</ulink></para> + </listitem> + </itemizedlist> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-markup"> + <title>SGML Markup</title> + + <para>This chapter describes the three 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.</para> + + <para>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.</para> + + <para>This is <emphasis>not</emphasis> 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 mailing list + <email>freebsd-doc@freebsd.org</email>.</para> + + <note> + <title>Inline vs. block</title> + + <para>In the remainder of this document, when describing elements, + <emphasis>inline</emphasis> means that the element can occur within a + block element, and does not cause a line break. A + <emphasis>block</emphasis> element, by comparison, will cause a line + break (and other processing) when it is encountered.</para> + </note> + + <sect1> + <title>HTML</title> + + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML is used to markup pages on the FreeBSD web site. It should not + (generally) be used to mark up other documention, 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.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the + latest, 4.0 (available in both <emphasis>strict</emphasis> and + <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> port. They are automatically + installed as part of the <filename>textproc/docproj</filename> port.</para> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>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.</para> + + <para>The majority of HTML documents on the FreeBSD web site comply with + the loose version of HTML 4.0.</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>An HTML document is normally split in to two sections. The first + section, called the <emphasis>head</emphasis>, 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 + <emphasis>body</emphasis>, contains the content that will be displayed + to the user.</para> + + <para>These sections are indicated with <sgmltag>head</sgmltag> and + <sgmltag>body</sgmltag> elements respectively. These elements are + contained within the top-level <sgmltag>html</sgmltag> element.</para> + + <example> + <title>Normal HTML document structure</title> + + <programlisting> +<html> + <head> + <title><replaceable>The document's title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Headings</title> + + <para>HTML allows you to denote headings in your document, at up to + six different levels.</para> + + <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, + then <sgmltag>h2</sgmltag>, continuing down to + <sgmltag>h6</sgmltag>.</para> + + <para>The element's content is the text of the heading.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 -->]]></programlisting> + </example> + + <para>Generally, an HTML page should have one first level heading + (<sgmltag>h1</sgmltag>). This can contain many second level headings + (<sgmltag>h2</sgmltag>), which can in turn contain many third level + headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> + element should have the same element, but one further up the + hierarchy, preceeding it. Leaving gaps in the numbering is to be + avoided.</para> + + <example> + <title>Bad ordering of + <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<h1>First section</h1> + +<!-- Document introduction --> + +<h3>Sub-section</h3> + +<!-- This is bad, <h2> has been left out -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Paragraphs</title> + + <para>HTML supports a single paragraph element, + <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>A block quotation is an extended quotation from another document + that should not appear within the current paragraph.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Lists</title> + + <para>You can present the user with three types of lists, ordered, + unordered, and definition.</para> + + <para>Typically, each entry in an ordered list will be numbered, while + each entry in an unordered list will be proceeded 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.</para> + + <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> + element, unordered lists by the <sgmltag>ul</sgmltag> element, and + definition lists by the <sgmltag>dl</sgmltag> element.</para> + + <para>Ordered and unordered lists contain listitems, indicated by the + <sgmltag>li</sgmltag> element. A listitem can contain textual + content, or it may be further wrapped in one or more + <sgmltag>p</sgmltag> elements.</para> + + <para>Definition lists contain definition terms + (<sgmltag>dt</sgmltag>) and definition descriptions + (<sgmltag>dd</sgmltag>). A definition term can only contain inline + elements. A definition description can contain other block + elements.</para> + + <example> + <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>An unordered list. Listitems will probably be + preceeded 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>]]></programlisting> + </example> + + <example> + <title>Definition lists with <sgmltag>dl</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p></dd> + + <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>Paragraph 1 of definition 3. Note that the <p> + element is not required in the single paragraph case.</dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Pre-formatted text</title> + + <para>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 in to one, and line + breaks in the text are significant.</para> + + <para>In order to do this, wrap the content in the + <sgmltag>pre</sgmltag> element.</para> + + <example> + <title><sgmltag>pre</sgmltag></title> + + <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail + message;</para> + + <programlisting> +<![ CDATA [<pre> + From: nik@freebsd.org + To: freebsd-doc@freebsd.org + Subject: New documentation available + + There's a new copy of my primer for contributers to the FreeBSD + Documentation Project available at + + <URL:http://www.freebsd.org/~nik/primer/index.html> + + Comments appreciated. + + N +</pre>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Tables</title> + + <note> + <para>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.</para> + </note> + + <para>Mark up tabular information using the <sgmltag>table</sgmltag> + element. A table consists of one or more table rows + (<sgmltag>tr</sgmltag>), each containing one or more cells of table + data (<sgmltag>td</sgmltag>). 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 + <sgmltag>p</sgmltag> element.</para> + + <example> + <title>Simple use of <sgmltag>table</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting></example> + + <para>A cell can span multiple rows and columns. To indicate this, add + the <literal>rowspan</literal> and/or <literal>colspan</literal> + attributes, with values indicating the number of rows of columns + that should be spanned.</para> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>colspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <example> + <title>Using <literal>rowspan</literal> and + <literal>colspan</literal> together</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged in to 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 in to + 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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>You have two levels of emphasis available in HTML, + <sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal + level of emphasis and <sgmltag>strong</sgmltag> indicates stronger + emphasis.</para> + + <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and + <sgmltag>strong</sgmltag> is rendered in bold. This is not always + the case however, and you should not rely on it.</para> + + <example> + <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><em>This</em> has been emphasised, while + <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Bold and italics</title> + + <para>Because HTML includes presentational markup, you can also + indicate that particular content should be rendered in bold or + italic. The elements are <sgmltag>b</sgmltag> and + <sgmltag>i</sgmltag> respectively.</para> + + <example> + <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> + + <programlisting> +<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + in italics.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating fixed pitch text</title> + + <para>If you have content that should be rendered in a fixed pitch + (typewriter) typeface, use <sgmltag>tt</sgmltag> (for + “teletype”).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This document was originally written by + Nik Clayton, who can be reached by e-mail as + <tt>nik@freebsd.org</tt>.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Content size</title> + + <para>You can indicate that content should be shown in a larger or + smaller font. There are three ways of doing this.</para> + + <orderedlist> + <listitem> + <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> + around the content you wish to change size. These tags can be + nested, so <literal><big><big>This is much + bigger</big></big></literal> is possible.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to <literal>+1</literal> or <literal>-1</literal> + respectively. This has the same effect as using + <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the + use of this approach is deprecated.</para> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to a number between 1 and 7. The default font size + is <literal>3</literal>. This approach is deprecated.</para> + </listitem> + </orderedlist> + + <example> + <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and + <sgmltag>font</sgmltag></title> + + <para>The following fragments all do the same thing.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other documents on the WWW</title> + + <para>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.</para> + + <para>The link is indicated with <sgmltag>a</sgmltag>, and the + <literal>href</literal> 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 + colour, different mouse cursor when over the link, and so on).</para> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>More information is available at the + <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting> + </example> + + <para>These links will take the user to the top of the chosen + document.</para> + </sect3> + + <sect3> + <title>Linking to other parts of documents</title> + + <para>Linking to a point within another document (or within the same + document) requires that the document author include anchors that you + can link to.</para> + + <para>Anchors are indicated with <sgmltag>a</sgmltag> and the + <literal>name</literal> attribute instead of + <literal>href</literal>.</para> + + <example> + <title>Using <literal><a name="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + in other links with the name <tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>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 + <literal>#</literal> symbol.</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in a + document called <filename>foo.html</filename>.</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="foo.html#para1">first paragraph</a> of + <tt>foo.html</tt>.</p>]]></programlisting> + </example> + + <para>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 preceeding <literal>#</literal>).</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in + this document</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="#para1">first paragraph</a> of this + document.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>DocBook</title> + + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be + a DTD for writing technical documentation. As such, and unlike LinuxDoc + and HTML, DocBook is very heavily orientated towards markup that + describes <emphasis>what</emphasis> something is, rather than describing + <emphasis>how</emphasis> it should be presented.</para> + + <note> + <title><literal>formal</literal> vs. <literal>informal</literal></title> + + <para>Some elements may exist in two forms, <emphasis>formal</emphasis> + and <emphasis>informal</emphasis>. Typically, the formal version of + the element will consist of a title followed by the information + version of the element. The informal version will not have a + title.</para> + </note> + + <para>The DocBook DTD is available from the ports collection in the + <filename>textproc/docbook</filename> port. It is automatically + installed as part of the <filename>textproc/docproj</filename> + port.</para> + + <sect2> + <title>FreeBSD extensions</title> + + <para>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.</para> + + <para>Where a FreeBSD specific element is listed below it is clearly + marked.</para> + + <para>Throughout the rest of this document, the term + “DocBook” is used to mean the FreeBSD extended DocBook + DTD.</para> + + <note> + <para>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 Nik Clayton <email>nik@freebsd.org</email>.</para> + </note> + </sect2> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing FPIs for + DocBook customisations, the FPI for the FreeBSD extended DocBook DTD + is;</para> + + <programlisting> +PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>DocBook contains a number of elements for marking up the structure + of a book.</para> + + <para>Generally, the top level (first) element will be + <sgmltag>book</sgmltag>.</para> + + <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a + mandatory requirement. There may be <sgmltag>part</sgmltag>s between + the book and the chapter to provide another layer of organisation. The + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. These are + indicated with the <sgmltag>sect1</sgmltag> element. If a section + contains another section then use the <sgmltag>sect2</sgmltag> + element, and so on, up to <sgmltag>sect5</sgmltag>.</para> + + <para>Chapters and sections contain the remainder of the content.</para> + + <sect3> + <title>Starting a book</title> + + <para>The content of the book is contained within the + <sgmltag>book</sgmltag> 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.</para> + + <para>This additional information should be contained within + <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting> +<book> + <bookinfo> + <title><replaceable>Your title here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating chapters</title> + + <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each + chapter has a mandatory <sgmltag>title</sgmltag>.</para> + + <example> + <title>A simple chapter</title> + + <programlisting> +<![ CDATA [<chapter> + <title>The chapter's title</title> + + ... +</chapter>]]></programlisting> + </example> + + <para>A chapter can not be empty, it must contain elements in addition + to <sgmltag>title</sgmltag>. If you need to include an empty chapter + then just use an empty paragraph.</para> + + <example> + <title>Empty chapters</title> + + <programlisting> +<![ CDATA [<chapter> + <title>This is an empty chapter</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sections below chapters</title> + + <para>Chapters can be broken up into sections, subsections, and so + on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> + element. The <replaceable>n</replaceable> indicates the section + number, which identifies the section level.</para> + + <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is + <sgmltag>sect1</sgmltag>. You can have one or more of these in a + chapter. They can contain one or more <sgmltag>sect2</sgmltag> + elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> + + <example> + <title>Sections in chapters</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Subdividing using <sgmltag>part</sgmltag>s</title> + + <para>You can introduce another layer of organisation between + <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or + more <sgmltag>part</sgmltag>s.</para> + + <programlisting> +<![ CDATA [<part> + <title>Introduction</title> + + <chapter> + <title>Overview</title> + + ... + </chapter> + + <chapter> + <title>What is FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>History</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs; + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and + <sgmltag>simpara</sgmltag>.</para> + + <para>Most of the time you will only need to use + <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a + <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> + disallows some elements from within <sgmltag>para</sgmltag>. Stick + with <sgmltag>para</sgmltag>.</para> + + <example> + <title><sgmltag>para</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>This is a paragraph. It can contain just about any + other element.</para> ]]></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any other + element.</para> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>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.</para> + + <para>Blockquotes can optionally contain a title and an attribution + (or they can be left untitled and unattributed).</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>A small excerpt from the US Constitution;</para> + +<blockquote> + <title>Preamble to the Constitution of the United States</para> + + <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>]]></programlisting> + + <para>Appearance:</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> + </example> + </sect3> + + <sect3> + <title>Tips, notes, warnings, cautions, important information and + sidebars.</title> + + <para>You may need to include extra information separate from the + main body of the text. Typically this is “meta” + information that the user should be aware of.</para> + + <para>Depending on the nature of the information, one of + <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, + <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and + <sgmltag>important</sgmltag> should be used. Alternatively, if the + information is related to the main text but is not one of the above, + use <sgmltag>sidebar</sgmltag>.</para> + + <para>The circumstances in which to choose one of these elements over + another is unclear. The DocBook documentation suggests;</para> + + <itemizedlist> + <listitem> + <para>A Note is for information that should be heeded by all + readers.</para> + </listitem> + + <listitem> + <para>An Important element is a variation on Note.</para> + </listitem> + + <listitem> + <para>A Caution is for information regarding possible data loss + or software damage.</para> + </listitem> + + <listitem> + <para>A Warning is for information regarding possible hardware + damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + harddisk.</para> +</warning>]]></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows from + your harddisk.</para> + </warning> + </sect3> + + <sect3> + <title>Lists and procedures</title> + + <para>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.</para> + + <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, or + <sgmltag>procedure</sgmltag><footnote><para>There are other types of + list element in DocBook, but we're not concerned with those at + the moment.</para> + </footnote> + </para> + + <para><sgmltag>itemizedlist</sgmltag> and + <sgmltag>orderedlist</sgmltag> are similar to the counterparts in + HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one + consists of one or more <sgmltag>listentry</sgmltag> elements, and + each <sgmltag>listentry</sgmltag> contains one or more block + elements. The <sgmltag>listentry</sgmltag> elements are analagous to + HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are + required.</para> + + <para><sgmltag>procedure</sgmltag> is slightly different. It consists + of <sgmltag>step</sgmltag>s, which may in turn consists of more + <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each + <sgmltag>step</sgmltag> contains block elements.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing file samples</title> + + <para>If you want to show a fragment of a file (or perhaps a complete + file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> + element.</para> + + <para>White space and line breaks within + <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> + significant. In particular, this means that the closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will be included.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA[<para>When you have finished, your program should look like + this;</para> + +<programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by their + entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this;</para> + + <programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + + <note> + <para>There is a mechanism within DocBook for referring to sections + of a previously occuring <sgmltag>programlisting</sgmltag>, called + callouts (see <sgmltag>programlistingco</sgmltag> for more + information). I don't fully understand (i.e., have never used) + this feature, so can't document it here. For the mean time, you + can include line numbers within the content, and then refer to + them later on in your description. That will change, as soon as I + find the time to understand and document callouts.</para> + </note> + </sect3> + + <sect3> + <title>Tables</title> + + <para>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.</para> + + <para>In general terms (and see the DocBook documentation for more + detail) a table (which can be either formal or informal) consists of + a <sgmltag>table</sgmltag> element. This contains at least one + <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) + the number of columns in this table group. Within the tablegroup you + can then have one <sgmltag>thead</sgmltag> element, which contains + elements for the table headings (column headings), and one + <sgmltag>tbody</sgmltag> which contains the body of the + table.</para> + + <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> + contain <sgmltag>row</sgmltag> elements, which in turn contain + <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> + element specifies one cell in the table.</para> + + <example> + <title><sgmltag>informaltable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informaltable> + <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>]]></programlisting> + + <para>Appearance:</para> + + <informaltable> + <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> + </example> + + <para>If you don't want a border around the table the + <literal>frame</literal> attribute can be added to the + <sgmltag>informaltable</sgmltag> element with a value of + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + <example> + <title>Tables where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none"> + <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> + </example> + </sect3> + + <sect3> + <title>Examples for the user to follow</title> + + <para>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.</para> + + <para>A number of distinct elements and entities come in to play + here.</para> + + <variablelist> + <varlistentry> + <term><sgmltag>informalexample</sgmltag></term> + + <listitem> + <para>Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be <sgmltag>informalexample</sgmltag>. For those times + when you do need to include a title on the example, use + <sgmltag>example</sgmltag>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Everything the user sees in this example will be on the + computer screen, so the next element is + <sgmltag>screen</sgmltag>.</para> + + <para>Within <sgmltag>screen</sgmltag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the screen + are prompts from the computer (either from the OS, command + shell, or application. These should be marked up using + <sgmltag>prompt</sgmltag>.</para> + + <para>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 <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. They do not + need to be inside <sgmltag>prompt</sgmltag>.</para> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the original + DTD.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>When displaying text that the user should type in, wrap it + in <sgmltag>userinput</sgmltag> tags. It will probably be + displayed differently to the user.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>informalexample</sgmltag>, + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <sgmltag>userinput</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <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> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <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> + </informalexample> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> marked + up as <sgmltag>programlisting</sgmltag>. Reserve + <sgmltag>programlisting</sgmltag> for showing fragments of files + outside the context of user actions.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>When you want to emphasise a particular word or phrase, use + <sgmltag>emphasis</sgmltag>. This may be presented as italic, or + bold, or might be spoken differently with a text-to-speech + system.</para> + + <para>There is no way to change the presentation of the emphasis + within your document, no equivalent of HTML's <sgmltag>b</sgmltag> + and <sgmltag>i</sgmltag>. If the information you are presenting is + important then consider presenting it in + <sgmltag>important</sgmltag> rather than + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix + like operating system for the Intel architecture.</para> + </example> + </sect3> + + <sect3> + <title>Applications, commands, options, and cites</title> + + <para>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.</para> + + <para>In addition, you will occasionally need to list one or more of + the options that a command might take.</para> + + <para>Finally, you will often want to list a command with it's manual + section number, in the “command(number)” format so + common in Unix manuals.</para> + + <para>Mark up application names with + <sgmltag>application</sgmltag>.</para> + + <para>When you want to list a command with it's manual section number + (which should be most of the time) the DocBook element is + <sgmltag>citerefentry</sgmltag>. This will contain a further two + elements, <sgmltag>refentrytitle</sgmltag> and + <sgmltag>manvolnum</sgmltag>. The content of + <sgmltag>refentrytitle</sgmltag> is the name of the command, and the + content of <sgmltag>manvolnum</sgmltag> is the manual page + section.</para> + + <para>This can be cumbersome to write, and so a series of <link + linkend="general-entities">general entities</link> have been + created to make this easier. Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/sgml/man-refs.ent</filename>, and can be + referred to using this FPI;</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to your documentation will probably + look like this;</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]]></programlisting> + + <para>Use <sgmltag>command</sgmltag> when you want to include a + command name “in-line” but present it as something the + user should type in.</para> + + <para>Use <sgmltag>option</sgmltag> to mark up a command's + options.</para> + + <para>This can be confusing, and sometimes the choice is not always + clear. Hopefully this example makes it clearer.</para> + + <example> + <title>Applications, commands, and options.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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.sendmail.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>]]></programlisting> + + <para>Appearance:</para> + + <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>, <citerefentry> + <refentrytitle>mailq</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, and <citerefentry> + <refentrytitle>newaliases</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> 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> + </example> + + <note> + <para>Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> + </note> + </sect3> + + <sect3> + <title>Files, directories, extensions</title> + + <para>Whenever you wish to refer to the name of a file, a directory, + or a file extension, use <sgmltag>filename</sgmltag>.</para> + + <example> + <title><sgmltag>filename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Devices</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When referring to devices you have two choices. You can either + refer to the device as it appears in <filename>/dev</filename>, or + you can use the name of the device as it appears in the kernel. For + this latter course, use <sgmltag>devicename</sgmltag>.</para> + + <para>Sometimes you will not have a choice. Some devices, such as + networking cards, do not have entries in <filename>/dev</filename>, + or the entries are markedly different from those entries.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Hosts, domains, IP addresses, and so forth</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>You can markup identification information for networked + computers (hosts) in several ways, depending on the nature of the + information. All of them use <sgmltag>hostid</sgmltag> as the + element, with the <literal>role</literal> attribute selecting the + type of the marked up information.</para> + + <variablelist> + <varlistentry> + <term>No role attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no role attribute (i.e., + <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the + marked up information is the simple hostname, such as + <literal>freefall</literal> or <literal>wcarchive</literal>. + You can explicitly specify this with + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>freebsd.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with both + hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>The text is an IP address, probably expressed as a dotted + quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be expressed as a + dotted quad, a hexadecimal string, or as a + <literal>/</literal> followed by a number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an ethernet MAC address, expressed as a series + of 2 digit hexadecimal numbers seperated by colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>hostid</sgmltag> and roles</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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 + in existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When you need to refer to a specific username, such as + <literal>root</literal> or <literal>bin</literal>, use + <sgmltag>username</sgmltag>.</para> + + <example> + <title><sgmltag>username</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>To carry out most system administration functions you + will need to be <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions you will + need to be <username>root</username>.</para> + </example> + </sect3> + + <sect3> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag>.</para> + + <para><sgmltag>maketarget</sgmltag> identifies a build target exported + by a <filename>Makefile</filename> that can be given as a parameter + to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a + variable that can be set (in the environment, on the + <command>make</command> command line, or within the + <filename>Makefile</filename>) to influence the process.</para> + + <example> + <title><sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Literal text</title> + + <para>You will often need to include “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.</para> + + <para>Some of the time, <sgmltag>programlisting</sgmltag> will be + sufficient to denote this text. <sgmltag>programlisting</sgmltag> is + not always appropriate, particularly when you want to include a + portion of a file “in-line” with the rest of the + paragraph.</para> + + <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + + <sect3> + <title>Showing items that the user <emphasis>must</emphasis> fill + in</title> + + <para>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 + can not simply copy the examples that you provide, but must instead + include some information themselves.</para> + + <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. + Use it <emphasis>inside</emphasis> other elements to indicate parts + of that element's content that the user must replace.</para> + + <example> + <title><sgmltag>replaceable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><sgmltag>replaceable</sgmltag> can be used in many different + elements, including <sgmltag>literal</sgmltag>. This example also + shows that <sgmltag>replaceable</sgmltag> should only be wrapped + around the content that the user <emphasis>is</emphasis> meant to + provide. The other content should be left alone.</para> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>Appearance:</para> + + <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> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other parts of the same document</title> + + <para>Linking within the same document requires you to 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).</para> + + <para>Each element within DocBook has an attribute called + <literal>id</literal>. You can place text in this attribute to + uniquely name the element it is attached to.</para> + + <para>This value will be used when you specify the link + source.</para> + + <para>Normally, you will only be linking to chapters or sections, so + you would add the <literal>id</literal> attribute to these + elements.</para> + + <example> + <title><literal>id on chapters and sections</literal></title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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 + <literal>id</literal> for the subsection is constructed by appending + text to the <literal>id</literal> of the chapter. This helps to + ensure that they are unique.</para> + + <para>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 <sgmltag>anchor</sgmltag>. This element has no content, but + takes an <literal>id</literal> attribute.</para> + + <example> + <title><sgmltag>anchor</sgmltag></title> + + <programlisting> +<![ CDATA [<para>This paragraph has an embedded + <anchor id="para1">link target in it. It won't show up in + the document.</para>]]></programlisting> + </example> + + <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 <literal>id</literal> attribute, you can use either + <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> + + <para>Both of these elements have a <literal>linkend</literal> + attribute. The value of this attribute should be the value that you + have used in a <literal>id</literal> attribute (it does not matter + if that value has not yet occured in your document, this will work + for forward links as well as backward links).</para> + + <para>If you use <sgmltag>xref</sgmltag> then you have no control over + the text of the link. It will be generated for you.</para> + + <example> + <title>Using <sgmltag>xref</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example;</para> + + <programlisting> +<![ CDATA [<para>More information can be found + in <xref linkend="chapter1">.</para> + +<para>More specific information can be found + in <xref linkend="chapter1-sect1">.</para>]]></programlisting> + + <para>The text of the link will be generated automatically, and will + look like (<emphasis>emphasised</emphasis> text indicates the text + that will be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + One</emphasis>.</para> + + <para>More specific information can be found in <emphasis>the + section called Sub-sect 1</emphasis>.</para> + </blockquote> + </example> + + <para>Notice how the text from the link is derived from the section + title or the chapter number.</para> + + <note> + <para>This means that you <emphasis>can not</emphasis> use + <sgmltag>xref</sgmltag> to link to an <literal>id</literal> + attribute on an <sgmltag>anchor</sgmltag> element. The + <sgmltag>anchor</sgmltag> has no content, so the + <sgmltag>xref</sgmltag> can not generate the text for the + link.</para> + </note> + + <para>If you want to control the text of the link then use + <sgmltag>link</sgmltag>. This element wraps content, and the content + will be used for the link.</para> + + <example> + <title>Using <sgmltag>link</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + + <para>This will generate the following + (<emphasis>emphasised</emphasis> text indicates the text that will + be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>the first + chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>this</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para>That last one is a bad example. Never use words like + “this” or “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.</para> + </note> + + <note> + <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to + include a link to an <literal>id</literal> on an + <sgmltag>anchor</sgmltag> element, since the + <sgmltag>link</sgmltag> content defines the text that will be used + for the link.</para> + </note> + </sect3> + + <sect3> + <title>Linking to documents on the WWW</title> + + <para>Linking to external documents is much simpler, as long as you + know the URL of the document you want to link to. Use + <sgmltag>ulink</sgmltag>. The <literal>url</literal> 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.</para> + + <example> + <title><sgmltag>ulink</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>Of course, you could stop reading this document and + go to the <ulink url="http://www.freebsd.org/">FreeBSD + home page</ulink> instead.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go to the + <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink> + instead.</para> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>* LinuxDoc</title> + + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the + <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD Documentation + Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup rather + than content related markup (i.e., it describes what something looks + like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux Documentation + Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + </sect1> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml new file mode 100644 index 0000000000..c25bacf1f1 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -0,0 +1,1554 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="sgml-primer"> + <title>SGML Primer</title> + + <para>The Documentation Project makes heavy use of the Standard Generalized + Markup Language (SGML). This chapter describes what SGML is, how to read + and understand markup, and some of the SGML tricks you will see used in + the FAQ, Handbook, and website.</para> + + <para>Portions of this section were inspired by Mark Galassi's <ulink + url="http://nis-www.lanl.gov/~rosalia/mydocs/docbook-intro/docbook-intro.html">Get Going With DocBook</ulink>.</para> + + <sect1> + <title>Overview</title> + + <para>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.</para> + + <para>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 emphasised, or added to a glossary, or be hyperlinks. + You might want filenames to be shown in a “typewriter” style + font for viewing on screen, but as “italics” when printed, + or any of a myriad of other options for presentation.</para> + + <para>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 the can + meaningfully process our text.</para> + + <para>More precisely, they need help identifying what is what. You or I + can look at + + <blockquote> + <para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + + <para><command>rm /tmp/foo</command></para> + </blockquote> + + 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 can not. For this we need + markup.</para> + + <para>“Markup” is commonly used to describe “adding + value” or “increasing cost”. The term takes on both + these meanings when applied to text. Markup is additional text included + in the document, distinguished from the document's content in some way, + so that programs that process the document can read the markup and use + it when making decisions about the document. Editors can hide the + markup from the user, so they are not distracted by it.</para> + + <para>The extra information stored in the markup <emphasis>adds + value</emphasis> to the document. Adding the markup to the document + must typically be done by a person—after all, if computers could + recognise the text sufficiently well to add the markup then there would + be no need to add it in the first place. This <emphasis>increases the + cost</emphasis> of the document.</para> + + <para>The previous example is actually represented in this document like + this;</para> + + <programlisting><![ CDATA [ +<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + +<para><command>rm /tmp/foo</command></para>]]></programlisting> + + <para>As you can see, the markup is clearly separate from the + content.</para> + + <para>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.</para> + + <para>SGML is <emphasis>not</emphasis> a markup langugage. Instead, SGML + is <emphasis>the language in which you write markup + languages</emphasis>. There have been many markup languages written + using SGML. HTML and DocBook are two of these.</para> + + <para>This is an important point to understand. Most of the time you are + not writing SGML documents. Instead, you are writing documents in a + particular markup language. The definition of the markup language you + are using is written in SGML.</para> + + <para>Each language definition (which is written in SGML) 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.</para> + + <para id="sgml-primer-validating">A DTD is a <emphasis>complete</emphasis> + 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 a + <emphasis>parser</emphasis> which reads in 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 <quote>validating the document</quote>.</para> + + <note> + <para>This processing simply confirms that the choice of elements, their + ordering, and so on, conforms to that listed in the DTD. It does + <emphasis>not</emphasis> check that you have used + <emphasis>appropriate</emphasis> markup for the content. If you were + to try and 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).</para> + </note> + + <para>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.</para> + </sect1> + + <sect1 id="elements"> + <title>Elements, tags, and attributes</title> + + <para>All the DTDs written in SGML share certain characteristics. This is + hardly surprising, as the philisophy behind SGML will inevitably show + through. One of the most obvious manifestations of this philisophy is + that of <emphasis>content</emphasis> and + <emphasis>elements</emphasis>.</para> + + <para>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.</para> + + <para>For example, consider a typical book. At the very top level, the + book is itself an element. This “book” element obviously + contains chapters, which can be considered to be elements in their own + right. Each chapter will contain more elements, such as paragraphs, + quotations, and footnotes. Each paragraph might contain further + elements, identifying content that was direct speech, or the name of a + character in the story.</para> + + <para>You might like to think of this as “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.</para> + + <para>Notice how you can make this differentation 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 colours to indicate + different types of content.</para> + + <para>Of course, we don't 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 <emphasis>tags</emphasis>.</para> + + <para>A tag is used to identify where a particular element starts, and + where the ends. <emphasis>The tag is not part of the element + itself</emphasis>. Because each DTD was normally written to mark up + specific types of information, each one will recognise different + elements, and will therefore have different names for the tags.</para> + + <para>For an element called <replaceable>element-name</replaceable> the + start tag will normally look like + <literal><<replaceable>element-name</replaceable>></literal>. The + corresponding closing tag for this element is + <literal></<replaceable>element-name</replaceable>></literal>.</para> + + <example> + <title>Using an element (start and end tags)</title> + + <para>HTML has an element for indicating that the content enclosed by + the element is a paragraph, called <literal>p</literal>. This + element has both start and end tags.</para> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Using an element (start tag only)</title> + + <para>HTML has an element for indicating a horizontal rule, called + <literal>hr</literal>. This element does not wrap content, so only has + a start tag.</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph.</p> + +<hr> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> + </example> + + <para>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.</para> + + <example> + <title>Elements within elements; <sgmltag>em</sgmltag></title> + + <programlisting> +<![ CDATA [<p>This is a simple <em>paragraph</em> where some + of the <em>words</em> have been <em>emphasised</em>.</p>]]></programlisting> + </example> + + <para>The DTD will specify the rules detailing which elements can contain + other elements, and exactly what they can contain.</para> + + <important> + <para>People often confuse the terms tags and elements, and use the terms + as if they were interchangeable. They are not.</para> + + <para>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.</para> + + <para>When this document (or anyone else knowledgable about SGML) refers + to “the <p> tag” they mean the literal text + consisting of the three characters <literal><</literal>, + <literal>p</literal>, and <literal>></literal>. But the phrase + “the <p> element” refers to the whole element.</para> + + <para>This distinction <emphasis>is</emphasis> very subtle. But keep it + in mind.</para> + </important> + + <para>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 occurence of the element, or + it might be something else.</para> + + <para>An element's attributes are written <emphasis>inside</emphasis> the + start tag for that element, and take the form + <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> + + <para>In sufficiently recent versions of HTML, the <sgmltag>p</sgmltag> + element has an attribute called <literal>align</literal>, which suggests + an alignment (justification) for the paragraph to the program displaying + the HTML.</para> + + <para>The <literal>align</literal> attribute can take one of four defined + values, <literal>left</literal>, <literal>center</literal>, + <literal>right</literal> and <literal>justify</literal>. If the + attribute is not specified then the default is + <literal>left</literal>.</para> + + <example> + <title>Using an element with an attribute</title> + + <programlisting> +<![ CDATA [<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>]]></programlisting> + </example> + + <para>Some attributes will only take specific values, such as + <literal>left</literal> or <literal>justify</literal>. Others will + allow you to enter anything you want. If you need to include quotes + (<literal>"</literal>) within an attribute then use single quotes around + the attribute value.</para> + + <example> + <title>Single quotes around attributes</title> + + <programlisting> +<![ CDATA [<p align='right'>I'm on the right!</p>]]></programlisting> + </example> + + <para>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 <emphasis>always</emphasis> quote your attribute values.</para> + + <sect2> + <title>For you to do…</title> + + <para>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.</para> + + <procedure> + <step> + <para>Download and install <filename>textproc/docproj</filename> + from the FreeBSD ports system. This is a + <emphasis>meta-port</emphasis> that should download and install + all of the programs and supporting files that are used by the + Documentation Project.</para> + </step> + + <step> + <para>Add lines to your shell startup files to set + <envar>SGML_CATALOG_FILES</envar>.</para> + + <example id="sgml-primer-envars"> + <title><filename>.profile</filename>, for &man.sh.1; and + &man.bash.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES</programlisting> + </example> + + <example> + <title><filename>.login</filename>, for &man.csh.1; and + &man.tcsh.1; users</title> + + <programlisting> +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/3.0/catalog:$SGML_CATALOG_FILES</programlisting> + </example> + + <para>Then either log out, and log back in again, or run those + commands from the command line to set the variable values.</para> + </step> + </procedure> + + <procedure> + <step> + <para>Create <filename>example.sgml</filename>, and enter the + following text;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Try and validate this file using an SGML parser.</para> + + <para>Part of <filename>textproc/docproj</filename> is the + &man.nsgmls.1; <link linkend="sgml-primer-validating">validating + parser</link>. Normally, &man.nsgmls.1; 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).</para> + + <para>However, when <option>-s</option> is passed as a parameter to + it, &man.nsgmls.1; 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.</para> + + <para>Use &man.nsgmls.1; to check that your document is + valid;</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput></screen> + + <para>As you will see, &man.nsgmls.1; returns without displaying any + output. This means that your document validated + successfully.</para> + </step> + + <step> + <para>See what happens when required elements are omitted. Try + removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> + tags, and re-run the validation.</para> + + <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> +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</screen> + + <para>The error output from &man.nsgmls.1; is organised into + colon-separated groups, or columns.</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Column</entry> + <entry>Meaning</entry> + </row> + </thead> + + <tbody> + <row> + <entry>1</entry> + <entry>The name of the program generating the error. This + will always be <literal>nsgmls</literal>.</entry> + </row> + + <row> + <entry>2</entry> + <entry>The name of the file that contains the error.</entry> + </row> + + <row> + <entry>3</entry> + <entry>Line number where the error appears.</entry> + </row> + + <row> + <entry>4</entry> + <entry>Column number where the error appears.</entry> + </row> + + <row> + <entry>5</entry> + <entry>A one letter code indicating the nature of the + message. <literal>I</literal> indicates an informational + message, <literal>W</literal> is for warnings, and + <literal>E</literal> is for errors<footnote> + <para>It is not always the fifth column either. + <command>nsgmls -sv</command> displays + <literal>nsgmls:I: SP version "1.3"</literal> + (depending on the installed version). As you can see, + this is an informational message.</para> + </footnote>, and <literal>X</literal> is for + cross-references. As you can see, these messages are + errors.</entry> + </row> + + <row> + <entry>6</entry> + <entry>The text of the error message.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Simply omitting the <sgmltag>title</sgmltag> tags has generated + 2 different errors.</para> + + <para>The first error indicates that content (in this case, + characters, rather than the start tag for an element) has occured + 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 <sgmltag>head</sgmltag> (such as + <sgmltag>title</sgmltag>).</para> + + <para>The second error is because <sgmltag>head</sgmltag> elements + <emphasis>must</emphasis> contain a <sgmltag>title</sgmltag> + element. Because it does not &man.nsgmls.1; 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.</para> + </step> + + <step> + <para>Put the <literal>title</literal> element back in.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 id="doctype-declaration"> + <title>The DOCTYPE declaration</title> + + <para>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 the + it.</para> + + <para>This information is generally expressed on one line, in the DOCTYPE + declaration.</para> + + <para>A typical declaration for document written to conform with version + 4.0 of the HTML DTD looks like this;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">]]></programlisting> + + <para>That line contains a number of different components.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>Is the <emphasis>indicator</emphasis> that indicates that this + is an SGML declaration. This line is declaring the document type. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Shows that this is an SGML declaration for the document + type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>Names the first <link linkend="elements">element</link> that + will appear in the document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD HTML 4.0//EN"</literal></term> + + <listitem> + <para>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.</para> + + <para><literal>PUBLIC</literal> 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 <link linkend="fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Returns to the document.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title>Formal Public Identifiers (FPIs)</title> + + <note> + <para>You don't need to know this, but it's useful background, and + might help you debug problems when your SGML processor can't locate + the DTD you are using.</para> + </note> + + <para>FPIs must follow a specific syntax. This syntax is as + follows;</para> + + <programlisting> +"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Owner</replaceable></term> + + <listitem> + <para>This indicates the owner of the FPI.</para> + + <para>If this string starts with “ISO” then this is an + ISO owned FPI. For example, the FPI <literal>"ISO + 8879:1986//ENTITIES Greek Symbols//EN"</literal> lists + <literal>ISO 8879:1986</literal> as being the owner for the set + of entities for greek symbols. ISO 8879:1986 is the ISO number + for the SGML standard.</para> + + <para>Otherwise, this string will either look like + <literal>-//<replaceable>Owner</replaceable></literal> or + <literal>+//<replaceable>Owner</replaceable></literal> (notice + the only difference is the leading <literal>+</literal> or + <literal>-</literal>).</para> + + <para>If the string starts with <literal>-</literal> then the + owner information is unregistered, with a <literal>+</literal> + it identifies it as being registered.</para> + + <para>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 organisation 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).</para> + + <para>Because the FreeBSD Project hasn't been registered the + owner string is <literal>-//FreeBSD</literal>. And as you can + see, the W3C are not a registered owner either.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Keyword</replaceable></term> + + <listitem> + <para>There are several keywords that indicate the type of + information in the file. Some of the most common keywords are + <literal>DTD</literal>, <literal>ELEMENT</literal>, + <literal>ENTITIES</literal>, and <literal>TEXT</literal>. + <literal>DTD</literal> is used only for DTD files, + <literal>ELEMENT</literal> is usually used for DTD fragments + that contain only entity or element declarations. + <literal>TEXT</literal> is used for SGML content (text and + tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Description</replaceable></term> + + <listitem> + <para>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.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Language</replaceable></term> + + <listitem> + <para>This is an ISO two-character code that identifies the native + language for the file. <literal>EN</literal> is used for + English.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title><filename>catalog</filename> files</title> + + <para>If you use the syntax above and try 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.</para> + + <para>In order to do this it can use a catalog file. A catalog file + (typically called <filename>catalog</filename>) contains lines that + map FPIs to filenames. For example, if the catalog file contained the + line;</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> + + <para>The SGML processor would know to look up the DTD from + <filename>strict.dtd</filename> in the <filename>4.0</filename> + subdirectory of whichever directory held the + <filename>catalog</filename> file that contained that line.</para> + + <para>Look at the contents of + <filename>/usr/local/share/sgml/html/catalog</filename>. This is the + catalog file for the HTML DTDs that will have been installed as part + of the <filename>textproc/docproj</filename> port.</para> + </sect3> + + <sect3> + <title><envar>SGML_CATALOG_FILES</envar></title> + + <para>In order to locate a <filename>catalog</filename> 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.</para> + + <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to + point to the files. This environment variable should consist of a + colon-separated list of catalog files (including their full + path).</para> + + <para>Typically, you will want to include the following files;</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/share/sgml/docbook/3.0/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/html/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/iso8879/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/sgml/jade/catalog</filename></para> + </listitem> + </itemizedlist> + + <para>You should <link linkend="sgml-primer-envars">already have done + this</link>.</para> + </sect3> + </sect2> + + <sect2 id="fpi-alternatives"> + <title>Alternatives to FPIs</title> + + <para>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.</para> + + <para>The syntax for this is slightly different;</para> + + <programlisting> +<![ CDATA [<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + + <para>The <literal>SYSTEM</literal> 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.</para> + + <para>Using FPIs is preferred for reasons of portability. You don't want + to have to ship a copy of the DTD around with your document, and if + you used the <literal>SYSTEM</literal> identifier then everyone would + need to keep their DTDs in the same place.</para> + </sect2> + </sect1> + + <sect1 id="sgml-escape"> + <title>Escaping back to SGML</title> + + <para>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.</para> + + <para>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.</para> + + <para>These sections are marked by <literal><! ... ></literal> in + your document. Everything between these delimiters is SGML syntax as you + might find within a DTD.</para> + + <para>As you may just have realised, the <link + linkend="doctype-declaration">DOCTYPE declaration</link> is an example + of SGML syntax that you need to include in your document…</para> + </sect1> + + <sect1> + <title>Comments</title> + + <para>Comments are an SGML construction, and are normally only valid + inside a DTD. However, as <xref linkend="sgml-escape"> shows, it is + possible to use SGML syntax within your document.</para> + + <para>The delimiters for SGML comments is the string + “<literal>--</literal>”. The first occurence of this string + opens a comment, and the second closes it.</para> + + <example> + <title>SGML generic comment</title> + + <programlisting> +<!-- test comment --></programlisting> + + <programlisting><![ CDATA [ +<!-- This is inside the comment --> + +<!-- This is another comment --> + +<!-- This is one way + of doing multiline comments --> + +<!-- This is another way of -- + -- doing multiline comments -->]]></programlisting> + </example> + + <![ %output.print; [ + <important> + <title>Use 2 dashes</title> + + <para>There is a problem with producing the Postscript and PDF versions + of this document. The above example probably shows just one hyphen + symbol, <literal>-</literal> after the <literal><!</literal> and + before the <literal>></literal>.</para> + + <para>You <emphasis>must</emphasis> use two <literal>-</literal>, + <emphasis>not</emphasis> one. The Postscript and PDF versions have + translated the two <literal>-</literal> in the original to a longer, + more professional <emphasis>em-dash</emphasis>, and broken this + example in the process.</para> + + <para>The HTML, plain text, and RTF versions of this document are not + affected.</para> + </important> + ]]> + + <para>If you have used HTML before you may have been shown different rules + for comments. In particular, you may think that the string + <literal><!--</literal> opens a comment, and it is only closed by + <literal>--></literal>.</para> + + <para>This is <emphasis>not</emphasis> 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.</para> + + <example> + <title>Errorneous SGML comments</title> + + <programlisting><![ CDATA [ +<!-- This is in the comment -- + + THIS IS OUTSIDE THE COMMENT! + + -- back inside the comment -->]]></programlisting> + + <para>The SGML parser will treat this as though it were actually;</para> + + <programlisting> +<!THIS IS OUTSIDE THE COMMENT></programlisting> + + <para>This is not valid SGML, and may give confusing error + messages.</para> + + <programlisting> +<![ CDATA [<!--------------- This is a very bad idea --------------->]]></programlisting> + + <para>As the example suggests, <emphasis>do not</emphasis> write + comments like that.</para> + + <programlisting> +<![ CDATA [<!--===================================================-->]]></programlisting> + + <para>That is a (slightly) better approach, but it still potentially + confusing to people new to SGML.</para> + </example> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add some comments to <filename>example.sgml</filename>, and + check that the file still validates using &man.nsgmls.1;</para> + </step> + + <step> + <para>Add some invalid comments to + <filename>example.sgml</filename>, and see the error messages that + &man.nsgmls.1; gives when it encounters an invalid comment.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Entities</title> + + <para>Entities are an SGML term. You might feel more comfortable thinking + of them as variables. There are two types of entity in SGML, general + entities and parameter entities.</para> + + <sect2 id="general-entities"> + <title>General Entities</title> + + <para>General entities are a way of assigning names to chunks of text, + and reusing that text (which may contain markup) throughout your + document.</para> + + <para>You can not use general entities in an SGML context (although you + define them in one). They can only be used in your document. Contrast + this with <link linkend="parameter-entities">parameter + entities</link>.</para> + + <para>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 + <literal>&<replaceable>entity-name</replaceable>;</literal>. For + example, suppose you had an entity called + <literal>current.version</literal> which expanded to the current + version number of your product. You could write;</para> + + <programlisting> +<![ CDATA [<para>The current version of our product is + ¤t.version;.</para>]]></programlisting> + + <para>When the version number changes you can simply change the + definition of the value of the general entity and reprocess your + document.</para> + + <para>You can also use general entities to enter characters that you + could not normally include in an SGML document. For example, < and + & can not normally appear in an SGML document. Normally, when the + SGML processor sees a < symbol it assumes that a tag (either a start + tag or an end tag) is about to appear, and when it sees a & symbol + it assumes the next text will be the name of an entity.</para> + + <para>Fortunately, you can use the two general entities &lt; and + &amp; whenever you need to include one or other of these </para> + + <para>A general entity can only be defined within an SGML context. + Typically, this is done immediately after the DOCTYPE + declaration.</para> + + <example> + <title>Defining general entities</title> + + <programlisting> +<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]>]]></programlisting> + + <para>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.</para> + + <para>The square brackets are necessary to indicate that we are + extending the DTD indicated by the DOCTYPE declaration.</para> + </example> + </sect2> + + <sect2 id="parameter-entities"> + <title>Parameter entities</title> + + <para>Like <link linkend="general-entities">general entities</link>, + 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 <link + linkend="sgml-escape">SGML context</link>.</para> + + <para>Parameter entities are defined in a similar way to general + entities. However, instead of using + <literal>&<replaceable>entity-name</replaceable>;</literal> to + refer to them, use + <literal>%<replaceable>entity-name</replaceable>;</literal><footnote> + <para><emphasis>P</emphasis>arameter entities use the + <emphasis>P</emphasis>ercent symbol.</para> + </footnote>. The definition also includes the <literal>%</literal> + between the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <example> + <title>Defining parameter entities</title> + + <programlisting> +<![ CDATA [<!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" --> +]>]]></programlisting> + </example> + + <para>This may not seem particularly useful. It will be.</para> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Add a general entity to + <filename>example.sgml</filename>.</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </step> + + <step> + <para>Validate the document using &man.nsgmls.1;</para> + </step> + + <step> + <para>Load <filename>example.sgml</filename> into your web browser + (you may need to copy it to <filename>example.html</filename> + before your browser recognises it as an HTML document).</para> + + <para>Unless your browser is very advanced, you won't see the entity + reference <literal>&version;</literal> replaced with the + version number. Most web browsers have very simplistic parsers + which don't do proper SGML<footnote> + <para>This is a shame. Imagine all the problems and hacks (such + as Server Side Includes) that could be avoided if they + did.</para> + </footnote>.</para> + </step> + + <step> + <para>The solution is to <emphasis>normalise</emphasis> your + document. Normalising it involves converting all the entity + references to the values of those entities.</para> + + <para>You can use &man.sgmlnorm.1; to do this.</para> + + <screen>&prompt.user; <userinput>sgmlnorm example.sgml > example.html</userinput></screen> + + <para>You should find a normalised (i.e., entity references + expanded) copy of your document in + <filename>example.html</filename>, ready to load into your web + browser.</para> + </step> + + <step> + <para>If you look at the output from &man.sgmlnorm.1; you will see + that it does not include a DOCTYPE declaration at the start. To + include this you need to use the <option>-d</option> + option;</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + </procedure> + </sect2> + </sect1> + + <sect1> + <title>Using entities to include files</title> + + <para>Entities (both <link linkend="general-entities">general</link> and + <link linkend="parameter-entities">parameter</link>) come into their own + when you realise they can be used to include other files.</para> + + <sect2 id="include-using-gen-entities"> + <title>Using general entities to include files</title> + + <para>Suppose you have some content for an SGML book organised into + files, one file per chapter, called + <filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so forth, with a + <filename>book.sgml</filename> file that will contain these + chapters.</para> + + <para>In order to use the contents of these files as the values for your + entities, you declare them with the <literal>SYSTEM</literal> keyword. + This directs the SGML parser to use the contents of the named file as + the value of the entity.</para> + + <example> + <title>Using general entities to include files</title> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + + <warning> + <para>When using general entities to include other files within a + document, the files being included + (<filename>chapter1.sgml</filename>, + <filename>chapter2.sgml</filename>, and so on) <emphasis>must + not</emphasis> start with a DOCTYPE declaration. This is a syntax + error.</para> + </warning> + </sect2> + + <sect2> + <title>Using parameter entities to include files</title> + + <para>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?</para> + + <para>You can use this to ensure that you can reuse your general + entities.</para> + + <para>Suppose that you had many chapters in your document, and you + reused these chapters in two different books, each book organising the + chapters in a different fashion.</para> + + <para>You could list the entities at the top of each book, but this + quickly becomes cumbersome to manage.</para> + + <para>Instead, place the general entity definitions inside one file, + and use a parameter entity to include that file within your + document.</para> + + <example> + <title>Using parameter entities to include files</title> + + <para>First, place your entity definitions in a separate file, called + <filename>chapters.ent</filename>. This file contains the + following;</para> + + <programlisting> +<![ CDATA [<!ENTITY chapter.1 SYSTEM "chapter1.sgml"> +<!ENTITY chapter.2 SYSTEM "chapter2.sgml"> +<!ENTITY chapter.3 SYSTEM "chapter3.sgml">]]></programlisting> + + <para>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;</para> + + <programlisting> +<![ CDATA [<!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>]]></programlisting> + </example> + </sect2> + + <sect2> + <title>For you to do…</title> + + <sect3> + <title>Use general entities to include files</title> + + <procedure> + <step> + <para>Create three files, <filename>para1.sgml</filename>, + <filename>para2.sgml</filename>, and + <filename>para3.sgml</filename>.</para> + + <para>Put content similar to the following in each file;</para> + + <programlisting> +<![ CDATA [<p>This is the first paragraph.</p>]]></programlisting> + </step> + + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Use parameter entities to include files</title> + + <note> + <para>You must have taken the previous steps first.</para> + </note> + + <procedure> + <step> + <para>Edit <filename>example.sgml</filename> so that it looks like + this;</para> + <programlisting> +<![ CDATA [<!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> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Create a new file, <filename>entities.sgml</filename>, with + this content;</para> + + <programlisting> +<![ CDATA [<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.sgml"> +<!ENTITY para2 SYSTEM "para2.sgml"> +<!ENTITY para3 SYSTEM "para3.sgml">]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by normalising + <filename>example.sgml</filename>.</para> + + <screen>&prompt.user; <userinput>sgmlnorm -d example.sgml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> in to your web + browser, and confirm that the + <filename>para<replaceable>n</replaceable>.sgml</filename> files + have been included in <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>Marked sections</title> + + <para>SGML provides a mechanism to indicate that particular pieces of the + document should be processed in a special way. These are termed + “marked sections”.</para> + + <example> + <title>Structure of a marked section</title> + + <programlisting> +<![ <replaceable>KEYWORD</replaceable> [ + Contents of marked section +]]></programlisting> + </example> + + <para>As you would expect, being an SGML construct, a marked section + starts <literal><!</literal>.</para> + + <para>The first square bracket begins to delimit the marked + section.</para> + + <para><replaceable>KEYWORD</replaceable> describes how this marked + section should be processed by the parser.</para> + + <para>The second square bracket indicates that the content of the marked + section starts here.</para> + + <para>The marked section is finished by closing the two square brackets, + and then returning to the document context from the SGML context with + <literal>></literal></para> + + <sect2> + <title>Marked section keywords</title> + + <sect3> + <title><literal>CDATA</literal>, <literal>RCDATA</literal></title> + + <para>These keywords denote the marked sections <emphasis>content + model</emphasis>, and allow you to change it from the + default.</para> + + <para>When an SGML processor is processing a document, it keeps track + of what is called the “content model”.</para> + + <para>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.</para> + + <para>The two content models you will probably find most useful are + <literal>CDATA</literal> and <literal>RCDATA</literal>.</para> + + <para><literal>CDATA</literal> is for “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.</para> + + <para><literal>RCDATA</literal> is for “Entity references and + character data” If the parser is in this content model then it + is expecting to see characters <emphasis>and</emphasis> entities. + < loses its special status, but & will still be treated as + starting the beginning of a general entity.</para> + + <para>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.</para> + + <!-- The nesting of CDATA within the next example is disgusting --> + + <example> + <title>Using a CDATA marked section</title> + + <programlisting> +<para>Here is an example of how you would include some text + that contained many &lt; and &amp; symbols. The sample + text is a fragment of HTML. The surrounding text (<para> and + <programlisting>) are from DocBook.</para> + +<programlisting> + <![ CDATA [ <![ 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's + 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></programlisting> + + <para>If you look at the source for this document you will see this + technique used throughout.</para> + </example> + </sect3> + + <sect3> + <title><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para>If the keyword is <literal>INCLUDE</literal> then the contents + of the marked section will be processed. If the keyword is + <literal>IGNORE</literal> then the marked section is ignored and + will not be processed. It will not appear in the output.</para> + + <example> + <title>Using <literal>INCLUDE</literal> and + <literal>IGNORE</literal> in marked sections</title> + + <programlisting> +<![ INCLUDE [ + This text will be processed and included. +]]> + +<![ IGNORE [ + This text will not be processed or included. +]]></programlisting> + </example> + + <para>By itself, this isn't too useful. If you wanted to remove text + from your document you could cut it out, or wrap it in + comments.</para> + + <para>It becomes more useful when you realise you can use <link + linkend="parameter-entities">parameter entities</link> to control + this. Remember that parameter entities can only be used in SGML + contexts, and the keyword of a marked section + <emphasis>is</emphasis> an SGML context.</para> + + <para>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 wasn't to + appear in the hard-copy.</para> + + <para>Create a parameter entity, and set it's value to + <literal>INCLUDE</literal>. 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.</para> + + <para>When you want to produce the hard-copy version of the document, + change the parameter entity's value to <literal>IGNORE</literal> and + reprocess the document.</para> + + <example> + <title>Using a parameter entity to control a marked + section</title> + + <programlisting> +<!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. +]]></programlisting> + + <para>When producing the hard-copy version, change the entity's + definition to;</para> + + <programlisting> +<!ENTITY % electronic.copy "IGNORE"></programlisting> + + <para>On reprocessing the document, the marked sections that use + <literal>%electronic.copy</literal> as their keyword will be + ignored.</para> + </example> + </sect3> + </sect2> + + <sect2> + <title>For you to do…</title> + + <procedure> + <step> + <para>Create a new file, <filename>section.sgml</filename>, that + contains the following;</para> + + <programlisting> +<!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> + ]]> + + <![ <![ CDATA [%text.output]]> [ + <p>This paragraph might appear in the output, or it + might not.</p> + + <p>Its appearance is controlled by the <![CDATA[%text.output]]> + parameter entity.</p> + ]]> + </body> +</html></programlisting> + </step> + + <step> + <para>Normalise this file using &man.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.</para> + </step> + + <step> + <para>Change the definition of the <literal>text.output</literal> + entity from <literal>INCLUDE</literal> to + <literal>IGNORE</literal>. Re-normalise the file, and examine the + output to see what has changed. </para> + </step> + </procedure> + </sect2> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml new file mode 100644 index 0000000000..85e5855414 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/stylesheets/chapter.sgml @@ -0,0 +1,68 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="stylesheets"> + <title>* Stylesheets</title> + + <para>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.</para> + + <para>For DocBook, we are using stylesheets written in DSSSL. For HTML we + are using CSS.</para> + + <sect1> + <title>* DSSSL</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + </sect1> + + <sect1> + <title>* CSS</title> + + <para></para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml new file mode 100644 index 0000000000..24cc68a30a --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-faq/chapter.sgml @@ -0,0 +1,47 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-faq"> + <title>* The FAQ</title> + + <para></para> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml new file mode 100644 index 0000000000..9b860d2e7f --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml @@ -0,0 +1,280 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-handbook"> + <title>* The Handbook</title> + + <sect1> + <title>Logical structure</title> + + <para>The Handbook is written to comply with the FreeBSD DocBook extended + DTD.</para> + + <para>The Handbook is organised as a DocBook <sgmltag>book</sgmltag>. It + is then divided into <sgmltag>part</sgmltag>s, each of which may contain + several <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are + further subdivided into sections (<sgmltag>sect1</sgmltag>) and + subsections (<sgmltag>sect2</sgmltag>, <sgmltag>sect3</sgmltag>) and so + on.</para> + </sect1> + + <sect1> + <title>Physical organisation</title> + + <para>The Handbook (and its translations) are in the + <filename>doc/<replaceable>language</replaceable>/handbook</filename> + subdirectory of the main CVS + repository. <replaceable>language</replaceable> corresponds to the ISO + language code for that translation, <literal>en</literal> for English, + <literal>ja</literal> for Japanese, and so on.</para> + + <para>There are a number of files and directories within the + <filename>handbook</filename> directory.</para> + + <note> + <para>The Handbook's organisation may change over time, and this + document may lag in detailing the organisational changes. If you have + any questions about how the Handbook is organised, please contact the + FreeBSD Documentation Project, <email>doc@FreeBSD.ORG</email>.</para> + </note> + + <sect2> + <title><filename>Makefile</filename></title> + + <para>The <filename>Makefile</filename> defines the rules that are used + to convert the Handbook from its source form (DocBook) to a number of + other target formats (including HTML, PostScript, and plain + text).</para> + + <para>A more detailed description of the <filename>Makefile</filename> + is in <xref linkend="the-handbook-converting">.</para> + </sect2> + + <sect2> + <title><filename>handbook.sgml</filename></title> + + <para>This is the top level document in the Handbook. It contains the + Handbook's <link linkend="doctype-declaration">DOCTYPE + declaration</link>, as well as the elements that describe the + Handbook's structure.</para> + + <para><filename>handbook.sgml</filename> uses <link + linkend="parameter-entities">parameter entities</link> to load in + the files with the <filename>.ent</filename> extension. These files + (described later) then define <link linkend="general-entities">general + entities</link> that are used throughout the rest of the + Handbook.</para> + </sect2> + + <sect2> + <title><filename><replaceable>directory</replaceable>/chapter.sgml</filename></title> + + <para>Each chapter in the Handbook is stored in a file called + <filename>chapter.sgml</filename> in a separate directory from the + other chapters. Each directory is named after the value of the + <literal>id</literal> attribute on the <sgmltag>chapter</sgmltag> + element.</para> + + <para>For example, if one of the chapter files contains:</para> + + <programlisting><![ CDATA [ +<chapter id="kernelconfiguration"> +... +</chapter>]]></programlisting> + + <para>then it will be called <filename>chapter.sgml</filename> in the + <filename>kernelconfiguration</filename> directory. In general, the + entire contents of the chapter will be held in this file.</para> + + <para>When the HTML version of the Handbook is produced, this will yield + <filename>kernelconfiguration.html</filename>. This is because of the + <literal>id</literal> value, and is not related to the name of the + directory.</para> + + <para>In earlier versions of the Handbook the files were stored in the + same directory as <filename>handbook.sgml</filename>, and named after + the value of the <literal>id</literal> attribute on the file's + <sgmltag>chapter</sgmltag> element. Moving them in to 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 and 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.</para> + + <para>A brief look will show that there are many directories with + individual <filename>chapter.sgml</filename> files, including + <filename>basics/chapter.sgml</filename>, + <filename>introduction/chapter.sgml</filename>, and + <filename>printing/chapter.sgml</filename>.</para> + + <important> + <para>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 reorganised; this + sort of reorganistion should not (generally) include the need to + rename files (unless entire chapters are being promoted or demoted + within the hierarchy).</para> + </important> + + <para>Each <filename>chapter.sgml</filename> file will not be a complete + SGML document. In particular, they will not have their own DOCTYPE + line at the start of the file.</para> + + <para>This is unfortunate for two reasons;</para> + + <itemizedlist> + <listitem> + <para>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 + <emphasis>would</emphasis> force you to rebuild the Handbook every + time you want to see the effect a change as had on just one + chapter.</para> + </listitem> + + <listitem> + <para>Emacs' <literal>sgml-mode</literal> can not use it to + determine the DTD to use, losing useful benefits of + <literal>sgml-mode</literal> (element completion, automatic + validation, and so on).</para> + </listitem> + </itemizedlist> + </sect2> + </sect1> + + <sect1> + <title>Style guide</title> + + <para>To keep the source for the Handbook consistent when many different + people are editing it, please follow these style conventions.</para> + + <sect2> + <title>Letter case</title> + + <para>Tags are entered in lower case, <literal><para></literal>, + <emphasis>not</emphasis> <literal><PARA></literal>.</para> + + <para>Text that appears in SGML contexts is generally written in upper + case, <literal><!ENTITY…></literal>, and + <literal><!DOCTYPE…></literal>, <emphasis>not</emphasis> + <literal><!entity…></literal> and + <literal><!doctype…></literal>.</para> + </sect2> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + + <para>Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line.</para> + + <para>For example, the source for this section looks something + like;</para> + + <programlisting> +<![ CDATA [+--- This is column 0 +V +<chapter> + <title>...</title> + + <sect1> + <title>...</title> + + <sect2> + <title>Indentation</title> + + <para>Each file starts with indentation set at column 0, + <emphasis>regardless</emphasis> of the indentation level of the file + which might contain this one.</para> + + <para>Every start tag increases the indentation level by 2 spaces, and + every end tag decreases the indentation level by 2 spaces. Content + within elements should be indented by two spaces if the content runs + over more than one line.</para> + + ... + </sect2> + </sect1> +</chapter>]]></programlisting> + + <para>If you use <application>Emacs</application> or + <application>Xemacs</application> to edit the files then + <literal>sgml-mode</literal> should be loaded automatically, and the + Emacs local variables at the bottom of each file should enforce these + styles.</para> + </sect2> + + <sect2> + <title>White space changes</title> + + <para>When committing changes, <emphasis>do not commit changes to the + content at the same time as changes to the + formatting</emphasis>.</para> + + <para>This is so that the teams that convert the Handbook to other + languages can quickly see what content has actually changed in your + commit, without having to decide whether a line has changed because of + the content, or just because it has been refilled.</para> + + <para>For example, if you have added two sentances to a paragraph, such + that the line lengths on the paragraph now go over 80 columns, first + commit your change with the too-long line lengths. Then fix the line + wrapping, and commit this second change. In the commit message for the + second change, be sure to indicate that this is a whitespace-only + change, and that the translation team can ignore it.</para> + </sect2> + </sect1> + + <sect1 id="the-handbook-converting"> + <title>Converting the Handbook to other formats</title> + + <para></para> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml new file mode 100644 index 0000000000..01e4e129f5 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/the-website/chapter.sgml @@ -0,0 +1,47 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="the-website"> + <title>* The Website</title> + + <para></para> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + diff --git a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml new file mode 100644 index 0000000000..2080134fad --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml @@ -0,0 +1,210 @@ +<chapter id="tools"> + <title>* Tools</title> + + <para>The Documentation Project uses a number of tools to assist in the + production of documentation. You will need to install some or all of these + tools before you will be able to make changes.</para> + + <important> + <title>Use <filename>textproc/docproj</filename> if possible</title> + + <para>You can save yourself a lot of time if you install the + <filename>textproc/docproj</filename> port. This is a + <emphasis>meta-port</emphasis> which does not contain any software + itself. Instead, it depends on various other ports being installed + correctly. Installing this port <emphasis>should</emphasis> + automatically download and install all of the packages listed in this + chapter that you need that are missing from your system.</para> + + <para>One of the packages that you might need is the JadeTeX macro set. + In turn, this macro set requires that TeX is installed. TeX is a large + package, and you only need it if you want to produce Postscript or PDF + output.</para> + + <para>To save yourself time and space you must specify whether or not you + want JadeTeX (and therefore TeX) installed when you install this port. + Either do; + + <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> + + or + + <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> + + as necessary.</para> + </important> + + <sect1> + <title>Software</title> + + <para>The project uses the following applications;</para> + + <variablelist> + <varlistentry> + <term><application>Jade</application> and + <application>SP</application></term> + + <listitem> + <para>These are two application suites by James Clark, who has + produced many useful SGML-processing applications. + <application>Jade</application> is “James' DSSSL + Engine”, a system that takes SGML documentation and a DSSSL + stylesheet and produces converted output. + <application>SP</application> contains a number of useful + applications to manipulate, normalise, and interrogate SGML + documents.</para> + + <para>Don't be concerned if these terms are unfamliar to you.</para> + + <para>They can be found in the ports system as + <filename>textproc/jade</filename> and + <filename>textproc/sp</filename> respectively.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>teTeX</application></term> + + <listitem> + <para><application>teTeX</application> is a distrubution of the TeX + typesetting system, and is used (in conjunction with Jade) to + produce the Postscript and PDF output formats.</para> + + <para>v0.9 of <application>teTeX</application> is required, which is + currently in the ports collection as + <filename>print/teTeX-beta</filename>.</para> + + <note> + <para>Might be installed as part of + <filename>textproc/docproj</filename>, depending on the + <makevar>JADETEX</makevar> setting.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Emacs</application> or + <application>Xemacs</application></term> + + <listitem> + <para>Neither of these programs is required. However, both of them + feature PSGML-MODE, a useful extension when dealing with SGML + documents that can reduce the amount of typing you need to do, and + remove some of the more obvious errors.</para> + + <para>They can be found in <filename>editor/emacs20</filename> and + <filename>editor/xemacs20</filename>.</para> + + <note> + <para>Not installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>Document Type Definitions (DTDs)</title> + + <para>The project uses the following DTDs;</para> + + <variablelist> + <varlistentry> + <term>HTML</term> + + <listitem> + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, + and the latest, 4.0 (available in both <emphasis>strict</emphasis> + and <emphasis>loose</emphasis> variants).</para> + + <para>The HTML DTDs are available from the ports collection in the + <filename>textproc/html</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>LinuxDoc</term> + + <listitem> + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by + the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD + Documentation Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup + rather than content related markup (i.e., it describes what + something looks like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux + Documentation Project are migrating from the LinuxDoc DTD to the + DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term>DocBook</term> + + <listitem> + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> + to be a DTD for writing technical documentation. As such, it + contains XXX</para> + + <note> + <para>Installed as part of + <filename>textproc/docproj</filename>.</para> + </note> + </listitem> + </varlistentry> + </variablelist> + </sect1> + + <sect1> + <title>DSSSL Stylesheets</title> + + <para>The Documentation Project uses a slightly customised version of + Norm Walsh's modular DocBook stylesheets.</para> + + <para>These can be found in + <filename>textproc/dsssl-docbook-modular</filename>.</para> + + <note> + <para>Installed as part of <filename>textproc/docproj</filename>.</para> + </note> + </sect1> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> diff --git a/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml new file mode 100644 index 0000000000..07361a43be --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/writing-style/chapter.sgml @@ -0,0 +1,137 @@ +<!-- Copyright (c) 1998 Nik Clayton, All rights reserved. + + 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. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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. +--> + +<chapter id="writing-style"> + <title>Writing style</title> + + <para>In order to promote consistency between the myriad authors of the + FreeBSD documentation, some guidelines have been drawn up for authors to + follow.</para> + + <variablelist> + <varlistentry> + <term>Do not use contractions</term> + + <listitem> + <para>Do not use contractions. Always spell the phrase out in full. + “Don't use contractions” would be wrong.</para> + + <para>Avoiding contractions makes for a more formal tone, is more + precise, and slightly easier for translators.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Use the serial comma</term> + + <listitem> + <para>In a list of items within a paragraph, seperate each item from + the others with a comma. Seperate the last item from the others with + a comma and the word “and”.</para> + + <para>For example, look at the following quote;</para> + + <blockquote> + <para>This is a list of one, two and three items.</para> + </blockquote> + + <para>Is this a list of three items, “one”, + “two”, and “three”, or a list of two items, + “one” and “two and three”?</para> + + <para>It is better to be explicit and include a serial comma;</para> + + <blockquote> + <para>This is a list of one, two, and three items.</para> + </blockquote> + </listitem> + </varlistentry> + + <varlistentry> + <term>Avoid redundant phrases</term> + + <listitem> + <para>Try not to use redundant phrases. In particular, “the + command”, “the file”, and “man + command” are probably redundant.</para> + + <para>These two examples show this for commands. The second example + is preferred.</para> + + <informalexample> + <para>Use the command <command>cvsup</command> to update your + sources</para> + </informalexample> + + <informalexample> + <para>Use <command>cvsup</command> to update your sources</para> + </informalexample> + + <para>These two examples show this for filenames. The second example + is preferred.</para> + + <informalexample> + <para>… in the filename + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <informalexample> + <para>… in + <filename>/etc/rc.local</filename>…</para> + </informalexample> + + <para>These two examples show this for manual references. The second + example is preferred (the second example uses + <sgmltag>citerefentry</sgmltag>).</para> + + <informalexample> + <para>See <command>man csh</command> for more + information.</para> + </informalexample> + + <informalexample> + <para>See &man.csh.1;</para> + </informalexample> + </listitem> + </varlistentry> + </variablelist> +</chapter> + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + |