diff options
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml')
| -rw-r--r-- | en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml | 2210 |
1 files changed, 2210 insertions, 0 deletions
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 new file mode 100644 index 0000000000..e749463375 --- /dev/null +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -0,0 +1,2210 @@ +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. +--> + +<chapter id="sgml-markup"> + <title>SGML Markup</title> + + <para>This chapter describes the three markup languages you will encounter + when you contribute to the FreeBSD documentation project. Each section + describes the markup language, and details the markup that you are likely + to want to use, or that is already in use.</para> + + <para>These markup languages contain a large number of elements, and it can + be confusing sometimes to know which element to use for a particular + situation. This section goes through the elements you are most likely to + need, and gives examples of how you would use them.</para> + + <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 + content, please post it to the FreeBSD Documentation Project mailing list + <email>freebsd-doc@freebsd.org</email>.</para> + + <note> + <title>Inline vs. block</title> + + <para>In the remainder of this document, when describing elements, + <emphasis>inline</emphasis> means that the element can occur within a + block element, and does not cause a line break. A + <emphasis>block</emphasis> element, by comparison, will cause a line + break (and other processing) when it is encountered.</para> + </note> + + <sect1> + <title>HTML</title> + + <para>HTML, the HyperText Markup Language, is the markup language of + choice on the World Wide Web. More information can be found at + <URL:<ulink + url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para> + + <para>HTML is used to markup pages on the FreeBSD web site. It should not + (generally) be used to mark up other documention, since DocBook offers a + far richer set of elements to choose from. Consequently, you will + normally only encounter HTML pages if you are writing for the web + site.</para> + + <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the + latest, 4.0 (available in both <emphasis>strict</emphasis> and + <emphasis>loose</emphasis> variants).</para> + + <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> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>There are a number of HTML FPIs, depending upon the version (also + known as the level) of HTML that you want to declare your document to + be compliant with.</para> + + <para>The majority of HTML documents on the FreeBSD web site comply with + the loose version of HTML 4.0.</para> + + <programlisting> +PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>An HTML document is normally split in to two sections. The first + section, called the <emphasis>head</emphasis>, contains + meta-information about the document, such as its title, the name of + the author, the parent document, and so on. The second section, the + <emphasis>body</emphasis>, contains the content that will be displayed + to the user.</para> + + <para>These sections are indicated with <sgmltag>head</sgmltag> and + <sgmltag>body</sgmltag> elements respectively. These elements are + contained within the top-level <sgmltag>html</sgmltag> element.</para> + + <example> + <title>Normal HTML document structure</title> + + <programlisting> +<html> + <head> + <title><replaceable>The document's title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Headings</title> + + <para>HTML allows you to denote headings in your document, at up to + six different levels.</para> + + <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>, + then <sgmltag>h2</sgmltag>, continuing down to + <sgmltag>h6</sgmltag>.</para> + + <para>The element's content is the text of the heading.</para> + + <example> + <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<h1>First section</h1> + +<!-- Document introduction goes here --> + +<h2>This is the heading for the first section</h2> + +<!-- Content for the first section goes here --> + +<h3>This is the heading for the first sub-section</h3> + +<!-- Content for the first sub-section goes here --> + +<h2>This is the heading for the second section</h2> + +<!-- Content for the second section goes here -->]]></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> + + <example> + <title>Bad ordering of + <sgmltag>h<replaceable>n</replaceable></sgmltag> elements</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<h1>First section</h1> + +<!-- Document introduction --> + +<h3>Sub-section</h3> + +<!-- This is bad, <h2> has been left out -->]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Paragraphs</title> + + <para>HTML supports a single paragraph element, + <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>A block quotation is an extended quotation from another document + that should not appear within the current paragraph.</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>A small excerpt from the US Constitution;</p> + +<blockquote>We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the general + Welfare, and secure the Blessings of Liberty to ourselves and our + Posterity, do ordain and establish this Constitution for the + United States of America.</blockquote>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Lists</title> + + <para>You can present the user with three types of lists, ordered, + 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> + + <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag> + element, unordered lists by the <sgmltag>ul</sgmltag> element, and + definition lists by the <sgmltag>dl</sgmltag> element.</para> + + <para>Ordered and unordered lists contain listitems, indicated by the + <sgmltag>li</sgmltag> element. A listitem can contain textual + content, or it may be further wrapped in one or more + <sgmltag>p</sgmltag> elements.</para> + + <para>Definition lists contain definition terms + (<sgmltag>dt</sgmltag>) and definition descriptions + (<sgmltag>dd</sgmltag>). A definition term can only contain inline + elements. A definition description can contain other block + elements.</para> + + <example> + <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>An unordered list. Listitems will probably be + preceeded by bullets.</p> + +<ul> + <li>First item</li> + + <li>Second item</li> + + <li>Third item</li> +</ul> + +<p>An ordered list, with list items consisting of multiple + paragraphs. Each item (note: not each paragraph) will be + numbered.</p> + +<ol> + <li><p>This is the first item. It only has one paragraph.</p></li> + + <li><p>This is the first paragraph of the second item.</p> + + <p>This is the second paragraph of the second item.</p></li> + + <li><p>This is the first and only paragraph of the third + item.</p></li> +</ol>]]></programlisting> + </example> + + <example> + <title>Definition lists with <sgmltag>dl</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p></dd> + + <p>Paragraph 2 of definition 1.</p></dd> + + <dt>Term 2</dt> + + <dd><p>Paragraph 1 of definition 2.</p></dd> + + <dt>Term 3</dt> + + <dd>Paragraph 1 of definition 3. Note that the <p> + element is not required in the single paragraph case.</dd> +</dl>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Pre-formatted text</title> + + <para>You can indicate that text should be shown to the user exactly + as it is in the file. Typically, this means that the text is shown + in a fixed font, multiple spaces are not merged in to one, and line + breaks in the text are significant.</para> + + <para>In order to do this, wrap the content in the + <sgmltag>pre</sgmltag> element.</para> + + <example> + <title><sgmltag>pre</sgmltag></title> + + <para>You could use <sgmltag>pre</sgmltag> to mark up an e-mail + message;</para> + + <programlisting> +<![ CDATA [<pre> + From: nik@freebsd.org + To: freebsd-doc@freebsd.org + Subject: New documentation available + + There's a new copy of my primer for contributers to the FreeBSD + Documentation Project available at + + <URL:http://www.freebsd.org/~nik/primer/index.html> + + Comments appreciated. + + N +</pre>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Tables</title> + + <note> + <para>Most text-mode browsers (such as Lynx) do not render tables + particularly effectively. If you are relying on the tabular + display of your content, you should consider using alternative + markup to prevent confusion.</para> + </note> + + <para>Mark up tabular information using the <sgmltag>table</sgmltag> + element. A table consists of one or more table rows + (<sgmltag>tr</sgmltag>), each containing one or more cells of table + data (<sgmltag>td</sgmltag>). Each cell can contain other block + elements, such as paragraphs or lists. It can also contain another + table (this nesting can repeat indefinitely). If the cell only + contains one paragraph then you do not need to include the + <sgmltag>p</sgmltag> element.</para> + + <example> + <title>Simple use of <sgmltag>table</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This is a simple 2x2 table.</p> + +<table> + <tr> + <td>Top left cell</td> + + <td>Top right cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom right cell</td> + </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> + attributes, with values indicating the number of rows of columns + that should be spanned.</para> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>One tall thin cell on the left, two short cells next to + it on the right.</p> + +<table> + <tr> + <td rowspan="2">Long and thin</td> + </tr> + + <tr> + <td>Top cell</td> + + <td>Bottom cell</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Using <literal>colspan</literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>One long cell on top, two short cells below it.</p> + +<table> + <tr> + <td colspan="2">Top cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom right cell</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Using <literal>rowspan</literal> and + <literal>colspan</literal> together</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged in to one. The other cells are normal.</p> + +<table> + <tr> + <td colspan="2" rowspan="2">Top left large cell</td> + + <td>Top right cell</td> + </tr> + + <tr> + <!-- Because the large cell on the left merges in to + this row, the first <td> will occur on its + right --> + + <td>Middle right cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom middle cell</td> + + <td>Bottom right cell</td> + </tr> +</table>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <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> + + <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and + <sgmltag>strong</sgmltag> is rendered in bold. This is not always + the case however, and you should not rely on it.</para> + + <example> + <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><em>This</em> has been emphasised, while + <strong>this</strong> has been strongly emphasised.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Bold and italics</title> + + <para>Because HTML includes presentational markup, you can also + indicate that particular content should be rendered in bold or + italic. The elements are <sgmltag>b</sgmltag> and + <sgmltag>i</sgmltag> respectively.</para> + + <example> + <title><sgmltag>b</sgmltag> and <sgmltag>i</sgmltag></title> + + <programlisting> +<![ CDATA [<p><b>This</b> is in bold, while <i>this</i> is + in italics.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating fixed pitch text</title> + + <para>If you have content that should be rendered in a fixed pitch + (typewriter) typeface, use <sgmltag>tt</sgmltag> (for + “teletype”).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>This document was originally written by + Nik Clayton, who can be reached by e-mail as + <tt>nik@freebsd.org</tt>.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Content size</title> + + <para>You can indicate that content should be shown in a larger or + smaller font. There are three ways of doing this.</para> + + <orderedlist> + <listitem> + <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag> + around the content you wish to change size. These tags can be + nested, so <literal><big><big>This is much + bigger</big></big></literal> is possible.</para> + </listitem> + + <listitem> + <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> + </listitem> + + <listitem> + <para>Use <sgmltag>font</sgmltag> with the <literal>size</literal> + attribute set to a number between 1 and 7. The default font size + is <literal>3</literal>. This approach is deprecated.</para> + </listitem> + </orderedlist> + + <example> + <title><sgmltag>big</sgmltag>, <sgmltag>small</sgmltag>, and + <sgmltag>font</sgmltag></title> + + <para>The following fragments all do the same thing.</para> + + <programlisting> +<![ CDATA [<p>This text is <small>slightly smaller</small>. But + this text is <big>slightly bigger</big>.</p> + +<p>This text is <font size="-1">slightly smaller</font>. But + this text is <font size="+1">slightly bigger</font.</p> + +<p>This text is <font size="2">slightly smaller</font>. But + this text is <font size="4">slightly bigger</font>.</p>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other documents on the WWW</title> + + <para>In order to include a link to another document on the WWW you + must know the URL of the document you want to link to.</para> + + <para>The link is indicated with <sgmltag>a</sgmltag>, and the + <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> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p>More information is available at the + <a href="http://www.freebsd.org/">FreeBSD web site</a>.</p>]]></programlisting> + </example> + + <para>These links will take the user to the top of the chosen + document.</para> + </sect3> + + <sect3> + <title>Linking to other parts of documents</title> + + <para>Linking to a point within another document (or within the same + document) requires that the document author include anchors that you + can link to.</para> + + <para>Anchors are indicated with <sgmltag>a</sgmltag> and the + <literal>name</literal> attribute instead of + <literal>href</literal>.</para> + + <example> + <title>Using <literal><a name="..."></literal></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<p><a name="para1">This</a> paragraph can be referenced + in other links with the name <tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>To link to a named part of a document, write a normal link to + that document, but include the name of the anchor after a + <literal>#</literal> symbol.</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in a + document called <filename>foo.html</filename>.</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="foo.html#para1">first paragraph</a> of + <tt>foo.html</tt>.</p>]]></programlisting> + </example> + + <para>If you are linking to a named anchor within the same document + then you can omit the document's URL, and just include the name of + the anchor (with the preceeding <literal>#</literal>).</para> + + <example> + <title>Linking to a named part of another document</title> + + <para>Assume that the <literal>para1</literal> example resides in + this document</para> + + <programlisting> +<![ CDATA [<p>More information can be found in the + <a href="#para1">first paragraph</a> of this + document.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>DocBook</title> + + <para>DocBook was designed by the <ulink + url="http://www.oreilly.com/davenport/">Davenport Group</ulink> to be + a DTD for writing technical documentation. As such, and unlike LinuxDoc + and HTML, DocBook is very heavily orientated towards markup that + describes <emphasis>what</emphasis> something is, rather than describing + <emphasis>how</emphasis> it should be presented.</para> + + <note> + <title><literal>formal</literal> vs. <literal>informal</literal></title> + + <para>Some elements may exist in two forms, <emphasis>formal</emphasis> + and <emphasis>informal</emphasis>. Typically, the formal version of + the element will consist of a title followed by the information + version of the element. The informal version will not have a + title.</para> + </note> + + <para>The DocBook DTD is available from the ports collection in the + <filename>textproc/docbook</filename> port. It is automatically + installed as part of the <filename>textproc/docproj</filename> + port.</para> + + <sect2> + <title>FreeBSD extensions</title> + + <para>The FreeBSD Documentation Project has extended the DocBook DTD by + adding some new elements. These elements serve to make some of the + markup more precise.</para> + + <para>Where a FreeBSD specific element is listed below it is clearly + marked.</para> + + <para>Throughout the rest of this document, the term + “DocBook” is used to mean the FreeBSD extended DocBook + DTD.</para> + + <note> + <para>There is nothing about these extensions that is FreeBSD + specific, it was just felt that they were useful enhancements for + this particular project. Should anyone from any of the other *nix + camps (NetBSD, OpenBSD, Linux, …) be interested in + collaborating on a standard DocBook extension set, please get in + touch with Nik Clayton <email>nik@freebsd.org</email>.</para> + </note> + </sect2> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing FPIs for + DocBook customisations, the FPI for the FreeBSD extended DocBook DTD + is;</para> + + <programlisting> +PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional elements</title> + + <para>DocBook contains a number of elements for marking up the structure + of a book.</para> + + <para>Generally, the top level (first) element will be + <sgmltag>book</sgmltag>.</para> + + <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> + + <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> + + <para>Chapters and sections contain the remainder of the content.</para> + + <sect3> + <title>Starting a book</title> + + <para>The content of the book is contained within the + <sgmltag>book</sgmltag> element. As well as containing structural + markup, this element can contain elements that include additional + information about the book. This is either meta-information, used + for reference purposes, or additional content used to produce a + title page.</para> + + <para>This additional information should be contained within + <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + <programlisting> +<book> + <bookinfo> + <title><replaceable>Your title here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your e-mail address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating chapters</title> + + <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. Each + chapter has a mandatory <sgmltag>title</sgmltag>.</para> + + <example> + <title>A simple chapter</title> + + <programlisting> +<![ CDATA [<chapter> + <title>The chapter's title</title> + + ... +</chapter>]]></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> + + <example> + <title>Empty chapters</title> + + <programlisting> +<![ CDATA [<chapter> + <title>This is an empty chapter</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sections below chapters</title> + + <para>Chapters can be broken up into sections, subsections, and so + on. Use the <sgmltag>sect<replaceable>n</replaceable></sgmltag> + element. The <replaceable>n</replaceable> indicates the section + number, which identifies the section level.</para> + + <para>The first <sgmltag>sect<replaceable>n</replaceable></sgmltag> is + <sgmltag>sect1</sgmltag>. You can have one or more of these in a + chapter. They can contain one or more <sgmltag>sect2</sgmltag> + elements, and so on, down to <sgmltag>sect5</sgmltag>.</para> + + <example> + <title>Sections in chapters</title> + + <programlisting> +<![ CDATA [<chapter> + <title>A sample chapter</title> + + <para>Some text in the chapter.</para> + + <sect1> + <title>First section (1.1)</title> + + ... + </sect1> + + <sect1> + <title>Second section (1.2)</title> + + <sect2> + <title>First sub-section (1.2.1)</title> + + <sect3> + <title>First sub-sub-section (1.2.1.1)</title> + + ... + </sect3> + </sect2> + + <sect2> + <title>Second sub-section (1.2.2)</title> + + ... + </sect2> + </sect1> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Subdividing using <sgmltag>part</sgmltag>s</title> + + <para>You can introduce another layer of organisation between + <sgmltag>book</sgmltag> and <sgmltag>chapter</sgmltag> with one or + more <sgmltag>part</sgmltag>s.</para> + + <programlisting> +<![ CDATA [<part> + <title>Introduction</title> + + <chapter> + <title>Overview</title> + + ... + </chapter> + + <chapter> + <title>What is FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>History</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Block elements</title> + + <sect3> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs; + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and + <sgmltag>simpara</sgmltag>.</para> + + <para>Most of the time you will only need to use + <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> includes a + <sgmltag>title</sgmltag> element, and <sgmltag>simpara</sgmltag> + disallows some elements from within <sgmltag>para</sgmltag>. Stick + with <sgmltag>para</sgmltag>.</para> + + <example> + <title><sgmltag>para</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>This is a paragraph. It can contain just about any + other element.</para> ]]></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any other + element.</para> + </example> + </sect3> + + <sect3> + <title>Block quotations</title> + + <para>A block quotation is an extended quotation from another document + that should not appear within the current paragraph. You will + probably only need it infrequently.</para> + + <para>Blockquotes can optionally contain a title and an attribution + (or they can be left untitled and unattributed).</para> + + <example> + <title><sgmltag>blockquote</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>A small excerpt from the US Constitution;</para> + +<blockquote> + <title>Preamble to the Constitution of the United States</para> + + <attribution>Copied from a web site somewhere</attribution> + + <para>We the People of the United States, in Order to form a more perfect + Union, establish Justice, insure domestic Tranquility, provide for the + common defence, promote the general Welfare, and secure the Blessings + of Liberty to ourselves and our Posterity, do ordain and establish this + Constitution for the United States of America.</para> +</blockquote>]]></programlisting> + + <para>Appearance:</para> + + <blockquote> + <title>Preamble to the Constitution of the United States</title> + + <attribution>Copied from a web site somewhere</attribution> + + <para>We the People of the United States, in Order to form a more + perfect Union, establish Justice, insure domestic Tranquility, + provide for the common defence, promote the general Welfare, and + secure the Blessings of Liberty to ourselves and our Posterity, + do ordain and establish this Constitution for the United States + of America.</para> + </blockquote> + </example> + </sect3> + + <sect3> + <title>Tips, notes, warnings, cautions, important information and + sidebars.</title> + + <para>You may need to include extra information separate from the + main body of the text. Typically this is “meta” + information that the user should be aware of.</para> + + <para>Depending on the nature of the information, one of + <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, + <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and + <sgmltag>important</sgmltag> should be used. Alternatively, if the + information is related to the main text but is not one of the above, + use <sgmltag>sidebar</sgmltag>.</para> + + <para>The circumstances in which to choose one of these elements over + another is unclear. The DocBook documentation suggests;</para> + + <itemizedlist> + <listitem> + <para>A Note is for information that should be heeded by all + readers.</para> + </listitem> + + <listitem> + <para>An Important element is a variation on Note.</para> + </listitem> + + <listitem> + <para>A Caution is for information regarding possible data loss + or software damage.</para> + </listitem> + + <listitem> + <para>A Warning is for information regarding possible hardware + damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><sgmltag>warning</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + harddisk.</para> +</warning>]]></programlisting> + </example> + + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows from + your harddisk.</para> + </warning> + </sect3> + + <sect3> + <title>Lists and procedures</title> + + <para>You will often need to list pieces of information to the user, + or present them with a number of steps that must be carried out in + order to accomplish a particular goal.</para> + + <para>In order to do this, use <sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, or + <sgmltag>procedure</sgmltag><footnote><para>There are other types of + list element in DocBook, but we're not concerned with those at + the moment.</para> + </footnote> + </para> + + <para><sgmltag>itemizedlist</sgmltag> and + <sgmltag>orderedlist</sgmltag> are similar to the counterparts in + HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one + consists of one or more <sgmltag>listentry</sgmltag> elements, and + each <sgmltag>listentry</sgmltag> contains one or more block + elements. The <sgmltag>listentry</sgmltag> elements are analagous to + HTMLs <sgmltag>li</sgmltag> tags. However, unlike HTML they are + required.</para> + + <para><sgmltag>procedure</sgmltag> is slightly different. It consists + of <sgmltag>step</sgmltag>s, which may in turn consists of more + <sgmltag>step</sgmltag>s or <sgmltag>substep</sgmltag>s. Each + <sgmltag>step</sgmltag> contains block elements.</para> + + <example> + <title><sgmltag>itemizedlist</sgmltag>, + <sgmltag>orderedlist</sgmltag>, and + <sgmltag>procedure</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> +</itemizedlist> + +<orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> +</orderedlist>]]></programlisting> + + <para>Appearance:</para> + + <itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> + </orderedlist> + </example> + </sect3> + + <sect3> + <title>Showing file samples</title> + + <para>If you want to show a fragment of a file (or perhaps a complete + file) to the user, wrap it in the <sgmltag>programlisting</sgmltag> + element.</para> + + <para>White space and line breaks within + <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> + significant. In particular, this means that the closing tag should + appear on the same line as the last line of the output, otherwise a + spurious blank line will be included.</para> + + <example> + <title><sgmltag>programlisting</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA[<para>When you have finished, your program should look like + this;</para> + +<programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by their + entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this;</para> + + <programlisting> +#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + + <note> + <para>There is a mechanism within DocBook for referring to sections + of a previously occuring <sgmltag>programlisting</sgmltag>, called + callouts (see <sgmltag>programlistingco</sgmltag> for more + information). I don't fully understand (i.e., have never used) + this feature, so can't document it here. For the mean time, you + can include line numbers within the content, and then refer to + them later on in your description. That will change, as soon as I + find the time to understand and document callouts.</para> + </note> + </sect3> + + <sect3> + <title>Tables</title> + + <para>Unlike HTML, you do not need to use tables for layout purposes, + as the stylesheet handles those issues for you. Instead, just use + tables for marking up tabular data.</para> + + <para>In general terms (and see the DocBook documentation for more + 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 + <sgmltag>tbody</sgmltag> which contains the body of the + table.</para> + + <para>Both <sgmltag>tgroup</sgmltag> and <sgmltag>thead</sgmltag> + contain <sgmltag>row</sgmltag> elements, which in turn contain + <sgmltag>entry</sgmltag> elements. Each <sgmltag>entry</sgmltag> + element specifies one cell in the table.</para> + + <example> + <title><sgmltag>informaltable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>This is column head 1</entry> + <entry>This is column head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> +</informaltable>]]></programlisting> + + <para>Appearance:</para> + + <informaltable> + <tgroup cols="2"> + <thead> + <row> + <entry>This is column head 1</entry> + <entry>This is column head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>If you don't want a border around the table the + <literal>frame</literal> attribute can be added to the + <sgmltag>informaltable</sgmltag> element with a value of + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + <example> + <title>Tables where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is column head 1</entry> + <entry>This is column head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect3> + + <sect3> + <title>Examples for the user to follow</title> + + <para>A lot of the time you need to show examples for the user to + follow. Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, they + type in another command, and so on.</para> + + <para>A number of distinct elements and entities come in to play + here.</para> + + <variablelist> + <varlistentry> + <term><sgmltag>informalexample</sgmltag></term> + + <listitem> + <para>Most of the time these examples will occur + “mid-flow” as it were, and you won't need to put a + title on them. So, most of the time, the outermost element + will be <sgmltag>informalexample</sgmltag>. For those times + when you do need to include a title on the example, use + <sgmltag>example</sgmltag>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>screen</sgmltag></term> + + <listitem> + <para>Everything the user sees in this example will be on the + computer screen, so the next element is + <sgmltag>screen</sgmltag>.</para> + + <para>Within <sgmltag>screen</sgmltag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>prompt</sgmltag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the screen + are prompts from the computer (either from the OS, command + shell, or application. These should be marked up using + <sgmltag>prompt</sgmltag>.</para> + + <para>As a special case, the two shell prompts for the normal + 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> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the original + DTD.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><sgmltag>userinput</sgmltag></term> + + <listitem> + <para>When displaying text that the user should type in, wrap it + in <sgmltag>userinput</sgmltag> tags. It will probably be + displayed differently to the user.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>informalexample</sgmltag>, + <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <sgmltag>userinput</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </informalexample> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> marked + up as <sgmltag>programlisting</sgmltag>. Reserve + <sgmltag>programlisting</sgmltag> for showing fragments of files + outside the context of user actions.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>In-line elements</title> + + <sect3> + <title>Emphasising information</title> + + <para>When you want to emphasise a particular word or phrase, use + <sgmltag>emphasis</sgmltag>. This may be presented as italic, or + bold, or might be spoken differently with a text-to-speech + system.</para> + + <para>There is no way to change the presentation of the emphasis + within your document, no equivalent of HTML's <sgmltag>b</sgmltag> + and <sgmltag>i</sgmltag>. If the information you are presenting is + important then consider presenting it in + <sgmltag>important</sgmltag> rather than + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> premiere Unix + like operating system for the Intel architecture.</para> + </example> + </sect3> + + <sect3> + <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> + + <para>In addition, you will occasionally need to list one or more of + the options that a command might take.</para> + + <para>Finally, you will often want to list a command with it's manual + section number, in the “command(number)” format so + common in Unix manuals.</para> + + <para>Mark up application names with + <sgmltag>application</sgmltag>.</para> + + <para>When you want to list a command with it's manual section number + (which should be most of the time) the DocBook element is + <sgmltag>citerefentry</sgmltag>. This will contain a further two + elements, <sgmltag>refentrytitle</sgmltag> and + <sgmltag>manvolnum</sgmltag>. The content of + <sgmltag>refentrytitle</sgmltag> is the name of the command, and the + content of <sgmltag>manvolnum</sgmltag> is the manual page + section.</para> + + <para>This can be cumbersome to write, and so a series of <link + linkend="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 + <filename>doc/share/sgml/man-refs.ent</filename>, and can be + referred to using this FPI;</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to your documentation will probably + look like this;</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V3.0-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]]></programlisting> + + <para>Use <sgmltag>command</sgmltag> when you want to include a + command name “in-line” but present it as something the + user should type in.</para> + + <para>Use <sgmltag>option</sgmltag> to mark up a command's + options.</para> + + <para>This can be confusing, and sometimes the choice is not always + clear. Hopefully this example makes it clearer.</para> + + <example> + <title>Applications, commands, and options.</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para><application>Sendmail</application> is the most + widely used Unix mail application.</para> + +<para><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.sendmail.8;, and &man.newaliases.8; + programs.</para> + +<para>One of the command line parameters to <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the current + status of messages in the mail queue. Check this on the command + line by running <command>sendmail -bp</command>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para><application>Sendmail</application> is the most widely used + Unix mail application.</para> + + <para><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <citerefentry> + <refentrytitle>mailq</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, and <citerefentry> + <refentrytitle>newaliases</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry> programs.</para> + + <para>One of the command line parameters to <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the current + status of messages in the mail queue. Check this on the command + line by running <command>sendmail -bp</command>.</para> + </example> + + <note> + <para>Notice how the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> notation is easier to follow.</para> + </note> + </sect3> + + <sect3> + <title>Files, directories, extensions</title> + + <para>Whenever you wish to refer to the name of a file, a directory, + or a file extension, use <sgmltag>filename</sgmltag>.</para> + + <example> + <title><sgmltag>filename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>The SGML source for the Handbook in English can be + found in <filename>/usr/doc/en/handbook/</filename>. The first + file is called <filename>handbook.sgml</filename> in that + directory. You should also see a <filename>Makefile</filename> + and a number of files with a <filename>.ent</filename> + extension.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The SGML source for the Handbook in English can be found in + <filename>/usr/doc/en/handbook/</filename>. The first file is + called <filename>handbook.sgml</filename> in that directory. You + should also see a <filename>Makefile</filename> and a number of + files with a <filename>.ent</filename> extension.</para> + </example> + </sect3> + + <sect3> + <title>Devices</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When referring to devices you have two choices. You can either + refer to the device as it appears in <filename>/dev</filename>, or + you can use the name of the device as it appears in the kernel. For + this latter course, use <sgmltag>devicename</sgmltag>.</para> + + <para>Sometimes you will not have a choice. Some devices, such as + networking cards, do not have entries in <filename>/dev</filename>, + or the entries are markedly different from those entries.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para><devicename>sio</devicename> is used for serial + communication in FreeBSD. <devicename>sio</devicename> manifests + through a number of entries in <filename>/dev</filename>, including + <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> + +<para>By contrast, the networking devices, such as + <devicename>ed0</devicename> do not appear in <filename>/dev</filename>. + +<para>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para><devicename>sio</devicename> is used for serial communication + in FreeBSD. <devicename>sio</devicename> manifests through a + number of entries in <filename>/dev</filename>, including + <filename>/dev/ttyd0</filename> and + <filename>/dev/cuaa0</filename>.</para> + + <para>By contrast, the networking devices, such as + <devicename>ed0</devicename> do not appear in + <filename>/dev</filename>.</para> + + <para>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para> + </example> + </sect3> + + <sect3> + <title>Hosts, domains, IP addresses, and so forth</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>You can markup identification information for networked + computers (hosts) in several ways, depending on the nature of the + information. All of them use <sgmltag>hostid</sgmltag> as the + element, with the <literal>role</literal> attribute selecting the + type of the marked up information.</para> + + <variablelist> + <varlistentry> + <term>No role attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no role attribute (i.e., + <sgmltag>hostid</sgmltag>...<sgmltag>hostid</sgmltag> the + marked up information is the simple hostname, such as + <literal>freefall</literal> or <literal>wcarchive</literal>. + You can explicitly specify this with + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>freebsd.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with both + hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>The text is an IP address, probably expressed as a dotted + quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be expressed as a + dotted quad, a hexadecimal string, or as a + <literal>/</literal> followed by a number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an ethernet MAC address, expressed as a series + of 2 digit hexadecimal numbers seperated by colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>hostid</sgmltag> and roles</title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>The local machine can always be referred to by the + name <hostid>localhost</hostid>, which will have the IP address + <hostid role="ipaddr">127.0.0.1</hostid>.</para> + +<para>The <hostid role="domainname">freebsd.org</hostid> domain + contains a number of different hosts, including + <hostid role="fqdn">freefall.freebsd.org</hostid> and + <hostid role="fqdn">bento.freebsd.org</hostid>.</para> + +<para>When adding an IP alias to an interface (using + <command>ifconfig</command>) <emphasis>always</emphasis> use a + netmask of <hostid role="netmask">255.255.255.255</hostid> + (which can also be expressed as <hostid + role="netmask">0xffffffff</hostid>.</para> + +<para>The MAC address uniquely identifies every network card in + in existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The local machine can always be referred to by the name + <hostid>localhost</hostid>, which will have the IP address <hostid + role="ipaddr">127.0.0.1</hostid>.</para> + + <para>The <hostid role="domainname">freebsd.org</hostid> domain + contains a number of different hosts, including <hostid + role="fqdn">freefall.freebsd.org</hostid> and <hostid + role="fqdn">bento.freebsd.org</hostid>.</para> + + <para>When adding an IP alias to an interface (using + <command>ifconfig</command>) <emphasis>always</emphasis> use a + netmask of <hostid role="netmask">255.255.255.255</hostid> (which + can also be expressed as <hostid + role="netmask">0xffffffff</hostid>.</para> + + <para>The MAC address uniquely identifies every network card in + existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>When you need to refer to a specific username, such as + <literal>root</literal> or <literal>bin</literal>, use + <sgmltag>username</sgmltag>.</para> + + <example> + <title><sgmltag>username</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>To carry out most system administration functions you + will need to be <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions you will + need to be <username>root</username>.</para> + </example> + </sect3> + + <sect3> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>FreeBSD extension</title> + + <para>These elements are part of the FreeBSD extension to DocBook, + and do not exist in the original DocBook DTD.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag>.</para> + + <para><sgmltag>maketarget</sgmltag> identifies a build target exported + by a <filename>Makefile</filename> that can be given as a parameter + to <command>make</command>. <sgmltag>makevar</sgmltag> identifies a + variable that can be set (in the environment, on the + <command>make</command> command line, or within the + <filename>Makefile</filename>) to influence the process.</para> + + <example> + <title><sgmltag>maketarget</sgmltag> and + <sgmltag>makevar</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>Two common targets in a <filename>Makefile</filename> + are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> + +<para>Typically, invoking <maketarget>all</maketarget> will rebuild the + application, and invoking <maketarget>clean</maketarget> will remove + the temporary files (<filename>.o</filename> for example) created by + the build process.</para> + +<para><maketarget>clean</maketarget> may be controlled by a number of + variables, including <makevar>CLOBBER</makevar> and + <makevar>RECURSE</makevar>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Two common targets in a <filename>Makefile</filename> are + <maketarget>all</maketarget> and + <maketarget>clean</maketarget>.</para> + + <para>Typically, invoking <maketarget>all</maketarget> will rebuild + the application, and invoking <maketarget>clean</maketarget> will + remove the temporary files (<filename>.o</filename> for example) + created by the build process.</para> + + <para><maketarget>clean</maketarget> may be controlled by a number + of variables, including <makevar>CLOBBER</makevar> and + <makevar>RECURSE</makevar>.</para> + </example> + </sect3> + + <sect3> + <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 + 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 + portion of a file “in-line” with the rest of the + paragraph.</para> + + <para>On these occasions, use <sgmltag>literal</sgmltag>.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system tables, and + is a rough guide to how many simultaneous logins the system will + support.</para> + </example> + </sect3> + + <sect3> + <title>Showing items that the user <emphasis>must</emphasis> fill + in</title> + + <para>There will often be times when you want to show the user what to + do, or refer to a file, or command line, or similar, where the user + can not simply copy the examples that you provide, but must instead + include some information themselves.</para> + + <para><sgmltag>replaceable</sgmltag> is designed for this eventuality. + Use it <emphasis>inside</emphasis> other elements to indicate parts + of that element's content that the user must replace.</para> + + <example> + <title><sgmltag>replaceable</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> +</informalexample>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + </informalexample> + + <para><sgmltag>replaceable</sgmltag> can be used in many different + elements, including <sgmltag>literal</sgmltag>. This example also + shows that <sgmltag>replaceable</sgmltag> should only be wrapped + around the content that the user <emphasis>is</emphasis> meant to + provide. The other content should be left alone.</para> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>The <literal>maxusers <replaceable>n</replaceable></literal> + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support.</para> + +<para>For a desktop workstation, <literal>32</literal> is a good value + for <replaceable>n</replaceable>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The <literal>maxusers <replaceable>n</replaceable></literal> + line in the kernel configuration file determines the size of many + system tables, and is a rough guide to how many simultaneous + logins the system will support.</para> + + <para>For a desktop workstation, <literal>32</literal> is a good + value for <replaceable>n</replaceable>.</para> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to other parts of the same document</title> + + <para>Linking within the same document requires you to to specify + where you are linking from (i.e., the text the user will click, or + otherwise indicate, as the source of the link) and where you are + linking to (the link's destination).</para> + + <para>Each element within DocBook has an attribute called + <literal>id</literal>. You can place text in this attribute to + uniquely name the element it is attached to.</para> + + <para>This value will be used when you specify the link + source.</para> + + <para>Normally, you will only be linking to chapters or sections, so + you would add the <literal>id</literal> attribute to these + elements.</para> + + <example> + <title><literal>id on chapters and sections</literal></title> + + <programlisting> +<![ CDATA [<chapter id="chapter1"> + <title>Introduction</title> + + <para>This is the introduction. It contains a subsection, + which is identified as well.</para> + + <sect1 id="chapter1-sect1"> + <title>Sub-sect 1</title> + + <para>This is the subsection.</para> + </sect1> +</chapter>]]></programlisting> + </example> + + <para>Obviously, you should use more descriptive values. The values + must be unique within the document (i.e., not just the file, but the + document the file might be included in as well). Notice how the + <literal>id</literal> for the subsection is constructed by appending + text to the <literal>id</literal> of the chapter. This helps to + ensure that they are unique.</para> + + <para>If you want to allow the user to jump into a specific portion of + the document (possibly in the middle of a paragraph or an example), + use <sgmltag>anchor</sgmltag>. This element has no content, but + takes an <literal>id</literal> attribute.</para> + + <example> + <title><sgmltag>anchor</sgmltag></title> + + <programlisting> +<![ CDATA [<para>This paragraph has an embedded + <anchor id="para1">link target in it. It won't show up in + the document.</para>]]></programlisting> + </example> + + <para>When you want to provide the user with a link they can activate + (probably by clicking) to go to a section of the document that has + an <literal>id</literal> attribute, you can use either + <sgmltag>xref</sgmltag> or <sgmltag>link</sgmltag>.</para> + + <para>Both of these elements have a <literal>linkend</literal> + attribute. The value of this attribute should be the value that you + have used in a <literal>id</literal> attribute (it does not matter + if that value has not yet occured in your document, this will work + for forward links as well as backward links).</para> + + <para>If you use <sgmltag>xref</sgmltag> then you have no control over + the text of the link. It will be generated for you.</para> + + <example> + <title>Using <sgmltag>xref</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example;</para> + + <programlisting> +<![ CDATA [<para>More information can be found + in <xref linkend="chapter1">.</para> + +<para>More specific information can be found + in <xref linkend="chapter1-sect1">.</para>]]></programlisting> + + <para>The text of the link will be generated automatically, and will + look like (<emphasis>emphasised</emphasis> text indicates the text + that will be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + One</emphasis>.</para> + + <para>More specific information can be found in <emphasis>the + section called Sub-sect 1</emphasis>.</para> + </blockquote> + </example> + + <para>Notice how the text from the link is derived from the section + title or the chapter number.</para> + + <note> + <para>This means that you <emphasis>can not</emphasis> use + <sgmltag>xref</sgmltag> to link to an <literal>id</literal> + attribute on an <sgmltag>anchor</sgmltag> element. The + <sgmltag>anchor</sgmltag> has no content, so the + <sgmltag>xref</sgmltag> can not generate the text for the + link.</para> + </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> + + <example> + <title>Using <sgmltag>link</sgmltag></title> + + <para>Assume that this fragment appears somewhere in a document that + includes the <literal>id</literal> example.</para> + + <programlisting> +<![ CDATA [<para>More information can be found in + <link linkend="chapter1">the first chapter</link>.</para> + +<para>More specific information can be found in + <link linkend="chapter1-sect1>this</link> section.</para>]]></programlisting> + + <para>This will generate the following + (<emphasis>emphasised</emphasis> text indicates the text that will + be the link);</para> + + <blockquote> + <para>More information can be found in <emphasis>the first + chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>this</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para>That last one is a bad example. Never use words like + “this” or “here” as the source for the + link. The reader will need to hunt around the surrounding context + to see where the link is actually taking them.</para> + </note> + + <note> + <para>You <emphasis>can</emphasis> use <sgmltag>link</sgmltag> to + include a link to an <literal>id</literal> on an + <sgmltag>anchor</sgmltag> element, since the + <sgmltag>link</sgmltag> content defines the text that will be used + for the link.</para> + </note> + </sect3> + + <sect3> + <title>Linking to documents on the WWW</title> + + <para>Linking to external documents is much simpler, as long as you + know the URL of the document you want to link to. Use + <sgmltag>ulink</sgmltag>. The <literal>url</literal> attribute is + the URL of the page that the link points to, and the content of the + element is the text that will be displayed for the user to + activate.</para> + + <example> + <title><sgmltag>ulink</sgmltag></title> + + <para>Use:</para> + + <programlisting> +<![ CDATA [<para>Of course, you could stop reading this document and + go to the <ulink url="http://www.freebsd.org/">FreeBSD + home page</ulink> instead.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go to the + <ulink url="http://www.freebsd.org/">FreeBSD home page</ulink> + instead.</para> + </example> + </sect3> + </sect2> + </sect1> + + <sect1> + <title>* LinuxDoc</title> + + <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by the + <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation + Project</ulink>, and subsequently adopted by the FreeBSD Documentation + Project.</para> + + <para>The LinuxDoc DTD contains primarily appearance related markup rather + than content related markup (i.e., it describes what something looks + like rather than what it is).</para> + + <para>Both the FreeBSD Documentation Project and the Linux Documentation + Project are migrating from the LinuxDoc DTD to the DocBook DTD.</para> + + <para>The LinuxDoc DTD is available from the ports collection in the + <filename>textproc/linuxdoc</filename> category.</para> + </sect1> +</chapter> + + +<!-- + Local Variables: + mode: sgml + sgml-declaration: "../chapter.decl" + sgml-indent-data: t + sgml-omittag: nil + sgml-always-quote-attributes: t + sgml-parent-document: ("../book.sgml" "part" "chapter") + End: +--> + |