Whitespace changes, to pretty the formatting after the previous commit.
Translation teams can ignore this.
This commit is contained in:
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
en_US.ISO8859-1/books/fdp-primer
en_US.ISO_8859-1/books/fdp-primer
|
@ -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><a href="..."></literal></title>
|
<title>Using <literal><a href="..."></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>&prompt.root;</literal> and
|
one of <literal>&prompt.root;</literal> and
|
||||||
<literal>&prompt.user;</literal> as necessary. They do not
|
<literal>&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>&prompt.root;</literal> and
|
<para><literal>&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>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
|
<literal>&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 “literal” text in the
|
<para>You will often need to include “literal” 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 “in-line” with the rest of the
|
portion of a file “in-line” 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>
|
||||||
|
|
|
@ -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 “the <p> tag” they mean the literal text
|
to “the <p> tag” they mean the literal text
|
||||||
consisting of the three characters <literal><</literal>,
|
consisting of the three characters <literal><</literal>,
|
||||||
<literal>p</literal>, and <literal>></literal>. But the phrase
|
<literal>p</literal>, and <literal>></literal>. But the phrase
|
||||||
“the <p> element” refers to the whole element.</para>
|
“the <p> element” 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…</title>
|
<title>For you to do…</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><! ... ></literal> in
|
<para>These sections are marked by <literal><! ... ></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…</para>
|
is an example of SGML syntax that you need to include in your
|
||||||
|
document…</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
|
||||||
“<literal>--</literal>”. The first occurence of this string
|
“<literal>--</literal>”. 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, <
|
could not otherwise include in an SGML document. For example, <
|
||||||
and & can not normally appear in an SGML document. When the SGML
|
and & can not normally appear in an SGML document. When the SGML
|
||||||
parser sees the < symbol it assumes that a tag (either a start tag
|
parser sees the < symbol it assumes that a tag (either a start tag
|
||||||
or an end tag) is about to appear, and when it sees the & symbol it
|
or an end tag) is about to appear, and when it sees the & 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 &lt; and
|
<para>Fortunately, you can use the two general entities &lt; and
|
||||||
&amp; whenever you need to include one or other of these </para>
|
&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 “Character Data”. If
|
<para><literal>CDATA</literal> is for “Character Data”.
|
||||||
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 < and &
|
characters, and characters only. In this model the < and &
|
||||||
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
|
||||||
|
|
|
@ -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>
|
||||||
|
|
|
@ -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><a href="..."></literal></title>
|
<title>Using <literal><a href="..."></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>&prompt.root;</literal> and
|
one of <literal>&prompt.root;</literal> and
|
||||||
<literal>&prompt.user;</literal> as necessary. They do not
|
<literal>&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>&prompt.root;</literal> and
|
<para><literal>&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>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
|
<literal>&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 “literal” text in the
|
<para>You will often need to include “literal” 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 “in-line” with the rest of the
|
portion of a file “in-line” 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>
|
||||||
|
|
|
@ -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 “the <p> tag” they mean the literal text
|
to “the <p> tag” they mean the literal text
|
||||||
consisting of the three characters <literal><</literal>,
|
consisting of the three characters <literal><</literal>,
|
||||||
<literal>p</literal>, and <literal>></literal>. But the phrase
|
<literal>p</literal>, and <literal>></literal>. But the phrase
|
||||||
“the <p> element” refers to the whole element.</para>
|
“the <p> element” 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…</title>
|
<title>For you to do…</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><! ... ></literal> in
|
<para>These sections are marked by <literal><! ... ></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…</para>
|
is an example of SGML syntax that you need to include in your
|
||||||
|
document…</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
|
||||||
“<literal>--</literal>”. The first occurence of this string
|
“<literal>--</literal>”. 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, <
|
could not otherwise include in an SGML document. For example, <
|
||||||
and & can not normally appear in an SGML document. When the SGML
|
and & can not normally appear in an SGML document. When the SGML
|
||||||
parser sees the < symbol it assumes that a tag (either a start tag
|
parser sees the < symbol it assumes that a tag (either a start tag
|
||||||
or an end tag) is about to appear, and when it sees the & symbol it
|
or an end tag) is about to appear, and when it sees the & 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 &lt; and
|
<para>Fortunately, you can use the two general entities &lt; and
|
||||||
&amp; whenever you need to include one or other of these </para>
|
&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 “Character Data”. If
|
<para><literal>CDATA</literal> is for “Character Data”.
|
||||||
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 < and &
|
characters, and characters only. In this model the < and &
|
||||||
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
|
||||||
|
|
|
@ -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><a href="..."></literal></title>
|
<title>Using <literal><a href="..."></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>&prompt.root;</literal> and
|
one of <literal>&prompt.root;</literal> and
|
||||||
<literal>&prompt.user;</literal> as necessary. They do not
|
<literal>&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>&prompt.root;</literal> and
|
<para><literal>&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>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para>
|
<literal>&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 “literal” text in the
|
<para>You will often need to include “literal” 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 “in-line” with the rest of the
|
portion of a file “in-line” 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>
|
||||||
|
|
|
@ -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 “the <p> tag” they mean the literal text
|
to “the <p> tag” they mean the literal text
|
||||||
consisting of the three characters <literal><</literal>,
|
consisting of the three characters <literal><</literal>,
|
||||||
<literal>p</literal>, and <literal>></literal>. But the phrase
|
<literal>p</literal>, and <literal>></literal>. But the phrase
|
||||||
“the <p> element” refers to the whole element.</para>
|
“the <p> element” 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…</title>
|
<title>For you to do…</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><! ... ></literal> in
|
<para>These sections are marked by <literal><! ... ></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…</para>
|
is an example of SGML syntax that you need to include in your
|
||||||
|
document…</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
|
||||||
“<literal>--</literal>”. The first occurence of this string
|
“<literal>--</literal>”. 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, <
|
could not otherwise include in an SGML document. For example, <
|
||||||
and & can not normally appear in an SGML document. When the SGML
|
and & can not normally appear in an SGML document. When the SGML
|
||||||
parser sees the < symbol it assumes that a tag (either a start tag
|
parser sees the < symbol it assumes that a tag (either a start tag
|
||||||
or an end tag) is about to appear, and when it sees the & symbol it
|
or an end tag) is about to appear, and when it sees the & 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 &lt; and
|
<para>Fortunately, you can use the two general entities &lt; and
|
||||||
&amp; whenever you need to include one or other of these </para>
|
&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 “Character Data”. If
|
<para><literal>CDATA</literal> is for “Character Data”.
|
||||||
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 < and &
|
characters, and characters only. In this model the < and &
|
||||||
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
|
||||||
|
|
|
@ -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>
|
||||||
|
|
Loading…
Reference in a new issue