os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

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

Browse source 
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
chapter.sgml
sgml-primer
chapter.sgml
the-handbook
chapter.sgml
en_US.ISO8859-1/books/fdp-primer
sgml-markup
chapter.sgml
sgml-primer
chapter.sgml
en_US.ISO_8859-1/books/fdp-primer
sgml-markup
chapter.sgml
sgml-primer
chapter.sgml
the-handbook
chapter.sgml

95
en/tutorials/docproj-primer/sgml-markup/chapter.sgml
View file

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

132
en/tutorials/docproj-primer/sgml-primer/chapter.sgml
View file

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

16
en/tutorials/docproj-primer/the-handbook/chapter.sgml
View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
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">
@ -88,11 +88,11 @@
Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to load in
the files with the <filename>.ent</filename> extension. These files
(described later) then define <link linkend="sgml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
linkend="sgml-primer-parameter-entities">parameter entities</link>
to load in the files with the <filename>.ent</filename> extension.
These files (described later) then define <link
linkend="sgml-primer-general-entities">general entities</link> that
are used throughout the rest of the Handbook.</para>
</sect2>
<sect2>
@ -256,8 +256,8 @@ V
<para>For example, if you have added two sentances to a paragraph, such
that the line lengths on the paragraph now go over 80 columns, first
commit your change with the too-long line lengths. Then fix the line
wrapping, and commit this second change. In the commit message for the
second change, be sure to indicate that this is a whitespace-only
wrapping, and commit this second change. In the commit message for
the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.</para>
</sect2>
</sect1>

95
en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml
View file

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

132
en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml
View file

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

95
en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
View file

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

132
en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml
View file

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

16
en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml
View file

@ -27,7 +27,7 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
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">
@ -88,11 +88,11 @@
Handbook's structure.</para>
<para><filename>handbook.sgml</filename> uses <link
linkend="sgml-primer-parameter-entities">parameter entities</link> to load in
the files with the <filename>.ent</filename> extension. These files
(described later) then define <link linkend="sgml-primer-general-entities">general
entities</link> that are used throughout the rest of the
Handbook.</para>
linkend="sgml-primer-parameter-entities">parameter entities</link>
to load in the files with the <filename>.ent</filename> extension.
These files (described later) then define <link
linkend="sgml-primer-general-entities">general entities</link> that
are used throughout the rest of the Handbook.</para>
</sect2>
<sect2>
@ -256,8 +256,8 @@ V
<para>For example, if you have added two sentances to a paragraph, such
that the line lengths on the paragraph now go over 80 columns, first
commit your change with the too-long line lengths. Then fix the line
wrapping, and commit this second change. In the commit message for the
second change, be sure to indicate that this is a whitespace-only
wrapping, and commit this second change. In the commit message for
the second change, be sure to indicate that this is a whitespace-only
change, and that the translation team can ignore it.</para>
</sect2>
</sect1>