diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/Makefile | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/book.xml | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/chapters.ent | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml | 2248 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml | 5 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml | 2759 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml | 613 |
7 files changed, 2870 insertions, 2764 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile index 60eaeea096..88291309b9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -23,7 +23,8 @@ SRCS= book.xml SRCS+= overview/chapter.xml SRCS+= psgml-mode/chapter.xml SRCS+= see-also/chapter.xml -SRCS+= sgml-markup/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml SRCS+= sgml-primer/chapter.xml SRCS+= stylesheets/chapter.xml SRCS+= structure/chapter.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml index 3d7fd3fdc0..af5dcffcac 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -248,7 +248,8 @@ Password:</screen></entry> &chap.overview; &chap.tools; &chap.xml-primer; - &chap.xml-markup; + &chap.xhtml-markup; + &chap.docbook-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent index 37c1e4f805..14b1677f56 100644 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -13,7 +13,8 @@ <!ENTITY chap.overview SYSTEM "overview/chapter.xml"> <!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml"> <!ENTITY chap.tools SYSTEM "tools/chapter.xml"> -<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml"> +<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> +<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> <!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> <!ENTITY chap.structure SYSTEM "structure/chapter.xml"> <!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml new file mode 100644 index 0000000000..a2e014fef5 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -0,0 +1,2248 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- 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$ +--> + +<chapter id="docbook-markup"> + <title>DocBook Markup</title> + + <sect1 id="docbook-markup-introduction"> + <title>Introduction</title> + + <para>This chapter is an introduction to DocBook as it is used for + &os; documentation. DocBook is a large and complex markup + system, but the subset described here covers the parts that are + most widely used for &os; documentation. While a moderate + subset is covered, it is impossible to anticipate every + situation. Please post questions that this document does + not answer to the &a.doc;.</para> + + <para>DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a <acronym>DTD</acronym> for + writing technical documentation <footnote><para>A short history + can be found under <ulink + url="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> + http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>. + Since 1998 it is maintained by the <ulink + url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</ulink>. As such, and unlike + LinuxDoc and <acronym>XHTML</acronym>, 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> + + <para>The DocBook <acronym>DTD</acronym> is available from the + Ports Collection in the + <filename role="package">textproc/docbook-xml-450</filename> + port. It is automatically installed as part of the + <filename role="package">textproc/docproj</filename> + port.</para> + + <note> + <title>Formal Versus Informal</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 informal version of the element. The + informal version will not have a title.</para> + </note> + + <note> + <title>Inline Versus 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> + + <sect1 id="docbook-markup-freebsd-extensions"> + <title>&os; Extensions</title> + + <para>The &os; Documentation Project has extended the + DocBook <acronym>DTD</acronym> by adding some new elements. + These elements serve to make some of the markup more + precise.</para> + + <para>Where a &os;-specific element is listed below, it is + clearly marked.</para> + + <para>Throughout the rest of this document, the term + <quote>DocBook</quote> is used to mean the &os;-extended + DocBook <acronym>DTD</acronym>.</para> + + <note> + <para>There is nothing about these extensions that is &os; + 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 + &a.doceng;.</para> + </note> + + <para>The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as <ulink + url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para> + </sect1> + + <sect1 id="docbook-markup-fpi"> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing + <acronym>FPI</acronym>s for DocBook customizations, the + <acronym>FPI</acronym> for the &os; extended DocBook + <acronym>DTD</acronym> is:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect1> + + <sect1 id="docbook-markup-document-structure"> + <title>Document Structure</title> + + <para>DocBook allows structuring documentation in several ways. + The &os; Documentation Project uses two primary types of DocBook + document: the book and the article.</para> + + <para>Books are organized 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 organization. For example, 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 organized 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>The nature of the document being written should be used to + determine 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="&url.base;/docs.html">&os; tutorials</ulink> + are all marked up as articles, while this + document, the + <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>, + and the <ulink url="&url.books.handbook;/index.html">FreeBSD + Handbook</ulink> are all marked up as books, for + example.</para> + + <sect2 id="docbook-markup-starting-a-book"> + <title>Starting a Book</title> + + <para>The content of a 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 is contained within + <sgmltag>bookinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>book</sgmltag> with + <sgmltag>bookinfo</sgmltag></title> + + <!-- Cannot 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 email address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect2> + + <sect2 id="docbook-markup-starting-an-article"> + <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 is contained within + <sgmltag>articleinfo</sgmltag>.</para> + + <example> + <title>Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>articleinfo</sgmltag></title> + + <!-- Cannot put this in a marked section because of the + replaceable elements --> + + <programlisting><article> + <articleinfo> + <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 email address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> + </abstract> + </articleinfo> + + … + +</article></programlisting> + </example> + </sect2> + + <sect2 id="docbook-markup-indicating-chapters"> + <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> + </sect2> + + <sect2 id="docbook-markup-sections-below-chapters"> + <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><![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> + + <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 by the stylesheets (of + which more later), and you do not need to manage them + yourself.</para> + </note> + </sect2> + + <sect2 id="docbook-markup-subdividing-part"> + <title>Subdividing Using <sgmltag>part</sgmltag> + Elements</title> + + <para><sgmltag>part</sgmltag>s introduce another level of + organization 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> + </sect2> + </sect1> + + <sect1 id="docbook-markup-block-elements"> + <title>Block Elements</title> + + <sect2 id="docbook-markup-paragraphs"> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs: + <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and + <sgmltag>simpara</sgmltag>.</para> + + <para>Almost all paragraphs in &os; documentation 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>Usage:</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> + </sect2> + + <sect2 id="docbook-markup-block-quotations"> + <title>Block Quotations</title> + + <para>A block quotation is an extended quotation from another + document that should not appear within the current + paragraph. These are rarely needed.</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>Usage:</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> + + <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> + </example> + </sect2> + + <sect2 id="docbook-markup-tips-notes"> + <title>Tips, Notes, Warnings, Cautions, Important Information + and Sidebars</title> + + <para>Extra information may need to be separated from + the main body of the text. Typically this is + <quote>meta</quote> information of which the user should be + aware.</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 loosely defined by the DocBook + documentation, which 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>Usage:</para> + + <programlisting><![CDATA[<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + hard disk.</para> +</warning>]]></programlisting> + </example> + + <para>Appearance:</para> + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows + from your hard disk.</para> + </warning> + </sect2> + + <sect2 id="docbook-markup-lists-and-procedures"> + <title>Lists and Procedures</title> + + <para>Information often needs to be presented as lists, or as a + number of steps that must be carried out in order to + accomplish a particular goal.</para> + + <para>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 are not + concerned with those at the + moment.</para></footnote></para> + + <para><sgmltag>itemizedlist</sgmltag> and + <sgmltag>orderedlist</sgmltag> are similar to their + counterparts in <acronym>HTML</acronym>, <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 + analogous to <acronym>HTML</acronym>'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>Usage:</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> + + <!-- Cannot 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> + </sect2> + + <sect2 id="docbook-markup-showing-file-samples"> + <title>Showing File Samples</title> + + <para>Fragments of a file (or perhaps a complete file) are shown + by wrapping them 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>Usage:</para> + + <programlisting><![CDATA[<para>When finished, the program will 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 finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + </sect2> + + <sect2 id="docbook-markup-callouts"> + <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 the 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 finished, the program will look like + this:</para> + +<programlisting>#include <stdio.h> <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 finished, the program will look like this:</para> + + <programlisting>#include <stdio.h> <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> + </sect2> + + <sect2 id="docbook-markup-tables"> + <title>Tables</title> + + <para>Unlike <acronym>HTML</acronym>, DocBook does not need + tables for layout purposes, as the stylesheet handles those + issues. 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 there is 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>Usage:</para> + + <programlisting><![CDATA[<informaltable pgwide="1"> + <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 pgwide="1"> + <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>Always use the <literal>pgwide</literal> attribute with + a value of <literal>1</literal> with the + <sgmltag>informaltable</sgmltag> element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted.</para> + + <para>Table borders can be suppressed by setting the + <literal>frame</literal> attribute to <literal>none</literal> + in the <sgmltag>informaltable</sgmltag> element. For example, + <literal><informaltable frame="none"></literal>.</para> + + <example> + <title>Tables Where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none" pgwide="1"> + <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> + </sect2> + + <sect2 id="docbook-markup-examples"> + <title>Examples for the User to Follow</title> + + <para>Examples for the user to follow are often necessary. + Typically, these will consist of dialogs with the computer; + the user types in a command, the user gets a response back, + the user types another command, and so on.</para> + + <para>A number of distinct elements and entities come into + 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>&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 + operating system, 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. 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 &os; + extensions to DocBook, and are not part of the + original <acronym>DTD</acronym>.</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 + be displayed differently than system output text.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, + and <sgmltag>userinput</sgmltag></title> + + <para>Usage:</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> + </sect2> + </sect1> + + <sect1 id="docbook-markup-inline-elements"> + <title>In-line Elements</title> + + <sect2 id="docbook-markup-inline-emphasizing"> + <title>Emphasizing Information</title> + + <para>To emphasize 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 the document, no equivalent of + <acronym>HTML</acronym>'s <sgmltag>b</sgmltag> and + <sgmltag>i</sgmltag>. If the information being presented is + important, then consider presenting it in + <sgmltag>important</sgmltag> rather than + <sgmltag>emphasis</sgmltag>.</para> + + <example> + <title><sgmltag>emphasis</sgmltag></title> + + <para>Usage:</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> + </sect2> + + <sect2 id="docbook-markup-quotations"> + <title>Quotations</title> + + <para>To quote text from another document or source, or to + denote a phrase that is used figuratively, use + <sgmltag>quote</sgmltag>. Most of the markup tags available + for normal text are also available from within a + <sgmltag>quote</sgmltag>.</para> + + <example> + <title>Quotations</title> + + <para>Usage:</para> + + <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the + <quote>boundary between local and public administration</quote>, + as RFC 1535 calls it.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>However, make sure that the search does not go beyond + the <quote>boundary between local and public + administration</quote>, as RFC 1535 calls it.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-keys"> + <title>Keys, Mouse Buttons, and Combinations</title> + + <para>To refer to a specific key on the keyboard, use + <sgmltag>keycap</sgmltag>. To refer to a mouse button, use + <sgmltag>mousebutton</sgmltag>. And to refer to + combinations of key presses or mouse clicks, wrap them all + in <sgmltag>keycombo</sgmltag>.</para> + + <para><sgmltag>keycombo</sgmltag> has an attribute called + <literal>action</literal>, which may be one of + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal>, or <literal>simul</literal>. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously.</para> + + <para>The stylesheets automatically add any connecting + symbols, such as <literal>+</literal>, between the key + names, when wrapped in <sgmltag>keycombo</sgmltag>.</para> + + <example> + <title>Keys, Mouse Buttons, and Combinations</title> + + <para>Usage:</para> + + <programlisting><![CDATA[<para>To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + +<para>To exit <command>vi</command> without saving changes, type + <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap> + <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> + +<para>My window manager is configured so that + <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>right</mousebutton> + </keycombo> mouse button is used to move windows.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + + <para>To exit <command>vi</command> without saving changes, + type <keycombo action="seq"> + <keycap>Esc</keycap> + <keycap>:</keycap> + <keycap>q</keycap> + <keycap>!</keycap></keycombo>.</para> + + <para>My window manager is configured so that + <keycombo action="simul"> + <keycap>Alt</keycap> + <mousebutton>right</mousebutton></keycombo> mouse button + is used to move windows.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-applications"> + <title>Applications, Commands, Options, and Cites</title> + + <para>Both applications and commands are frequently referred to + when writing documentation. The distinction between them is + that an application is the name of a program or suite of + programs that fulfill a particular task. A command is the + filename of a program that the user can type and run at a + command line.</para> + + <para>It is often necessary to show some of the options that a + command might take.</para> + + <para>Finally, it is often useful to list a command with its + manual section number, in the <quote>command(number)</quote> + format so common in Unix manuals.</para> + + <para>Mark up application names with + <sgmltag>application</sgmltag>.</para> + + <para>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="xml-primer-general-entities">general + entities</link> have been created to make this easier. + Each entity takes the form + <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/xml/man-refs.ent</filename>, and can be + referred to using this <acronym>FPI</acronym>:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to &os; documentation will + usually include this:</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para>Use <sgmltag>command</sgmltag> when to include a command + name <quote>in-line</quote> but present it as something the + user should type in.</para> + + <para>Use <sgmltag>option</sgmltag> to mark up the options + which will be passed to a command.</para> + + <para>When referring to the same command multiple times in + close proximity, it is preferred to use the + <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + notation to markup the first reference and use + <sgmltag>command</sgmltag> to markup subsequent references. + This makes the generated output, especially + <acronym>HTML</acronym>, appear visually better.</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>Usage:</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.1;, and &man.newaliases.1; + 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>, &man.mailq.1;, and &man.newaliases.1; + 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> + </sect2> + + <sect2 id="docbook-markup-files"> + <title>Files, Directories, Extensions</title> + + <para>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>Usage:</para> + + <programlisting><![CDATA[<para>The XML source for the Handbook in English is + found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first + file is called <filename>book.xml</filename> in that + directory. There is also a <filename>Makefile</filename> + and a number of files with a <filename>.ent</filename> + extension.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The XML source for the Handbook in English can be + found in <filename>/usr/doc/en/handbook/</filename>. The + first file is called <filename>handbook.xml</filename> in + that directory. There is also a + <filename>Makefile</filename> and a number of files with a + <filename>.ent</filename> extension.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-name-of-ports"> + <title>The Name of Ports</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>To include the name of a program from the &os; + Ports Collection in the document, use the + <sgmltag>filename</sgmltag> tag with the + <literal>role</literal> attribute set to + <literal>package</literal>. Since ports can be installed in + any number of locations, only include the category and the + port name; do not include + <filename>/usr/ports</filename>.</para> + + <example> + <title><sgmltag>filename</sgmltag> Tag with + <literal>package</literal> Role</title> + + <para>Usage:</para> + + <programlisting><![CDATA[<para>Install the <filename role="package">net/wireshark</filename> port to view network traffic.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Install the <filename + role="package">net/wireshark</filename> port to view + network traffic.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-devices"> + <title>Devices</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>There are two names for devices: the device name as it + appears in <filename>/dev</filename>, or the name of the + device as it appears in the kernel. For this latter course, + use <sgmltag>devicename</sgmltag>.</para> + + <para>Sometimes there is no choice. Some devices, such as + network cards, do not have entries in + <filename>/dev</filename>, or the entries are markedly + different from their kernel device names.</para> + + <example> + <title><sgmltag>devicename</sgmltag></title> + + <para>Usage:</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, network 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>]]></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, network 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> + </sect2> + + <sect2 id="docbook-markup-hosts"> + <title>Hosts, Domains, IP Addresses, and So Forth</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>Identification information for networked computers (hosts) + can be marked up 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 <literal>role</literal> attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no <literal>role</literal> 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>. The hostname can be + explicitly specified 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 <acronym>IP</acronym> address, + probably expressed as a dotted quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ip6addr"</literal></term> + + <listitem> + <para>The text is an <acronym>IPv6</acronym> + 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 + (<acronym>CIDR</acronym> notation).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an Ethernet <acronym>MAC</acronym> + address, expressed as a series of 2 digit hexadecimal + numbers separated by colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><sgmltag>hostid</sgmltag> and Roles</title> + + <para>Usage:</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 <acronym>IP</acronym> 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 <acronym>MAC</acronym> address uniquely identifies + every network card in existence. A typical + <acronym>MAC</acronym> 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 <acronym>IP</acronym> 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 <acronym>MAC</acronym> address uniquely identifies + every network card in existence. A typical + <acronym>MAC</acronym> address looks like + <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-usernames"> + <title>Usernames</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</para> + </note> + + <para>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>Usage:</para> + + <programlisting><![CDATA[<para>To carry out most system administration functions + requires logging in as <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions + requires logging in as <username>root</username>.</para> + </example> + </sect2> + + <sect2 id="docbook-markup-describing-makefiles"> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the &os; extension to + DocBook, and do not exist in the original DocBook + <acronym>DTD</acronym>.</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>Usage:</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> + </sect2> + + <sect2 id="docbook-markup-literal-text"> + <title>Literal Text</title> + + <para>Literal text, or text which should be entered verbatim, is + often needed in documentation. This is text that is excerpted + from another file, or which should be copied exactly as shown + from the documentation into another file.</para> + + <para>Some of the time, <sgmltag>programlisting</sgmltag> will + be sufficient to denote this text. But + <sgmltag>programlisting</sgmltag> is not always appropriate, + particularly when you want to include a portion of a file + <quote>in-line</quote> with the rest of the + paragraph.</para> + + <para>On these occasions, use + <sgmltag>literal</sgmltag>.</para> + + <example> + <title><sgmltag>literal</sgmltag></title> + + <para>Usage:</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> + </sect2> + + <sect2 id="docbook-markup-replaceable"> + <title>Showing Items That the User <emphasis>Must</emphasis> + Fill In</title> + + <para>There will often be times when the user is shown + what to do, or referred to a file or command line, but + cannot simply copy the example provided. Instead, they + must supply 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>Usage:</para> + + <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></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>Usage:</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> + </sect2> + + <sect2 id="docbook-markup-system-errors"> + <title>Quoting System Errors</title> + + <para>System errors generated by &os; are marked with + <sgmltag>errorname</sgmltag>. This indicates the exact error + that appears.</para> + + <example> + <title><sgmltag>errorname</sgmltag></title> + + <para>Usage:</para> + + <programlisting><![CDATA[<screen><errorname>Panic: cannot mount root</errorname></screen>]]></programlisting> + + + <para>Appearance:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect2> + </sect1> + + <sect1 id="docbook-markup-images"> + <title>Images</title> + + <important> + <para>Image support in the documentation is currently + extremely experimental. The mechanisms described here are + unlikely to change, but that is not guaranteed.</para> + + <para>Installation of the + <filename role="package">graphics/ImageMagick</filename> + port is required. It is used to convert between the different + image formats. This port is <emphasis>not</emphasis> in + the <filename role="package">textproc/docproj</filename> meta + port, it must be installed by hand.</para> + + <para>The best example of what follows in practice is the + <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> + document. If the description that follows is unclear, take a + look at the files in that directory to see how everything + hangs together. Experiment with creating different formatted + versions of the document to see how the image markup appears + in the formatted output.</para> + </important> + + <sect2 id="docbook-markup-image-formats"> + <title>Image Formats</title> + + <para>Two image formats are currently supported. Which to + choose will depend on the nature of the image.</para> + + <para>Images that are primarily vector based, such as network + diagrams, time lines, and similar, should be in + <acronym>EPS</acronym> (Encapsulated Postscript) format. + These images have a <filename>.eps</filename> + extension.</para> + + <para>For bitmaps, such as screen captures, use the + <acronym>PNG</acronym> (Portable Network Graphic) format. + These images have the <filename>.png</filename> + extension.</para> + + <para>These are the <emphasis>only</emphasis> formats in which + images should be committed to the Subversion + repository.</para> + + <para>Use the appropriate format for each image. It is to be + expected that documentation will have a mix of + <acronym>EPS</acronym> and <acronym>PNG</acronym> 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 <acronym>SVG</acronym> (Scalable Vector + Graphic) format for vector images. However, the current + state of <acronym>SVG</acronym> capable editing tools makes + this impractical.</para> + </important> + </sect2> + + <sect2 id="docbook-markup-image-markup"> + <title>Image 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>Include one <sgmltag>imageobject</sgmltag>, + and two <sgmltag>textobject</sgmltag> elements. The + <sgmltag>imageobject</sgmltag> will point to the name of the + image file (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 itself.</para> + + <para>There are two circumstances where this can + happen.</para> + + <itemizedlist> + <listitem> + <para>When the reader is viewing the documentation in + <acronym>HTML</acronym>. In this case, each image will + need associated alternate text to show the user, typically + while 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 + <acronym>ASCII</acronym> art equivalent to show the + user.</para> + + </listitem> + </itemizedlist> + + <para>An example will make things easier to understand. Suppose + there is an image called <filename>fig1.png</filename> that is + to be included in the document. This image is of a rectangle + with an A inside it. The markup for this would be as + follows.</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="fig1"> <co id="co-image-ext"/> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ <co id="co-image-literal"/> +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> <co id="co-image-phrase"/> + </textobject> +</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> contains a + <sgmltag>literallayout</sgmltag> element, where the + <literal>class</literal> attribute is set to + <literal>monospaced</literal>. This is an opportunity to + demonstrate <acronym>ASCII</acronym> 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> contains a + single <sgmltag>phrase</sgmltag> element. The contents of + this phrase will become the <literal>alt</literal> + attribute for the image when this document is converted to + <acronym>HTML</acronym>.</para> + </callout> + </calloutlist> + </sect2> + + <sect2 id="docbook-markup-image-makefile-entries"> + <title>Image <filename>Makefile</filename> Entries</title> + + <para>Images must be listed in the <filename>Makefile</filename> + in the <makevar>IMAGES</makevar> variable. This variable must + contain the names of all the <emphasis>source</emphasis> + images. For example, if there are three figures, + <filename>fig1.eps</filename>, <filename>fig2.png</filename>, + <filename>fig3.png</filename>, then the + <filename>Makefile</filename> should have lines like this in + it.</para> + + <programlisting>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>or</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para>Again, the <filename>Makefile</filename> will work out + the complete list of images it needs to build the source + document, you only need to list the image files + <emphasis>you</emphasis> provided.</para> + </sect2> + + <sect2 id="docbook-markup-images-in-subdirectories"> + <title>Images and Chapters in Subdirectories</title> + + <para>Be careful when separating documentation into smaller + files in different directories (see <xref + linkend="xml-primer-include-using-gen-entities"/>).</para> + + <para>Suppose there is a book with three chapters, and the + chapters are stored in their own directories, called + <filename>chapter1/chapter.xml</filename>, + <filename>chapter2/chapter.xml</filename>, and + <filename>chapter3/chapter.xml</filename>. If each chapter + has images associated with it, it is suggested to place + those images in each chapter's subdirectory + (<filename>chapter1/</filename>, + <filename>chapter2/</filename>, and + <filename>chapter3/</filename>).</para> + + <para>However, doing this requires including the directory + names in the <makevar>IMAGES</makevar> variable in the + <filename>Makefile</filename>, <emphasis>and</emphasis> + including the directory name in the + <sgmltag>imagedata</sgmltag> element in the document + document.</para> + + <para>For example, if the book has + <filename>chapter1/fig1.png</filename>, then + <filename>chapter1/chapter.xml</filename> should + contain:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/> + </imageobject> + + … + +</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>… +IMAGES= chapter1/fig1.png +…</programlisting> + + <para>Then everything will work.</para> + </sect2> + </sect1> + + <sect1 id="docbook-markup-links"> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect2 id="docbook-markup-links-ids"> + <title><literal>id</literal> Attributes</title> + + <para>Most DocBook elements accept an <literal>id</literal> + attribute to give that part of the document a unique name. + The <literal>id</literal> can be used as a target for a + crossreference or link.</para> + + <para>Any portion of the document that will be a link target + must have an <literal>id</literal> attribute. Assigning an + <literal>id</literal> to all chapters and sections, even if + there are no current plans to link to them, is a good idea. + These <literal>id</literal>s can be used as unique anchor + reference points by anyone referring to the + <acronym>HTML</acronym> version of the document.</para> + + <example> + <title><literal>id</literal> on Chapters and + Sections</title> + + <programlisting><![CDATA[<chapter id="sample-chapter1"> + <title>Introduction</title> + + <para>This is the introduction. It contains a subsection, + which is identified as well.</para> + + <sect1 id="sample-chapter1-sect1"> + <title>Sub-sect 1</title> + + <para>This is a subsection.</para> + </sect1> +</chapter>]]></programlisting> + </example> + + <para>Use descriptive values for <literal>id</literal> names. + The values must be unique within the entire document, not just + in a single file. In the example, the subsection + <literal>id</literal> is constructed by appending text to the + chapter <literal>id</literal>. This ensures that the + <literal>id</literal>s are unique. It also helps both reader + and anyone editing the document to see where the link is + located within the document, similar to a directory + path to a file.</para> + + <para>To allow the user to jump into a specific portion of the + document, even 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 will not + show up in the document.</para>]]></programlisting> + </example> + </sect2> + + <sect2 id="docbook-markup-links-crossreferences"> + <title>Crossreferences with <literal>xref</literal></title> + + <para><sgmltag>xref</sgmltag> provides the reader with a link to + jump to another section of the document. The target + <literal>id</literal> is specified in the + <literal>linkend</literal> attribute, and + <sgmltag>xref</sgmltag> generates the link text + automatically.</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 link text will be generated automatically, looking + like (<emphasis>emphasized</emphasis> text indicates the + link text):</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + 1, The Sample Chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>Section 1.1, + <quote>Sample Sub-Sect</quote></emphasis>.</para> + </blockquote> + </example> + + <para>The link text is generated automatically from the chapter + and section number and <literal>title</literal> + elements.</para> + + <note> + <para><sgmltag>xref</sgmltag> cannot 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> cannot generate the link + text.</para> + </note> + </sect2> + + <sect2 id="docbook-markup-links-to-same-or-web-documents"> + <title>Linking to the Same Document or Other Documents on the + Web</title> + + <para>The link elements described here allow the writer to + define the link text. It is very important to use descriptive + link text to give the reader an idea of where the link will + take them. Remember that DocBook can be rendered to multiple + types of media. The reader may be looking at a printed book + or other form of media where there are no links. If the link + text is not descriptive enough, the reader may not be able to + locate the linked section.</para> + + <sect3 id="docbook-markup-links-to-same-document"> + <title>Links to the Same Document</title> + + <para><sgmltag>link</sgmltag> is used to create a link + within the same document. The target <literal>id</literal> + is specified in the <literal>linkend</literal> attribute. + This element wraps content, which is used for the link + text.</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 the + <link linkend="chapter1">sample chapter</link>.</para> + +<para>More specific information can be found in the + <link linkend="chapter1-sect1">even more samples</link> section.</para>]]></programlisting> + + <para>This output will be generated + (<emphasis>emphasized</emphasis> text is used to show the + link text):</para> + + <blockquote> + <para>More information can be found in the + <emphasis>sample chapter</emphasis>.</para> + + <para>More specific information can be found in the + <emphasis>even more samples</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para><sgmltag>link</sgmltag> can be used to include links + to the <literal>id</literal> of an + <sgmltag>anchor</sgmltag> element, since the + <sgmltag>link</sgmltag> content defines the link + text.</para> + </note> + </sect3> + + <sect3 id="docbook-markup-links-to-web-documents"> + <title>Linking to Other Documents on the Web</title> + + <para>The <sgmltag>ulink</sgmltag> is used to link to + external documents on the web. The <literal>url</literal> + attribute is the <acronym>URL</acronym> 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> to a &os; Documentation Web + Page</title> + + <para>Link to the book or article <acronym>URL</acronym> + entity. To link to a specific chapter in a book, add a + slash and the chapter file name, followed by an optional + anchor within the chapter. For articles, link to the + article <acronym>URL</acronym> entity, followed by an + optional anchor within the article. + <acronym>URL</acronym> entities can be found in + <filename>doc/share/xml/urls.ent</filename>.</para> + + <para>Usage for book links:</para> + + <programlisting><![CDATA[<para>Read the <ulink + url="&url.books.handbook;/svn.html#svn-intro">SVN + introduction</ulink>, then pick the nearest mirror from + the list of <ulink + url="&url.books.handbook;/subversion-mirrors.html">Subversion + mirror sites</ulink>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Read the <ulink + url="&url.books.handbook;/svn.html#svn-intro">SVN + introduction</ulink>, then pick the nearest mirror from + the list of <ulink + url="&url.books.handbook;/subversion-mirrors.html">Subversion + mirror sites</ulink>.</para> + + <para>Usage for article links:</para> + + <programlisting><![CDATA[<para>Read this <ulink url="&url.articles.bsdl-gpl;">article + about the BSD license</ulink>, or just the <ulink + url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Read this <ulink url="&url.articles.bsdl-gpl;">article + about the BSD license</ulink>, or just the <ulink + url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para> + </example> + + <example> + <title><sgmltag>ulink</sgmltag> to a &os; Web Page</title> + + <para>Usage:</para> + + <programlisting><![CDATA[<para>Of course, you could stop reading this document and + go to the <ulink url="&url.base;/index.html">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="&url.base;/index.html">FreeBSD home + page</ulink> instead.</para> + </example> + + <example> + <title><sgmltag>ulink</sgmltag> to an External Web + Page</title> + + <para>Usage:</para> + + <programlisting><![CDATA[<para>Wikipedia has an excellent reference on + <ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</ulink>.</para>]]></programlisting> + + <para>Wikipedia has an excellent reference on + <ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</ulink>.</para> + </example> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml index e1e15426fa..5ead068fd9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -211,7 +211,8 @@ to the tags which surround the text or the entities that represent that text in the <acronym>XML</acronym> file. A reference to the commonly used tags and entities can be - found in <xref linkend="xml-markup"/>.</para> + found in <xref linkend="xhtml-markup"/> and + <xref linkend="docbook-markup"/>.</para> </step> <step> @@ -291,4 +292,4 @@ </step> </procedure> </sect1> - </chapter>
\ No newline at end of file + </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml deleted file mode 100644 index 49626b5055..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml +++ /dev/null @@ -1,2759 +0,0 @@ -<?xml version="1.0" encoding="iso-8859-1"?> -<!-- 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$ ---> - -<chapter id="xml-markup"> - <title>XML Markup</title> - - <para>This chapter describes the two 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 &a.doc;.</para> - - <note> - <title>Inline Versus 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 id="xml-markup-xhtml"> - <title>XHTML</title> - - <para>XHTML is the XML version of the HyperText Markup Language, - which is the markup language - of choice on the World Wide Web. More information can be found - at <ulink url="http://www.w3.org/"></ulink>.</para> - - <para>XHTML is used to markup pages on the FreeBSD web site. It - should not (generally) be used to mark up other documentation, - since DocBook offers a far richer set of elements to choose - from. Consequently, you will normally only encounter XHTML 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, - 4.0 and then an XML-compliant version has also been created, which - is called XHTML and the latest widespread version of it is - XHTML 1.0(available in both - <emphasis>strict</emphasis> and <emphasis>transitional</emphasis> - variants).</para> - - <para>The XHTML DTDs are available from the Ports Collection - in the <filename role="package">textproc/xhtml</filename> port. - They are automatically installed as part of the <filename - role="package">textproc/docproj</filename> port.</para> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>There are a number of XHTML FPIs, depending upon the - version (also known as the level) of XHTML that you want to - declare your document to be compliant with.</para> - - <para>The majority of XHTML documents on the FreeBSD web site - comply with the transitional version of XHTML 1.0.</para> - - <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> - </sect2> - - <sect2> - <title>Sectional Elements</title> - - <para>An XHTML document is normally split into 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 XHTML Document Structure</title> - - <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> - <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>XHTML 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>, - and Other Header Tags</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 XHTML 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, preceding 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>XHTML 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 - preceded 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> - - <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><p>Paragraph 1 of definition 3.</p></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 into 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 - email message:</para> - - <programlisting><![CDATA[<pre> From: nik@FreeBSD.org - To: freebsd-doc@FreeBSD.org - Subject: New documentation available - - There is a new copy of my primer for contributors to the FreeBSD - Documentation Project available at - - <URL:http://people.FreeBSD.org/~nik/primer/index.html> - - Comments appreciated. - - N</pre>]]></programlisting> - - <para>Keep in mind that <literal><</literal> and - <literal>&</literal> still are recognized as special - characters in pre-formatted text. This is why the example - shown had to use <literal>&lt;</literal> instead of - <literal><</literal>. For consistency, - <literal>&gt;</literal> was used in place of - <literal>></literal>, too. Watch out for the special - characters that may appear in text copied from a - plain-text source, e.g., an email message or program - code.</para> - </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 or 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 into 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 into - 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>Emphasizing Information</title> - - <para>You have two levels of emphasis available in XHTML, - <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. According to best practices, webpages only hold - structural and semantical information and stylesheets are - later applied to use these two so you should think of - semantics not formatting when using these tags.</para> - - <example> - <title><sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><em>This</em> has been emphasized, while - <strong>this</strong> has been strongly emphasized.</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 - <quote>teletype</quote>).</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 email as - <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> - </example> - </sect3> - </sect2> - - <sect2> - <title>Links</title> - - <note> - <para>Links are also inline 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 color, 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>id</literal> attribute instead of - <literal>href</literal>.</para> - - <example> - <title>Using <literal><a id="..."></literal></title> - - <para>Use:</para> - - <programlisting><![CDATA[<p><a id="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 id 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 preceding - <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 id="xml-markup-docbook"> - <title>DocBook</title> - - <para>DocBook was originally developed by HaL Computer Systems and - O'Reilly & Associates to be a DTD for writing technical - documentation <footnote><para>A short history can be found under - <ulink - url="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> - http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>. - Since 1998 it is maintained by the <ulink - url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</ulink>. As such, and unlike - LinuxDoc and XHTML, 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>Formal Versus Informal</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 informal 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 role="package">textproc/docbook-xml-450</filename> - port. It is automatically installed as part of the <filename - role="package">textproc/docproj</filename> port.</para> - - <sect2> - <title>&os; 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 - <quote>DocBook</quote> 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 - &a.doceng;.</para> - </note> - - <para>The &os; extensions are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as <ulink - url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para> - </sect2> - - <sect2> - <title>Formal Public Identifier (FPI)</title> - - <para>In compliance with the DocBook guidelines for writing FPIs - for DocBook customizations, the FPI for the FreeBSD extended - DocBook DTD is:</para> - - <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-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 organized 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 organization. For example, 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 organized - 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="&url.base;/docs.html">FreeBSD - tutorials</ulink> are all marked up as articles, while this - document, the - <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>, - and the <ulink url="&url.books.handbook;/index.html">FreeBSD - Handbook</ulink> are all marked up as books, for - example.</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 email address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> - </abstract> - </bookinfo> - - … - -</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><article> - <articleinfo> - <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 email address</replaceable></email></address> - </affiliation> - </author> - - <copyright> - <year><replaceable>1998</replaceable></year> - <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> - </copyright> - - <releaseinfo>$FreeBSD$</releaseinfo> - - <abstract> - <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> - </abstract> - </articleinfo> - - … - -</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><![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> - - <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 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> - Elements</title> - - <para>You can introduce another layer of organization 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> - - <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> - </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 - <quote>meta</quote> 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 - hard disk.</para> -</warning>]]></programlisting> - </example> - - <para>Appearance:</para> - <!-- Need to do this outside of the example --> - <warning> - <para>Installing FreeBSD may make you want to delete Windows - from your hard disk.</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 are 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 - analogous 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 <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> - </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 <stdio.h> <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 <stdio.h> <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 pgwide="1"> - <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 pgwide="1"> - <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>Always use the <literal>pgwide</literal> attribute with - a value of <literal>1</literal> with the - <sgmltag>informaltable</sgmltag> element. A bug in Internet - Explorer can cause the table to render incorrectly if this - is omitted.</para> - - <para>If you do not 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" pgwide="1"> - <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 into - 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>&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 - operating system, 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>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>Emphasizing Information</title> - - <para>When you want to emphasize 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>Quotations</title> - - <para>To quote text from another document or source, or to - denote a phrase that is used figuratively, use - <sgmltag>quote</sgmltag>. Within a <sgmltag>quote</sgmltag> - tag, you may use most of the markup tags available for - normal text.</para> - - <example> - <title>Quotations</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the - <quote>boundary between local and public administration</quote>, - as RFC 1535 calls it.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>However, make sure that the search does not go beyond - the <quote>boundary between local and public - administration</quote>, as RFC 1535 calls it.</para> - </example> - </sect3> - - <sect3> - <title>Keys, Mouse Buttons, and Combinations</title> - - <para>To refer to a specific key on the keyboard, use - <sgmltag>keycap</sgmltag>. To refer to a mouse button, use - <sgmltag>mousebutton</sgmltag>. And to refer to - combinations of key presses or mouse clicks, wrap them all - in <sgmltag>keycombo</sgmltag>.</para> - - <para><sgmltag>keycombo</sgmltag> has an attribute called - <literal>action</literal>, which may be one of - <literal>click</literal>, <literal>double-click</literal>, - <literal>other</literal>, <literal>press</literal>, - <literal>seq</literal>, or <literal>simul</literal>. The - last two values denote whether the keys or buttons should be - pressed in sequence, or simultaneously.</para> - - <para>The stylesheets automatically add any connecting - symbols, such as <literal>+</literal>, between the key - names, when wrapped in <sgmltag>keycombo</sgmltag>.</para> - - <example> - <title>Keys, Mouse Buttons, and Combinations</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>To switch to the second virtual terminal, press - <keycombo action="simul"><keycap>Alt</keycap> - <keycap>F1</keycap></keycombo>.</para> - -<para>To exit <command>vi</command> without saving your work, type - <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap> - <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> - -<para>My window manager is configured so that - <keycombo action="simul"><keycap>Alt</keycap> - <mousebutton>right</mousebutton> - </keycombo> mouse button is used to move windows.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>To switch to the second virtual terminal, press - <keycombo action="simul"><keycap>Alt</keycap> - <keycap>F1</keycap></keycombo>.</para> - - <para>To exit <command>vi</command> without saving your - work, type <keycombo action="seq"> - <keycap>Esc</keycap> - <keycap>:</keycap> - <keycap>q</keycap> - <keycap>!</keycap></keycombo>.</para> - - <para>My window manager is configured so that - <keycombo action="simul"> - <keycap>Alt</keycap> - <mousebutton>right</mousebutton></keycombo> mouse button - is used to move windows.</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 documentation. The distinction - between them is simple: an application is the name for a - suite (or possibly just 1) of programs that fulfill 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 <quote>command(number)</quote> - 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="xml-primer-general-entities">general - entities</link> have been created to make this easier. - Each entity takes the form - <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> - - <para>The file that contains these entities is in - <filename>doc/share/xml/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 V4.1-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 <quote>in-line</quote> but present it as - something the user should type in.</para> - - <para>Use <sgmltag>option</sgmltag> to mark up the options - which will be passed to a command.</para> - - <para>When referring to the same command multiple times in - close proximity it is preferred to use the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> - notation to markup the first reference and use - <sgmltag>command</sgmltag> to markup subsequent references. - This makes the generated output, especially HTML, appear - visually better.</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.1;, and &man.newaliases.1; - 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>, &man.mailq.1;, and &man.newaliases.1; - 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 class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first - file is called <filename>book.xml</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.xml</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>The Name of Ports</title> - - <note> - <title>&os; 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 might need to include the name of a program from the - FreeBSD Ports Collection in the documentation. Use the - <sgmltag>filename</sgmltag> tag with the - <literal>role</literal> attribute set to - <literal>package</literal> to identify these. Since ports - can be installed in any number of locations, only include - the category and the port name; do not include - <filename>/usr/ports</filename>.</para> - - <example> - <title><sgmltag>filename</sgmltag> Tag with - <literal>package</literal> Role</title> - - <para>Use:</para> - - <programlisting><![CDATA[<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting> - - <para>Appearance:</para> - - <para>Install the <filename - role="package">net/ethereal</filename> port to view - network traffic.</para> - </example> - </sect3> - - <sect3> - <title>Devices</title> - - <note> - <title>&os; 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> - -<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>&os; 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 <literal>role</literal> attribute, or - <literal>role="hostname"</literal></term> - - <listitem> - <para>With no <literal>role</literal> 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 separated 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">pointyhat.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>]]></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>&os; 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>&os; 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 <quote>literal</quote> - text in the documentation. This is text that is excerpted - from another file, or which should be copied from the - documentation 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 - <quote>in-line</quote> 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 cannot 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[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></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> - - <sect3> - <title>Quoting System Errors</title> - - <para>You might want to show errors generated by FreeBSD. - Mark these with <sgmltag>errorname</sgmltag>. This - indicates the exact error that appears.</para> - - <example> - <title><sgmltag>errorname</sgmltag></title> - - <para>Use:</para> - - <programlisting><![CDATA[ -<screen><errorname>Panic: cannot mount root</errorname></screen> ]]> -</programlisting> - - - <para>Appearance:</para> - - <informalexample> - <screen><errorname>Panic: cannot mount root</errorname></screen> - </informalexample> - </example> - </sect3> - </sect2> - - <sect2> - <title>Images</title> - - <important> - <para>Image support in the documentation is currently - extremely experimental. The mechanisms described here are - unlikely to change, but that is not guaranteed.</para> - - <para>You will also need to install the - <filename role="package">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 are working on the - <filename>Makefile</filename>s and other infrastructure it - makes things easier. This port is <emphasis>not</emphasis> - in the <filename role="package">textproc/docproj</filename> - meta port, you must install it by hand.</para> - - <para>The best example of what follows in practice is the - <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> - document. If you are unsure of the description that - follows, take a look at the files in that directory to see - how everything hangs together. 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, time lines, 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 Subversion - 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.png</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><mediaobject> - <imageobject> - <imagedata fileref="fig1"> <co id="co-image-ext"/> - </imageobject> - - <textobject> - <literallayout class="monospaced">+---------------+ <co id="co-image-literal"/> -| A | -+---------------+</literallayout> - </textobject> - - <textobject> - <phrase>A picture</phrase> <co id="co-image-phrase"/> - </textobject> -</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>… -IMAGES= fig1.eps fig2.png fig3.png -…</programlisting> - - <para>or</para> - - <programlisting>… -IMAGES= fig1.eps -IMAGES+= fig2.png -IMAGES+= fig3.png -…</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 - into smaller files (see - <xref linkend="xml-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.xml</filename>, - <filename>chapter2/chapter.xml</filename>, and - <filename>chapter3/chapter.xml</filename>. If each chapter - has images associated with it, it is suggested to 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.xml</filename> should - contain:</para> - - <programlisting><mediaobject> - <imageobject> - <imagedata fileref="chapter1/fig1"> <co id="co-image-dir"/> - </imageobject> - - … - -</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>… -IMAGES= chapter1/fig1.png -…</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 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>Attribute <literal>id</literal> on Chapters and - Sections</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 will not 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>emphasized</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>cannot</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> cannot 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>emphasized</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 - <quote>this</quote> or <quote>here</quote> 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="&url.base;/index.html">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="&url.base;/index.html">FreeBSD home - page</ulink> instead.</para> - </example> - </sect3> - </sect2> - </sect1> -</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml new file mode 100644 index 0000000000..43e0f8adbe --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml @@ -0,0 +1,613 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- 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$ +--> + +<chapter id="xhtml-markup"> + <title><acronym>XHTML</acronym> Markup</title> + + <sect1 id="xhtml-markup-introduction"> + <title>Introduction</title> + + <para>This chapter describes usage of the <acronym>XHTML</acronym> + markup language used for the &os; web site.</para> + + <para><acronym>XHTML</acronym> is the <acronym>XML</acronym> + version of the HyperText Markup Language, the markup language of + choice on the World Wide Web. More information can be found at + <ulink url="http://www.w3.org/"></ulink>.</para> + + <para><acronym>XHTML</acronym> is used to mark up pages on the + &os; web site. It is usually not used to mark up other + documentation, since DocBook offers a far richer set of elements + from which to choose. Consequently, <acronym>XHTML</acronym> + pages will normally only be encountered when writing for the web + site.</para> + + <para><acronym>HTML</acronym> has gone through a number of + versions. The <acronym>XML</acronym>-compliant version + described here is called <acronym>XHTML</acronym>. The latest + widespread version is <acronym>XHTML</acronym> 1.0, available in + both <emphasis>strict</emphasis> and + <emphasis>transitional</emphasis> variants.</para> + + <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are + available from the Ports Collection in + <filename role="package">textproc/xhtml</filename>. They are + automatically installed as part of the <filename + role="package">textproc/docproj</filename> port.</para> + + <note> + <para>This is <emphasis>not</emphasis> an exhaustive list of + elements, since that would just repeat the documentation for + <acronym>XHTML</acronym>. The aim is to list those elements + most commonly used. Please post questions about elements or + uses not covered here to the &a.doc;.</para> + </note> + + <note> + <title>Inline Versus 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> + + <sect1 id="xhtml-markup-fpi"> + <title>Formal Public Identifier (<acronym>FPI</acronym>)</title> + + <para>There are a number of <acronym>XHTML</acronym> + <acronym>FPI</acronym>s, depending upon the version, or + <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which + a document conforms. Most XHTML documents on the FreeBSD web + site comply with the transitional version of + <acronym>XHTML</acronym> 1.0.</para> + + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> + </sect1> + + <sect1 id="xhtml-markup-sectional-elements"> + <title>Sectional Elements</title> + + <para>An <acronym>XHTML</acronym> document is normally split into + 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 <acronym>XHTML</acronym> Document + Structure</title> + + <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><replaceable>The Document's Title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect1> + + <sect1 id="xhtml-markup-block-elements"> + <title>Block Elements</title> + + <sect2 id="xhtml-markup-block-elements-headings"> + <title>Headings</title> + + <para><acronym>XHTML</acronym> has tags to denote headings in + the 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>, + and Other Header Tags</title> + + <para>Usage:</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 <acronym>XHTML</acronym> 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, preceding 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>Usage:</para> + + <programlisting><![CDATA[<h1>First section</h1> + +<!-- Document introduction --> + +<h3>Sub-section</h3> + +<!-- This is bad, <h2> has been left out -->]]></programlisting> + </example> + </sect2> + + <sect2 id="xhtml-markup-block-elements-paragraphs"> + <title>Paragraphs</title> + + <para><acronym>XHTML</acronym> supports a single paragraph + element, <sgmltag>p</sgmltag>.</para> + + <example> + <title><sgmltag>p</sgmltag></title> + + <para>Usage:</para> + + <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect2> + + <sect2 id="xhtml-markup-block-elements-block-quotations"> + <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>Usage:</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> + </sect2> + + <sect2 id="xhtml-markup-block-elements-lists"> + <title>Lists</title> + + <para><acronym>XHTML</acronym> 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>Usage:</para> + + <programlisting><![CDATA[<p>An unordered list. Listitems will probably be + preceded 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>Usage:</para> + + <programlisting><![CDATA[<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p> + + <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><p>Paragraph 1 of definition 3.</p></dd> +</dl>]]></programlisting> + </example> + </sect2> + + <sect2 id="xhtml-markup-block-elements-preformatted-text"> + <title>Pre-formatted Text</title> + + <para>Pre-formatted text can 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 into 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>For example, the <sgmltag>pre</sgmltag> tags could be + used to mark up an email message:</para> + + <programlisting><![CDATA[<pre> From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N</pre>]]></programlisting> + + <para>Keep in mind that <literal><</literal> and + <literal>&</literal> still are recognized as special + characters in pre-formatted text. This is why the example + shown had to use <literal>&lt;</literal> instead of + <literal><</literal>. For consistency, + <literal>&gt;</literal> was used in place of + <literal>></literal>, too. Watch out for the special + characters that may appear in text copied from a plain-text + source, like an email message or program code.</para> + </example> + </sect2> + + <sect2 id="xhtml-markup-block-elements-tables"> + <title>Tables</title> + + <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 the <sgmltag>p</sgmltag>element is not needed.</para> + + <example> + <title>Simple Use of <sgmltag>table</sgmltag></title> + + <para>Usage:</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 or columns that should be spanned.</para> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Usage:</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>Usage:</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>Usage:</para> + + <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged into 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 into + 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> + </sect2> + </sect1> + + <sect1 id="xhtml-markup-inline-elements"> + <title>In-line Elements</title> + + <sect2 id="xhtml-markup-inline-elements-emphasizing-information"> + <title>Emphasizing Information</title> + + <para>Two levels of emphasis are available in + <acronym>XHTML</acronym>, <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 should not be relied upon. + According to best practices, webpages only hold structural and + semantical information and stylesheets are later applied to + them. Think of semantics, not formatting, when using these + tags.</para> + + <example> + <title><sgmltag>em</sgmltag> and + <sgmltag>strong</sgmltag></title> + + <para>Usage:</para> + + <programlisting><![CDATA[<p><em>This</em> has been emphasized, while + <strong>this</strong> has been strongly emphasized.</p>]]></programlisting> + </example> + </sect2> + + <sect2 id="xhtml-markup-inline-elements-fixed-pitch-text"> + <title>Indicating Fixed-Pitch Text</title> + + <para>Content that should be rendered in a fixed pitch + (typewriter) typeface is tagged with <sgmltag>tt</sgmltag> + (for <quote>teletype</quote>).</para> + + <example> + <title><sgmltag>tt</sgmltag></title> + + <para>Usage:</para> + + <programlisting><![CDATA[<p>This document was originally written by + Nik Clayton, who can be reached by email as + <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> + </example> + </sect2> + + <sect2 id="xhtml-markup-inline-elements-links"> + <title>Links</title> + + <note> + <para>Links are also inline elements.</para> + </note> + + <sect3 id="xhtml-markup-inline-elements-linking"> + <title>Linking to Other Documents on the Web</title> + + <para>A link points to the <acronym>URL</acronym> of another + document on the web. The link is indicated with + <sgmltag>a</sgmltag>, and the <literal>href</literal> + attribute contains the <acronym>URL</acronym> of the target + document. The content of the element becomes the link, and + is normally indicated to the user in some way, + typically by a different color or underlining.</para> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Usage:</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 id="xhtml-markup-inline-elements-other-parts"> + <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 + <emphasis>anchors</emphasis>. Anchors are indicated with + <sgmltag>a</sgmltag> and the <literal>id</literal> attribute + instead of <literal>href</literal>.</para> + + <example> + <title>Using <literal><a id="..."></literal></title> + + <para>Usage:</para> + + <programlisting><![CDATA[<p><a id="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 <acronym>ID</acronym> + 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 preceding + <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> +</chapter> |