From owner-svn-doc-all@FreeBSD.ORG Wed Jun 25 15:10:39 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 7CBF41B4; Wed, 25 Jun 2014 15:10:39 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 5D8FC2290; Wed, 25 Jun 2014 15:10:39 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s5PFAdle069956; Wed, 25 Jun 2014 15:10:39 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s5PFAdE7069955; Wed, 25 Jun 2014 15:10:39 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201406251510.s5PFAdE7069955@svn.freebsd.org> From: Warren Block Date: Wed, 25 Jun 2014 15:10:39 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.18 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 25 Jun 2014 15:10:39 -0000 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 @@ The DocBook DTD is available from the Ports Collection in the - textproc/docbook-xml-450 + textproc/docbook-xml port. It is automatically installed as part of the textproc/docproj port. @@ -418,10 +418,9 @@ The &os; tutorials are all marked up as articles, while this document, the FreeBSD FAQ, + xlink:href="&url.books.faq;/index.html">FAQ, and the FreeBSD - Handbook are all marked up as books, for + xlink:href="&url.books.handbook;/index.html">Handbook are all marked up as books, for example. @@ -435,24 +434,29 @@ content used to produce a title page. This additional information is contained within - bookinfo. + info. Boilerplate <tag>book</tag> with - <tag>bookinfo</tag> + info book - bookinfo + info titleYour Title Heretitle author - firstnameYour first namefirstname - surnameYour surnamesurname + personname + firstnameYour first namefirstname + surnameYour surnamesurname + personname + affiliation - addressemailYour email addressemailaddress + address + emailYour email addressemail + address affiliation author @@ -466,7 +470,7 @@ abstract paraInclude an abstract of the book's contents here.para abstract - bookinfo + info … @@ -485,24 +489,29 @@ additional content used to produce a title page. This additional information is contained within - articleinfo. + info. Boilerplate <tag>article</tag> with - <tag>articleinfo</tag> + info article - articleinfo + info titleYour title heretitle author - firstnameYour first namefirstname - surnameYour surnamesurname + personname + firstnameYour first namefirstname + surnameYour surnamesurname + personname + affiliation - addressemailYour email addressemailaddress + address + emailYour email addressemailaddress + address affiliation author @@ -516,7 +525,7 @@ abstract paraInclude an abstract of the article's contents here.para abstract - articleinfo + info … @@ -762,63 +771,71 @@ - Tips, Notes, Warnings, Cautions, Important Information - and Sidebars + Tips, Notes, Warnings, Cautions, and Important + Information Extra information may need to be separated from the main body of the text. Typically this is meta information of which the user should be aware. - Depending on the nature of the information, one of + Several types of admonitions are available: tip, note, warning, caution, and - important should be used. Alternatively, - if the information is related to the main text but is not - one of the above, use sidebar. - - The circumstances in which to choose one of these - elements over another is loosely defined by the DocBook - documentation, which suggests: + important. + + Which admonition to choose depends on the situation. + The DocBook + documentation suggests: - A Note is for information that should be heeded by + Note is for information that should be heeded by all readers. - An Important element is a variation on Note. + Important is a variation on Note. - A Caution is for information regarding possible data + Caution is for information regarding possible data loss or software damage. - A Warning is for information regarding possible + Warning is for information regarding possible hardware damage or injury to life or limb. - <tag>warning</tag> + <tag>tip</tag> and <tag>important</tag> Usage: - warning - paraInstalling &os; may make you want to delete Windows from your - hard disk.para -warning + tip + para&os; may reduce stress.para +tip + +important + paraPlease use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect.para +important Appearance: - - Installing FreeBSD may make you want to delete Windows - from your hard disk. - + + &os; may reduce stress. + + + + Please use admonitions sparingly. Too many admonitions + are visually jarring and can have the opposite of the + intended effect. + @@ -830,10 +847,8 @@ To do this, use itemizedlist, orderedlist, variablelist, or - procedureThere are other - types of list element in DocBook, but we are not - concerned with those at the - moment.. + procedure. There are other types of list + elements in DocBook, but we will not cover them here. itemizedlist and orderedlist are similar to their @@ -1380,7 +1395,7 @@ This is the file called 'foo2' Appearance: - FreeBSD is without doubt the + &os; is without doubt the premiere &unix;-like operating system for the Intel architecture. @@ -1558,9 +1573,9 @@ This is the file called 'foo2' ]> - Use command when to include a command + Use command to include a command name in-line but present it as something the - user should type in. + user should type. Use option to mark up the options which will be passed to a command.