aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO_8859-1/books/fdp-primer/sgml-markup
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO_8859-1/books/fdp-primer/sgml-markup')
-rw-r--r--en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml2563
1 files changed, 0 insertions, 2563 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
deleted file mode 100644
index d497523e7b..0000000000
--- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml
+++ /dev/null
@@ -1,2563 +0,0 @@
-<!-- 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.
-
- $FreeBSD: doc/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.19 2001/04/17 16:02:54 nik Exp $
--->
-
-<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
- &lt;URL:<ulink
- url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</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>&lt;html>
- &lt;head>
- &lt;title><replaceable>The document's title</replaceable>&lt;/title>
- &lt;/head>
-
- &lt;body>
-
- &hellip;
-
- &lt;/body>
-&lt;/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 preceded 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 &lt;p&gt;
- 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://people.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
- &ldquo;teletype&rdquo;).</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>&lt;big&gt;&lt;big&gt;This is much
- bigger&lt;/big&gt;&lt;/big&gt;</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>&lt;a href="..."&gt;</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>&lt;a name="..."&gt;</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 the same 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 oriented 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
- &ldquo;DocBook&rdquo; 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, &hellip;) be interested in
- collaborating on a standard DocBook extension set, please get in
- touch with Nik Clayton <email>nik@FreeBSD.org</email>.</para>
- </note>
-
- <para>The FreeBSD extensions are not (currently) in the ports
- collection. They are stored in the FreeBSD CVS tree, as <ulink
- url="http://www.freebsd.org/cgi/cvsweb.cgi/doc/share/sgml/freebsd.dtd">doc/share/sgml/freebsd.dtd</ulink>.</para>
- </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 V4.1-Based Extension//EN"</programlisting>
- </sect2>
-
- <sect2>
- <title>Document structure</title>
-
- <para>DocBook allows you to structure your documentation in several
- ways. In the FreeBSD Documentation Project we are using two primary
- types of DocBook document: the book and the article.</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>
-
- <para>An article is simpler than a book, and does not use chapters.
- Instead, the content of an article is organised into one or more
- sections, using the same <sgmltag>sect1</sgmltag> (and
- <sgmltag>sect2</sgmltag> and so on) elements that are used in
- books.</para>
-
- <para>Obviously, you should consider the nature of the documentation you
- are writing in order to decide whether it is best marked up as a book
- or an article. Articles are well suited to information that does not
- need to be broken down into several chapters, and that is, relatively
- speaking, quite short, at up to 20-25 pages of content. Books are
- best suited to information that can be broken up into several
- chapters, possibly with appendices and similar content as well.</para>
-
- <para>The <ulink url="http://www.FreeBSD.org/tutorials/">FreeBSD
- tutorials</ulink> are all marked up as articles, while this
- document, the <ulink url="http://www.FreeBSD.org/FAQ/">FreeBSD
- FAQ</ulink>, and the <ulink
- url="http://www.FreeBSD.org/handbook/">FreeBSD Handbook</ulink> are
- all marked up as books.</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>&lt;book>
- &lt;bookinfo>
- &lt;title><replaceable>Your title here</replaceable>&lt;/title>
-
- &lt;author>
- &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
- &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
- &lt;affiliation>
- &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
- &lt;/affiliation>
- &lt;/author>
-
- &lt;copyright>
- &lt;year><replaceable>1998</replaceable>&lt;/year>
- &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
- &lt;/copyright>
-
- &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
-
- &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
-
- &lt;abstract>
- &lt;para><replaceable>Include an abstract of the book's contents here.</replaceable>&lt;/para>
- &lt;/abstract>
- &lt;/bookinfo>
-
- &hellip;
-
-&lt;/book></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Starting an article</title>
-
- <para>The content of the article is contained within the
- <sgmltag>article</sgmltag> element. As well as containing
- structural markup, this element can contain elements that include
- additional information about the article. 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>articleinfo</sgmltag>.</para>
-
- <example>
- <title>Boilerplate <sgmltag>article</sgmltag> with
- <sgmltag>articleinfo</sgmltag></title>
-
- <!-- Can't put this in a marked section because of the
- replaceable elements -->
- <programlisting>&lt;article>
- &lt;articleinfo>
- &lt;title><replaceable>Your title here</replaceable>&lt;/title>
-
- &lt;author>
- &lt;firstname><replaceable>Your first name</replaceable>&lt;/firstname>
- &lt;surname><replaceable>Your surname</replaceable>&lt;/surname>
- &lt;affiliation>
- &lt;address>&lt;email><replaceable>Your e-mail address</replaceable>&lt;/email>&lt;/address>
- &lt;/affiliation>
- &lt;/author>
-
- &lt;copyright>
- &lt;year><replaceable>1998</replaceable>&lt;/year>
- &lt;holder role="mailto:<replaceable>your e-mail address</replaceable>"><replaceable>Your name</replaceable>&lt;/holder>
- &lt;/copyright>
-
- &lt;pubdate role="rcs">&#36;Date&#36;&lt;/pubdate>
-
- &lt;releaseinfo>&#36;Id&#36;&lt;/releaseinfo>
-
- &lt;abstract>
- &lt;para><replaceable>Include an abstract of the article's contents here.</replaceable>&lt;/para>
- &lt;/abstract>
- &lt;/articleinfo>
-
- &hellip;
-
-&lt;/article></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>. Articles do not
- contain chapters, they are reserved for books.</para>
-
- <example>
- <title>A simple chapter</title>
-
- <programlisting><![ CDATA [<chapter>
- <title>The chapter's title</title>
-
- ...
-</chapter>]]></programlisting>
- </example>
-
- <para>A chapter cannot 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>In books, chapters may (but do not need to) be broken up into
- sections, subsections, and so on. In articles, sections are the
- main structural element, and each article must contain at least one
- section. 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><![ RCDATA [<chapter>
- <title>A sample chapter</title>
-
- <para>Some text in the chapter.</para>
-
- <sect1>
- <title>First section (1.1)</title>
-
- &hellip;
- </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>
-
- &hellip;
- </sect3>
- </sect2>
-
- <sect2>
- <title>Second sub-section (1.2.2)</title>
-
- &hellip;
- </sect2>
- </sect1>
-</chapter>]]></programlisting>
- </example>
-
- <note>
- <para>This example includes section numbers in the section titles.
- You should not do this in your documents. Adding the section
- numbers is carried out the by the stylesheets (of which more
- later), and you do not need to manage them yourself.</para>
- </note>
- </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. This cannot be done in an
- <sgmltag>article</sgmltag>.</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</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>]]></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 &ldquo;meta&rdquo;
- 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 their counterparts in
- HTML, <sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag>. Each one
- consists of one or more <sgmltag>listitem</sgmltag> elements, and
- each <sgmltag>listitem</sgmltag> contains one or more block
- elements. The <sgmltag>listitem</sgmltag> elements are analagous to
- HTML's <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>
-
-<procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
-</procedure>]]></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>
-
- <!-- Can't have <procedure> inside <example>, so this is a cheat -->
-
- <procedure>
- <step>
- <para>Do this.</para>
- </step>
-
- <step>
- <para>Then do this.</para>
- </step>
-
- <step>
- <para>And now do this.</para>
- </step>
- </procedure>
- </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 opening tag should
- appear on the same line as the first line of the output, and the
- closing tag should appear on the same line as the last line of the
- output, otherwise spurious blank lines may 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 &lt;stdio.h&gt;
-
-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 &lt;stdio.h&gt;
-
-int
-main(void)
-{
- printf("hello, world\n");
-}</programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Callouts</title>
-
- <para>A callout is a mechanism for referring back to an earlier piece
- of text or specific position within an earlier example without
- linking to it within the text.</para>
-
- <para>To do this, mark areas of interest in your example
- (<sgmltag>programlisting</sgmltag>,
- <sgmltag>literallayout</sgmltag>, or whatever) with the
- <sgmltag>co</sgmltag> element. Each element must have a unique
- <literal>id</literal> assigned to it. After the example include a
- <sgmltag>calloutlist</sgmltag> that refers back to the example and
- provides additional commentary.</para>
-
- <example>
- <title><sgmltag>co</sgmltag> and
- <sgmltag>calloutlist</sgmltag></title>
-
- <programlisting><![ CDATA[<para>When you have finished, your program should look like
- this;</para>
-
-<programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
-
-int <co id="co-ex-return">
-main(void)
-{
- printf("hello, world\n"); <co id="co-ex-printf">
-}</programlisting>
-
-<calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns an
- int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard output.</para>
- </callout>
-</calloutlist>]]></programlisting>
-
- <para>Appearance:</para>
-
- <para>When you have finished, your program should look like
- this;</para>
-
- <programlisting>#include &lt;stdio.h&gt; <co id="co-ex-include">
-
-int <co id="co-ex-return">
-main(void)
-{
- printf("hello, world\n"); <co id="co-ex-printf">
-}</programlisting>
-
- <calloutlist>
- <callout arearefs="co-ex-include">
- <para>Includes the standard IO header file.</para>
- </callout>
-
- <callout arearefs="co-ex-return">
- <para>Specifies that <function>main()</function> returns an
- int.</para>
- </callout>
-
- <callout arearefs="co-ex-printf">
- <para>The <function>printf()</function> call that writes
- <literal>hello, world</literal> to standard output.</para>
- </callout>
- </calloutlist>
- </example>
- </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>&lt;informaltable
- frame="none"&gt;</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>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>&amp;prompt.root;</literal> and
- <literal>&amp;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>&amp;prompt.root;</literal> and
- <literal>&amp;prompt.user;</literal> as necessary. They do
- not need to be inside <sgmltag>prompt</sgmltag>.</para>
-
- <note>
- <para><literal>&amp;prompt.root;</literal> and
- <literal>&amp;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>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and
- <sgmltag>userinput</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![ CDATA [<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>]]></programlisting>
-
- <para>Appearance:</para>
-
- <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>
- </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 its manual
- section number, in the &ldquo;command(number)&rdquo; 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 its 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="sgml-primer-general-entities">general entities</link>
- have been created to make this easier. Each entity takes the form
- <literal>&amp;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>&lt;!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
-
-&lt;!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"&gt;
-%man;
-
-&hellip;
-
-]&gt;</programlisting>
-
- <para>Use <sgmltag>command</sgmltag> when you want to include a
- command name &ldquo;in-line&rdquo; 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.mailq.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>&amp;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="ip6addr"</literal></term>
-
- <listitem>
- <para>The text is an IPv6 address.</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 &ldquo;literal&rdquo; 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 &ldquo;in-line&rdquo; 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>Images</title>
-
- <important>
- <para>Image support in the documentation is currently extremely
- experimental. I think the mechanisms described here are unlikely to
- change, but that's not guaranteed.</para>
-
- <para>You will also need to install the
- <filename>graphics/ImageMagick</filename> port, which is used to
- convert between the different image formats. This is a big port,
- and most of it is not required. However, while we're working on the
- <filename>Makefile</filename>s and other infrastructure it makes
- things easier. This port is <emphasis>not</emphasis> in the
- <filename>textproc/docproj</filename> meta port, you must install it
- by hand.</para>
-
- <para>The best example of what follows in practice is the
- <filename>en_US.ISO_8859-1/articles/vm-design/</filename> document.
- If you're unsure of the description that follows, take a look at the
- files in that directory to see how everything hangs togther.
- Experiment with creating different formatted versions of the
- document to see how the image markup appears in the formatted
- output.</para>
- </important>
-
- <sect3>
- <title>Image formats</title>
-
- <para>We currently support two formats for images. The format you
- should use will depend on the nature of your image.</para>
-
- <para>For images that are primarily vector based, such as network
- diagrams, timelines, and similar, use Encapsulated Postscript, and
- make sure that your images have the <filename>.eps</filename>
- extension.</para>
-
- <para>For bitmaps, such as screen captures, use the Portable Network
- Graphic format, and make sure that your images have the
- <filename>.png</filename> extension.</para>
-
- <para>These are the <emphasis>only</emphasis> formats in which images
- should be committed to the CVS repository.</para>
-
- <para>Use the right format for the right image. It is to be expected
- that your documentation will have a mix of EPS and PNG images. The
- <filename>Makefile</filename>s ensure that the correct format image
- is chosen depending on the output format that you use for your
- documentation. <emphasis>Do not commit the same image to the
- repository in two different formats</emphasis>.</para>
-
- <important>
- <para>It is anticipated that the Documentation Project will switch to
- using the Scalable Vector Graphic (SVG) format for vector images.
- However, the current state of SVG capable editing tools makes this
- impractical.</para>
- </important>
- </sect3>
-
- <sect3>
- <title>Markup</title>
-
- <para>The markup for an image is relatively simple. First, markup a
- <sgmltag>mediaobject</sgmltag>. The <sgmltag>mediaobject</sgmltag>
- can contain other, more specific objects. We are concerned with
- two, the <sgmltag>imageobject</sgmltag> and the
- <sgmltag>textobject</sgmltag>.</para>
-
- <para>You should include one <sgmltag>imageobject</sgmltag>, and two
- <sgmltag>textobject</sgmltag> elements. The
- <sgmltag>imageobject</sgmltag> will point to the name of the image
- file that will be used (without the extension). The
- <sgmltag>textobject</sgmltag> elements contain information that will
- be presented to the user as well as, or instead of, the
- image.</para>
-
- <para>There are two circumstances where this can happen.</para>
-
- <itemizedlist>
- <listitem>
- <para>When the reader is viewing the documentation in HTML. In
- this case, each image will need to have associated alternate
- text to show the user, typically whilst the image is loading, or
- if they hover the mouse pointer over the image.</para>
- </listitem>
-
- <listitem>
- <para>When the reader is viewing the documentation in plain text.
- In this case, each image should have an ASCII art equivalent to
- show the user.</para>
- </listitem>
- </itemizedlist>
-
- <para>An example will probably make things easier to understand.
- Suppose you have an image, called <filename>fig1</filename>, that
- you want to include in the document. This image is of a rectangle
- with an A inside it. The markup for this would be as
- follows.</para>
-
- <programlisting>&lt;mediaobject>
- &lt;imageobject>
- &lt;imagedata fileref="fig1"> <co id="co-image-ext">
- &lt;/imageobject>
-
- &lt;textobject>
- &lt;literallayout class="monospaced">+---------------+ <co id="co-image-literal">
-| A |
-+---------------+&lt;/literallayout>
- &lt;/textobject>
-
- &lt;textobject>
- &lt;phrase>A picture&lt;/phrase> <co id="co-image-phrase">
- &lt;/textobject>
-&lt;/mediaobject></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-ext">
- <para>Include an <sgmltag>imagedata</sgmltag> element inside the
- <sgmltag>imageobject</sgmltag> element. The
- <literal>fileref</literal> attribute should contain the filename
- of the image to include, without the extension. The stylesheets
- will work out which extension should be added to the filename
- automatically.</para>
- </callout>
-
- <callout arearefs="co-image-literal">
- <para>The first <sgmltag>textobject</sgmltag> should contain a
- <sgmltag>literallayout</sgmltag> element, where the
- <literal>class</literal> attribute is set to
- <literal>monospaced</literal>. This is your opportunity to
- demonstrate your ASCII art skills. This content will be used if
- the document is converted to plain text.</para>
-
- <para>Notice how the first and last lines of the content of the
- <sgmltag>literallayout</sgmltag> element butt up next to the
- element's tags. This ensures no extraneous white space is
- included.</para>
- </callout>
-
- <callout arearefs="co-image-phrase">
- <para>The second <sgmltag>textobject</sgmltag> should contain a
- single <sgmltag>phrase</sgmltag> element. The contents of this
- will become the <literal>alt</literal> attribute for the image
- when this document is converted to HTML.</para>
- </callout>
- </calloutlist>
- </sect3>
-
- <sect3>
- <title><filename>Makefile</filename> entries</title>
-
- <para>Your images must be listed in the
- <filename>Makefile</filename> in the <makevar>IMAGES</makevar>
- variable. This variable should contain the name of all your
- <emphasis>source</emphasis> images. For example, if you have
- created three figures, <filename>fig1.eps</filename>,
- <filename>fig2.png</filename>, <filename>fig3.png</filename>, then
- your <filename>Makefile</filename> should have lines like this in
- it.</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps fig2.png fig3.png
-&hellip;</programlisting>
-
- <para>or</para>
-
- <programlisting>&hellip;
-IMAGES= fig1.eps
-IMAGES+= fig2.png
-IMAGES+= fig3.png
-&hellip;</programlisting>
-
- <para>Again, the <filename>Makefile</filename> will work out the
- complete list of images it needs to build your source document, you
- only need to list the image files <emphasis>you</emphasis>
- provided.</para>
- </sect3>
-
- <sect3>
- <title>Images and chapters in subdirectories</title>
-
- <para>You must be careful when you separate your documentation in to
- smaller files (see <xref linkend="sgml-primer-include-using-gen-entities">) in
- different directories.</para>
-
- <para>Suppose you have a book with three chapters, and the chapters
- are stored in their own directories, called
- <filename>chapter1/chapter.sgml</filename>,
- <filename>chapter2/chapter.sgml</filename>, and
- <filename>chapter3/chapter.sgml</filename>. If each chapter has
- images associated with it, I suggest you place those images in each
- chapter's subdirectory (<filename>chapter1/</filename>,
- <filename>chapter2/</filename>, and
- <filename>chapter3/</filename>).</para>
-
- <para>However, if you do this you must include the directory names in
- the <makevar>IMAGES</makevar> variable in the
- <filename>Makefile</filename>, <emphasis>and</emphasis> you must
- include the directory name in the <sgmltag>imagedata</sgmltag>
- element in your document.</para>
-
- <para>For example, if you have <filename>chapter1/fig1.png</filename>,
- then <filename>chapter1/chapter.sgml</filename> should
- contain</para>
-
- <programlisting>&lt;mediaobject>
- &lt;imageobject>
- &lt;imagedata fileref="chapter1/fig1"> <co id="co-image-dir">
- &lt;/imageobject>
-
- &hellip;
-
-&lt;/mediaobject></programlisting>
-
- <calloutlist>
- <callout arearefs="co-image-dir">
- <para>The directory name must be included in the
- <literal>fileref</literal> attribute</para>
- </callout>
- </calloutlist>
-
- <para>The <filename>Makefile</filename> must contain</para>
-
- <programlisting>&hellip;
-IMAGES= chapter1/fig1.png
-&hellip;</programlisting>
-
- <para>Then everything should just work.</para>
- </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 occurred 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
- &ldquo;this&rdquo; or &ldquo;here&rdquo; 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://www.linuxdoc.org/">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:
--->
-