Whitespace changes, to pretty the formatting after the previous commit.

Translation teams can ignore this.
This commit is contained in:
Nik Clayton 1999-07-30 20:51:01 +00:00
parent ba74b08a1c
commit 6c26cf33ae
Notes: svn2git 2020-12-08 03:00:23 +00:00
svn path=/head/; revision=5279
8 changed files with 370 additions and 343 deletions
en/tutorials/docproj-primer
sgml-markup
sgml-primer
the-handbook
en_US.ISO8859-1/books/fdp-primer
sgml-markup
sgml-primer
en_US.ISO_8859-1/books/fdp-primer
sgml-markup
sgml-primer
the-handbook

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $
--> -->
<chapter id="sgml-markup"> <chapter id="sgml-markup">
@ -45,8 +45,8 @@
<para>This is <emphasis>not</emphasis> an exhaustive list of elements, since <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of 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 this section is to list those elements more likely to be useful to you.
you have a question about how best to markup a particular piece of 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 content, please post it to the FreeBSD Documentation Project mailing list
<email>freebsd-doc@freebsd.org</email>.</para> <email>freebsd-doc@freebsd.org</email>.</para>
@ -80,7 +80,8 @@
<para>The HTML DTDs are available from the ports collection in the <para>The HTML DTDs are available from the ports collection in the
<filename>textproc/html</filename> port. They are automatically <filename>textproc/html</filename> port. They are automatically
installed as part of the <filename>textproc/docproj</filename> port.</para> installed as part of the <filename>textproc/docproj</filename>
port.</para>
<sect2> <sect2>
<title>Formal Public Identifier (FPI)</title> <title>Formal Public Identifier (FPI)</title>
@ -167,12 +168,12 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</example> </example>
<para>Generally, an HTML page should have one first level heading <para>Generally, an HTML page should have one first level heading
(<sgmltag>h1</sgmltag>). This can contain many second level headings (<sgmltag>h1</sgmltag>). This can contain many second level
(<sgmltag>h2</sgmltag>), which can in turn contain many third level headings (<sgmltag>h2</sgmltag>), which can in turn contain many
headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> third level headings. Each
element should have the same element, but one further up the <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
hierarchy, preceeding it. Leaving gaps in the numbering is to be the same element, but one further up the hierarchy, preceeding it.
avoided.</para> Leaving gaps in the numbering is to be avoided.</para>
<example> <example>
<title>Bad ordering of <title>Bad ordering of
@ -238,10 +239,10 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
unordered, and definition.</para> unordered, and definition.</para>
<para>Typically, each entry in an ordered list will be numbered, while <para>Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be proceeded by a bullet each entry in an unordered list will be proceeded by a bullet point.
point. Definition lists are composed of two sections for each Definition lists are composed of two sections for each entry. The
entry. The first section is the term being defined, and the second first section is the term being defined, and the second section is
section is the definition of the term.</para> the definition of the term.</para>
<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
element, unordered lists by the <sgmltag>ul</sgmltag> element, and element, unordered lists by the <sgmltag>ul</sgmltag> element, and
@ -276,7 +277,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</ul> </ul>
<p>An ordered list, with list items consisting of multiple <p>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be paragraphs. Each item (note: not each paragraph) will be
numbered.</p> numbered.</p>
<ol> <ol>
@ -392,8 +393,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</tr> </tr>
</table>]]></programlisting></example> </table>]]></programlisting></example>
<para>A cell can span multiple rows and columns. To indicate this, add <para>A cell can span multiple rows and columns. To indicate this,
the <literal>rowspan</literal> and/or <literal>colspan</literal> add the <literal>rowspan</literal> and/or <literal>colspan</literal>
attributes, with values indicating the number of rows of columns attributes, with values indicating the number of rows of columns
that should be spanned.</para> that should be spanned.</para>
@ -484,10 +485,9 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<title>Emphasising information</title> <title>Emphasising information</title>
<para>You have two levels of emphasis available in HTML, <para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal <sgmltag>em</sgmltag> is for a normal level of emphasis and
level of emphasis and <sgmltag>strong</sgmltag> indicates stronger <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
emphasis.</para>
<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
<sgmltag>strong</sgmltag> is rendered in bold. This is not always <sgmltag>strong</sgmltag> is rendered in bold. This is not always
@ -558,8 +558,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
attribute set to <literal>+1</literal> or <literal>-1</literal> attribute set to <literal>+1</literal> or <literal>-1</literal>
respectively. This has the same effect as using respectively. This has the same effect as using
<sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However,
use of this approach is deprecated.</para> the use of this approach is deprecated.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -605,7 +605,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<literal>href</literal> attribute contains the URL of the target <literal>href</literal> attribute contains the URL of the target
document. The content of the element becomes the link, and is document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of normally indicated to the user in some way (underlining, change of
colour, different mouse cursor when over the link, and so on).</para> colour, different mouse cursor when over the link, and so
on).</para>
<example> <example>
<title>Using <literal>&lt;a href="..."&gt;</literal></title> <title>Using <literal>&lt;a href="..."&gt;</literal></title>
@ -748,11 +749,11 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a
mandatory requirement. There may be <sgmltag>part</sgmltag>s between mandatory requirement. There may be <sgmltag>part</sgmltag>s between
the book and the chapter to provide another layer of organisation. The the book and the chapter to provide another layer of organisation.
Handbook is arranged in this way.</para> The Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections. These are <para>A chapter may (or may not) contain one or more sections. These
indicated with the <sgmltag>sect1</sgmltag> element. If a section are indicated with the <sgmltag>sect1</sgmltag> element. If a section
contains another section then use the <sgmltag>sect2</sgmltag> contains another section then use the <sgmltag>sect2</sgmltag>
element, and so on, up to <sgmltag>sect5</sgmltag>.</para> element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
@ -828,8 +829,8 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</example> </example>
<para>A chapter can not be empty, it must contain elements in addition <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 to <sgmltag>title</sgmltag>. If you need to include an empty
then just use an empty paragraph.</para> chapter then just use an empty paragraph.</para>
<example> <example>
<title>Empty chapters</title> <title>Empty chapters</title>
@ -1217,9 +1218,9 @@ main(void)
detail) a table (which can be either formal or informal) consists of detail) a table (which can be either formal or informal) consists of
a <sgmltag>table</sgmltag> element. This contains at least one a <sgmltag>table</sgmltag> element. This contains at least one
<sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
the number of columns in this table group. Within the tablegroup you the number of columns in this table group. Within the tablegroup
can then have one <sgmltag>thead</sgmltag> element, which contains you can then have one <sgmltag>thead</sgmltag> element, which
elements for the table headings (column headings), and one contains elements for the table headings (column headings), and one
<sgmltag>tbody</sgmltag> which contains the body of the <sgmltag>tbody</sgmltag> which contains the body of the
table.</para> table.</para>
@ -1372,8 +1373,8 @@ main(void)
user and the root user have been provided as entities. Every user and the root user have been provided as entities. Every
time you want to indicate the user is at a shell prompt, use time you want to indicate the user is at a shell prompt, use
one of <literal>&amp;prompt.root;</literal> and one of <literal>&amp;prompt.root;</literal> and
<literal>&amp;prompt.user;</literal> as necessary. They do not <literal>&amp;prompt.user;</literal> as necessary. They do
need to be inside <sgmltag>prompt</sgmltag>.</para> not need to be inside <sgmltag>prompt</sgmltag>.</para>
<note> <note>
<para><literal>&amp;prompt.root;</literal> and <para><literal>&amp;prompt.root;</literal> and
@ -1480,10 +1481,10 @@ This is the file called 'foo2'</screen>
<title>Applications, commands, options, and cites</title> <title>Applications, commands, options, and cites</title>
<para>You will frequently want to refer to both applications and <para>You will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between them commands when writing for the Handbook. The distinction between
is simple; an application is the name for a suite (or possibly just them is simple; an application is the name for a suite (or possibly
1) of programs that fulfil a particular task. A command is the name just 1) of programs that fulfil a particular task. A command is the
of a program that the user can run.</para> name of a program that the user can run.</para>
<para>In addition, you will occasionally need to list one or more of <para>In addition, you will occasionally need to list one or more of
the options that a command might take.</para> the options that a command might take.</para>
@ -1505,8 +1506,8 @@ This is the file called 'foo2'</screen>
section.</para> section.</para>
<para>This can be cumbersome to write, and so a series of <link <para>This can be cumbersome to write, and so a series of <link
linkend="sgml-primer-general-entities">general entities</link> have been linkend="sgml-primer-general-entities">general entities</link>
created to make this easier. Each entity takes the form have been created to make this easier. Each entity takes the form
<literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
<para>The file that contains these entities is in <para>The file that contains these entities is in
@ -1894,13 +1895,13 @@ This is the file called 'foo2'</screen>
<title>Literal text</title> <title>Literal text</title>
<para>You will often need to include &ldquo;literal&rdquo; text in the <para>You will often need to include &ldquo;literal&rdquo; text in the
Handbook. This is text that is excerpted from another file, or which Handbook. This is text that is excerpted from another file, or
should be copied from the Handbook into another file which should be copied from the Handbook into another file
verbatim.</para> verbatim.</para>
<para>Some of the time, <sgmltag>programlisting</sgmltag> will be <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
sufficient to denote this text. <sgmltag>programlisting</sgmltag> is sufficient to denote this text. <sgmltag>programlisting</sgmltag>
not always appropriate, particularly when you want to include a is not always appropriate, particularly when you want to include a
portion of a file &ldquo;in-line&rdquo; with the rest of the portion of a file &ldquo;in-line&rdquo; with the rest of the
paragraph.</para> paragraph.</para>
@ -2103,8 +2104,8 @@ This is the file called 'foo2'</screen>
</note> </note>
<para>If you want to control the text of the link then use <para>If you want to control the text of the link then use
<sgmltag>link</sgmltag>. This element wraps content, and the content <sgmltag>link</sgmltag>. This element wraps content, and the
will be used for the link.</para> content will be used for the link.</para>
<example> <example>
<title>Using <sgmltag>link</sgmltag></title> <title>Using <sgmltag>link</sgmltag></title>

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.5 1999-07-28 20:04:30 nik Exp $ $Id: chapter.sgml,v 1.6 1999-07-30 20:50:59 nik Exp $
--> -->
<chapter id="sgml-primer"> <chapter id="sgml-primer">
@ -231,8 +231,8 @@
<title>Using an element (start tag only)</title> <title>Using an element (start tag only)</title>
<para>HTML has an element for indicating a horizontal rule, called <para>HTML has an element for indicating a horizontal rule, called
<literal>hr</literal>. This element does not wrap content, so only has <literal>hr</literal>. This element does not wrap content, so only
a start tag.</para> has a start tag.</para>
<programlisting> <programlisting>
<![ CDATA [<p>This is a paragraph.</p> <![ CDATA [<p>This is a paragraph.</p>
@ -260,8 +260,8 @@
other elements, and exactly what they can contain.</para> other elements, and exactly what they can contain.</para>
<important> <important>
<para>People often confuse the terms tags and elements, and use the terms <para>People often confuse the terms tags and elements, and use the
as if they were interchangeable. They are not.</para> terms as if they were interchangeable. They are not.</para>
<para>An element is a conceptual part of your document. An element has <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 a defined start and end. The tags mark where the element starts and
@ -271,7 +271,8 @@
to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text
consisting of the three characters <literal>&lt;</literal>, consisting of the three characters <literal>&lt;</literal>,
<literal>p</literal>, and <literal>&gt;</literal>. But the phrase <literal>p</literal>, and <literal>&gt;</literal>. But the phrase
&ldquo;the &lt;p&gt; element&rdquo; refers to the whole element.</para> &ldquo;the &lt;p&gt; element&rdquo; refers to the whole
element.</para>
<para>This distinction <emphasis>is</emphasis> very subtle. But keep it <para>This distinction <emphasis>is</emphasis> very subtle. But keep it
in mind.</para> in mind.</para>
@ -322,8 +323,9 @@
</example> </example>
<para>Sometimes you do not need to use quotes around attribute values at <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 all. However, the rules for doing this are subtle, and it is far
just to <emphasis>always</emphasis> quote your attribute values.</para> simpler just to <emphasis>always</emphasis> quote your attribute
values.</para>
<sect2> <sect2>
<title>For you to do&hellip;</title> <title>For you to do&hellip;</title>
@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</prog
<step> <step>
<para>See what happens when required elements are omitted. Try <para>See what happens when required elements are omitted. Try
removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> removing the <sgmltag>title</sgmltag> and
tags, and re-run the validation.</para> <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
<screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:5:4:E: character data is not allowed here
@ -490,8 +492,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</tgroup> </tgroup>
</informaltable> </informaltable>
<para>Simply omitting the <sgmltag>title</sgmltag> tags has generated <para>Simply omitting the <sgmltag>title</sgmltag> tags has
2 different errors.</para> generated 2 different errors.</para>
<para>The first error indicates that content (in this case, <para>The first error indicates that content (in this case,
characters, rather than the start tag for an element) has occured characters, rather than the start tag for an element) has occured
@ -573,8 +575,9 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para><literal>PUBLIC</literal> is not a part of the FPI, but <para><literal>PUBLIC</literal> is not a part of the FPI, but
indicates to the SGML processor how to find the DTD referenced in 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 the FPI. Other ways of telling the SGML parser how to find the
are shown <link linkend="sgml-primer-fpi-alternatives">later</link>.</para> DTD are shown <link
linkend="sgml-primer-fpi-alternatives">later</link>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>ISO 9070:1991 defines how registered names are generated; it <para>ISO 9070:1991 defines how registered names are generated; it
might be derived from the number of an ISO publication, an ISBN might be derived from the number of an ISO publication, an ISBN
code, or an organisation code assigned according to ISO 6523. In code, or an organisation code assigned according to ISO 6523.
addition, a registration authority could be created in order to In addition, a registration authority could be created in order
assign registered names. The ISO council delegated this to the to assign registered names. The ISO council delegated this to
American National Standards Institute (ANSI).</para> the American National Standards Institute (ANSI).</para>
<para>Because the FreeBSD Project hasn't been registered the <para>Because the FreeBSD Project hasn't been registered the
owner string is <literal>-//FreeBSD</literal>. And as you can owner string is <literal>-//FreeBSD</literal>. And as you can
@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<listitem> <listitem>
<para>Any description you want to supply for the contents of this <para>Any description you want to supply for the contents of this
file. This may include version numbers or any short text that is file. This may include version numbers or any short text that
meaningful to you and unique for the SGML system.</para> is meaningful to you and unique for the SGML system.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>In order to do this it can use a catalog file. A catalog file <para>In order to do this it can use a catalog file. A catalog file
(typically called <filename>catalog</filename>) contains lines that (typically called <filename>catalog</filename>) contains lines that
map FPIs to filenames. For example, if the catalog file contained the map FPIs to filenames. For example, if the catalog file contained
line;</para> the line;</para>
<programlisting> <programlisting>
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<filename>catalog</filename> file that contained that line.</para> <filename>catalog</filename> file that contained that line.</para>
<para>Look at the contents of <para>Look at the contents of
<filename>/usr/local/share/sgml/html/catalog</filename>. This is the <filename>/usr/local/share/sgml/html/catalog</filename>. This is
catalog file for the HTML DTDs that will have been installed as part the catalog file for the HTML DTDs that will have been installed as
of the <filename>textproc/docproj</filename> port.</para> part of the <filename>textproc/docproj</filename> port.</para>
</sect3> </sect3>
<sect3> <sect3>
<title><envar>SGML_CATALOG_FILES</envar></title> <title><envar>SGML_CATALOG_FILES</envar></title>
<para>In order to locate a <filename>catalog</filename> file, your <para>In order to locate a <filename>catalog</filename> file, your
SGML processor will need to know where to look. Many of them feature SGML processor will need to know where to look. Many of them
command line parameters for specifying the path to one or more feature command line parameters for specifying the path to one or
catalogs.</para> more catalogs.</para>
<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
point to the files. This environment variable should consist of a point to the files. This environment variable should consist of a
@ -758,10 +761,10 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
typically (but not always) means the DTD will be provided as a typically (but not always) means the DTD will be provided as a
filename.</para> filename.</para>
<para>Using FPIs is preferred for reasons of portability. You don't want <para>Using FPIs is preferred for reasons of portability. You don't
to have to ship a copy of the DTD around with your document, and if want to have to ship a copy of the DTD around with your document, and
you used the <literal>SYSTEM</literal> identifier then everyone would if you used the <literal>SYSTEM</literal> identifier then everyone
need to keep their DTDs in the same place.</para> would need to keep their DTDs in the same place.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
SGML that the parser should act upon.</para> SGML that the parser should act upon.</para>
<para>These sections are marked by <literal>&lt;! ... &gt;</literal> in <para>These sections are marked by <literal>&lt;! ... &gt;</literal> in
your document. Everything between these delimiters is SGML syntax as you your document. Everything between these delimiters is SGML syntax as
might find within a DTD.</para> you might find within a DTD.</para>
<para>As you may just have realised, the <link <para>As you may just have realised, the <link
linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> is an example linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
of SGML syntax that you need to include in your document&hellip;</para> is an example of SGML syntax that you need to include in your
document&hellip;</para>
</sect1> </sect1>
<sect1> <sect1>
<title>Comments</title> <title>Comments</title>
<para>Comments are an SGML construction, and are normally only valid <para>Comments are an SGML construction, and are normally only valid
inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> shows, it is inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape">
possible to use SGML syntax within your document.</para> shows, it is possible to use SGML syntax within your document.</para>
<para>The delimiters for SGML comments is the string <para>The delimiters for SGML comments is the string
&ldquo;<literal>--</literal>&rdquo;. The first occurence of this string &ldquo;<literal>--</literal>&rdquo;. The first occurence of this string
@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Entities</title> <title>Entities</title>
<para>Entities are a mechanism for assigning names to chunks of <para>Entities are a mechanism for assigning names to chunks of content.
content. As an SGML parser processes your document, any entities As an SGML parser processes your document, any entities it finds are
it finds are replaced by the content of the entity.</para> replaced by the content of the entity.</para>
<para>This is a good way to have re-usable, easily changeable chunks <para>This is a good way to have re-usable, easily changeable chunks of
of content in your SGML documents. It is also the only way to content in your SGML documents. It is also the only way to include one
include one marked up file inside another using SGML.</para> marked up file inside another using SGML.</para>
<para>There are two types of entities which can be used in two <para>There are two types of entities which can be used in two different
different situations; <emphasis>general entities</emphasis> and situations; <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para> <emphasis>parameter entities</emphasis>.</para>
<sect2 id="sgml-primer-general-entities"> <sect2 id="sgml-primer-general-entities">
<title>General Entities</title> <title>General Entities</title>
<para>You can not use general entities in an SGML context (although you <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 define them in one). They can only be used in your document.
this with <link linkend="sgml-primer-parameter-entities">parameter Contrast this with <link
linkend="sgml-primer-parameter-entities">parameter
entities</link>.</para> entities</link>.</para>
<para>Each general entity has a name. When you want to reference a <para>Each general entity has a name. When you want to reference a
@ -939,8 +944,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
could not otherwise include in an SGML document. For example, &lt; could not otherwise include in an SGML document. For example, &lt;
and &amp; can not normally appear in an SGML document. When the SGML and &amp; can not normally appear in an SGML document. When the SGML
parser sees the &lt; symbol it assumes that a tag (either a start tag parser sees the &lt; symbol it assumes that a tag (either a start tag
or an end tag) is about to appear, and when it sees the &amp; symbol it or an end tag) is about to appear, and when it sees the &amp; symbol
assumes the next text will be the name of an entity.</para> it assumes the next text will be the name of an entity.</para>
<para>Fortunately, you can use the two general entities &amp;lt; and <para>Fortunately, you can use the two general entities &amp;lt; and
&amp;amp; whenever you need to include one or other of these </para> &amp;amp; whenever you need to include one or other of these </para>
@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect2 id="sgml-primer-parameter-entities"> <sect2 id="sgml-primer-parameter-entities">
<title>Parameter entities</title> <title>Parameter entities</title>
<para>Like <link linkend="sgml-primer-general-entities">general entities</link>, <para>Like <link linkend="sgml-primer-general-entities">general
parameter entities are used to assign names to reusable chunks of entities</link>, parameter entities are used to assign names to
text. However, where as general entities can only be used within your reusable chunks of text. However, where as general entities can only
document, parameter entities can only be used within an <link be used within your document, parameter entities can only be used
linkend="sgml-primer-sgml-escape">SGML context</link>.</para> within an <link linkend="sgml-primer-sgml-escape">SGML
context</link>.</para>
<para>Parameter entities are defined in a similar way to general <para>Parameter entities are defined in a similar way to general
entities. However, instead of using entities. However, instead of using
@ -1088,8 +1094,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Using entities to include files</title> <title>Using entities to include files</title>
<para>Entities (both <link linkend="sgml-primer-general-entities">general</link> and <para>Entities (both <link
<link linkend="sgml-primer-parameter-entities">parameter</link>) are linkend="sgml-primer-general-entities">general</link> and <link
linkend="sgml-primer-parameter-entities">parameter</link>) are
particularly useful when used to include one file inside another.</para> particularly useful when used to include one file inside another.</para>
<sect2 id="sgml-primer-include-using-gen-entities"> <sect2 id="sgml-primer-include-using-gen-entities">
@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<step> <step>
<para>Edit <filename>example.sgml</filename> so that it looks like <para>Edit <filename>example.sgml</filename> so that it looks like
this;</para> this;</para>
<programlisting> <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.sgml"> %entities; <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<para>The two content models you will probably find most useful are <para>The two content models you will probably find most useful are
<literal>CDATA</literal> and <literal>RCDATA</literal>.</para> <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
<para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;. If <para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;.
the parser is in this content model then it is expecting to see If the parser is in this content model then it is expecting to see
characters, and characters only. In this model the &lt; and &amp; characters, and characters only. In this model the &lt; and &amp;
symbols lose their special status, and will be treated as ordinary symbols lose their special status, and will be treated as ordinary
characters.</para> characters.</para>
@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
comments.</para> comments.</para>
<para>It becomes more useful when you realise you can use <link <para>It becomes more useful when you realise you can use <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to control linkend="sgml-primer-parameter-entities">parameter entities</link>
this. Remember that parameter entities can only be used in SGML to control this. Remember that parameter entities can only be used
contexts, and the keyword of a marked section in SGML contexts, and the keyword of a marked section
<emphasis>is</emphasis> an SGML context.</para> <emphasis>is</emphasis> an SGML context.</para>
<para>For example, suppose that you produced a hard-copy version of <para>For example, suppose that you produced a hard-copy version of

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ $Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $
--> -->
<chapter id="the-handbook"> <chapter id="the-handbook">
@ -88,11 +88,11 @@
Handbook's structure.</para> Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link <para><filename>handbook.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to load in linkend="sgml-primer-parameter-entities">parameter entities</link>
the files with the <filename>.ent</filename> extension. These files to load in the files with the <filename>.ent</filename> extension.
(described later) then define <link linkend="sgml-primer-general-entities">general These files (described later) then define <link
entities</link> that are used throughout the rest of the linkend="sgml-primer-general-entities">general entities</link> that
Handbook.</para> are used throughout the rest of the Handbook.</para>
</sect2> </sect2>
<sect2> <sect2>
@ -256,8 +256,8 @@ V
<para>For example, if you have added two sentances to a paragraph, such <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 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 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 wrapping, and commit this second change. In the commit message for
second change, be sure to indicate that this is a whitespace-only the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.</para> change, and that the translation team can ignore it.</para>
</sect2> </sect2>
</sect1> </sect1>

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $
--> -->
<chapter id="sgml-markup"> <chapter id="sgml-markup">
@ -45,8 +45,8 @@
<para>This is <emphasis>not</emphasis> an exhaustive list of elements, since <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of 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 this section is to list those elements more likely to be useful to you.
you have a question about how best to markup a particular piece of 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 content, please post it to the FreeBSD Documentation Project mailing list
<email>freebsd-doc@freebsd.org</email>.</para> <email>freebsd-doc@freebsd.org</email>.</para>
@ -80,7 +80,8 @@
<para>The HTML DTDs are available from the ports collection in the <para>The HTML DTDs are available from the ports collection in the
<filename>textproc/html</filename> port. They are automatically <filename>textproc/html</filename> port. They are automatically
installed as part of the <filename>textproc/docproj</filename> port.</para> installed as part of the <filename>textproc/docproj</filename>
port.</para>
<sect2> <sect2>
<title>Formal Public Identifier (FPI)</title> <title>Formal Public Identifier (FPI)</title>
@ -167,12 +168,12 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</example> </example>
<para>Generally, an HTML page should have one first level heading <para>Generally, an HTML page should have one first level heading
(<sgmltag>h1</sgmltag>). This can contain many second level headings (<sgmltag>h1</sgmltag>). This can contain many second level
(<sgmltag>h2</sgmltag>), which can in turn contain many third level headings (<sgmltag>h2</sgmltag>), which can in turn contain many
headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> third level headings. Each
element should have the same element, but one further up the <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
hierarchy, preceeding it. Leaving gaps in the numbering is to be the same element, but one further up the hierarchy, preceeding it.
avoided.</para> Leaving gaps in the numbering is to be avoided.</para>
<example> <example>
<title>Bad ordering of <title>Bad ordering of
@ -238,10 +239,10 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
unordered, and definition.</para> unordered, and definition.</para>
<para>Typically, each entry in an ordered list will be numbered, while <para>Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be proceeded by a bullet each entry in an unordered list will be proceeded by a bullet point.
point. Definition lists are composed of two sections for each Definition lists are composed of two sections for each entry. The
entry. The first section is the term being defined, and the second first section is the term being defined, and the second section is
section is the definition of the term.</para> the definition of the term.</para>
<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
element, unordered lists by the <sgmltag>ul</sgmltag> element, and element, unordered lists by the <sgmltag>ul</sgmltag> element, and
@ -276,7 +277,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</ul> </ul>
<p>An ordered list, with list items consisting of multiple <p>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be paragraphs. Each item (note: not each paragraph) will be
numbered.</p> numbered.</p>
<ol> <ol>
@ -392,8 +393,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</tr> </tr>
</table>]]></programlisting></example> </table>]]></programlisting></example>
<para>A cell can span multiple rows and columns. To indicate this, add <para>A cell can span multiple rows and columns. To indicate this,
the <literal>rowspan</literal> and/or <literal>colspan</literal> add the <literal>rowspan</literal> and/or <literal>colspan</literal>
attributes, with values indicating the number of rows of columns attributes, with values indicating the number of rows of columns
that should be spanned.</para> that should be spanned.</para>
@ -484,10 +485,9 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<title>Emphasising information</title> <title>Emphasising information</title>
<para>You have two levels of emphasis available in HTML, <para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal <sgmltag>em</sgmltag> is for a normal level of emphasis and
level of emphasis and <sgmltag>strong</sgmltag> indicates stronger <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
emphasis.</para>
<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
<sgmltag>strong</sgmltag> is rendered in bold. This is not always <sgmltag>strong</sgmltag> is rendered in bold. This is not always
@ -558,8 +558,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
attribute set to <literal>+1</literal> or <literal>-1</literal> attribute set to <literal>+1</literal> or <literal>-1</literal>
respectively. This has the same effect as using respectively. This has the same effect as using
<sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However,
use of this approach is deprecated.</para> the use of this approach is deprecated.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -605,7 +605,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<literal>href</literal> attribute contains the URL of the target <literal>href</literal> attribute contains the URL of the target
document. The content of the element becomes the link, and is document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of normally indicated to the user in some way (underlining, change of
colour, different mouse cursor when over the link, and so on).</para> colour, different mouse cursor when over the link, and so
on).</para>
<example> <example>
<title>Using <literal>&lt;a href="..."&gt;</literal></title> <title>Using <literal>&lt;a href="..."&gt;</literal></title>
@ -748,11 +749,11 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a
mandatory requirement. There may be <sgmltag>part</sgmltag>s between mandatory requirement. There may be <sgmltag>part</sgmltag>s between
the book and the chapter to provide another layer of organisation. The the book and the chapter to provide another layer of organisation.
Handbook is arranged in this way.</para> The Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections. These are <para>A chapter may (or may not) contain one or more sections. These
indicated with the <sgmltag>sect1</sgmltag> element. If a section are indicated with the <sgmltag>sect1</sgmltag> element. If a section
contains another section then use the <sgmltag>sect2</sgmltag> contains another section then use the <sgmltag>sect2</sgmltag>
element, and so on, up to <sgmltag>sect5</sgmltag>.</para> element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
@ -828,8 +829,8 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</example> </example>
<para>A chapter can not be empty, it must contain elements in addition <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 to <sgmltag>title</sgmltag>. If you need to include an empty
then just use an empty paragraph.</para> chapter then just use an empty paragraph.</para>
<example> <example>
<title>Empty chapters</title> <title>Empty chapters</title>
@ -1217,9 +1218,9 @@ main(void)
detail) a table (which can be either formal or informal) consists of detail) a table (which can be either formal or informal) consists of
a <sgmltag>table</sgmltag> element. This contains at least one a <sgmltag>table</sgmltag> element. This contains at least one
<sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
the number of columns in this table group. Within the tablegroup you the number of columns in this table group. Within the tablegroup
can then have one <sgmltag>thead</sgmltag> element, which contains you can then have one <sgmltag>thead</sgmltag> element, which
elements for the table headings (column headings), and one contains elements for the table headings (column headings), and one
<sgmltag>tbody</sgmltag> which contains the body of the <sgmltag>tbody</sgmltag> which contains the body of the
table.</para> table.</para>
@ -1372,8 +1373,8 @@ main(void)
user and the root user have been provided as entities. Every user and the root user have been provided as entities. Every
time you want to indicate the user is at a shell prompt, use time you want to indicate the user is at a shell prompt, use
one of <literal>&amp;prompt.root;</literal> and one of <literal>&amp;prompt.root;</literal> and
<literal>&amp;prompt.user;</literal> as necessary. They do not <literal>&amp;prompt.user;</literal> as necessary. They do
need to be inside <sgmltag>prompt</sgmltag>.</para> not need to be inside <sgmltag>prompt</sgmltag>.</para>
<note> <note>
<para><literal>&amp;prompt.root;</literal> and <para><literal>&amp;prompt.root;</literal> and
@ -1480,10 +1481,10 @@ This is the file called 'foo2'</screen>
<title>Applications, commands, options, and cites</title> <title>Applications, commands, options, and cites</title>
<para>You will frequently want to refer to both applications and <para>You will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between them commands when writing for the Handbook. The distinction between
is simple; an application is the name for a suite (or possibly just them is simple; an application is the name for a suite (or possibly
1) of programs that fulfil a particular task. A command is the name just 1) of programs that fulfil a particular task. A command is the
of a program that the user can run.</para> name of a program that the user can run.</para>
<para>In addition, you will occasionally need to list one or more of <para>In addition, you will occasionally need to list one or more of
the options that a command might take.</para> the options that a command might take.</para>
@ -1505,8 +1506,8 @@ This is the file called 'foo2'</screen>
section.</para> section.</para>
<para>This can be cumbersome to write, and so a series of <link <para>This can be cumbersome to write, and so a series of <link
linkend="sgml-primer-general-entities">general entities</link> have been linkend="sgml-primer-general-entities">general entities</link>
created to make this easier. Each entity takes the form have been created to make this easier. Each entity takes the form
<literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
<para>The file that contains these entities is in <para>The file that contains these entities is in
@ -1894,13 +1895,13 @@ This is the file called 'foo2'</screen>
<title>Literal text</title> <title>Literal text</title>
<para>You will often need to include &ldquo;literal&rdquo; text in the <para>You will often need to include &ldquo;literal&rdquo; text in the
Handbook. This is text that is excerpted from another file, or which Handbook. This is text that is excerpted from another file, or
should be copied from the Handbook into another file which should be copied from the Handbook into another file
verbatim.</para> verbatim.</para>
<para>Some of the time, <sgmltag>programlisting</sgmltag> will be <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
sufficient to denote this text. <sgmltag>programlisting</sgmltag> is sufficient to denote this text. <sgmltag>programlisting</sgmltag>
not always appropriate, particularly when you want to include a is not always appropriate, particularly when you want to include a
portion of a file &ldquo;in-line&rdquo; with the rest of the portion of a file &ldquo;in-line&rdquo; with the rest of the
paragraph.</para> paragraph.</para>
@ -2103,8 +2104,8 @@ This is the file called 'foo2'</screen>
</note> </note>
<para>If you want to control the text of the link then use <para>If you want to control the text of the link then use
<sgmltag>link</sgmltag>. This element wraps content, and the content <sgmltag>link</sgmltag>. This element wraps content, and the
will be used for the link.</para> content will be used for the link.</para>
<example> <example>
<title>Using <sgmltag>link</sgmltag></title> <title>Using <sgmltag>link</sgmltag></title>

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.5 1999-07-28 20:04:30 nik Exp $ $Id: chapter.sgml,v 1.6 1999-07-30 20:50:59 nik Exp $
--> -->
<chapter id="sgml-primer"> <chapter id="sgml-primer">
@ -231,8 +231,8 @@
<title>Using an element (start tag only)</title> <title>Using an element (start tag only)</title>
<para>HTML has an element for indicating a horizontal rule, called <para>HTML has an element for indicating a horizontal rule, called
<literal>hr</literal>. This element does not wrap content, so only has <literal>hr</literal>. This element does not wrap content, so only
a start tag.</para> has a start tag.</para>
<programlisting> <programlisting>
<![ CDATA [<p>This is a paragraph.</p> <![ CDATA [<p>This is a paragraph.</p>
@ -260,8 +260,8 @@
other elements, and exactly what they can contain.</para> other elements, and exactly what they can contain.</para>
<important> <important>
<para>People often confuse the terms tags and elements, and use the terms <para>People often confuse the terms tags and elements, and use the
as if they were interchangeable. They are not.</para> terms as if they were interchangeable. They are not.</para>
<para>An element is a conceptual part of your document. An element has <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 a defined start and end. The tags mark where the element starts and
@ -271,7 +271,8 @@
to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text
consisting of the three characters <literal>&lt;</literal>, consisting of the three characters <literal>&lt;</literal>,
<literal>p</literal>, and <literal>&gt;</literal>. But the phrase <literal>p</literal>, and <literal>&gt;</literal>. But the phrase
&ldquo;the &lt;p&gt; element&rdquo; refers to the whole element.</para> &ldquo;the &lt;p&gt; element&rdquo; refers to the whole
element.</para>
<para>This distinction <emphasis>is</emphasis> very subtle. But keep it <para>This distinction <emphasis>is</emphasis> very subtle. But keep it
in mind.</para> in mind.</para>
@ -322,8 +323,9 @@
</example> </example>
<para>Sometimes you do not need to use quotes around attribute values at <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 all. However, the rules for doing this are subtle, and it is far
just to <emphasis>always</emphasis> quote your attribute values.</para> simpler just to <emphasis>always</emphasis> quote your attribute
values.</para>
<sect2> <sect2>
<title>For you to do&hellip;</title> <title>For you to do&hellip;</title>
@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</prog
<step> <step>
<para>See what happens when required elements are omitted. Try <para>See what happens when required elements are omitted. Try
removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> removing the <sgmltag>title</sgmltag> and
tags, and re-run the validation.</para> <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
<screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:5:4:E: character data is not allowed here
@ -490,8 +492,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</tgroup> </tgroup>
</informaltable> </informaltable>
<para>Simply omitting the <sgmltag>title</sgmltag> tags has generated <para>Simply omitting the <sgmltag>title</sgmltag> tags has
2 different errors.</para> generated 2 different errors.</para>
<para>The first error indicates that content (in this case, <para>The first error indicates that content (in this case,
characters, rather than the start tag for an element) has occured characters, rather than the start tag for an element) has occured
@ -573,8 +575,9 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para><literal>PUBLIC</literal> is not a part of the FPI, but <para><literal>PUBLIC</literal> is not a part of the FPI, but
indicates to the SGML processor how to find the DTD referenced in 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 the FPI. Other ways of telling the SGML parser how to find the
are shown <link linkend="sgml-primer-fpi-alternatives">later</link>.</para> DTD are shown <link
linkend="sgml-primer-fpi-alternatives">later</link>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>ISO 9070:1991 defines how registered names are generated; it <para>ISO 9070:1991 defines how registered names are generated; it
might be derived from the number of an ISO publication, an ISBN might be derived from the number of an ISO publication, an ISBN
code, or an organisation code assigned according to ISO 6523. In code, or an organisation code assigned according to ISO 6523.
addition, a registration authority could be created in order to In addition, a registration authority could be created in order
assign registered names. The ISO council delegated this to the to assign registered names. The ISO council delegated this to
American National Standards Institute (ANSI).</para> the American National Standards Institute (ANSI).</para>
<para>Because the FreeBSD Project hasn't been registered the <para>Because the FreeBSD Project hasn't been registered the
owner string is <literal>-//FreeBSD</literal>. And as you can owner string is <literal>-//FreeBSD</literal>. And as you can
@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<listitem> <listitem>
<para>Any description you want to supply for the contents of this <para>Any description you want to supply for the contents of this
file. This may include version numbers or any short text that is file. This may include version numbers or any short text that
meaningful to you and unique for the SGML system.</para> is meaningful to you and unique for the SGML system.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>In order to do this it can use a catalog file. A catalog file <para>In order to do this it can use a catalog file. A catalog file
(typically called <filename>catalog</filename>) contains lines that (typically called <filename>catalog</filename>) contains lines that
map FPIs to filenames. For example, if the catalog file contained the map FPIs to filenames. For example, if the catalog file contained
line;</para> the line;</para>
<programlisting> <programlisting>
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<filename>catalog</filename> file that contained that line.</para> <filename>catalog</filename> file that contained that line.</para>
<para>Look at the contents of <para>Look at the contents of
<filename>/usr/local/share/sgml/html/catalog</filename>. This is the <filename>/usr/local/share/sgml/html/catalog</filename>. This is
catalog file for the HTML DTDs that will have been installed as part the catalog file for the HTML DTDs that will have been installed as
of the <filename>textproc/docproj</filename> port.</para> part of the <filename>textproc/docproj</filename> port.</para>
</sect3> </sect3>
<sect3> <sect3>
<title><envar>SGML_CATALOG_FILES</envar></title> <title><envar>SGML_CATALOG_FILES</envar></title>
<para>In order to locate a <filename>catalog</filename> file, your <para>In order to locate a <filename>catalog</filename> file, your
SGML processor will need to know where to look. Many of them feature SGML processor will need to know where to look. Many of them
command line parameters for specifying the path to one or more feature command line parameters for specifying the path to one or
catalogs.</para> more catalogs.</para>
<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
point to the files. This environment variable should consist of a point to the files. This environment variable should consist of a
@ -758,10 +761,10 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
typically (but not always) means the DTD will be provided as a typically (but not always) means the DTD will be provided as a
filename.</para> filename.</para>
<para>Using FPIs is preferred for reasons of portability. You don't want <para>Using FPIs is preferred for reasons of portability. You don't
to have to ship a copy of the DTD around with your document, and if want to have to ship a copy of the DTD around with your document, and
you used the <literal>SYSTEM</literal> identifier then everyone would if you used the <literal>SYSTEM</literal> identifier then everyone
need to keep their DTDs in the same place.</para> would need to keep their DTDs in the same place.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
SGML that the parser should act upon.</para> SGML that the parser should act upon.</para>
<para>These sections are marked by <literal>&lt;! ... &gt;</literal> in <para>These sections are marked by <literal>&lt;! ... &gt;</literal> in
your document. Everything between these delimiters is SGML syntax as you your document. Everything between these delimiters is SGML syntax as
might find within a DTD.</para> you might find within a DTD.</para>
<para>As you may just have realised, the <link <para>As you may just have realised, the <link
linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> is an example linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
of SGML syntax that you need to include in your document&hellip;</para> is an example of SGML syntax that you need to include in your
document&hellip;</para>
</sect1> </sect1>
<sect1> <sect1>
<title>Comments</title> <title>Comments</title>
<para>Comments are an SGML construction, and are normally only valid <para>Comments are an SGML construction, and are normally only valid
inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> shows, it is inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape">
possible to use SGML syntax within your document.</para> shows, it is possible to use SGML syntax within your document.</para>
<para>The delimiters for SGML comments is the string <para>The delimiters for SGML comments is the string
&ldquo;<literal>--</literal>&rdquo;. The first occurence of this string &ldquo;<literal>--</literal>&rdquo;. The first occurence of this string
@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Entities</title> <title>Entities</title>
<para>Entities are a mechanism for assigning names to chunks of <para>Entities are a mechanism for assigning names to chunks of content.
content. As an SGML parser processes your document, any entities As an SGML parser processes your document, any entities it finds are
it finds are replaced by the content of the entity.</para> replaced by the content of the entity.</para>
<para>This is a good way to have re-usable, easily changeable chunks <para>This is a good way to have re-usable, easily changeable chunks of
of content in your SGML documents. It is also the only way to content in your SGML documents. It is also the only way to include one
include one marked up file inside another using SGML.</para> marked up file inside another using SGML.</para>
<para>There are two types of entities which can be used in two <para>There are two types of entities which can be used in two different
different situations; <emphasis>general entities</emphasis> and situations; <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para> <emphasis>parameter entities</emphasis>.</para>
<sect2 id="sgml-primer-general-entities"> <sect2 id="sgml-primer-general-entities">
<title>General Entities</title> <title>General Entities</title>
<para>You can not use general entities in an SGML context (although you <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 define them in one). They can only be used in your document.
this with <link linkend="sgml-primer-parameter-entities">parameter Contrast this with <link
linkend="sgml-primer-parameter-entities">parameter
entities</link>.</para> entities</link>.</para>
<para>Each general entity has a name. When you want to reference a <para>Each general entity has a name. When you want to reference a
@ -939,8 +944,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
could not otherwise include in an SGML document. For example, &lt; could not otherwise include in an SGML document. For example, &lt;
and &amp; can not normally appear in an SGML document. When the SGML and &amp; can not normally appear in an SGML document. When the SGML
parser sees the &lt; symbol it assumes that a tag (either a start tag parser sees the &lt; symbol it assumes that a tag (either a start tag
or an end tag) is about to appear, and when it sees the &amp; symbol it or an end tag) is about to appear, and when it sees the &amp; symbol
assumes the next text will be the name of an entity.</para> it assumes the next text will be the name of an entity.</para>
<para>Fortunately, you can use the two general entities &amp;lt; and <para>Fortunately, you can use the two general entities &amp;lt; and
&amp;amp; whenever you need to include one or other of these </para> &amp;amp; whenever you need to include one or other of these </para>
@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect2 id="sgml-primer-parameter-entities"> <sect2 id="sgml-primer-parameter-entities">
<title>Parameter entities</title> <title>Parameter entities</title>
<para>Like <link linkend="sgml-primer-general-entities">general entities</link>, <para>Like <link linkend="sgml-primer-general-entities">general
parameter entities are used to assign names to reusable chunks of entities</link>, parameter entities are used to assign names to
text. However, where as general entities can only be used within your reusable chunks of text. However, where as general entities can only
document, parameter entities can only be used within an <link be used within your document, parameter entities can only be used
linkend="sgml-primer-sgml-escape">SGML context</link>.</para> within an <link linkend="sgml-primer-sgml-escape">SGML
context</link>.</para>
<para>Parameter entities are defined in a similar way to general <para>Parameter entities are defined in a similar way to general
entities. However, instead of using entities. However, instead of using
@ -1088,8 +1094,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Using entities to include files</title> <title>Using entities to include files</title>
<para>Entities (both <link linkend="sgml-primer-general-entities">general</link> and <para>Entities (both <link
<link linkend="sgml-primer-parameter-entities">parameter</link>) are linkend="sgml-primer-general-entities">general</link> and <link
linkend="sgml-primer-parameter-entities">parameter</link>) are
particularly useful when used to include one file inside another.</para> particularly useful when used to include one file inside another.</para>
<sect2 id="sgml-primer-include-using-gen-entities"> <sect2 id="sgml-primer-include-using-gen-entities">
@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<step> <step>
<para>Edit <filename>example.sgml</filename> so that it looks like <para>Edit <filename>example.sgml</filename> so that it looks like
this;</para> this;</para>
<programlisting> <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.sgml"> %entities; <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<para>The two content models you will probably find most useful are <para>The two content models you will probably find most useful are
<literal>CDATA</literal> and <literal>RCDATA</literal>.</para> <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
<para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;. If <para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;.
the parser is in this content model then it is expecting to see If the parser is in this content model then it is expecting to see
characters, and characters only. In this model the &lt; and &amp; characters, and characters only. In this model the &lt; and &amp;
symbols lose their special status, and will be treated as ordinary symbols lose their special status, and will be treated as ordinary
characters.</para> characters.</para>
@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
comments.</para> comments.</para>
<para>It becomes more useful when you realise you can use <link <para>It becomes more useful when you realise you can use <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to control linkend="sgml-primer-parameter-entities">parameter entities</link>
this. Remember that parameter entities can only be used in SGML to control this. Remember that parameter entities can only be used
contexts, and the keyword of a marked section in SGML contexts, and the keyword of a marked section
<emphasis>is</emphasis> an SGML context.</para> <emphasis>is</emphasis> an SGML context.</para>
<para>For example, suppose that you produced a hard-copy version of <para>For example, suppose that you produced a hard-copy version of

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $
--> -->
<chapter id="sgml-markup"> <chapter id="sgml-markup">
@ -45,8 +45,8 @@
<para>This is <emphasis>not</emphasis> an exhaustive list of elements, since <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
that would just reiterate the documentation for each language. The aim of 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 this section is to list those elements more likely to be useful to you.
you have a question about how best to markup a particular piece of 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 content, please post it to the FreeBSD Documentation Project mailing list
<email>freebsd-doc@freebsd.org</email>.</para> <email>freebsd-doc@freebsd.org</email>.</para>
@ -80,7 +80,8 @@
<para>The HTML DTDs are available from the ports collection in the <para>The HTML DTDs are available from the ports collection in the
<filename>textproc/html</filename> port. They are automatically <filename>textproc/html</filename> port. They are automatically
installed as part of the <filename>textproc/docproj</filename> port.</para> installed as part of the <filename>textproc/docproj</filename>
port.</para>
<sect2> <sect2>
<title>Formal Public Identifier (FPI)</title> <title>Formal Public Identifier (FPI)</title>
@ -167,12 +168,12 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</example> </example>
<para>Generally, an HTML page should have one first level heading <para>Generally, an HTML page should have one first level heading
(<sgmltag>h1</sgmltag>). This can contain many second level headings (<sgmltag>h1</sgmltag>). This can contain many second level
(<sgmltag>h2</sgmltag>), which can in turn contain many third level headings (<sgmltag>h2</sgmltag>), which can in turn contain many
headings. Each <sgmltag>h<replaceable>n</replaceable></sgmltag> third level headings. Each
element should have the same element, but one further up the <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
hierarchy, preceeding it. Leaving gaps in the numbering is to be the same element, but one further up the hierarchy, preceeding it.
avoided.</para> Leaving gaps in the numbering is to be avoided.</para>
<example> <example>
<title>Bad ordering of <title>Bad ordering of
@ -238,10 +239,10 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
unordered, and definition.</para> unordered, and definition.</para>
<para>Typically, each entry in an ordered list will be numbered, while <para>Typically, each entry in an ordered list will be numbered, while
each entry in an unordered list will be proceeded by a bullet each entry in an unordered list will be proceeded by a bullet point.
point. Definition lists are composed of two sections for each Definition lists are composed of two sections for each entry. The
entry. The first section is the term being defined, and the second first section is the term being defined, and the second section is
section is the definition of the term.</para> the definition of the term.</para>
<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
element, unordered lists by the <sgmltag>ul</sgmltag> element, and element, unordered lists by the <sgmltag>ul</sgmltag> element, and
@ -276,7 +277,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</ul> </ul>
<p>An ordered list, with list items consisting of multiple <p>An ordered list, with list items consisting of multiple
paragraphs. Each item (note: not each paragraph) will be paragraphs. Each item (note: not each paragraph) will be
numbered.</p> numbered.</p>
<ol> <ol>
@ -392,8 +393,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</tr> </tr>
</table>]]></programlisting></example> </table>]]></programlisting></example>
<para>A cell can span multiple rows and columns. To indicate this, add <para>A cell can span multiple rows and columns. To indicate this,
the <literal>rowspan</literal> and/or <literal>colspan</literal> add the <literal>rowspan</literal> and/or <literal>colspan</literal>
attributes, with values indicating the number of rows of columns attributes, with values indicating the number of rows of columns
that should be spanned.</para> that should be spanned.</para>
@ -484,10 +485,9 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<title>Emphasising information</title> <title>Emphasising information</title>
<para>You have two levels of emphasis available in HTML, <para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal <sgmltag>em</sgmltag> is for a normal level of emphasis and
level of emphasis and <sgmltag>strong</sgmltag> indicates stronger <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
emphasis.</para>
<para>Typically, <sgmltag>em</sgmltag> is rendered in italic and <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
<sgmltag>strong</sgmltag> is rendered in bold. This is not always <sgmltag>strong</sgmltag> is rendered in bold. This is not always
@ -558,8 +558,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal>
attribute set to <literal>+1</literal> or <literal>-1</literal> attribute set to <literal>+1</literal> or <literal>-1</literal>
respectively. This has the same effect as using respectively. This has the same effect as using
<sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However, the <sgmltag>big</sgmltag> or <sgmltag>small</sgmltag>. However,
use of this approach is deprecated.</para> the use of this approach is deprecated.</para>
</listitem> </listitem>
<listitem> <listitem>
@ -605,7 +605,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
<literal>href</literal> attribute contains the URL of the target <literal>href</literal> attribute contains the URL of the target
document. The content of the element becomes the link, and is document. The content of the element becomes the link, and is
normally indicated to the user in some way (underlining, change of normally indicated to the user in some way (underlining, change of
colour, different mouse cursor when over the link, and so on).</para> colour, different mouse cursor when over the link, and so
on).</para>
<example> <example>
<title>Using <literal>&lt;a href="..."&gt;</literal></title> <title>Using <literal>&lt;a href="..."&gt;</literal></title>
@ -748,11 +749,11 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
<para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a <para>A book is organised into <sgmltag>chapter</sgmltag>s. This is a
mandatory requirement. There may be <sgmltag>part</sgmltag>s between mandatory requirement. There may be <sgmltag>part</sgmltag>s between
the book and the chapter to provide another layer of organisation. The the book and the chapter to provide another layer of organisation.
Handbook is arranged in this way.</para> The Handbook is arranged in this way.</para>
<para>A chapter may (or may not) contain one or more sections. These are <para>A chapter may (or may not) contain one or more sections. These
indicated with the <sgmltag>sect1</sgmltag> element. If a section are indicated with the <sgmltag>sect1</sgmltag> element. If a section
contains another section then use the <sgmltag>sect2</sgmltag> contains another section then use the <sgmltag>sect2</sgmltag>
element, and so on, up to <sgmltag>sect5</sgmltag>.</para> element, and so on, up to <sgmltag>sect5</sgmltag>.</para>
@ -828,8 +829,8 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN"</programlisting>
</example> </example>
<para>A chapter can not be empty, it must contain elements in addition <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 to <sgmltag>title</sgmltag>. If you need to include an empty
then just use an empty paragraph.</para> chapter then just use an empty paragraph.</para>
<example> <example>
<title>Empty chapters</title> <title>Empty chapters</title>
@ -1217,9 +1218,9 @@ main(void)
detail) a table (which can be either formal or informal) consists of detail) a table (which can be either formal or informal) consists of
a <sgmltag>table</sgmltag> element. This contains at least one a <sgmltag>table</sgmltag> element. This contains at least one
<sgmltag>tgroup</sgmltag> element, which specifies (as an attribute) <sgmltag>tgroup</sgmltag> element, which specifies (as an attribute)
the number of columns in this table group. Within the tablegroup you the number of columns in this table group. Within the tablegroup
can then have one <sgmltag>thead</sgmltag> element, which contains you can then have one <sgmltag>thead</sgmltag> element, which
elements for the table headings (column headings), and one contains elements for the table headings (column headings), and one
<sgmltag>tbody</sgmltag> which contains the body of the <sgmltag>tbody</sgmltag> which contains the body of the
table.</para> table.</para>
@ -1372,8 +1373,8 @@ main(void)
user and the root user have been provided as entities. Every user and the root user have been provided as entities. Every
time you want to indicate the user is at a shell prompt, use time you want to indicate the user is at a shell prompt, use
one of <literal>&amp;prompt.root;</literal> and one of <literal>&amp;prompt.root;</literal> and
<literal>&amp;prompt.user;</literal> as necessary. They do not <literal>&amp;prompt.user;</literal> as necessary. They do
need to be inside <sgmltag>prompt</sgmltag>.</para> not need to be inside <sgmltag>prompt</sgmltag>.</para>
<note> <note>
<para><literal>&amp;prompt.root;</literal> and <para><literal>&amp;prompt.root;</literal> and
@ -1480,10 +1481,10 @@ This is the file called 'foo2'</screen>
<title>Applications, commands, options, and cites</title> <title>Applications, commands, options, and cites</title>
<para>You will frequently want to refer to both applications and <para>You will frequently want to refer to both applications and
commands when writing for the Handbook. The distinction between them commands when writing for the Handbook. The distinction between
is simple; an application is the name for a suite (or possibly just them is simple; an application is the name for a suite (or possibly
1) of programs that fulfil a particular task. A command is the name just 1) of programs that fulfil a particular task. A command is the
of a program that the user can run.</para> name of a program that the user can run.</para>
<para>In addition, you will occasionally need to list one or more of <para>In addition, you will occasionally need to list one or more of
the options that a command might take.</para> the options that a command might take.</para>
@ -1505,8 +1506,8 @@ This is the file called 'foo2'</screen>
section.</para> section.</para>
<para>This can be cumbersome to write, and so a series of <link <para>This can be cumbersome to write, and so a series of <link
linkend="sgml-primer-general-entities">general entities</link> have been linkend="sgml-primer-general-entities">general entities</link>
created to make this easier. Each entity takes the form have been created to make this easier. Each entity takes the form
<literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> <literal>&amp;man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
<para>The file that contains these entities is in <para>The file that contains these entities is in
@ -1894,13 +1895,13 @@ This is the file called 'foo2'</screen>
<title>Literal text</title> <title>Literal text</title>
<para>You will often need to include &ldquo;literal&rdquo; text in the <para>You will often need to include &ldquo;literal&rdquo; text in the
Handbook. This is text that is excerpted from another file, or which Handbook. This is text that is excerpted from another file, or
should be copied from the Handbook into another file which should be copied from the Handbook into another file
verbatim.</para> verbatim.</para>
<para>Some of the time, <sgmltag>programlisting</sgmltag> will be <para>Some of the time, <sgmltag>programlisting</sgmltag> will be
sufficient to denote this text. <sgmltag>programlisting</sgmltag> is sufficient to denote this text. <sgmltag>programlisting</sgmltag>
not always appropriate, particularly when you want to include a is not always appropriate, particularly when you want to include a
portion of a file &ldquo;in-line&rdquo; with the rest of the portion of a file &ldquo;in-line&rdquo; with the rest of the
paragraph.</para> paragraph.</para>
@ -2103,8 +2104,8 @@ This is the file called 'foo2'</screen>
</note> </note>
<para>If you want to control the text of the link then use <para>If you want to control the text of the link then use
<sgmltag>link</sgmltag>. This element wraps content, and the content <sgmltag>link</sgmltag>. This element wraps content, and the
will be used for the link.</para> content will be used for the link.</para>
<example> <example>
<title>Using <sgmltag>link</sgmltag></title> <title>Using <sgmltag>link</sgmltag></title>

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.5 1999-07-28 20:04:30 nik Exp $ $Id: chapter.sgml,v 1.6 1999-07-30 20:50:59 nik Exp $
--> -->
<chapter id="sgml-primer"> <chapter id="sgml-primer">
@ -231,8 +231,8 @@
<title>Using an element (start tag only)</title> <title>Using an element (start tag only)</title>
<para>HTML has an element for indicating a horizontal rule, called <para>HTML has an element for indicating a horizontal rule, called
<literal>hr</literal>. This element does not wrap content, so only has <literal>hr</literal>. This element does not wrap content, so only
a start tag.</para> has a start tag.</para>
<programlisting> <programlisting>
<![ CDATA [<p>This is a paragraph.</p> <![ CDATA [<p>This is a paragraph.</p>
@ -260,8 +260,8 @@
other elements, and exactly what they can contain.</para> other elements, and exactly what they can contain.</para>
<important> <important>
<para>People often confuse the terms tags and elements, and use the terms <para>People often confuse the terms tags and elements, and use the
as if they were interchangeable. They are not.</para> terms as if they were interchangeable. They are not.</para>
<para>An element is a conceptual part of your document. An element has <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 a defined start and end. The tags mark where the element starts and
@ -271,7 +271,8 @@
to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text to &ldquo;the &lt;p&gt; tag&rdquo; they mean the literal text
consisting of the three characters <literal>&lt;</literal>, consisting of the three characters <literal>&lt;</literal>,
<literal>p</literal>, and <literal>&gt;</literal>. But the phrase <literal>p</literal>, and <literal>&gt;</literal>. But the phrase
&ldquo;the &lt;p&gt; element&rdquo; refers to the whole element.</para> &ldquo;the &lt;p&gt; element&rdquo; refers to the whole
element.</para>
<para>This distinction <emphasis>is</emphasis> very subtle. But keep it <para>This distinction <emphasis>is</emphasis> very subtle. But keep it
in mind.</para> in mind.</para>
@ -322,8 +323,9 @@
</example> </example>
<para>Sometimes you do not need to use quotes around attribute values at <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 all. However, the rules for doing this are subtle, and it is far
just to <emphasis>always</emphasis> quote your attribute values.</para> simpler just to <emphasis>always</emphasis> quote your attribute
values.</para>
<sect2> <sect2>
<title>For you to do&hellip;</title> <title>For you to do&hellip;</title>
@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES</prog
<step> <step>
<para>See what happens when required elements are omitted. Try <para>See what happens when required elements are omitted. Try
removing the <sgmltag>title</sgmltag> and <sgmltag>/title</sgmltag> removing the <sgmltag>title</sgmltag> and
tags, and re-run the validation.</para> <sgmltag>/title</sgmltag> tags, and re-run the validation.</para>
<screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput> <screen>&prompt.user; <userinput>nsgmls -s example.sgml</userinput>
nsgmls:example.sgml:5:4:E: character data is not allowed here nsgmls:example.sgml:5:4:E: character data is not allowed here
@ -490,8 +492,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
</tgroup> </tgroup>
</informaltable> </informaltable>
<para>Simply omitting the <sgmltag>title</sgmltag> tags has generated <para>Simply omitting the <sgmltag>title</sgmltag> tags has
2 different errors.</para> generated 2 different errors.</para>
<para>The first error indicates that content (in this case, <para>The first error indicates that content (in this case,
characters, rather than the start tag for an element) has occured characters, rather than the start tag for an element) has occured
@ -573,8 +575,9 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para><literal>PUBLIC</literal> is not a part of the FPI, but <para><literal>PUBLIC</literal> is not a part of the FPI, but
indicates to the SGML processor how to find the DTD referenced in 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 the FPI. Other ways of telling the SGML parser how to find the
are shown <link linkend="sgml-primer-fpi-alternatives">later</link>.</para> DTD are shown <link
linkend="sgml-primer-fpi-alternatives">later</link>.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>ISO 9070:1991 defines how registered names are generated; it <para>ISO 9070:1991 defines how registered names are generated; it
might be derived from the number of an ISO publication, an ISBN might be derived from the number of an ISO publication, an ISBN
code, or an organisation code assigned according to ISO 6523. In code, or an organisation code assigned according to ISO 6523.
addition, a registration authority could be created in order to In addition, a registration authority could be created in order
assign registered names. The ISO council delegated this to the to assign registered names. The ISO council delegated this to
American National Standards Institute (ANSI).</para> the American National Standards Institute (ANSI).</para>
<para>Because the FreeBSD Project hasn't been registered the <para>Because the FreeBSD Project hasn't been registered the
owner string is <literal>-//FreeBSD</literal>. And as you can owner string is <literal>-//FreeBSD</literal>. And as you can
@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<listitem> <listitem>
<para>Any description you want to supply for the contents of this <para>Any description you want to supply for the contents of this
file. This may include version numbers or any short text that is file. This may include version numbers or any short text that
meaningful to you and unique for the SGML system.</para> is meaningful to you and unique for the SGML system.</para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished</screen>
<para>In order to do this it can use a catalog file. A catalog file <para>In order to do this it can use a catalog file. A catalog file
(typically called <filename>catalog</filename>) contains lines that (typically called <filename>catalog</filename>) contains lines that
map FPIs to filenames. For example, if the catalog file contained the map FPIs to filenames. For example, if the catalog file contained
line;</para> the line;</para>
<programlisting> <programlisting>
PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting> PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<filename>catalog</filename> file that contained that line.</para> <filename>catalog</filename> file that contained that line.</para>
<para>Look at the contents of <para>Look at the contents of
<filename>/usr/local/share/sgml/html/catalog</filename>. This is the <filename>/usr/local/share/sgml/html/catalog</filename>. This is
catalog file for the HTML DTDs that will have been installed as part the catalog file for the HTML DTDs that will have been installed as
of the <filename>textproc/docproj</filename> port.</para> part of the <filename>textproc/docproj</filename> port.</para>
</sect3> </sect3>
<sect3> <sect3>
<title><envar>SGML_CATALOG_FILES</envar></title> <title><envar>SGML_CATALOG_FILES</envar></title>
<para>In order to locate a <filename>catalog</filename> file, your <para>In order to locate a <filename>catalog</filename> file, your
SGML processor will need to know where to look. Many of them feature SGML processor will need to know where to look. Many of them
command line parameters for specifying the path to one or more feature command line parameters for specifying the path to one or
catalogs.</para> more catalogs.</para>
<para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to <para>In addition, you can set <envar>SGML_CATALOG_FILES</envar> to
point to the files. This environment variable should consist of a point to the files. This environment variable should consist of a
@ -758,10 +761,10 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
typically (but not always) means the DTD will be provided as a typically (but not always) means the DTD will be provided as a
filename.</para> filename.</para>
<para>Using FPIs is preferred for reasons of portability. You don't want <para>Using FPIs is preferred for reasons of portability. You don't
to have to ship a copy of the DTD around with your document, and if want to have to ship a copy of the DTD around with your document, and
you used the <literal>SYSTEM</literal> identifier then everyone would if you used the <literal>SYSTEM</literal> identifier then everyone
need to keep their DTDs in the same place.</para> would need to keep their DTDs in the same place.</para>
</sect2> </sect2>
</sect1> </sect1>
@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
SGML that the parser should act upon.</para> SGML that the parser should act upon.</para>
<para>These sections are marked by <literal>&lt;! ... &gt;</literal> in <para>These sections are marked by <literal>&lt;! ... &gt;</literal> in
your document. Everything between these delimiters is SGML syntax as you your document. Everything between these delimiters is SGML syntax as
might find within a DTD.</para> you might find within a DTD.</para>
<para>As you may just have realised, the <link <para>As you may just have realised, the <link
linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link> is an example linkend="sgml-primer-doctype-declaration">DOCTYPE declaration</link>
of SGML syntax that you need to include in your document&hellip;</para> is an example of SGML syntax that you need to include in your
document&hellip;</para>
</sect1> </sect1>
<sect1> <sect1>
<title>Comments</title> <title>Comments</title>
<para>Comments are an SGML construction, and are normally only valid <para>Comments are an SGML construction, and are normally only valid
inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape"> shows, it is inside a DTD. However, as <xref linkend="sgml-primer-sgml-escape">
possible to use SGML syntax within your document.</para> shows, it is possible to use SGML syntax within your document.</para>
<para>The delimiters for SGML comments is the string <para>The delimiters for SGML comments is the string
&ldquo;<literal>--</literal>&rdquo;. The first occurence of this string &ldquo;<literal>--</literal>&rdquo;. The first occurence of this string
@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Entities</title> <title>Entities</title>
<para>Entities are a mechanism for assigning names to chunks of <para>Entities are a mechanism for assigning names to chunks of content.
content. As an SGML parser processes your document, any entities As an SGML parser processes your document, any entities it finds are
it finds are replaced by the content of the entity.</para> replaced by the content of the entity.</para>
<para>This is a good way to have re-usable, easily changeable chunks <para>This is a good way to have re-usable, easily changeable chunks of
of content in your SGML documents. It is also the only way to content in your SGML documents. It is also the only way to include one
include one marked up file inside another using SGML.</para> marked up file inside another using SGML.</para>
<para>There are two types of entities which can be used in two <para>There are two types of entities which can be used in two different
different situations; <emphasis>general entities</emphasis> and situations; <emphasis>general entities</emphasis> and
<emphasis>parameter entities</emphasis>.</para> <emphasis>parameter entities</emphasis>.</para>
<sect2 id="sgml-primer-general-entities"> <sect2 id="sgml-primer-general-entities">
<title>General Entities</title> <title>General Entities</title>
<para>You can not use general entities in an SGML context (although you <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 define them in one). They can only be used in your document.
this with <link linkend="sgml-primer-parameter-entities">parameter Contrast this with <link
linkend="sgml-primer-parameter-entities">parameter
entities</link>.</para> entities</link>.</para>
<para>Each general entity has a name. When you want to reference a <para>Each general entity has a name. When you want to reference a
@ -939,8 +944,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
could not otherwise include in an SGML document. For example, &lt; could not otherwise include in an SGML document. For example, &lt;
and &amp; can not normally appear in an SGML document. When the SGML and &amp; can not normally appear in an SGML document. When the SGML
parser sees the &lt; symbol it assumes that a tag (either a start tag parser sees the &lt; symbol it assumes that a tag (either a start tag
or an end tag) is about to appear, and when it sees the &amp; symbol it or an end tag) is about to appear, and when it sees the &amp; symbol
assumes the next text will be the name of an entity.</para> it assumes the next text will be the name of an entity.</para>
<para>Fortunately, you can use the two general entities &amp;lt; and <para>Fortunately, you can use the two general entities &amp;lt; and
&amp;amp; whenever you need to include one or other of these </para> &amp;amp; whenever you need to include one or other of these </para>
@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect2 id="sgml-primer-parameter-entities"> <sect2 id="sgml-primer-parameter-entities">
<title>Parameter entities</title> <title>Parameter entities</title>
<para>Like <link linkend="sgml-primer-general-entities">general entities</link>, <para>Like <link linkend="sgml-primer-general-entities">general
parameter entities are used to assign names to reusable chunks of entities</link>, parameter entities are used to assign names to
text. However, where as general entities can only be used within your reusable chunks of text. However, where as general entities can only
document, parameter entities can only be used within an <link be used within your document, parameter entities can only be used
linkend="sgml-primer-sgml-escape">SGML context</link>.</para> within an <link linkend="sgml-primer-sgml-escape">SGML
context</link>.</para>
<para>Parameter entities are defined in a similar way to general <para>Parameter entities are defined in a similar way to general
entities. However, instead of using entities. However, instead of using
@ -1088,8 +1094,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<sect1> <sect1>
<title>Using entities to include files</title> <title>Using entities to include files</title>
<para>Entities (both <link linkend="sgml-primer-general-entities">general</link> and <para>Entities (both <link
<link linkend="sgml-primer-parameter-entities">parameter</link>) are linkend="sgml-primer-general-entities">general</link> and <link
linkend="sgml-primer-parameter-entities">parameter</link>) are
particularly useful when used to include one file inside another.</para> particularly useful when used to include one file inside another.</para>
<sect2 id="sgml-primer-include-using-gen-entities"> <sect2 id="sgml-primer-include-using-gen-entities">
@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<step> <step>
<para>Edit <filename>example.sgml</filename> so that it looks like <para>Edit <filename>example.sgml</filename> so that it looks like
this;</para> this;</para>
<programlisting> <programlisting>
<![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [ <![ CDATA [<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
<!ENTITY % entities SYSTEM "entities.sgml"> %entities; <!ENTITY % entities SYSTEM "entities.sgml"> %entities;
@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
<para>The two content models you will probably find most useful are <para>The two content models you will probably find most useful are
<literal>CDATA</literal> and <literal>RCDATA</literal>.</para> <literal>CDATA</literal> and <literal>RCDATA</literal>.</para>
<para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;. If <para><literal>CDATA</literal> is for &ldquo;Character Data&rdquo;.
the parser is in this content model then it is expecting to see If the parser is in this content model then it is expecting to see
characters, and characters only. In this model the &lt; and &amp; characters, and characters only. In this model the &lt; and &amp;
symbols lose their special status, and will be treated as ordinary symbols lose their special status, and will be treated as ordinary
characters.</para> characters.</para>
@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"</programlisting>
comments.</para> comments.</para>
<para>It becomes more useful when you realise you can use <link <para>It becomes more useful when you realise you can use <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to control linkend="sgml-primer-parameter-entities">parameter entities</link>
this. Remember that parameter entities can only be used in SGML to control this. Remember that parameter entities can only be used
contexts, and the keyword of a marked section in SGML contexts, and the keyword of a marked section
<emphasis>is</emphasis> an SGML context.</para> <emphasis>is</emphasis> an SGML context.</para>
<para>For example, suppose that you produced a hard-copy version of <para>For example, suppose that you produced a hard-copy version of

View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE. POSSIBILITY OF SUCH DAMAGE.
$Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ $Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $
--> -->
<chapter id="the-handbook"> <chapter id="the-handbook">
@ -88,11 +88,11 @@
Handbook's structure.</para> Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link <para><filename>handbook.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to load in linkend="sgml-primer-parameter-entities">parameter entities</link>
the files with the <filename>.ent</filename> extension. These files to load in the files with the <filename>.ent</filename> extension.
(described later) then define <link linkend="sgml-primer-general-entities">general These files (described later) then define <link
entities</link> that are used throughout the rest of the linkend="sgml-primer-general-entities">general entities</link> that
Handbook.</para> are used throughout the rest of the Handbook.</para>
</sect2> </sect2>
<sect2> <sect2>
@ -256,8 +256,8 @@ V
<para>For example, if you have added two sentances to a paragraph, such <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 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 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 wrapping, and commit this second change. In the commit message for
second change, be sure to indicate that this is a whitespace-only the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.</para> change, and that the translation team can ignore it.</para>
</sect2> </sect2>
</sect1> </sect1>