Date: Wed, 25 Jun 2014 15:10:39 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r45126 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup Message-ID: <201406251510.s5PFAdE7069955@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201406251510.s5PFAdE7069955>