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