svn commit: r42005 - in head/en_US.ISO8859-1/books/fdp-primer: . docbook-markup overview sgml-markup xhtml-markup
Warren Block
wblock at FreeBSD.org
Sun Jun 23 19:45:14 UTC 2013
Author: wblock
Date: Sun Jun 23 19:45:12 2013
New Revision: 42005
URL: http://svnweb.freebsd.org/changeset/doc/42005
Log:
Split the old sgml-markup chapter into two chapters, one for XHTML and
one for DocBook. Both are edited and expanded versions of the content
from the old chapter.
Added:
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
- copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml
head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/
head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
- copied, changed from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml
Deleted:
head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/
Modified:
head/en_US.ISO8859-1/books/fdp-primer/Makefile
head/en_US.ISO8859-1/books/fdp-primer/book.xml
head/en_US.ISO8859-1/books/fdp-primer/chapters.ent
head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/Makefile
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 17:59:58 2013 (r42004)
+++ head/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 19:45:12 2013 (r42005)
@@ -23,7 +23,8 @@ SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= psgml-mode/chapter.xml
SRCS+= see-also/chapter.xml
-SRCS+= sgml-markup/chapter.xml
+SRCS+= xhtml-markup/chapter.xml
+SRCS+= docbook-markup/chapter.xml
SRCS+= sgml-primer/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= structure/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/book.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 17:59:58 2013 (r42004)
+++ head/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 19:45:12 2013 (r42005)
@@ -248,7 +248,8 @@ Password:</screen></entry>
&chap.overview;
&chap.tools;
&chap.xml-primer;
- &chap.xml-markup;
+ &chap.xhtml-markup;
+ &chap.docbook-markup;
&chap.stylesheets;
&chap.structure;
&chap.doc-build;
Modified: head/en_US.ISO8859-1/books/fdp-primer/chapters.ent
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 17:59:58 2013 (r42004)
+++ head/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 19:45:12 2013 (r42005)
@@ -13,7 +13,8 @@
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
-<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml">
+<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
+<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
Copied and modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml (from r41997, head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml)
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml Fri Jun 21 17:57:26 2013 (r41997, copy source)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Sun Jun 23 19:45:12 2013 (r42005)
@@ -31,620 +31,40 @@
$FreeBSD$
-->
-<chapter id="xml-markup">
- <title>XML Markup</title>
+<chapter id="docbook-markup">
+ <title>DocBook Markup</title>
- <para>This chapter describes the two markup languages you will
- encounter when you contribute to the FreeBSD documentation
- project. Each section describes the markup language, and details
- the markup that you are likely to want to use, or that is already
- in use.</para>
-
- <para>These markup languages contain a large number of elements, and
- it can be confusing sometimes to know which element to use for a
- particular situation. This section goes through the elements you
- are most likely to need, and gives examples of how you would use
- them.</para>
-
- <para>This is <emphasis>not</emphasis> an exhaustive list of
- elements, since that would just reiterate the documentation for
- each language. The aim of this section is to list those elements
- more likely to be useful to you. If you have a question about how
- best to markup a particular piece of content, please post it to
- the &a.doc;.</para>
-
- <note>
- <title>Inline Versus Block</title>
-
- <para>In the remainder of this document, when describing elements,
- <emphasis>inline</emphasis> means that the element can occur
- within a block element, and does not cause a line break. A
- <emphasis>block</emphasis> element, by comparison, will cause a
- line break (and other processing) when it is encountered.</para>
- </note>
-
- <sect1 id="xml-markup-xhtml">
- <title>XHTML</title>
-
- <para>XHTML is the XML version of the HyperText Markup Language,
- which is the markup language
- of choice on the World Wide Web. More information can be found
- at <ulink url="http://www.w3.org/"></ulink>.</para>
-
- <para>XHTML is used to markup pages on the FreeBSD web site. It
- should not (generally) be used to mark up other documentation,
- since DocBook offers a far richer set of elements to choose
- from. Consequently, you will normally only encounter XHTML pages
- if you are writing for the web site.</para>
-
- <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
- 4.0 and then an XML-compliant version has also been created, which
- is called XHTML and the latest widespread version of it is
- XHTML 1.0(available in both
- <emphasis>strict</emphasis> and <emphasis>transitional</emphasis>
- variants).</para>
-
- <para>The XHTML DTDs are available from the Ports Collection
- in the <filename role="package">textproc/xhtml</filename> port.
- They are automatically installed as part of the <filename
- role="package">textproc/docproj</filename> port.</para>
+ <sect1 id="docbook-markup-introduction">
+ <title>Introduction</title>
- <sect2>
- <title>Formal Public Identifier (FPI)</title>
-
- <para>There are a number of XHTML FPIs, depending upon the
- version (also known as the level) of XHTML that you want to
- declare your document to be compliant with.</para>
-
- <para>The majority of XHTML documents on the FreeBSD web site
- comply with the transitional version of XHTML 1.0.</para>
-
- <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
- </sect2>
-
- <sect2>
- <title>Sectional Elements</title>
-
- <para>An XHTML document is normally split into two sections. The
- first section, called the <emphasis>head</emphasis>, contains
- meta-information about the document, such as its title, the
- name of the author, the parent document, and so on. The
- second section, the <emphasis>body</emphasis>, contains the
- content that will be displayed to the user.</para>
-
- <para>These sections are indicated with <sgmltag>head</sgmltag>
- and <sgmltag>body</sgmltag> elements respectively. These
- elements are contained within the top-level
- <sgmltag>html</sgmltag> element.</para>
-
- <example>
- <title>Normal XHTML Document Structure</title>
-
- <programlisting><html xmlns="http://www.w3.org/1999/xhtml">
- <head>
- <title><replaceable>The Document's Title</replaceable></title>
- </head>
-
- <body>
-
- …
-
- </body>
-</html></programlisting>
- </example>
- </sect2>
-
- <sect2>
- <title>Block Elements</title>
-
- <sect3>
- <title>Headings</title>
-
- <para>XHTML allows you to denote headings in your document, at
- up to six different levels.</para>
-
- <para>The largest and most prominent heading is
- <sgmltag>h1</sgmltag>, then <sgmltag>h2</sgmltag>,
- continuing down to <sgmltag>h6</sgmltag>.</para>
-
- <para>The element's content is the text of the heading.</para>
-
- <example>
- <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>,
- and Other Header Tags</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<h1>First section</h1>
-
-<!-- Document introduction goes here -->
-
-<h2>This is the heading for the first section</h2>
-
-<!-- Content for the first section goes here -->
-
-<h3>This is the heading for the first sub-section</h3>
-
-<!-- Content for the first sub-section goes here -->
-
-<h2>This is the heading for the second section</h2>
-
-<!-- Content for the second section goes here -->]]></programlisting>
- </example>
-
- <para>Generally, an XHTML page should have one first level
- heading (<sgmltag>h1</sgmltag>). This can contain many
- second level headings (<sgmltag>h2</sgmltag>), which can in
- turn contain many third level headings. Each
- <sgmltag>h<replaceable>n</replaceable></sgmltag> element
- should have the same element, but one further up the
- hierarchy, preceding it. Leaving gaps in the numbering is
- to be avoided.</para>
-
- <example>
- <title>Bad Ordering of
- <sgmltag>h<replaceable>n</replaceable></sgmltag>
- Elements</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<h1>First section</h1>
-
-<!-- Document introduction -->
-
-<h3>Sub-section</h3>
-
-<!-- This is bad, <h2> has been left out -->]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Paragraphs</title>
-
- <para>XHTML supports a single paragraph element,
- <sgmltag>p</sgmltag>.</para>
-
- <example>
- <title><sgmltag>p</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any
- other element.</p>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Block Quotations</title>
-
- <para>A block quotation is an extended quotation from another
- document that should not appear within the current
- paragraph.</para>
-
- <example>
- <title><sgmltag>blockquote</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p>
-
-<blockquote>We the People of the United States, in Order to form
- a more perfect Union, establish Justice, insure domestic
- Tranquility, provide for the common defence, promote the general
- Welfare, and secure the Blessings of Liberty to ourselves and our
- Posterity, do ordain and establish this Constitution for the
- United States of America.</blockquote>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Lists</title>
-
- <para>You can present the user with three types of lists,
- ordered, unordered, and definition.</para>
-
- <para>Typically, each entry in an ordered list will be
- numbered, while each entry in an unordered list will be
- preceded by a bullet point. Definition lists are composed
- of two sections for each entry. The first section is the
- term being defined, and the second section is the definition
- of the term.</para>
-
- <para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
- element, unordered lists by the <sgmltag>ul</sgmltag>
- element, and definition lists by the <sgmltag>dl</sgmltag>
- element.</para>
-
- <para>Ordered and unordered lists contain listitems, indicated
- by the <sgmltag>li</sgmltag> element. A listitem can
- contain textual content, or it may be further wrapped in one
- or more <sgmltag>p</sgmltag> elements.</para>
-
- <para>Definition lists contain definition terms
- (<sgmltag>dt</sgmltag>) and definition descriptions
- (<sgmltag>dd</sgmltag>). A definition term can only contain
- inline elements. A definition description can contain other
- block elements.</para>
-
- <example>
- <title><sgmltag>ul</sgmltag> and
- <sgmltag>ol</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>An unordered list. Listitems will probably be
- preceded by bullets.</p>
-
-<ul>
- <li>First item</li>
-
- <li>Second item</li>
-
- <li>Third item</li>
-</ul>
-
-<p>An ordered list, with list items consisting of multiple
- paragraphs. Each item (note: not each paragraph) will be
- numbered.</p>
-
-<ol>
- <li><p>This is the first item. It only has one paragraph.</p></li>
-
- <li><p>This is the first paragraph of the second item.</p>
-
- <p>This is the second paragraph of the second item.</p></li>
-
- <li><p>This is the first and only paragraph of the third
- item.</p></li>
-</ol>]]></programlisting>
- </example>
-
- <example>
- <title>Definition Lists with <sgmltag>dl</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<dl>
- <dt>Term 1</dt>
-
- <dd><p>Paragraph 1 of definition 1.</p>
-
- <p>Paragraph 2 of definition 1.</p></dd>
-
- <dt>Term 2</dt>
-
- <dd><p>Paragraph 1 of definition 2.</p></dd>
-
- <dt>Term 3</dt>
-
- <dd><p>Paragraph 1 of definition 3.</p></dd>
-</dl>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Pre-formatted Text</title>
-
- <para>You can indicate that text should be shown to the user
- exactly as it is in the file. Typically, this means that
- the text is shown in a fixed font, multiple spaces are not
- merged into one, and line breaks in the text are
- significant.</para>
-
- <para>In order to do this, wrap the content in the
- <sgmltag>pre</sgmltag> element.</para>
-
- <example>
- <title><sgmltag>pre</sgmltag></title>
-
- <para>You could use <sgmltag>pre</sgmltag> to mark up an
- email message:</para>
-
- <programlisting><![CDATA[<pre> From: nik at FreeBSD.org
- To: freebsd-doc at FreeBSD.org
- Subject: New documentation available
-
- There is a new copy of my primer for contributors to the FreeBSD
- Documentation Project available at
-
- <URL:http://people.FreeBSD.org/~nik/primer/index.html>
-
- Comments appreciated.
-
- N</pre>]]></programlisting>
-
- <para>Keep in mind that <literal><</literal> and
- <literal>&</literal> still are recognized as special
- characters in pre-formatted text. This is why the example
- shown had to use <literal><</literal> instead of
- <literal><</literal>. For consistency,
- <literal>></literal> was used in place of
- <literal>></literal>, too. Watch out for the special
- characters that may appear in text copied from a
- plain-text source, e.g., an email message or program
- code.</para>
- </example>
- </sect3>
-
- <sect3>
- <title>Tables</title>
-
- <note>
- <para>Most text-mode browsers (such as Lynx) do not render
- tables particularly effectively. If you are relying on
- the tabular display of your content, you should consider
- using alternative markup to prevent confusion.</para>
- </note>
-
- <para>Mark up tabular information using the
- <sgmltag>table</sgmltag> element. A table consists of one
- or more table rows (<sgmltag>tr</sgmltag>), each containing
- one or more cells of table data (<sgmltag>td</sgmltag>).
- Each cell can contain other block elements, such as
- paragraphs or lists. It can also contain another table
- (this nesting can repeat indefinitely). If the cell only
- contains one paragraph then you do not need to include the
- <sgmltag>p</sgmltag> element.</para>
-
- <example>
- <title>Simple Use of <sgmltag>table</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>This is a simple 2x2 table.</p>
-
-<table>
- <tr>
- <td>Top left cell</td>
-
- <td>Top right cell</td>
- </tr>
-
- <tr>
- <td>Bottom left cell</td>
-
- <td>Bottom right cell</td>
- </tr>
-</table>]]></programlisting></example>
-
- <para>A cell can span multiple rows and columns. To indicate
- this, add the <literal>rowspan</literal> and/or
- <literal>colspan</literal> attributes, with values
- indicating the number of rows or columns that should be
- spanned.</para>
-
- <example>
- <title>Using <literal>rowspan</literal></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>One tall thin cell on the left, two short cells next to
- it on the right.</p>
-
-<table>
- <tr>
- <td rowspan="2">Long and thin</td>
- </tr>
-
- <tr>
- <td>Top cell</td>
-
- <td>Bottom cell</td>
- </tr>
-</table>]]></programlisting>
- </example>
-
- <example>
- <title>Using <literal>colspan</literal></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>One long cell on top, two short cells below it.</p>
-
-<table>
- <tr>
- <td colspan="2">Top cell</td>
- </tr>
-
- <tr>
- <td>Bottom left cell</td>
-
- <td>Bottom right cell</td>
- </tr>
-</table>]]></programlisting>
- </example>
-
- <example>
- <title>Using <literal>rowspan</literal> and
- <literal>colspan</literal> Together</title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of
- cells merged into one. The other cells are normal.</p>
-
-<table>
- <tr>
- <td colspan="2" rowspan="2">Top left large cell</td>
-
- <td>Top right cell</td>
- </tr>
-
- <tr>
- <!-- Because the large cell on the left merges into
- this row, the first <td> will occur on its
- right -->
-
- <td>Middle right cell</td>
- </tr>
-
- <tr>
- <td>Bottom left cell</td>
-
- <td>Bottom middle cell</td>
-
- <td>Bottom right cell</td>
- </tr>
-</table>]]></programlisting>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title>In-line Elements</title>
-
- <sect3>
- <title>Emphasizing Information</title>
-
- <para>You have two levels of emphasis available in XHTML,
- <sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
- <sgmltag>em</sgmltag> is for a normal level of emphasis and
- <sgmltag>strong</sgmltag> indicates stronger
- emphasis.</para>
-
- <para>Typically, <sgmltag>em</sgmltag> is rendered in italic
- and <sgmltag>strong</sgmltag> is rendered in bold. This is
- not always the case, however, and you should not rely on
- it. According to best practices, webpages only hold
- structural and semantical information and stylesheets are
- later applied to use these two so you should think of
- semantics not formatting when using these tags.</para>
-
- <example>
- <title><sgmltag>em</sgmltag> and
- <sgmltag>strong</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p><em>This</em> has been emphasized, while
- <strong>this</strong> has been strongly emphasized.</p>]]></programlisting>
- </example>
- </sect3>
-
- <sect3>
- <title>Indicating Fixed-Pitch Text</title>
-
- <para>If you have content that should be rendered in a fixed
- pitch (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
- <quote>teletype</quote>).</para>
-
- <example>
- <title><sgmltag>tt</sgmltag></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>This document was originally written by
- Nik Clayton, who can be reached by email as
- <tt>nik at FreeBSD.org</tt>.</p>]]></programlisting>
- </example>
- </sect3>
- </sect2>
-
- <sect2>
- <title>Links</title>
-
- <note>
- <para>Links are also inline elements.</para>
- </note>
-
- <sect3>
- <title>Linking to Other Documents on the WWW</title>
-
- <para>In order to include a link to another document on the
- WWW you must know the URL of the document you want to link
- to.</para>
-
- <para>The link is indicated with <sgmltag>a</sgmltag>, and the
- <literal>href</literal> attribute contains the URL of the
- target document. The content of the element becomes the
- link, and is normally indicated to the user in some way
- (underlining, change of color, different mouse cursor when
- over the link, and so on).</para>
-
- <example>
- <title>Using <literal><a href="..."></literal></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p>More information is available at the
- <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting>
- </example>
-
- <para>These links will take the user to the top of the chosen
- document.</para>
- </sect3>
-
- <sect3>
- <title>Linking to Other Parts of Documents</title>
-
- <para>Linking to a point within another document (or within
- the same document) requires that the document author include
- anchors that you can link to.</para>
-
- <para>Anchors are indicated with <sgmltag>a</sgmltag> and the
- <literal>id</literal> attribute instead of
- <literal>href</literal>.</para>
-
- <example>
- <title>Using <literal><a id="..."></literal></title>
-
- <para>Use:</para>
-
- <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced
- in other links with the name <tt>para1</tt>.</p>]]></programlisting>
- </example>
-
- <para>To link to a named part of a document, write a normal
- link to that document, but include the id of the anchor
- after a <literal>#</literal> symbol.</para>
-
- <example>
- <title>Linking to a Named Part of Another Document</title>
-
- <para>Assume that the <literal>para1</literal> example
- resides in a document called
- <filename>foo.html</filename>.</para>
-
- <programlisting><![CDATA[<p>More information can be found in the
- <a href="foo.html#para1">first paragraph</a> of
- <tt>foo.html</tt>.</p>]]></programlisting>
- </example>
-
- <para>If you are linking to a named anchor within the same
- document then you can omit the document's URL, and just
- include the name of the anchor (with the preceding
- <literal>#</literal>).</para>
-
- <example>
- <title>Linking to a Named Part of the Same Document</title>
-
- <para>Assume that the <literal>para1</literal> example
- resides in this document:</para>
-
- <programlisting><![CDATA[<p>More information can be found in the
- <a href="#para1">first paragraph</a> of this
- document.</p>]]></programlisting>
- </example>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1 id="xml-markup-docbook">
- <title>DocBook</title>
+ <para>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 DTD for writing technical
- documentation <footnote><para>A short history can be found under
- <ulink
+ O'Reilly & Associates to be a <acronym>DTD</acronym> for
+ writing technical documentation <footnote><para>A short history
+ can be found under <ulink
url="http://www.oasis-open.org/docbook/intro.shtml#d0e41">
http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>.
Since 1998 it is maintained by the <ulink
url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook">
DocBook Technical Committee</ulink>. As such, and unlike
- LinuxDoc and XHTML, DocBook is very heavily oriented towards
- markup that describes <emphasis>what</emphasis> something is,
- rather than describing <emphasis>how</emphasis> it should be
- presented.</para>
+ LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily
+ oriented towards markup that describes <emphasis>what</emphasis>
+ something is, rather than describing <emphasis>how</emphasis> it
+ should be presented.</para>
+
+ <para>The DocBook <acronym>DTD</acronym> is available from the
+ Ports Collection in the
+ <filename role="package">textproc/docbook-xml-450</filename>
+ port. It is automatically installed as part of the
+ <filename role="package">textproc/docproj</filename>
+ port.</para>
<note>
<title>Formal Versus Informal</title>
@@ -656,209 +76,217 @@
informal version will not have a title.</para>
</note>
- <para>The DocBook DTD is available from the Ports Collection
- in the <filename role="package">textproc/docbook-xml-450</filename>
- port. It is automatically installed as part of the <filename
- role="package">textproc/docproj</filename> port.</para>
-
- <sect2>
- <title>&os; Extensions</title>
-
- <para>The FreeBSD Documentation Project has extended the DocBook
- DTD by adding some new elements. These elements serve to make
- some of the markup more precise.</para>
-
- <para>Where a FreeBSD specific element is listed below it is
- clearly marked.</para>
-
- <para>Throughout the rest of this document, the term
- <quote>DocBook</quote> is used to mean the FreeBSD extended
- DocBook DTD.</para>
-
- <note>
- <para>There is nothing about these extensions that is FreeBSD
- specific, it was just felt that they were useful
- enhancements for this particular project. Should anyone
- from any of the other *nix camps (NetBSD, OpenBSD, Linux,
- …) be interested in collaborating on a standard
- DocBook extension set, please get in touch with
- &a.doceng;.</para>
- </note>
+ <note>
+ <title>Inline Versus Block</title>
- <para>The &os; extensions are not (currently) in the
- Ports Collection. They are stored in the &os; Subversion
- tree, as <ulink
- url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>
- </sect2>
+ <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>
- <sect2>
- <title>Formal Public Identifier (FPI)</title>
+ <sect1 id="docbook-markup-freebsd-extensions">
+ <title>&os; Extensions</title>
- <para>In compliance with the DocBook guidelines for writing FPIs
- for DocBook customizations, the FPI for the FreeBSD extended
- DocBook DTD is:</para>
+ <para>The &os; Documentation Project has extended the
+ DocBook <acronym>DTD</acronym> by adding some new elements.
+ These elements serve to make some of the markup more
+ precise.</para>
+
+ <para>Where a &os;-specific element is listed below, it is
+ clearly marked.</para>
+
+ <para>Throughout the rest of this document, the term
+ <quote>DocBook</quote> is used to mean the &os;-extended
+ DocBook <acronym>DTD</acronym>.</para>
- <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
- </sect2>
+ <note>
+ <para>There is nothing about these extensions that is &os;
+ specific, it was just felt that they were useful
+ enhancements for this particular project. Should anyone
+ from any of the other *nix camps (NetBSD, OpenBSD, Linux,
+ …) be interested in collaborating on a standard
+ DocBook extension set, please get in touch with
+ &a.doceng;.</para>
+ </note>
- <sect2>
- <title>Document Structure</title>
+ <para>The &os; extensions are not (currently) in the
+ Ports Collection. They are stored in the &os; Subversion
+ tree, as <ulink
+ url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para>
+ </sect1>
- <para>DocBook allows you to structure your documentation in
- several ways. In the FreeBSD Documentation Project we are
- using two primary types of DocBook document: the book and the
- article.</para>
-
- <para>A book is organized into <sgmltag>chapter</sgmltag>s.
- This is a mandatory requirement. There may be
- <sgmltag>part</sgmltag>s between the book and the chapter to
- provide another layer of organization. For example, the
- Handbook is arranged in this way.</para>
-
- <para>A chapter may (or may not) contain one or more sections.
- These are indicated with the <sgmltag>sect1</sgmltag> element.
- If a section contains another section then use the
- <sgmltag>sect2</sgmltag> element, and so on, up to
- <sgmltag>sect5</sgmltag>.</para>
+ <sect1 id="docbook-markup-fpi">
+ <title>Formal Public Identifier (FPI)</title>
- <para>Chapters and sections contain the remainder of the
- content.</para>
+ <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>
- <para>An article is simpler than a book, and does not use
- chapters. Instead, the content of an article is organized
- into one or more sections, using the same
- <sgmltag>sect1</sgmltag> (and <sgmltag>sect2</sgmltag> and so
- on) elements that are used in books.</para>
-
- <para>Obviously, you should consider the nature of the
- documentation you are writing in order to decide whether it is
- best marked up as a book or an article. Articles are well
- suited to information that does not need to be broken down
- into several chapters, and that is, relatively speaking, quite
- short, at up to 20-25 pages of content. Books are best suited
- to information that can be broken up into several chapters,
- possibly with appendices and similar content as well.</para>
-
- <para>The <ulink url="&url.base;/docs.html">FreeBSD
- tutorials</ulink> are all marked up as articles, while this
- document, the
- <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
- and the <ulink url="&url.books.handbook;/index.html">FreeBSD
- Handbook</ulink> are all marked up as books, for
- example.</para>
+ <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting>
+ </sect1>
- <sect3>
- <title>Starting a Book</title>
+ <sect1 id="docbook-markup-document-structure">
+ <title>Document Structure</title>
- <para>The content of the book is contained within the
- <sgmltag>book</sgmltag> element. As well as containing
- structural markup, this element can contain elements that
- include additional information about the book. This is
- either meta-information, used for reference purposes, or
- additional content used to produce a title page.</para>
+ <para>DocBook allows structuring documentation in several ways.
+ The &os; Documentation Project uses two primary types of DocBook
+ document: the book and the article.</para>
+
+ <para>Books are organized into <sgmltag>chapter</sgmltag>s.
+ This is a mandatory requirement. There may be
+ <sgmltag>part</sgmltag>s between the book and the chapter to
+ provide another layer of organization. For example, the
+ Handbook is arranged in this way.</para>
+
+ <para>A chapter may (or may not) contain one or more sections.
+ These are indicated with the <sgmltag>sect1</sgmltag> element.
+ If a section contains another section then use the
+ <sgmltag>sect2</sgmltag> element, and so on, up to
+ <sgmltag>sect5</sgmltag>.</para>
+
+ <para>Chapters and sections contain the remainder of the
+ content.</para>
+
+ <para>An article is simpler than a book, and does not use
+ chapters. Instead, the content of an article is organized into
+ one or more sections, using the same <sgmltag>sect1</sgmltag>
+ (and <sgmltag>sect2</sgmltag> and so on) elements that are used
+ in books.</para>
+
+ <para>The nature of the document being written should be used to
+ determine whether it is best marked up as a book or an article.
+ Articles are well suited to information that does not need to be
+ broken down into several chapters, and that is, relatively
+ speaking, quite short, at up to 20-25 pages of content. Books
+ are best suited to information that can be broken up into
+ several chapters, possibly with appendices and similar content
+ as well.</para>
+
+ <para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink>
+ are all marked up as articles, while this
+ document, the
+ <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>,
+ and the <ulink url="&url.books.handbook;/index.html">FreeBSD
+ Handbook</ulink> are all marked up as books, for
+ example.</para>
+
+ <sect2 id="docbook-markup-starting-a-book">
+ <title>Starting a Book</title>
+
+ <para>The content of a book is contained within the
+ <sgmltag>book</sgmltag> element. As well as containing
+ structural markup, this element can contain elements that
+ include additional information about the book. This is either
+ meta-information, used for reference purposes, or additional
+ content used to produce a title page.</para>
- <para>This additional information should be contained within
- <sgmltag>bookinfo</sgmltag>.</para>
+ <para>This additional information is contained within
+ <sgmltag>bookinfo</sgmltag>.</para>
- <example>
- <title>Boilerplate <sgmltag>book</sgmltag> with
- <sgmltag>bookinfo</sgmltag></title>
+ <example>
+ <title>Boilerplate <sgmltag>book</sgmltag> with
+ <sgmltag>bookinfo</sgmltag></title>
- <!-- Can't put this in a marked section because of the
- replaceable elements -->
+ <!-- Cannot put this in a marked section because of the
+ replaceable elements -->
- <programlisting><book>
- <bookinfo>
- <title><replaceable>Your Title Here</replaceable></title>
-
- <author>
- <firstname><replaceable>Your first name</replaceable></firstname>
- <surname><replaceable>Your surname</replaceable></surname>
- <affiliation>
- <address><email><replaceable>Your email address</replaceable></email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year><replaceable>1998</replaceable></year>
- <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
- </copyright>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para><replaceable>Include an abstract of the book's contents here.</replaceable></para>
- </abstract>
- </bookinfo>
+ <programlisting><book>
+ <bookinfo>
+ <title><replaceable>Your Title Here</replaceable></title>
+
+ <author>
+ <firstname><replaceable>Your first name</replaceable></firstname>
+ <surname><replaceable>Your surname</replaceable></surname>
+ <affiliation>
+ <address><email><replaceable>Your email address</replaceable></email></address>
+ </affiliation>
+ </author>
+
+ <copyright>
+ <year><replaceable>1998</replaceable></year>
+ <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder>
+ </copyright>
+
+ <releaseinfo>$FreeBSD$</releaseinfo>
+
+ <abstract>
+ <para><replaceable>Include an abstract of the book's contents here.</replaceable></para>
+ </abstract>
+ </bookinfo>
…
-</book></programlisting>
- </example>
- </sect3>
+</book></programlisting>
+ </example>
+ </sect2>
- <sect3>
- <title>Starting an Article</title>
+ <sect2 id="docbook-markup-starting-an-article">
+ <title>Starting an Article</title>
- <para>The content of the article is contained within the
- <sgmltag>article</sgmltag> element. As well as containing
- structural markup, this element can contain elements that
- include additional information about the article. This is
- either meta-information, used for reference purposes, or
- additional content used to produce a title page.</para>
+ <para>The content of the article is contained within the
+ <sgmltag>article</sgmltag> element. As well as containing
+ structural markup, this element can contain elements that
+ include additional information about the article. This is
+ either meta-information, used for reference purposes, or
+ additional content used to produce a title page.</para>
- <para>This additional information should be contained within
- <sgmltag>articleinfo</sgmltag>.</para>
+ <para>This additional information is contained within
+ <sgmltag>articleinfo</sgmltag>.</para>
- <example>
- <title>Boilerplate <sgmltag>article</sgmltag> with
- <sgmltag>articleinfo</sgmltag></title>
+ <example>
+ <title>Boilerplate <sgmltag>article</sgmltag> with
+ <sgmltag>articleinfo</sgmltag></title>
- <!-- Can't put this in a marked section because of the
- replaceable elements -->
+ <!-- Cannot put this in a marked section because of the
+ replaceable elements -->
- <programlisting><article>
- <articleinfo>
- <title><replaceable>Your title here</replaceable></title>
-
- <author>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-head
mailing list