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