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

@@ -260,8 +260,8 @@ other elements, and exactly what they can contain. - People often confuse the terms tags and elements, and use the terms - as if they were interchangeable. They are not. + People often confuse the terms tags and elements, and use the + terms as if they were interchangeable. They are not. 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 <, p, and >. But the phrase - “the <p> element” refers to the whole element. + “the <p> element” refers to the whole + element. This distinction is very subtle. But keep it in mind. @@ -322,8 +323,9 @@ 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 always quote your attribute values. + all. However, the rules for doing this are subtle, and it is far + simpler just to always quote your attribute + values. For you to do… @@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES See what happens when required elements are omitted. Try - removing the title and /title - tags, and re-run the validation. + removing the title and + /title tags, and re-run the validation. &prompt.user; nsgmls -s example.sgml 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 - Simply omitting the title tags has generated - 2 different errors. + Simply omitting the title tags has + generated 2 different errors. 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 PUBLIC 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 later. + the FPI. Other ways of telling the SGML parser how to find the + DTD are shown later. @@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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). + 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). Because the FreeBSD Project hasn't been registered the owner string is -//FreeBSD. And as you can @@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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. + file. This may include version numbers or any short text that + is meaningful to you and unique for the SGML system. @@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that - map FPIs to filenames. For example, if the catalog file contained the - line; + map FPIs to filenames. For example, if the catalog file contained + the line; PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" @@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" catalog file that contained that line. Look at the contents of - /usr/local/share/sgml/html/catalog. This is the - catalog file for the HTML DTDs that will have been installed as part - of the textproc/docproj port. + /usr/local/share/sgml/html/catalog. This is + the catalog file for the HTML DTDs that will have been installed as + part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog 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. + 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. In addition, you can set SGML_CATALOG_FILES 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" typically (but not always) means the DTD will be provided as a filename. - 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 SYSTEM identifier then everyone would - need to keep their DTDs in the same place. + 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 SYSTEM identifier then everyone + would need to keep their DTDs in the same place. @@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" SGML that the parser should act upon. These sections are marked by <! ... > in - your document. Everything between these delimiters is SGML syntax as you - might find within a DTD. + your document. Everything between these delimiters is SGML syntax as + you might find within a DTD. As you may just have realised, the DOCTYPE declaration is an example - of SGML syntax that you need to include in your document… + linkend="sgml-primer-doctype-declaration">DOCTYPE declaration + is an example of SGML syntax that you need to include in your + document… Comments Comments are an SGML construction, and are normally only valid - inside a DTD. However, as shows, it is - possible to use SGML syntax within your document. + inside a DTD. However, as + shows, it is possible to use SGML syntax within your document. The delimiters for SGML comments is the string “--”. The first occurence of this string @@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Entities - 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. + 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. - 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. + 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. - There are two types of entities which can be used in two - different situations; general entities and + There are two types of entities which can be used in two different + situations; general entities and parameter entities. General Entities 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 parameter + define them in one). They can only be used in your document. + Contrast this with parameter entities. 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" 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. + 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. Fortunately, you can use the two general entities &lt; and &amp; whenever you need to include one or other of these @@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Parameter entities - Like general entities, - 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 SGML context. + Like general + entities, 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 SGML + context. 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" Using entities to include files - Entities (both general and - parameter) are + Entities (both general and parameter) are particularly useful when used to include one file inside another. @@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Edit example.sgml so that it looks like this; + %entities; @@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" The two content models you will probably find most useful are CDATA and RCDATA. - CDATA is for “Character Data”. If - the parser is in this content model then it is expecting to see + CDATA 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. @@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" comments. It becomes more useful when you realise you can use parameter entities 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 + to control this. Remember that parameter entities can only be used + in SGML contexts, and the keyword of a marked section is an SGML context. For example, suppose that you produced a hard-copy version of diff --git a/en/tutorials/docproj-primer/the-handbook/chapter.sgml b/en/tutorials/docproj-primer/the-handbook/chapter.sgml index c923b10780..004ccb34ef 100644 --- a/en/tutorials/docproj-primer/the-handbook/chapter.sgml +++ b/en/tutorials/docproj-primer/the-handbook/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.4 1999-07-28 20:06:03 nik Exp $ + $Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $ --> @@ -88,11 +88,11 @@ Handbook's structure. handbook.sgml uses parameter entities to load in - the files with the .ent extension. These files - (described later) then define general - entities that are used throughout the rest of the - Handbook. + linkend="sgml-primer-parameter-entities">parameter entities + to load in the files with the .ent extension. + These files (described later) then define general entities that + are used throughout the rest of the Handbook. @@ -256,8 +256,8 @@ V For example, if you have added two sentances to a paragraph, such that the line lengths on the paragraph now go over 80 columns, first commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for the - second change, be sure to indicate that this is a whitespace-only + wrapping, and commit this second change. In the commit message for + the second change, be sure to indicate that this is a whitespace-only change, and that the translation team can ignore it. diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 34c4cc2399..8a8c216754 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/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.4 1999-07-28 20:06:03 nik Exp $ + $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $ --> @@ -45,8 +45,8 @@ This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. If - you have a question about how best to markup a particular piece of + this section is to list those elements more likely to be useful to you. + If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list freebsd-doc@freebsd.org. @@ -80,7 +80,8 @@ The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically - installed as part of the textproc/docproj port. + installed as part of the textproc/docproj + port. Formal Public Identifier (FPI) @@ -167,12 +168,12 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Generally, an HTML page should have one first level heading - (h1). This can contain many second level headings - (h2), which can in turn contain many third level - headings. Each hn - element should have the same element, but one further up the - hierarchy, preceeding it. Leaving gaps in the numbering is to be - avoided. + (h1). This can contain many second level + headings (h2), which can in turn contain many + third level headings. Each + hn element should have + the same element, but one further up the hierarchy, preceeding it. + Leaving gaps in the numbering is to be avoided. Bad ordering of @@ -238,10 +239,10 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> unordered, and definition.</para> <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be proceeded by a bullet - point. Definition lists are composed of two sections for each - entry. The first section is the term being defined, and the second - section is the definition of the term.</para> + each entry in an unordered list will be proceeded by a bullet point. + Definition lists are composed of two sections for each entry. The + first section is the term being defined, and the second section is + the definition of the term.</para> <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> element, unordered lists by the <sgmltag>ul</sgmltag> element, and @@ -276,7 +277,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </ul> <p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be + paragraphs. Each item (note: not each paragraph) will be numbered.</p> <ol> @@ -392,8 +393,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </tr> </table>]]></programlisting></example> - <para>A cell can span multiple rows and columns. To indicate this, add - the <literal>rowspan</literal> and/or <literal>colspan</literal> + <para>A cell can span multiple rows and columns. To indicate this, + add the <literal>rowspan</literal> and/or <literal>colspan</literal> attributes, with values indicating the number of rows of columns that should be spanned.</para> @@ -484,10 +485,9 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <title>Emphasising information You have two levels of emphasis available in HTML, - em and - strong. em is for a normal - level of emphasis and strong indicates stronger - emphasis. + em and strong. + em is for a normal level of emphasis and + strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always @@ -558,8 +558,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using - big or small. However, the - use of this approach is deprecated. + big or small. However, + the use of this approach is deprecated. @@ -605,7 +605,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of - colour, different mouse cursor when over the link, and so on). + colour, different mouse cursor when over the link, and so + on). Using <literal><a href="..."></literal> @@ -748,11 +749,11 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" A book is organised into chapters. This is a mandatory requirement. There may be parts between - the book and the chapter to provide another layer of organisation. The - Handbook is arranged in this way. + the book and the chapter to provide another layer of organisation. + The Handbook is arranged in this way. - A chapter may (or may not) contain one or more sections. These are - indicated with the sect1 element. If a section + A chapter may (or may not) contain one or more sections. These + are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. @@ -828,8 +829,8 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" A chapter can not be empty, it must contain elements in addition - to title. If you need to include an empty chapter - then just use an empty paragraph. + to title. If you need to include an empty + chapter then just use an empty paragraph. Empty chapters @@ -1217,9 +1218,9 @@ main(void) detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup you - can then have one thead element, which contains - elements for the table headings (column headings), and one + the number of columns in this table group. Within the tablegroup + you can then have one thead element, which + contains elements for the table headings (column headings), and one tbody which contains the body of the table. @@ -1372,8 +1373,8 @@ main(void) user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and - &prompt.user; as necessary. They do not - need to be inside prompt. + &prompt.user; as necessary. They do + not need to be inside prompt. &prompt.root; and @@ -1480,10 +1481,10 @@ This is the file called 'foo2' Applications, commands, options, and cites You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between them - is simple; an application is the name for a suite (or possibly just - 1) of programs that fulfil a particular task. A command is the name - of a program that the user can run. + commands when writing for the Handbook. The distinction between + them is simple; an application is the name for a suite (or possibly + just 1) of programs that fulfil a particular task. A command is the + name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. @@ -1505,8 +1506,8 @@ This is the file called 'foo2' section. This can be cumbersome to write, and so a series of general entities have been - created to make this easier. Each entity takes the form + linkend="sgml-primer-general-entities">general entities + have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in @@ -1894,13 +1895,13 @@ This is the file called 'foo2' Literal text You will often need to include “literal” text in the - Handbook. This is text that is excerpted from another file, or which - should be copied from the Handbook into another file + Handbook. This is text that is excerpted from another file, or + which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be - sufficient to denote this text. programlisting is - not always appropriate, particularly when you want to include a + sufficient to denote this text. programlisting + is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph. @@ -2103,8 +2104,8 @@ This is the file called 'foo2' If you want to control the text of the link then use - link. This element wraps content, and the content - will be used for the link. + link. This element wraps content, and the + content will be used for the link. Using <sgmltag>link</sgmltag> diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml index ab19ac8e98..213fe4aee3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-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 $ --> @@ -231,8 +231,8 @@ Using an element (start tag only) HTML has an element for indicating a horizontal rule, called - hr. This element does not wrap content, so only has - a start tag. + hr. This element does not wrap content, so only + has a start tag. This is a paragraph.

@@ -260,8 +260,8 @@ other elements, and exactly what they can contain. - People often confuse the terms tags and elements, and use the terms - as if they were interchangeable. They are not. + People often confuse the terms tags and elements, and use the + terms as if they were interchangeable. They are not. 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 <, p, and >. But the phrase - “the <p> element” refers to the whole element. + “the <p> element” refers to the whole + element. This distinction is very subtle. But keep it in mind. @@ -322,8 +323,9 @@ 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 always quote your attribute values. + all. However, the rules for doing this are subtle, and it is far + simpler just to always quote your attribute + values. For you to do… @@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES See what happens when required elements are omitted. Try - removing the title and /title - tags, and re-run the validation. + removing the title and + /title tags, and re-run the validation. &prompt.user; nsgmls -s example.sgml 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 - Simply omitting the title tags has generated - 2 different errors. + Simply omitting the title tags has + generated 2 different errors. 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 PUBLIC 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 later. + the FPI. Other ways of telling the SGML parser how to find the + DTD are shown later. @@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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). + 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). Because the FreeBSD Project hasn't been registered the owner string is -//FreeBSD. And as you can @@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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. + file. This may include version numbers or any short text that + is meaningful to you and unique for the SGML system. @@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that - map FPIs to filenames. For example, if the catalog file contained the - line; + map FPIs to filenames. For example, if the catalog file contained + the line; PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" @@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" catalog file that contained that line. Look at the contents of - /usr/local/share/sgml/html/catalog. This is the - catalog file for the HTML DTDs that will have been installed as part - of the textproc/docproj port. + /usr/local/share/sgml/html/catalog. This is + the catalog file for the HTML DTDs that will have been installed as + part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog 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. + 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. In addition, you can set SGML_CATALOG_FILES 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" typically (but not always) means the DTD will be provided as a filename. - 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 SYSTEM identifier then everyone would - need to keep their DTDs in the same place. + 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 SYSTEM identifier then everyone + would need to keep their DTDs in the same place. @@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" SGML that the parser should act upon. These sections are marked by <! ... > in - your document. Everything between these delimiters is SGML syntax as you - might find within a DTD. + your document. Everything between these delimiters is SGML syntax as + you might find within a DTD. As you may just have realised, the DOCTYPE declaration is an example - of SGML syntax that you need to include in your document… + linkend="sgml-primer-doctype-declaration">DOCTYPE declaration + is an example of SGML syntax that you need to include in your + document… Comments Comments are an SGML construction, and are normally only valid - inside a DTD. However, as shows, it is - possible to use SGML syntax within your document. + inside a DTD. However, as + shows, it is possible to use SGML syntax within your document. The delimiters for SGML comments is the string “--”. The first occurence of this string @@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Entities - 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. + 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. - 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. + 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. - There are two types of entities which can be used in two - different situations; general entities and + There are two types of entities which can be used in two different + situations; general entities and parameter entities. General Entities 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 parameter + define them in one). They can only be used in your document. + Contrast this with parameter entities. 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" 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. + 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. Fortunately, you can use the two general entities &lt; and &amp; whenever you need to include one or other of these @@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Parameter entities - Like general entities, - 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 SGML context. + Like general + entities, 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 SGML + context. 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" Using entities to include files - Entities (both general and - parameter) are + Entities (both general and parameter) are particularly useful when used to include one file inside another. @@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Edit example.sgml so that it looks like this; + %entities; @@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" The two content models you will probably find most useful are CDATA and RCDATA. - CDATA is for “Character Data”. If - the parser is in this content model then it is expecting to see + CDATA 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. @@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" comments. It becomes more useful when you realise you can use parameter entities 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 + to control this. Remember that parameter entities can only be used + in SGML contexts, and the keyword of a marked section is an SGML context. For example, suppose that you produced a hard-copy version of diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 34c4cc2399..8a8c216754 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ + $Id: chapter.sgml,v 1.5 1999-07-30 20:51:01 nik Exp $ --> @@ -45,8 +45,8 @@ This is not an exhaustive list of elements, since that would just reiterate the documentation for each language. The aim of - this section is to list those elements more likely to be useful to you. If - you have a question about how best to markup a particular piece of + this section is to list those elements more likely to be useful to you. + If you have a question about how best to markup a particular piece of content, please post it to the FreeBSD Documentation Project mailing list freebsd-doc@freebsd.org. @@ -80,7 +80,8 @@ The HTML DTDs are available from the ports collection in the textproc/html port. They are automatically - installed as part of the textproc/docproj port. + installed as part of the textproc/docproj + port. Formal Public Identifier (FPI) @@ -167,12 +168,12 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Generally, an HTML page should have one first level heading - (h1). This can contain many second level headings - (h2), which can in turn contain many third level - headings. Each hn - element should have the same element, but one further up the - hierarchy, preceeding it. Leaving gaps in the numbering is to be - avoided. + (h1). This can contain many second level + headings (h2), which can in turn contain many + third level headings. Each + hn element should have + the same element, but one further up the hierarchy, preceeding it. + Leaving gaps in the numbering is to be avoided. Bad ordering of @@ -238,10 +239,10 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> unordered, and definition.</para> <para>Typically, each entry in an ordered list will be numbered, while - each entry in an unordered list will be proceeded by a bullet - point. Definition lists are composed of two sections for each - entry. The first section is the term being defined, and the second - section is the definition of the term.</para> + each entry in an unordered list will be proceeded by a bullet point. + Definition lists are composed of two sections for each entry. The + first section is the term being defined, and the second section is + the definition of the term.</para> <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> element, unordered lists by the <sgmltag>ul</sgmltag> element, and @@ -276,7 +277,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </ul> <p>An ordered list, with list items consisting of multiple - paragraphs. Each item (note: not each paragraph) will be + paragraphs. Each item (note: not each paragraph) will be numbered.</p> <ol> @@ -392,8 +393,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> </tr> </table>]]></programlisting></example> - <para>A cell can span multiple rows and columns. To indicate this, add - the <literal>rowspan</literal> and/or <literal>colspan</literal> + <para>A cell can span multiple rows and columns. To indicate this, + add the <literal>rowspan</literal> and/or <literal>colspan</literal> attributes, with values indicating the number of rows of columns that should be spanned.</para> @@ -484,10 +485,9 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> <title>Emphasising information You have two levels of emphasis available in HTML, - em and - strong. em is for a normal - level of emphasis and strong indicates stronger - emphasis. + em and strong. + em is for a normal level of emphasis and + strong indicates stronger emphasis. Typically, em is rendered in italic and strong is rendered in bold. This is not always @@ -558,8 +558,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use font with the size attribute set to +1 or -1 respectively. This has the same effect as using - big or small. However, the - use of this approach is deprecated. + big or small. However, + the use of this approach is deprecated. @@ -605,7 +605,8 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" href attribute contains the URL of the target document. The content of the element becomes the link, and is normally indicated to the user in some way (underlining, change of - colour, different mouse cursor when over the link, and so on). + colour, different mouse cursor when over the link, and so + on). Using <literal><a href="..."></literal> @@ -748,11 +749,11 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" A book is organised into chapters. This is a mandatory requirement. There may be parts between - the book and the chapter to provide another layer of organisation. The - Handbook is arranged in this way. + the book and the chapter to provide another layer of organisation. + The Handbook is arranged in this way. - A chapter may (or may not) contain one or more sections. These are - indicated with the sect1 element. If a section + A chapter may (or may not) contain one or more sections. These + are indicated with the sect1 element. If a section contains another section then use the sect2 element, and so on, up to sect5. @@ -828,8 +829,8 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" A chapter can not be empty, it must contain elements in addition - to title. If you need to include an empty chapter - then just use an empty paragraph. + to title. If you need to include an empty + chapter then just use an empty paragraph. Empty chapters @@ -1217,9 +1218,9 @@ main(void) detail) a table (which can be either formal or informal) consists of a table element. This contains at least one tgroup element, which specifies (as an attribute) - the number of columns in this table group. Within the tablegroup you - can then have one thead element, which contains - elements for the table headings (column headings), and one + the number of columns in this table group. Within the tablegroup + you can then have one thead element, which + contains elements for the table headings (column headings), and one tbody which contains the body of the table. @@ -1372,8 +1373,8 @@ main(void) user and the root user have been provided as entities. Every time you want to indicate the user is at a shell prompt, use one of &prompt.root; and - &prompt.user; as necessary. They do not - need to be inside prompt. + &prompt.user; as necessary. They do + not need to be inside prompt. &prompt.root; and @@ -1480,10 +1481,10 @@ This is the file called 'foo2' Applications, commands, options, and cites You will frequently want to refer to both applications and - commands when writing for the Handbook. The distinction between them - is simple; an application is the name for a suite (or possibly just - 1) of programs that fulfil a particular task. A command is the name - of a program that the user can run. + commands when writing for the Handbook. The distinction between + them is simple; an application is the name for a suite (or possibly + just 1) of programs that fulfil a particular task. A command is the + name of a program that the user can run. In addition, you will occasionally need to list one or more of the options that a command might take. @@ -1505,8 +1506,8 @@ This is the file called 'foo2' section. This can be cumbersome to write, and so a series of general entities have been - created to make this easier. Each entity takes the form + linkend="sgml-primer-general-entities">general entities + have been created to make this easier. Each entity takes the form &man.manual-page.manual-section;. The file that contains these entities is in @@ -1894,13 +1895,13 @@ This is the file called 'foo2' Literal text You will often need to include “literal” text in the - Handbook. This is text that is excerpted from another file, or which - should be copied from the Handbook into another file + Handbook. This is text that is excerpted from another file, or + which should be copied from the Handbook into another file verbatim. Some of the time, programlisting will be - sufficient to denote this text. programlisting is - not always appropriate, particularly when you want to include a + sufficient to denote this text. programlisting + is not always appropriate, particularly when you want to include a portion of a file “in-line” with the rest of the paragraph. @@ -2103,8 +2104,8 @@ This is the file called 'foo2' If you want to control the text of the link then use - link. This element wraps content, and the content - will be used for the link. + link. This element wraps content, and the + content will be used for the link. Using <sgmltag>link</sgmltag> diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml index ab19ac8e98..213fe4aee3 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-primer/chapter.sgml @@ -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 $ --> @@ -231,8 +231,8 @@ Using an element (start tag only) HTML has an element for indicating a horizontal rule, called - hr. This element does not wrap content, so only has - a start tag. + hr. This element does not wrap content, so only + has a start tag. This is a paragraph.

@@ -260,8 +260,8 @@ other elements, and exactly what they can contain. - People often confuse the terms tags and elements, and use the terms - as if they were interchangeable. They are not. + People often confuse the terms tags and elements, and use the + terms as if they were interchangeable. They are not. 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 <, p, and >. But the phrase - “the <p> element” refers to the whole element. + “the <p> element” refers to the whole + element. This distinction is very subtle. But keep it in mind. @@ -322,8 +323,9 @@ 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 always quote your attribute values. + all. However, the rules for doing this are subtle, and it is far + simpler just to always quote your attribute + values. For you to do… @@ -425,8 +427,8 @@ setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/catalog:$SGML_CATALOG_FILES See what happens when required elements are omitted. Try - removing the title and /title - tags, and re-run the validation. + removing the title and + /title tags, and re-run the validation. &prompt.user; nsgmls -s example.sgml 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 - Simply omitting the title tags has generated - 2 different errors. + Simply omitting the title tags has + generated 2 different errors. 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 PUBLIC 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 later. + the FPI. Other ways of telling the SGML parser how to find the + DTD are shown later. @@ -628,10 +631,10 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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). + 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). Because the FreeBSD Project hasn't been registered the owner string is -//FreeBSD. And as you can @@ -660,8 +663,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished 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. + file. This may include version numbers or any short text that + is meaningful to you and unique for the SGML system. @@ -686,8 +689,8 @@ nsgmls:example.sgml:6:8:E: end tag for "HEAD" which is not finished In order to do this it can use a catalog file. A catalog file (typically called catalog) contains lines that - map FPIs to filenames. For example, if the catalog file contained the - line; + map FPIs to filenames. For example, if the catalog file contained + the line; PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" @@ -698,18 +701,18 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" catalog file that contained that line. Look at the contents of - /usr/local/share/sgml/html/catalog. This is the - catalog file for the HTML DTDs that will have been installed as part - of the textproc/docproj port. + /usr/local/share/sgml/html/catalog. This is + the catalog file for the HTML DTDs that will have been installed as + part of the textproc/docproj port. <envar>SGML_CATALOG_FILES</envar> In order to locate a catalog 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. + 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. In addition, you can set SGML_CATALOG_FILES 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" typically (but not always) means the DTD will be provided as a filename. - 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 SYSTEM identifier then everyone would - need to keep their DTDs in the same place. + 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 SYSTEM identifier then everyone + would need to keep their DTDs in the same place. @@ -780,20 +783,21 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" SGML that the parser should act upon. These sections are marked by <! ... > in - your document. Everything between these delimiters is SGML syntax as you - might find within a DTD. + your document. Everything between these delimiters is SGML syntax as + you might find within a DTD. As you may just have realised, the DOCTYPE declaration is an example - of SGML syntax that you need to include in your document… + linkend="sgml-primer-doctype-declaration">DOCTYPE declaration + is an example of SGML syntax that you need to include in your + document… Comments Comments are an SGML construction, and are normally only valid - inside a DTD. However, as shows, it is - possible to use SGML syntax within your document. + inside a DTD. However, as + shows, it is possible to use SGML syntax within your document. The delimiters for SGML comments is the string “--”. The first occurence of this string @@ -899,24 +903,25 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Entities - 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. + 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. - 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. + 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. - There are two types of entities which can be used in two - different situations; general entities and + There are two types of entities which can be used in two different + situations; general entities and parameter entities. General Entities 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 parameter + define them in one). They can only be used in your document. + Contrast this with parameter entities. 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" 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. + 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. Fortunately, you can use the two general entities &lt; and &amp; whenever you need to include one or other of these @@ -971,11 +976,12 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Parameter entities - Like general entities, - 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 SGML context. + Like general + entities, 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 SGML + context. 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" Using entities to include files - Entities (both general and - parameter) are + Entities (both general and parameter) are particularly useful when used to include one file inside another. @@ -1264,6 +1271,7 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" Edit example.sgml so that it looks like this; + %entities; @@ -1365,8 +1373,8 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" The two content models you will probably find most useful are CDATA and RCDATA. - CDATA is for “Character Data”. If - the parser is in this content model then it is expecting to see + CDATA 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. @@ -1447,9 +1455,9 @@ PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd" comments. It becomes more useful when you realise you can use parameter entities 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 + to control this. Remember that parameter entities can only be used + in SGML contexts, and the keyword of a marked section is an SGML context. For example, suppose that you produced a hard-copy version of diff --git a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml index c923b10780..004ccb34ef 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/the-handbook/chapter.sgml @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: chapter.sgml,v 1.4 1999-07-28 20:06:03 nik Exp $ + $Id: chapter.sgml,v 1.5 1999-07-30 20:51:00 nik Exp $ --> @@ -88,11 +88,11 @@ Handbook's structure. handbook.sgml uses parameter entities to load in - the files with the .ent extension. These files - (described later) then define general - entities that are used throughout the rest of the - Handbook. + linkend="sgml-primer-parameter-entities">parameter entities + to load in the files with the .ent extension. + These files (described later) then define general entities that + are used throughout the rest of the Handbook. @@ -256,8 +256,8 @@ V For example, if you have added two sentances to a paragraph, such that the line lengths on the paragraph now go over 80 columns, first commit your change with the too-long line lengths. Then fix the line - wrapping, and commit this second change. In the commit message for the - second change, be sure to indicate that this is a whitespace-only + wrapping, and commit this second change. In the commit message for + the second change, be sure to indicate that this is a whitespace-only change, and that the translation team can ignore it. -- cgit v1.2.3