svn commit: r45126 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup
Warren Block
wblock at FreeBSD.org
Wed Jun 25 15:10:39 UTC 2014
Author: wblock
Date: Wed Jun 25 15:10:38 2014
New Revision: 45126
URL: http://svnweb.freebsd.org/changeset/doc/45126
Log:
Correct and expand DocBook examples, fix some that have embarrassing
errors and some that do exactly what the guidelines say to avoid.
Modified:
head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
Modified: head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Wed Jun 25 14:21:19 2014 (r45125)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml Wed Jun 25 15:10:38 2014 (r45126)
@@ -63,7 +63,7 @@
<para>The DocBook <acronym>DTD</acronym> is available from the
Ports Collection in the
- <package>textproc/docbook-xml-450</package>
+ <package>textproc/docbook-xml</package>
port. It is automatically installed as part of the
<package>textproc/docproj</package>
port.</para>
@@ -418,10 +418,9 @@
<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">FreeBSD FAQ</link>,
+ xlink:href="&url.books.faq;/index.html">FAQ</link>,
and the <link
- xlink:href="&url.books.handbook;/index.html">FreeBSD
- Handbook</link> are all marked up as books, for
+ 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">
@@ -435,24 +434,29 @@
content used to produce a title page.</para>
<para>This additional information is contained within
- <tag>bookinfo</tag>.</para>
+ <tag>info</tag>.</para>
<example>
<title>Boilerplate <tag>book</tag> with
- <tag>bookinfo</tag></title>
+ <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">bookinfo</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">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="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="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>
@@ -466,7 +470,7 @@
<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">bookinfo</tag>
+ <tag class="endtag">info</tag>
…
@@ -485,24 +489,29 @@
additional content used to produce a title page.</para>
<para>This additional information is contained within
- <tag>articleinfo</tag>.</para>
+ <tag>info</tag>.</para>
<example>
<title>Boilerplate <tag>article</tag> with
- <tag>articleinfo</tag></title>
+ <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">articleinfo</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">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="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="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>
@@ -516,7 +525,7 @@
<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">articleinfo</tag>
+ <tag class="endtag">info</tag>
…
@@ -762,63 +771,71 @@
</sect2>
<sect2 xml:id="docbook-markup-tips-notes">
- <title>Tips, Notes, Warnings, Cautions, Important Information
- and Sidebars</title>
+ <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>Depending on the nature of the information, one of
+ <para>Several types of admonitions are available:
<tag>tip</tag>, <tag>note</tag>,
<tag>warning</tag>, <tag>caution</tag>, and
- <tag>important</tag> should be used. Alternatively,
- if the information is related to the main text but is not
- one of the above, use <tag>sidebar</tag>.</para>
-
- <para>The circumstances in which to choose one of these
- elements over another is loosely defined by the DocBook
- documentation, which suggests:</para>
+ <tag>important</tag>.</para>
+
+ <para>Which admonition to choose depends on the situation.
+ The DocBook
+ documentation suggests:</para>
<itemizedlist>
<listitem>
- <para>A Note is for information that should be heeded by
+ <para>Note is for information that should be heeded by
all readers.</para>
</listitem>
<listitem>
- <para>An Important element is a variation on Note.</para>
+ <para>Important is a variation on Note.</para>
</listitem>
<listitem>
- <para>A Caution is for information regarding possible data
+ <para>Caution is for information regarding possible data
loss or software damage.</para>
</listitem>
<listitem>
- <para>A Warning is for information regarding possible
+ <para>Warning is for information regarding possible
hardware damage or injury to life or limb.</para>
</listitem>
</itemizedlist>
<example>
- <title><tag>warning</tag></title>
+ <title><tag>tip</tag> and <tag>important</tag></title>
<para>Usage:</para>
- <programlisting><tag class="starttag">warning</tag>
- <tag class="starttag">para</tag>Installing &os; may make you want to delete Windows from your
- hard disk.<tag class="endtag">para</tag>
-<tag class="endtag">warning</tag></programlisting>
+ <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 -->
- <warning>
- <para>Installing FreeBSD may make you want to delete Windows
- from your hard disk.</para>
- </warning>
+ <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-lists-and-procedures">
@@ -830,10 +847,8 @@
<para>To do this, use <tag>itemizedlist</tag>,
<tag>orderedlist</tag>, <tag>variablelist</tag>, or
- <tag>procedure</tag><footnote><para>There are other
- types of list element in DocBook, but we are not
- concerned with those at the
- moment.</para></footnote>.</para>
+ <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
@@ -1380,7 +1395,7 @@ This is the file called 'foo2'</screen>
<para>Appearance:</para>
- <para>FreeBSD is without doubt <emphasis>the</emphasis>
+ <para>&os; is without doubt <emphasis>the</emphasis>
premiere &unix;-like operating system for the Intel
architecture.</para>
</example>
@@ -1558,9 +1573,9 @@ This is the file called 'foo2'</screen>
]></programlisting>
- <para>Use <tag>command</tag> when to include a command
+ <para>Use <tag>command</tag> to include a command
name <quote>in-line</quote> but present it as something the
- user should type in.</para>
+ user should type.</para>
<para>Use <tag>option</tag> to mark up the options
which will be passed to a command.</para>
More information about the svn-doc-head
mailing list