diff options
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml')
| -rw-r--r-- | en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml | 2761 |
1 files changed, 0 insertions, 2761 deletions
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 deleted file mode 100644 index 7c2ece8dba..0000000000 --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ /dev/null @@ -1,2761 +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. - ---> - -<chapter xmlns="http://docbook.org/ns/docbook" - xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" - xml:id="docbook-markup"> - - <title>DocBook Markup</title> - - <sect1 xml: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 Document Type Definition - (<acronym>DTD</acronym>) for writing technical documentation - <footnote><para>A short history can be found under <link - xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41">http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. - Since 1998 it is maintained by the <link - xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</link>. 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 - <package>textproc/docbook-xml</package> - port. It is automatically installed as part of the - <package>textproc/docproj</package> - 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 xml:id="docbook-markup-freebsd-extensions"> - <title>&os; Extensions</title> - - <para>The &os; Documentation Project has extended the DocBook - <acronym>DTD</acronym> with additional elements and entities. - These additions serve to make some of the markup easier or more - precise.</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>Most of these extensions are not unique to &os;, 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 - contact &a.doceng;.</para> - </note> - - <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> - <title>&os; Elements</title> - - <para>The additional &os; elements are not (currently) in the - Ports Collection. They are stored in the &os; Subversion - tree, as <link - xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> - - <para>&os;-specific elements used in the examples below are - clearly marked.</para> - </sect2> - - <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> - <title>&os; Entities</title> - - <para>This table shows some of the most useful entities - available in the <acronym>FDP</acronym>. For a complete list, - see the <filename>*.ent</filename> files in - <filename>doc/share/xml</filename>.</para> - - <informaltable frame="none" pgwide="1"> - <tgroup cols="3"> - <colspec colname="entity"/> - <colspec colname="expandsto"/> - <colspec colname="notes"/> - <thead> - <row> - <entry></entry> - <entry></entry> - <entry></entry> - </row> - </thead> - - <tbody valign="top"> - <row> - <entry namest="entity" nameend="notes"><emphasis>&os; - Name Entities</emphasis></entry> - </row> - - <row> - <entry><literal>&os;</literal></entry> - <entry><literal>&os;</literal></entry> - <entry/> - </row> - - <row> - <entry><literal>&os.stable;</literal></entry> - <entry><literal>&os.stable;</literal></entry> - <entry/> - </row> - - <row> - <entry><literal>&os.current;</literal></entry> - <entry><literal>&os.current;</literal></entry> - <entry/> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Manual Page - Entities</entry> - </row> - - <row> - <entry><literal>&man.ls.1;</literal></entry> - <entry>&man.ls.1;</entry> - <entry>Usage: <literal>&man.ls.1; is the manual page - for - <command>ls</command>.</literal></entry> - </row> - - <row> - <entry><literal>&man.cp.1;</literal></entry> - <entry>&man.cp.1;</entry> - <entry>Usage: <literal>The manual page for - <command>cp</command> is - &man.cp.1;.</literal></entry> - </row> - - <row> - <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> - <entry><emphasis>link to - <replaceable>command</replaceable> manual page in - section - <replaceable>sectionnumber</replaceable></emphasis></entry> - <entry>Entities are defined for all the - <link xlink:href="&url.base;/cgi/man.cgi">&os; manual - pages</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">&os; Mailing List - Entities</entry> - </row> - - <row> - <entry><literal>&a.doc;</literal></entry> - <entry><literal>&a.doc;</literal></entry> - <entry>Usage: <literal>A link to the - &a.doc;.</literal></entry> - </row> - - <row> - <entry><literal>&a.questions;</literal></entry> - <entry><literal>&a.questions;</literal></entry> - <entry>Usage: <literal>A link to the - &a.questions;.</literal></entry> - </row> - - <row> - <entry><literal>&a.<replaceable>listname</replaceable>;</literal></entry> - <entry><emphasis>link to - <replaceable>listname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os; - mailing lists</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">&os; Document - Link Entities</entry> - </row> - - <row> - <entry><literal>&url.books.handbook;</literal></entry> - <entry><literal>&url.books.handbook;</literal></entry> - <entry>Usage: <literal>A link to the <link - xlink:href="&url.books.handbook;/advanced-networking.html">Advanced - Networking</link> chapter of the - Handbook.</literal></entry> - </row> - - <row> - <entry><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> - <entry><emphasis>relative path to - <replaceable>bookname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.doc.langbase;/books/">&os; - books</link>.</entry> - </row> - - <row> - <entry><literal>&url.articles.committers-guide;</literal></entry> - <entry><literal>&url.articles.committers-guide;</literal></entry> - <entry>Usage: <literal>A link to the <link - xlink:href="&url.articles.committers-guide;">Committer's - Guide</link> - article.</literal></entry> - </row> - - <row> - <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> - <entry><emphasis>relative path to - <replaceable>articlename</replaceable></emphasis></entry> - <entry>Entities are defined for all the <link - xlink:href="&url.doc.langbase;/articles/">&os; - articles</link>.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Other Operating - System Name Entities</entry> - </row> - - <row> - <entry><literal>&linux;</literal></entry> - <entry>&linux;</entry> - <entry>The &linux; operating system.</entry> - </row> - - <row> - <entry><literal>&unix;</literal></entry> - <entry>&unix;</entry> - <entry>The &unix; operating system.</entry> - </row> - - <row> - <entry><literal>&windows;</literal></entry> - <entry>&windows;</entry> - <entry>The &windows; operating system.</entry> - </row> - - <row> - <entry/> - <entry/> - <entry/> - </row> - - <row> - <entry namest="entity" nameend="notes">Miscellaneous - Entities</entry> - </row> - - <row> - <entry><literal>&prompt.root;</literal></entry> - <entry>&prompt.root;</entry> - <entry>The <systemitem - class="username">root</systemitem> user - prompt.</entry> - </row> - - <row> - <entry><literal>&prompt.user;</literal></entry> - <entry>&prompt.user;</entry> - <entry>A prompt for an unprivileged user.</entry> - </row> - - <row> - <entry><literal>&postscript;</literal></entry> - <entry>&postscript;</entry> - <entry>The - &postscript; programming language.</entry> - </row> - - <row> - <entry><literal>&tex;</literal></entry> - <entry>&tex;</entry> - <entry>The - &tex; typesetting language.</entry> - </row> - - <row> - <entry><literal>&xorg;</literal></entry> - <entry>&xorg;</entry> - <entry>The &xorg; open source X - Window System.</entry> - </row> - </tbody> - </tgroup> - </informaltable> - </sect2> - </sect1> - - <sect1 xml: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 xml: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 <tag>chapter</tag>s. - This is a mandatory requirement. There may be - <tag>part</tag>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 <tag>sect1</tag> element. - If a section contains another section then use the - <tag>sect2</tag> element, and so on, up to - <tag>sect5</tag>.</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 <tag>sect1</tag> - (and <tag>sect2</tag> 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 <link xlink:href="&url.base;/docs.html">&os; - tutorials</link> are all marked up as articles, while this - document, the <link - xlink:href="&url.books.faq;/index.html">FAQ</link>, and the - <link - xlink:href="&url.books.handbook;/index.html">Handbook</link> - are all marked up as books, for example.</para> - - <sect2 xml:id="docbook-markup-starting-a-book"> - <title>Starting a Book</title> - - <para>The content of a book is contained within the - <tag>book</tag> 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 - <tag>info</tag>.</para> - - <example> - <title>Boilerplate <tag>book</tag> with - <tag>info</tag></title> - - <!-- Cannot put this in a marked section because of the - replaceable elements --> - - <programlisting><tag class="starttag">book</tag> - <tag class="starttag">info</tag> - <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> - <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - … - -<tag class="endtag">book</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-starting-an-article"> - <title>Starting an Article</title> - - <para>The content of the article is contained within the - <tag>article</tag> 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 - <tag>info</tag>.</para> - - <example> - <title>Boilerplate <tag>article</tag> with - <tag>info</tag></title> - - <!-- Cannot put this in a marked section because of the - replaceable elements --> - - <programlisting><tag class="starttag">article</tag> - <tag class="starttag">info</tag> - <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> - - <tag class="starttag">author</tag> - <tag class="starttag">personname</tag> - <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> - <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> - <tag class="endtag">personname</tag> - - <tag class="starttag">affiliation</tag> - <tag class="starttag">address</tag> - <tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> - <tag class="endtag">address</tag> - <tag class="endtag">affiliation</tag> - <tag class="endtag">author</tag> - - <tag class="starttag">copyright</tag> - <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> - <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> - <tag class="endtag">copyright</tag> - - <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - - <tag class="starttag">abstract</tag> - <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> - <tag class="endtag">abstract</tag> - <tag class="endtag">info</tag> - - … - -<tag class="endtag">article</tag></programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-indicating-chapters"> - <title>Indicating Chapters</title> - - <para>Use <tag>chapter</tag> to mark up your chapters. - Each chapter has a mandatory <tag>title</tag>. - Articles do not contain chapters, they are reserved for - books.</para> - - <example> - <title>A Simple Chapter</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> - - ... -<tag class="endtag">chapter</tag></programlisting> - </example> - - <para>A chapter cannot be empty; it must contain elements in - addition to <tag>title</tag>. If you need to - include an empty chapter then just use an empty - paragraph.</para> - - <example> - <title>Empty Chapters</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> - - <tag class="starttag">para</tag><tag class="endtag">para</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - </sect2> - - <sect2 xml: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 - <tag>sect<replaceable>n</replaceable></tag> element. - The <replaceable>n</replaceable> indicates the section number, - which identifies the section level.</para> - - <para>The first - <tag>sect<replaceable>n</replaceable></tag> is - <tag>sect1</tag>. You can have one or more of these - in a chapter. They can contain one or more - <tag>sect2</tag> elements, and so on, down to - <tag>sect5</tag>.</para> - - <example> - <title>Sections in Chapters</title> - - <programlisting><tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> - - … - <tag class="endtag">sect1</tag> - - <tag class="starttag">sect1</tag> - <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> - - <tag class="starttag">sect3</tag> - <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> - - … - <tag class="endtag">sect3</tag> - <tag class="endtag">sect2</tag> - - <tag class="starttag">sect2</tag> - <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> - - … - <tag class="endtag">sect2</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - - <note> - <para>Section numbers are automatically generated and - prepended to titles when the document is rendered to an - output format. The generated section numbers and titles - from the example above will be:</para> - - <itemizedlist> - <listitem> - <para>1.1. First Section</para> - </listitem> - - <listitem> - <para>1.2. Second Section</para> - </listitem> - - <listitem> - <para>1.2.1. First Sub-Section</para> - </listitem> - - <listitem> - <para>1.2.1.1. First Sub-Sub-Section</para> - </listitem> - - <listitem> - <para>1.2.2. Second Sub-Section</para> - </listitem> - </itemizedlist> - </note> - </sect2> - - <sect2 xml:id="docbook-markup-subdividing-part"> - <title>Subdividing Using <tag>part</tag> - Elements</title> - - <para><tag>part</tag>s introduce another level of - organization between <tag>book</tag> and - <tag>chapter</tag> with one or more - <tag>part</tag>s. This cannot be done in an - <tag>article</tag>.</para> - - <programlisting><tag class="starttag">part</tag> - <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> - - <tag class="starttag">chapter</tag> - <tag class="starttag">title</tag>History<tag class="endtag">title</tag> - - ... - <tag class="endtag">chapter</tag> -<tag class="endtag">part</tag></programlisting> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-block-elements"> - <title>Block Elements</title> - - <sect2 xml:id="docbook-markup-paragraphs"> - <title>Paragraphs</title> - - <para>DocBook supports three types of paragraphs: - <tag>formalpara</tag>, <tag>para</tag>, and - <tag>simpara</tag>.</para> - - <para>Almost all paragraphs in &os; documentation use - <tag>para</tag>. <tag>formalpara</tag> - includes a <tag>title</tag> element, and - <tag>simpara</tag> disallows some elements from - within <tag>para</tag>. Stick with - <tag>para</tag>.</para> - - <example> - <title><tag>para</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any - other element.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>This is a paragraph. It can contain just about any - other element.</para> - </example> - </sect2> - - <sect2 xml: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><tag>blockquote</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> - -<tag class="starttag">blockquote</tag> - <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> - - <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> - - <tag class="starttag">para</tag>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.<tag class="endtag">para</tag> -<tag class="endtag">blockquote</tag></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 xml:id="docbook-markup-tips-notes"> - <title>Tips, Notes, Warnings, Cautions, and Important - Information</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>Several types of admonitions are available: - <tag>tip</tag>, <tag>note</tag>, - <tag>warning</tag>, <tag>caution</tag>, and - <tag>important</tag>.</para> - - <para>Which admonition to choose depends on the situation. - The DocBook - documentation suggests:</para> - - <itemizedlist> - <listitem> - <para>Note is for information that should be heeded by - all readers.</para> - </listitem> - - <listitem> - <para>Important is a variation on Note.</para> - </listitem> - - <listitem> - <para>Caution is for information regarding possible data - loss or software damage.</para> - </listitem> - - <listitem> - <para>Warning is for information regarding possible - hardware damage or injury to life or limb.</para> - </listitem> - </itemizedlist> - - <example> - <title><tag>tip</tag> and <tag>important</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">tip</tag> - <tag class="starttag">para</tag>&os; may reduce stress.<tag class="endtag">para</tag> -<tag class="endtag">tip</tag> - -<tag class="starttag">important</tag> - <tag class="starttag">para</tag>Please use admonitions sparingly. Too many admonitions - are visually jarring and can have the opposite of the - intended effect.<tag class="endtag">para</tag> -<tag class="endtag">important</tag></programlisting> - </example> - - <para>Appearance:</para> - <!-- Need to do this outside of the example --> - <tip> - <para>&os; may reduce stress.</para> - </tip> - - <important> - <para>Please use admonitions sparingly. Too many admonitions - are visually jarring and can have the opposite of the - intended effect.</para> - </important> - </sect2> - - <sect2 xml:id="docbook-markup-example"> - <title>Examples</title> - - <para>Examples can be shown with <tag>example</tag>.</para> - - <example> - <title><tag>example</tag> Source</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">example</tag> - <tag class="starttag">para</tag>Empty files can be created easily:<tag class="endtag">para</tag> - - <tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>touch file1 file2 file3<tag class="endtag">userinput</tag><tag class="endtag">screen</tag> -<tag class="endtag">example</tag></programlisting> - </example> - - <!-- Need to do this outside of the example --> - <para>Appearance:</para> - - <example> - <title>Rendered <tag>example</tag></title> - - <para>Empty files can be created easily:</para> - - <screen>&prompt.user; <userinput>touch file1 file2 file3</userinput></screen> - </example> - </sect2> - - <sect2 xml: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 <tag>itemizedlist</tag>, - <tag>orderedlist</tag>, <tag>variablelist</tag>, or - <tag>procedure</tag>. There are other types of list - elements in DocBook, but we will not cover them here.</para> - - <para><tag>itemizedlist</tag> and - <tag>orderedlist</tag> are similar to their - counterparts in <acronym>HTML</acronym>, <tag>ul</tag> - and <tag>ol</tag>. Each one consists of one or more - <tag>listitem</tag> elements, and each - <tag>listitem</tag> contains one or more block - elements. The <tag>listitem</tag> elements are - analogous to <acronym>HTML</acronym>'s <tag>li</tag> - tags. However, unlike HTML, they are required.</para> - - <example> - <title><tag>itemizedlist</tag> and - <tag>orderedlist</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">itemizedlist</tag> - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> -<tag class="endtag">itemizedlist</tag> - -<tag class="starttag">orderedlist</tag> - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> -<tag class="endtag">orderedlist</tag></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> - - <para xml:id="docbook-markup-varlist">An alternate and often - useful way of presenting information is the - <tag>variablelist</tag>. These are lists where each entry has - a term and a description. They are well suited for many types - of descriptions, and present information in a form that is - often easier for the reader than sections and - subsections.</para> - - <para>A <tag>variablelist</tag> has a <tag>title</tag>, and then - pairs of <tag>term</tag> and <tag>listitem</tag> - entries.</para> - - <example xml:id="docbook-markup-variablelist-example"> - <title><tag>variablelist</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">variablelist</tag> - <tag class="starttag">varlistentry</tag> - <tag class="starttag">term</tag>Parallel<tag class="endtag">term</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>In parallel communications, groups of bits arrive - at the same time over multiple communications - channels.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - <tag class="endtag">varlistentry</tag> - - <tag class="starttag">varlistentry</tag> - <tag class="starttag">term</tag>Serial<tag class="endtag">term</tag> - - <tag class="starttag">listitem</tag> - <tag class="starttag">para</tag>In serial communications, bits arrive one at a - time over a single communications - channel.<tag class="endtag">para</tag> - <tag class="endtag">listitem</tag> - <tag class="endtag">varlistentry</tag> -<tag class="endtag">variablelist</tag></programlisting> - - <para>Appearance:</para> - - <variablelist> - <varlistentry> - <term>Parallel</term> - - <listitem> - <para>In parallel communications, groups of bits arrive - at the same time over multiple communications - channels.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term>Serial</term> - - <listitem> - <para>In serial communications, bits arrive one at a - time over a single communications channel.</para> - </listitem> - </varlistentry> - </variablelist> - </example> - - <para>A <tag>procedure</tag> shows a series of <tag>step</tag>s, - which may in turn consist of more <tag>step</tag>s or - <tag>substep</tag>s. Each <tag>step</tag> contains block - elements and may include an optional title.</para> - - <para>Sometimes, steps are not sequential, but present a choice: - do <emphasis>this</emphasis> or do <emphasis>that</emphasis>, - but not both. For these alternative choices, use - <tag>stepalternatives</tag>.</para> - - <example> - <title><tag>procedure</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">procedure</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">substeps</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>And now do this smaller thing.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>And now do this other smaller thing.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - <tag class="endtag">substeps</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Finally, do one of these:<tag class="endtag">para</tag> - - <tag class="starttag">stepalternatives</tag> - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Go left.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - - <tag class="starttag">step</tag> - <tag class="starttag">para</tag>Go right.<tag class="endtag">para</tag> - <tag class="endtag">step</tag> - <tag class="endtag">stepalternatives</tag> - <tag class="endtag">step</tag> -<tag class="endtag">procedure</tag></programlisting> - - <para>Appearance:</para> - - <procedure> - <step> - <para>Do this.</para> - </step> - - <step> - <para>Then do this.</para> - </step> - - <step> - <substeps> - <step> - <para>And now do this small thing.</para> - </step> - - <step> - <para>And this other small thing.</para> - </step> - </substeps> - </step> - - <step> - <para>Finally, do one of these:</para> - - <stepalternatives> - <step> - <para>Go left.</para> - </step> - - <step> - <para>Go right.</para> - </step> - </stepalternatives> - </step> - </procedure> - </example> - </sect2> - - <sect2 xml: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 <tag>programlisting</tag> - element.</para> - - <para>White space and line breaks within - <tag>programlisting</tag> <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><tag>programlisting</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>When finished, the program will look like - this:<tag class="endtag">para</tag> - -<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; - -int -main(void) -{ - printf("hello, world\n"); - return 0; -}<tag class="endtag">programlisting</tag></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"); - return 0; -}</programlisting> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-callouts"> - <title>Callouts</title> - - <para>A callout is a visual marker for referring to a - piece of text or specific position within an - example.</para> - - <para>Callouts are marked with the <tag>co</tag> - element. Each element must have a unique - <literal>id</literal> assigned to it. After the example, - include a <tag>calloutlist</tag> that describes each - callout.</para> - - <example> - <title><tag>co</tag> and - <tag>calloutlist</tag> Example</title> - - <programlisting><tag class="starttag">para</tag>When finished, the program will look like - this:<tag class="endtag">para</tag> - -<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co xml:id="co-ex-include"</tag> - -int <tag class="emptytag">co xml:id="co-ex-return"</tag> -main(void) -{ - printf("hello, world\n"); <tag class="emptytag">co xml:id="co-ex-printf"</tag> -}<tag class="endtag">programlisting</tag> - -<tag class="starttag">calloutlist</tag> - <tag class="starttag">callout arearefs="co-ex-include"</tag> - <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> - - <tag class="starttag">callout arearefs="co-ex-return"</tag> - <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an - int.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> - - <tag class="starttag">callout arearefs="co-ex-printf"</tag> - <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes - <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> - <tag class="endtag">callout</tag> -<tag class="endtag">calloutlist</tag></programlisting> - - <para>Appearance:</para> - - <para>When finished, the program will look like this:</para> - - <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> - -int <co xml:id="co-ex-return"/> -main(void) -{ - printf("hello, world\n"); <co xml: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 xml: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 <tag>table</tag> element. This contains - at least one <tag>tgroup</tag> element, which - specifies (as an attribute) the number of columns in this - table group. Within the tablegroup there is one - <tag>thead</tag> element, which contains elements for - the table headings (column headings), and one - <tag>tbody</tag> which contains the body of the - table.</para> - - <para>Both <tag>tgroup</tag> and - <tag>thead</tag> contain <tag>row</tag> - elements, which in turn contain <tag>entry</tag> - elements. Each <tag>entry</tag> element specifies - one cell in the table.</para> - - <example> - <title><tag>informaltable</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">informaltable pgwide="1"</tag> - <tag class="starttag">tgroup cols="2"</tag> - <tag class="starttag">thead</tag> - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - <tag class="endtag">thead</tag> - - <tag class="starttag">tbody</tag> - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - - <tag class="starttag">row</tag> - <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> - <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> - <tag class="endtag">row</tag> - <tag class="endtag">tbody</tag> - <tag class="endtag">tgroup</tag> -<tag class="endtag">informaltable</tag></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 - <tag>informaltable</tag> 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 <tag>informaltable</tag> element. For example, - <literal>informaltable frame="none"</literal>.</para> - - <example> - <title>Table with <literal>frame="none"</literal> - Example</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 xml: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><tag>screen</tag></term> - - <listitem> - <para>Everything the user sees in this example will be - on the computer screen, so the next element is - <tag>screen</tag>.</para> - - <para>Within <tag>screen</tag>, white space is - significant.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><tag>prompt</tag>, - <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 - <tag>prompt</tag>.</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 - <tag>prompt</tag>.</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><tag>userinput</tag></term> - - <listitem> - <para>When displaying text that the user should type in, - wrap it in <tag>userinput</tag> tags. It will - be displayed differently than system output text.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>screen</tag>, <tag>prompt</tag>, - and <tag>userinput</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> -foo1 -foo2 -foo3 -&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> -foo2 -&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> -<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> -&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> -This is the file called 'foo2'<tag class="endtag">screen</tag></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 <tag>programlisting</tag>. Reserve - <tag>programlisting</tag> for showing fragments of - files outside the context of user actions.</para> - </note> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-inline-elements"> - <title>In-line Elements</title> - - <sect2 xml:id="docbook-markup-inline-emphasizing"> - <title>Emphasizing Information</title> - - <para>To emphasize a particular word or phrase, use - <tag>emphasis</tag>. 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 <tag>b</tag> and - <tag>i</tag>. If the information being presented is - important, then consider presenting it in - <tag>important</tag> rather than - <tag>emphasis</tag>.</para> - - <example> - <title><tag>emphasis</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>&os; is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> - premiere &unix;-like operating system for the Intel - architecture.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>&os; is without doubt <emphasis>the</emphasis> - premiere &unix;-like operating system for the Intel - architecture.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-acronyms"> - <title>Acronyms</title> - - <para>Many computer terms are <emphasis>acronyms</emphasis>, - words formed from the first letter of each word in a - phrase. Acronyms are marked up into - <tag>acronym</tag> elements. It is helpful to the - reader when an acronym is defined on the first use, as shown - in the example below.</para> - - <example> - <title><tag>acronym</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 - defined the use of avian carriers for transmission of - Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The - quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently - transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Request For Comments (<acronym>RFC</acronym>) 1149 - defined the use of avian carriers for transmission of - Internet Protocol (<acronym>IP</acronym>) data. The - quantity of <acronym>IP</acronym> data currently - transmitted in that manner is unknown.</para> - </example> - </sect2> - - <sect2 xml: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 - <tag>quote</tag>. Most of the markup tags available - for normal text are also available from within a - <tag>quote</tag>.</para> - - <example> - <title><tag>quote</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the - <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, - as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></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 <acronym>RFC</acronym> 1535 - calls it.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-keys"> - <title>Keys, Mouse Buttons, and Combinations</title> - - <para>To refer to a specific key on the keyboard, use - <tag>keycap</tag>. To refer to a mouse button, use - <tag>mousebutton</tag>. And to refer to - combinations of key presses or mouse clicks, wrap them all - in <tag>keycombo</tag>.</para> - - <para><tag>keycombo</tag> 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 <tag>keycombo</tag>.</para> - - <example> - <title>Keys, Mouse Buttons, and Combinations Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press - <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> - <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type - <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> - <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>My window manager is configured so that - <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> - <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> - <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></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 xml: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 - <tag>application</tag>.</para> - - <para>To list a command with its manual section - number (which should be most of the time) the DocBook - element is <tag>citerefentry</tag>. This will - contain a further two elements, - <tag>refentrytitle</tag> and - <tag>manvolnum</tag>. The content of - <tag>refentrytitle</tag> is the name of the command, - and the content of <tag>manvolnum</tag> 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 <tag>command</tag> to include a command - name <quote>in-line</quote> but present it as something the - user should type.</para> - - <para>Use <tag>option</tag> 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 - <tag>command</tag> to markup subsequent references. - This makes the generated output, especially - <acronym>HTML</acronym>, appear visually better.</para> - - <example> - <title>Applications, Commands, and Options Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most - widely used Unix mail application.<tag class="starttag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the - <tag class="starttag">citerefentry</tag> - <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> - <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> - <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; - programs.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> - <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> - <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> - <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current - status of messages in the mail queue. Check this on the command - line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></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 xml:id="docbook-markup-files"> - <title>Files, Directories, Extensions, Device Names</title> - - <para>To refer to the name of a file, a directory, a file - extension, or a device name, use <tag>filename</tag>.</para> - - <example> - <title><tag>filename</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The source for the Handbook in English is found in - <tag class="starttag">filename</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. - The main file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag>. - There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> and a - number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> extension.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">filename</tag>kbd0<tag class="endtag">filename</tag> is the first keyboard detected - by the system, and appears in - <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The source for the Handbook in English is found in - <filename>/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. - The main file is called <filename>book.xml</filename>. - There is also a <filename>Makefile</filename> and a number - of files with a <filename>.ent</filename> extension.</para> - - <para><filename>kbd0</filename> is the first keyboard detected - by the system, and appears in - <filename>/dev</filename>.</para> - </example> - </sect2> - - <sect2 xml: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 <tag>package</tag> - tag. Since the Ports Collection can be installed in any - number of locations, only include the category and the port - name; do not include <filename>/usr/ports</filename>.</para> - - <para>By default, <tag>package</tag> refers to a binary package. - To refer to a port that will be built from source, set the - <literal>role</literal> attribute to - <literal>port</literal>.</para> - - <example> - <title><tag>package</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">package</tag>net/wireshark<tag class="endtag">package</tag> binary - package to view network traffic.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">package role="port"</tag>net/wireshark<tag class="endtag">package</tag> can also be - built and installed from the Ports Collection.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Install the <package>net/wireshark</package> binary - package to view network traffic.</para> - - <para><package role="port">net/wireshark</package> can also be - built and installed from the Ports Collection.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-hosts"> - <title>Hosts, Domains, IP Addresses, User Names, Group Names, - and Other System Items</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>Information for <quote>system items</quote> is marked up - with <tag>systemitem</tag>. The <literal>class</literal> - attribute is used to identify the particular type of - information shown.</para> - - <variablelist> - <varlistentry> - <term><literal>class="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>class="etheraddress"</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> - - <varlistentry> - <term><literal>class="fqdomainname"</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>class="ipaddress"</literal></term> - - <listitem> - <para>The text is an <acronym>IP</acronym> address, - probably expressed as a dotted quad.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="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>class="systemname"</literal></term> - - <listitem> - <para>With <literal>class="systemname"</literal> - the marked up information is the simple hostname, such - as <literal>freefall</literal> or - <literal>wcarchive</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="username"</literal></term> - - <listitem> - <para>The text is a username, like - <literal>root</literal>.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><literal>class="groupname"</literal></term> - - <listitem> - <para>The text is a groupname, like - <literal>wheel</literal>.</para> - </listitem> - </varlistentry> - </variablelist> - - <example> - <title><tag>systemitem</tag> and Classes Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the - name <tag class="starttag">systemitem class="systemname"</tag>localhost<tag class="endtag">systemitem</tag>, which will have the IP - address <tag class="starttag">systemitem class="ipaddress"</tag>127.0.0.1<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>The <tag class="starttag">systemitem class="domainname"</tag>FreeBSD.org<tag class="endtag">systemitem</tag> - domain contains a number of different hosts, including - <tag class="starttag">systemitem class="fqdomainname"</tag>freefall.FreeBSD.org<tag class="endtag">systemitem</tag> and - <tag class="starttag">systemitem class="fqdomainname"</tag>bento.FreeBSD.org<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an - interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) - <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of - <tag class="starttag">systemitem class="netmask"</tag>255.255.255.255<tag class="endtag">systemitem</tag> (which can - also be expressed as - <tag class="starttag">systemitem class="netmask"</tag>0xffffffff<tag class="endtag">systemitem</tag>).<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies - every network card in existence. A typical - <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like - <tag class="starttag">systemitem class="etheraddress"</tag>08:00:20:87:ef:d0<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>To carry out most system administration functions - requires logging in as <tag class="starttag">systemitem class="username"</tag>root<tag class="endtag">systemitem</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>The local machine can always be referred to by the name - <systemitem>localhost</systemitem>, which will have the IP - address - <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> - - <para>The - <systemitem class="fqdomainname">FreeBSD.org</systemitem> - domain contains a number of different hosts, including - <systemitem - class="fqdomainname">freefall.FreeBSD.org</systemitem> and - <systemitem - class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> - - <para>When adding an <acronym>IP</acronym> alias to an - interface (using <command>ifconfig</command>) - <emphasis>always</emphasis> use a netmask of - <systemitem class="netmask">255.255.255.255</systemitem> - (which can also be expressed as - <systemitem class="netmask">0xffffffff</systemitem>).</para> - - <para>The <acronym>MAC</acronym> address uniquely identifies - every network card in existence. A typical - <acronym>MAC</acronym> address looks like <systemitem - class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> - - <para>To carry out most system administration functions - requires logging in as - <systemitem class="username">root</systemitem>.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-uri"> - <title>Uniform Resource Identifiers - (<acronym>URI</acronym>s)</title> - - <para>Occasionally it is useful to show a - Uniform Resource Identifier (<acronym>URI</acronym>) without - making it an active hyperlink. The <tag>uri</tag> element - makes this possible:</para> - - <example> - <title><tag>uri</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>This <acronym>URL</acronym> shows only as text: - <tag class="starttag">uri</tag>https://www.FreeBSD.org<tag class="endtag">uri</tag>. It does not - create a link.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>This <acronym>URL</acronym> shows only as text: - <uri>https://www.FreeBSD.org</uri>. It does not - create a link.</para> - </example> - - <para>To create links, see - <xref linkend="docbook-markup-links"/>.</para> - </sect2> - - <sect2 xml:id="docbook-markup-email-addresses"> - <title>Email Addresses</title> - - <para>Email addresses are marked up as <tag>email</tag> - elements. In the <acronym>HTML</acronym> output format, the - wrapped text becomes a hyperlink to the email address. Other - output formats that support hyperlinks may also make the email - address into a link.</para> - - <example> - <title><tag>email</tag> with a Hyperlink Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>An email address that does not actually exist, like - <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an - example.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>An email address that does not actually exist, like - <email>notreal@example.com</email>, can be used as an - example.</para> - </example> - - <para>A &os;-specific extension allows setting the - <literal>role</literal> attribute to <literal>nolink</literal> - to prevent the creation of the hyperlink to the email - address.</para> - - <example> - <title><tag>email</tag> Without a Hyperlink Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Sometimes a link to an email address like - <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not - desired.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Sometimes a link to an email address like - <email role="nolink">notreal@example.com</email> is not - desired.</para> - </example> - </sect2> - - <sect2 xml: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, <tag>buildtarget</tag> - and <tag>varname</tag>.</para> - - <para><tag>buildtarget</tag> identifies a build target - exported by a <filename>Makefile</filename> that can be - given as a parameter to <command>make</command>. - <tag>varname</tag> identifies a variable that can be - set (in the environment, on the command line with - <command>make</command>, or within the - <filename>Makefile</filename>) to influence the - process.</para> - - <example> - <title><tag>buildtarget</tag> and - <tag>varname</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> - are <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> and - <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">buildtarget</tag>all<tag class="endtag">buildtarget</tag> will - rebuild the application, and invoking - <tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> will remove the temporary - files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the - build process.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag><tag class="starttag">buildtarget</tag>clean<tag class="endtag">buildtarget</tag> may be controlled by a - number of variables, including <tag class="starttag">varname</tag>CLOBBER<tag class="endtag">varname</tag> - and <tag class="starttag">varname</tag>RECURSE<tag class="endtag">varname</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Two common targets in a <filename>Makefile</filename> - are <buildtarget>all</buildtarget> and - <buildtarget>clean</buildtarget>.</para> - - <para>Typically, invoking <buildtarget>all</buildtarget> will - rebuild the application, and invoking - <buildtarget>clean</buildtarget> will remove the temporary - files (<filename>.o</filename> for example) created by the - build process.</para> - - <para><buildtarget>clean</buildtarget> may be controlled by a - number of variables, including <varname>CLOBBER</varname> - and <varname>RECURSE</varname>.</para> - </example> - </sect2> - - <sect2 xml: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, <tag>programlisting</tag> will - be sufficient to denote this text. But - <tag>programlisting</tag> 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 - <tag>literal</tag>.</para> - - <example> - <title><tag>literal</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> 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.<tag class="endtag">para</tag></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 xml: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><tag>replaceable</tag> 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><tag>replaceable</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> - </informalexample> - - <para><tag>replaceable</tag> can be used in many - different elements, including <tag>literal</tag>. - This example also shows that <tag>replaceable</tag> - 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><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> - 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.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value - for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></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 xml:id="docbook-markup-gui-buttons"> - <title>Showing <acronym>GUI</acronym> Buttons</title> - - <para>Buttons presented by a graphical user interface are marked - with <tag>guibutton</tag>. To make the text look more - like a graphical button, brackets and non-breaking spaces are - added surrounding the text.</para> - - <example> - <title><tag>guibutton</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Edit the file, then click - <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the - changes.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Edit the file, then click - <guibutton>[ Save ]</guibutton> to save the - changes.</para> - </example> - </sect2> - - <sect2 xml:id="docbook-markup-system-errors"> - <title>Quoting System Errors</title> - - <para>System errors generated by &os; are marked with - <tag>errorname</tag>. This indicates the exact error - that appears.</para> - - <example> - <title><tag>errorname</tag> Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> - - <para>Appearance:</para> - - <informalexample> - <screen><errorname>Panic: cannot mount root</errorname></screen> - </informalexample> - </example> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-images"> - <title>Images</title> - - <important> - <para>Image support in the documentation is somewhat - experimental. The mechanisms described here are unlikely to - change, but that is not guaranteed.</para> - - <para>To provide conversion between different image formats, the - <package>graphics/ImageMagick</package> - port must be installed. This port is not included in the - <package>textproc/docproj</package> meta - port, and must be installed separately.</para> - - <para>A good example of the use of images is the - <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> - document. Examine the files in that directory to see how - these elements are used together. Build different output - formats to see how the format determines what images are shown - in the rendered document.</para> - </important> - - <sect2 xml:id="docbook-markup-image-formats"> - <title>Image Formats</title> - - <para>The following image formats are currently supported. An - image file will automatically be converted to bitmap or vector - image depending on the output document format.</para> - - <para>These are the <emphasis>only</emphasis> formats in which - images should be committed to the documentation - repository.</para> - - <variablelist> - <varlistentry> - <term><acronym>EPS</acronym> (Encapsulated - Postscript)</term> - - <listitem> - <para>Images that are primarily vector based, such as - network diagrams, time lines, and similar, should be in - this format. These images have a - <filename>.eps</filename> extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>PNG</acronym> (Portable Network - Graphic)</term> - - <listitem> - <para>For bitmaps, such as screen captures, use this - format. These images have the <filename>.png</filename> - extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>PIC</acronym> (PIC graphics language)</term> - - <listitem> - <para><acronym>PIC</acronym> is a language for drawing - simple vector-based figures used in the &man.pic.1; - utility. These images have the - <filename>.pic</filename> extension.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><acronym>SCR</acronym> (SCReen capture)</term> - - <listitem> - <para>This format is specific to screenshots of console - output. The following command generates an SCR file - <filename>shot.scr</filename> from video buffer of - <filename>/dev/ttyv0</filename>:</para> - - <screen>&prompt.root; <userinput><command>vidcontrol -p</command> < <filename><replaceable>/dev/ttyv0</replaceable></filename> > <filename><replaceable>shot.scr</replaceable></filename></userinput></screen> - - <para>This is preferable to <acronym>PNG</acronym> format - for screenshots because the <acronym>SCR</acronym> file - contains plain text of the command lines so that it can - be converted to a <acronym>PNG</acronym> image or a - plain text depending on the output document - format.</para> - </listitem> - </varlistentry> - </variablelist> - - <para>Use the appropriate format for each image. Documentation - will often 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 used. - <emphasis>Do not commit the same image to the repository in - two different formats</emphasis>.</para> - - <important> - <para>The Documentation Project may eventually 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 xml:id="docbook-markup-image-file-locations"> - <title>Image File Locations</title> - - <para>Image files can be stored in one of several locations, - depending on the document and image:</para> - - <itemizedlist> - <listitem> - <para>In the same directory as the document itself, usually - done for articles and small books that keep all their - files in a single directory.</para> - </listitem> - - <listitem> - <para>In a subdirectory of the main document. Typically - done when a large book uses separate subdirectories to - organize individual chapters.</para> - - <para>When images are stored in a subdirectory of the - main document directory, the subdirectory name must be - included in their paths in the - <filename>Makefile</filename> and the - <tag>imagedata</tag> element.</para> - </listitem> - - <listitem> - <para>In a subdirectory of - <filename>doc/share/images</filename> named after the - document. For example, images for the Handbook are stored - in <filename>doc/share/images/books/handbook</filename>. - Images that work for multiple translations are stored in - this upper level of the documentation file tree. - Generally, these are images that can be used unchanged in - non-English translations of the document.</para> - </listitem> - </itemizedlist> - </sect2> - - <sect2 xml:id="docbook-markup-image-markup"> - <title>Image Markup</title> - - <para>Images are included as part of a <tag>mediaobject</tag>. - The <tag>mediaobject</tag> can contain other, more specific - objects. We are concerned with two, the - <tag>imageobject</tag> and the <tag>textobject</tag>.</para> - - <para>Include one <tag>imageobject</tag>, and two - <tag>textobject</tag> elements. The <tag>imageobject</tag> - will point to the name of the image file without the - extension. The <tag>textobject</tag> elements contain - information that will be presented to the user as well as, or - instead of, the image itself.</para> - - <para>Text elements are shown to the reader in several - situations. When the document is viewed in - <acronym>HTML</acronym>, text elements are shown while the - image is loading, or if the mouse pointer is hovered over the - image, or if a text-only browser is being used. In formats - like plain text where graphics are not possible, the text - elements are shown instead of the graphical ones.</para> - - <para>This example shows how to include an image called - <filename>fig1.png</filename> in a document. The image is a - rectangle with an A inside it:</para> - - <programlisting><tag class="starttag">mediaobject</tag> - <tag class="starttag">imageobject</tag> - <tag class="emptytag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> - <tag class="endtag">imageobject</tag> - - <tag class="starttag">textobject</tag> - <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> -| A | -+---------------+<tag class="endtag">literallayout</tag> - <tag class="endtag">textobject</tag> - - <tag class="starttag">textobject</tag> - <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> - <tag class="endtag">textobject</tag> -<tag class="endtag">mediaobject</tag></programlisting> - - <calloutlist> - <callout arearefs="co-image-ext"> - <para>Include an <tag>imagedata</tag> element - inside the <tag>imageobject</tag> 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 <tag>textobject</tag> contains a - <tag>literallayout</tag> 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 <tag>literallayout</tag> 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 <tag>textobject</tag> contains a - single <tag>phrase</tag> 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 xml: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 <varname>IMAGES</varname> 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 xml: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, 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 <varname>IMAGES</varname> variable in the - <filename>Makefile</filename>, <emphasis>and</emphasis> - including the directory name in the <tag>imagedata</tag> - element in the document.</para> - - <para>For example, if the book has - <filename>chapter1/fig1.png</filename>, then - <filename>chapter1/chapter.xml</filename> should - contain:</para> - - <programlisting><tag class="starttag">mediaobject</tag> - <tag class="starttag">imageobject</tag> - <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> - <tag class="endtag">imageobject</tag> - - … - -<tag class="endtag">mediaobject</tag></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> - </sect2> - </sect1> - - <sect1 xml:id="docbook-markup-links"> - <title>Links</title> - - <note> - <para>Links are also in-line elements. To show a - <acronym>URI</acronym> without creating a link, see - <xref linkend="docbook-markup-uri"/>.</para> - </note> - - <sect2 xml:id="docbook-markup-links-ids"> - <title><literal>xml:id</literal> Attributes</title> - - <para>Most DocBook elements accept an <literal>xml:id</literal> - attribute to give that part of the document a unique name. - The <literal>xml: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>xml:id</literal> attribute. Assigning - an <literal>xml:id</literal> to all chapters and sections, - even if there are no current plans to link to them, is a good - idea. These <literal>xml:id</literal>s can be used as unique - reference points by anyone referring to the - <acronym>HTML</acronym> version of the document.</para> - - <example> - <title><literal>xml:id</literal> on Chapters and - Sections Example</title> - - <programlisting><tag class="starttag">chapter xml:id="introduction"</tag> - <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is the introduction. It contains a subsection, - which is identified as well.<tag class="endtag">para</tag> - - <tag class="starttag">sect1 xml:id="introduction-moredetails"</tag> - <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> - - <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> - <tag class="endtag">sect1</tag> -<tag class="endtag">chapter</tag></programlisting> - </example> - - <para>Use descriptive values for <literal>xml:id</literal> - names. The values must be unique within the entire document, - not just in a single file. In the example, the subsection - <literal>xml:id</literal> is constructed by appending text to - the chapter <literal>xml:id</literal>. This ensures that the - <literal>xml: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> - </sect2> - - <sect2 xml:id="docbook-markup-links-crossreferences"> - <title>Crossreferences with <literal>xref</literal></title> - - <para><tag>xref</tag> provides the reader with a link to jump to - another section of the document. The target - <literal>xml:id</literal> is specified in the - <literal>linkend</literal> attribute, and <tag>xref</tag> - generates the link text automatically.</para> - - <example> - <title><tag>xref</tag> Example</title> - - <para>Assume that this fragment appears somewhere in a - document that includes the <literal>xml:id</literal> - example shown above:</para> - - <programlisting><tag class="starttag">para</tag>More information can be found - in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> - -<tag class="starttag">para</tag>More specific information can be found - in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></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, Introduction</emphasis>.</para> - - <para>More specific information can be found in - <emphasis>Section 1.1, - <quote>More Details</quote></emphasis>.</para> - </blockquote> - </example> - - <para>The link text is generated automatically from the chapter - and section number and <literal>title</literal> - elements.</para> - </sect2> - - <sect2 xml:id="docbook-markup-links-to-web-documents"> - <title>Linking to Other Documents on the - Web</title> - - <para>The link element described here allows the writer to - define the link text. When link text is used, it is very - important to be descriptive to give the reader an idea of - where the link goes. Remember that DocBook can be rendered to - multiple types of media. The reader might 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 might - not be able to locate the linked section.</para> - - <para>The <literal>xlink:href</literal> attribute is the - <acronym>URL</acronym> of the page, and the content of the - element is the text that will be displayed for the user to - activate.</para> - - <para>In many situations, it is preferable to show the actual - <acronym>URL</acronym> rather than text. This can be done by - leaving out the element text entirely.</para> - - <example> - <title><tag>link</tag> to a &os; Documentation Web - Page Example</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 &os; book links:</para> - - <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">link - xlink:href="&url.books.handbook;/svn.html#svn-intro"</tag>SVN - introduction<tag class="endtag">link</tag>, then pick the nearest mirror from - the list of <tag class="starttag">link - xlink:href="&url.books.handbook;/svn.html#svn-mirrors"</tag>Subversion - mirror sites<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Read the <link - xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN - introduction</link>, then pick the nearest mirror from - the list of <link - xlink:href="&url.books.handbook;/svn.html#svn-mirrors">Subversion - mirror sites</link>.</para> - - <para>Usage for &os; article links:</para> - - <programlisting><tag class="starttag">para</tag>Read this - <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;"</tag>article - about the BSD license<tag class="endtag">link</tag>, or just the - <tag class="starttag">link xlink:href="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Read this - <link xlink:href="&url.articles.bsdl-gpl;">article - about the BSD license</link>, or just the <link - xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para> - </example> - - <example> - <title><tag>link</tag> to a &os; Web Page Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the - <tag class="starttag">link xlink:href="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">link</tag> instead.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Of course, you could stop reading this document and go - to the <link xlink:href="&url.base;/index.html">FreeBSD - home page</link> instead.</para> - </example> - - <example> - <title><tag>link</tag> to an External Web - Page Example</title> - - <para>Usage:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - <tag class="starttag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID - Partition Tables<tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>Appearance:</para> - - <para>Wikipedia has an excellent reference on <link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</link>.</para> - - <para>The link text can be omitted to show the actual - URL:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - GUID Partition Tables: <tag class="starttag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">link</tag>.<tag class="endtag">para</tag></programlisting> - - <para>The same link can be entered using shorter - notation instead of a separate ending tag:</para> - - <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on - GUID Partition Tables: <tag class="emptytag">link - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>.<tag class="endtag">para</tag></programlisting> - - <para>The two methods are equivalent. Appearance:</para> - - <para>Wikipedia has an excellent reference on GUID Partition - Tables: <uri - xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para> - </example> - </sect2> - </sect1> -</chapter> |