diff options
| author | Nik Clayton <nik@FreeBSD.org> | 1999-04-20 20:59:59 +0000 |
|---|---|---|
| committer | Nik Clayton <nik@FreeBSD.org> | 1999-04-20 20:59:59 +0000 |
| commit | c4ab126805b0ecf8d200daba8990ddaac649b18f (patch) | |
| tree | 17449c394290549d27f07d8049ae25ae811bb03f | |
| parent | 8bdee18bd8c6ee8c3846276f21b651b1ed393420 (diff) | |
| download | doc-c4ab126805b0ecf8d200daba8990ddaac649b18f.tar.gz doc-c4ab126805b0ecf8d200daba8990ddaac649b18f.zip | |
My primer for people new to the Doc. Proj. Incomplete, but should be
enough for most people, and gets it into the repository, making it
easier for others to add to as necessary.
This has not (yet) been turned on in the upper level Makefile or
listed on the web site yet, I want to get some more feedback
from readers first. It should be "made visible" later this week.
Notes
Notes:
svn path=/head/; revision=4718
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: +--> + |