From 6c93ae10eb7277c44c2b11ecc300430b31f00b24 Mon Sep 17 00:00:00 2001 From: Warren Block Date: Tue, 9 Jul 2013 05:34:52 +0000 Subject: [PATCH] Clarity improvements, convert the rest of examples using CDATA to . --- .../fdp-primer/docbook-markup/chapter.xml | 546 +++++++++--------- 1 file changed, 282 insertions(+), 264 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 index 2a8376390c..9958cb5717 100644 --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -195,33 +195,33 @@ - <book> - <bookinfo> - <title>Your Title Here</title> + book + bookinfo + titleYour Title Heretitle - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your email address</email></address> - </affiliation> - </author> + author + firstnameYour first namefirstname + surnameYour surnamesurname + affiliation + addressemailYour email addressemailaddress + affiliation + author - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> + copyright + year1998year + holder role="mailto:your email address"Your nameholder + copyright - <releaseinfo>$FreeBSD$</releaseinfo> + releaseinfo$&os;$releaseinfo - <abstract> - <para>Include an abstract of the book's contents here.</para> - </abstract> - </bookinfo> + abstract + paraInclude an abstract of the book's contents here.para + abstract + bookinfo … -</book> +book @@ -245,33 +245,33 @@ - <article> - <articleinfo> - <title>Your title here</title> + article + articleinfo + titleYour title heretitle - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>Your email address</email></address> - </affiliation> - </author> + author + firstnameYour first namefirstname + surnameYour surnamesurname + affiliation + addressemailYour email addressemailaddress + affiliation + author - <copyright> - <year>1998</year> - <holder role="mailto:your email address">Your name</holder> - </copyright> + copyright + year1998year + holder role="mailto:your email address"Your nameholder + copyright - <releaseinfo>$FreeBSD$</releaseinfo> + releaseinfo$&os;$releaseinfo - <abstract> - <para>Include an abstract of the article's contents here.</para> - </abstract> - </articleinfo> + abstract + paraInclude an abstract of the article's contents here.para + abstract + articleinfo … -</article> +article @@ -286,11 +286,11 @@ A Simple Chapter - - The Chapter's Title + chapter + titleThe Chapter's Titletitle ... -]]> +chapter A chapter cannot be empty; it must contain elements in @@ -301,11 +301,11 @@ Empty Chapters - - This is An Empty Chapter + chapter + titleThis is An Empty Chaptertitle - -]]> + parapara +chapter @@ -330,45 +330,66 @@ Sections in Chapters - - A Sample Chapter + chapter + titleA Sample Chaptertitle - Some text in the chapter. + paraSome text in the chapter.para - - First Section (1.1) + sect1 + titleFirst Sectiontitle … - + sect1 - - Second Section (1.2) + sect1 + titleSecond Sectiontitle - - First Sub-Section (1.2.1) + sect2 + titleFirst Sub-Sectiontitle - - First Sub-Sub-Section (1.2.1.1) + sect3 + titleFirst Sub-Sub-Sectiontitle - … - - + … + sect3 + sect2 - - Second Sub-Section (1.2.2) + sect2 + titleSecond Sub-Section (1.2.2)title … - - -]]> + sect2 + sect1 +chapter - This example includes section numbers in the section - titles. You should not do this in your documents. Adding - the section numbers is carried out by the stylesheets (of - which more later), and you do not need to manage them - yourself. + 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: + + + + 1.1. First Section + + + + 1.2. Second Section + + + + 1.2.1. First Sub-Section + + + + 1.2.1.1. First Sub-Sub-Section + + + + 1.2.2. Second Sub-Section + + @@ -382,27 +403,27 @@ parts. This cannot be done in an article. - - Introduction + part + titleIntroductiontitle - - Overview + chapter + titleOverviewtitle ... - + chapter - - What is FreeBSD? + chapter + titleWhat is FreeBSD?title ... - + chapter - - History + chapter + titleHistorytitle ... - -]]> + chapter +part @@ -428,8 +449,8 @@ Usage: - This is a paragraph. It can contain just about any - other element. ]]> + paraThis is a paragraph. It can contain just about any + other element.para Appearance: @@ -454,20 +475,20 @@ Usage: - A small excerpt from the US Constitution: + paraA small excerpt from the US Constitution:para -
- Preamble to the Constitution of the United States +blockquote + titlePreamble to the Constitution of the United Statestitle - Copied from a web site somewhere + attributionCopied from a web site somewhereattribution - We the People of the United States, in Order to form a more + paraWe 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. -
]]> + America.para +blockquote Appearance: @@ -537,10 +558,10 @@ Usage: - - Installing FreeBSD may make you want to delete Windows from your - hard disk. -]]> + warning + paraInstalling FreeBSD may make you want to delete Windows from your + hard disk.para +warning Appearance: @@ -588,39 +609,39 @@ Usage: - - - This is the first itemized item. - + itemizedlist + listitem + paraThis is the first itemized item.para + listitem - - This is the second itemized item. - - + listitem + paraThis is the second itemized item.para + listitem +itemizedlist - - - This is the first ordered item. - +orderedlist + listitem + paraThis is the first ordered item.para + listitem - - This is the second ordered item. - - + listitem + paraThis is the second ordered item.para + listitem +orderedlist - - - Do this. - +procedure + step + paraDo this.para + step - - Then do this. - + step + paraThen do this.para + step - - And now do this. - -]]> + step + paraAnd now do this.para + step +procedure Appearance: @@ -683,16 +704,16 @@ Usage: - When finished, the program will look like - this: + paraWhen finished, the program will look like + this:para -#include <stdio.h> +programlisting#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); -}]]> +}programlisting Notice how the angle brackets in the #include line need to be referenced by @@ -715,49 +736,46 @@ main(void) Callouts - A callout is a mechanism for referring back to an - earlier piece of text or specific position within an earlier - example without linking to it within the text. + A callout is a visual marker for referring to a + piece of text or specific position within an + example. - To do this, mark areas of interest in the example - (programlisting, - literallayout, or whatever) with the + Callouts are marked with the co element. Each element must have a unique id assigned to it. After the - example include a calloutlist that refers - back to the example and provides additional - commentary. + example, include a calloutlist that describes + each callout. <sgmltag>co</sgmltag> and <sgmltag>calloutlist</sgmltag> - When finished, the program will look like - this: + paraWhen finished, the program will look like + this:para -#include <stdio.h> +programlisting#include &lt;stdio.h&gt; co id="co-ex-include" -int +int co id="co-ex-return" main(void) { - printf("hello, world\n"); -} + printf("hello, world\n"); co id="co-ex-printf" +}programlisting - - - Includes the standard IO header file. - +calloutlist + callout arearefs="co-ex-include" + paraIncludes the standard IO header file.para + callout - - Specifies that main() returns an - int. - + callout arearefs="co-ex-return" + paraSpecifies that functionmain()function returns an + int.para + callout - - The printf() call that writes - hello, world to standard output. - -]]> + callout arearefs="co-ex-printf" + paraThe functionprintf()function call that writes + literalhello, worldliteral to standard output.para + callout +calloutlist Appearance: @@ -820,28 +838,28 @@ main(void) Usage: - - - - - This is Column Head 1 - This is Column Head 2 - - + informaltable pgwide="1" + tgroup cols="2" + thead + row + entryThis is Column Head 1entry + entryThis is Column Head 2entry + row + thead - - - Row 1, column 1 - Row 1, column 2 - + tbody + row + entryRow 1, column 1entry + entryRow 1, column 2entry + row - - Row 2, column 1 - Row 2, column 2 - - - -]]> + row + entryRow 2, column 1entry + entryRow 2, column 2entry + row + tbody + tgroup +informaltable Appearance: @@ -878,7 +896,7 @@ main(void) Table borders can be suppressed by setting the frame attribute to none in the informaltable element. For example, - <informaltable frame="none">. + informaltable frame="none". Tables Where <literal>frame="none"</literal> @@ -981,16 +999,16 @@ main(void) Usage: - &prompt.user; ls -1 + screen&prompt.user; userinputls -1userinput foo1 foo2 foo3 -&prompt.user; ls -1 | grep foo2 +&prompt.user; userinputls -1 | grep foo2userinput foo2 -&prompt.user; su -Password: -&prompt.root; cat foo2 -This is the file called 'foo2']]> +&prompt.user; userinputsuuserinput +promptPassword: prompt +&prompt.root; userinputcat foo2userinput +This is the file called 'foo2'screen Appearance: @@ -1040,8 +1058,8 @@ This is the file called 'foo2' Usage: - FreeBSD is without doubt the - premiere Unix like operating system for the Intel architecture.]]> + paraFreeBSD is without doubt emphasistheemphasis + premiere Unix like operating system for the Intel architecture.para Appearance: @@ -1065,9 +1083,9 @@ This is the file called 'foo2' Usage: - However, make sure that the search does not go beyond the - boundary between local and public administration, - as RFC 1535 calls it.]]> + paraHowever, make sure that the search does not go beyond the + quoteboundary between local and public administrationquote, + as RFC 1535 calls it.para Appearance: @@ -1103,18 +1121,18 @@ This is the file called 'foo2' Usage: - To switch to the second virtual terminal, press - Alt - F1. + paraTo switch to the second virtual terminal, press + keycombo action="simul"keycapAltkeycap + keycapF1keycapkeycombo.para -To exit vi without saving changes, type - Esc: - q!. +paraTo exit commandvicommand without saving changes, type + keycombo action="seq"keycapEsckeycapkeycap:keycap + keycapqkeycapkeycap!keycapkeycombo.para -My window manager is configured so that - Alt - right - mouse button is used to move windows.]]> +paraMy window manager is configured so that + keycombo action="simul"keycapAltkeycap + mousebuttonrightmousebutton + keycombo mouse button is used to move windows.para Appearance: @@ -1215,22 +1233,22 @@ This is the file called 'foo2' Usage: - Sendmail is the most - widely used Unix mail application. + paraapplicationSendmailapplication is the most + widely used Unix mail application.para -Sendmail includes the - - sendmail - 8 - , &man.mailq.1;, and &man.newaliases.1; - programs. +paraapplicationSendmailapplication includes the + citerefentry + refentrytitlesendmailrefentrytitle + manvolnum8manvolnum + citerefentry, &man.mailq.1;, and &man.newaliases.1; + programs.para -One of the command line parameters to - sendmail - 8 - , , will display the current +paraOne of the command line parameters to citerefentry + refentrytitlesendmailrefentrytitle + manvolnum8manvolnum + citerefentry, option-bpoption, will display the current status of messages in the mail queue. Check this on the command - line by running sendmail -bp.]]> + line by running commandsendmail -bpcommand.para Appearance: @@ -1272,12 +1290,12 @@ This is the file called 'foo2' Usage: - The XML source for the Handbook in English is - found in /usr/doc/en_US.ISO8859-1/books/handbook/. The first - file is called book.xml in that - directory. There is also a Makefile - and a number of files with a .ent - extension.]]> + paraThe XML source for the Handbook in English is + found in filename class="directory"/usr/doc/en_US.ISO8859-1/books/handbook/filename. The first + file is called filenamebook.xmlfilename in that + directory. There is also a filenameMakefilefilename + and a number of files with a filename.entfilename + extension.para Appearance: @@ -1316,7 +1334,7 @@ This is the file called 'foo2' Usage: - Install the net/wireshark port to view network traffic.]]> + paraInstall the filename role="package"net/wiresharkfilename port to view network traffic.para Appearance: @@ -1352,17 +1370,17 @@ This is the file called 'foo2' Usage: - sio is used for serial - communication in FreeBSD. sio manifests - through a number of entries in /dev, including - /dev/ttyd0 and /dev/cuaa0. + paradevicenamesiodevicename is used for serial + communication in FreeBSD. devicenamesiodevicename manifests + through a number of entries in filename/devfilename, including + filename/dev/ttyd0filename and filename/dev/cuaa0filename.para -By contrast, network devices such as - ed0 do not appear in /dev. +paraBy contrast, network devices such as + devicenameed0devicename do not appear in filename/devfilename.para -In MS-DOS, the first floppy drive is referred to as - a:. In FreeBSD it is - /dev/fd0.]]> +paraIn MS-DOS, the first floppy drive is referred to as + devicenamea:devicename. In FreeBSD it is + filename/dev/fd0filename.para Appearance: @@ -1481,26 +1499,26 @@ This is the file called 'foo2' Usage: - The local machine can always be referred to by the - name localhost, which will have the IP - address 127.0.0.1. + paraThe local machine can always be referred to by the + name hostidlocalhosthostid, which will have the IP + address hostid role="ipaddr"127.0.0.1hostid.para -The FreeBSD.org +paraThe hostid role="domainname"FreeBSD.orghostid domain contains a number of different hosts, including - freefall.FreeBSD.org and - bento.FreeBSD.org. + hostid role="fqdn"freefall.FreeBSD.orghostid and + hostid role="fqdn"bento.FreeBSD.orghostid.para -When adding an IP alias to an - interface (using ifconfig) - always use a netmask of - 255.255.255.255 (which can +paraWhen adding an acronymIPacronym alias to an + interface (using commandifconfigcommand) + emphasisalwaysemphasis use a netmask of + hostid role="netmask"255.255.255.255hostid (which can also be expressed as - 0xffffffff). + hostid role="netmask"0xffffffffhostid).para -The MAC address uniquely identifies +paraThe acronymMACacronym address uniquely identifies every network card in existence. A typical - MAC address looks like - 08:00:20:87:ef:d0.]]> + acronymMACacronym address looks like + hostid role="mac"08:00:20:87:ef:d0hostid.para Appearance: @@ -1547,8 +1565,8 @@ This is the file called 'foo2' Usage: - To carry out most system administration functions - requires logging in as root.]]> + paraTo carry out most system administration functions + requires logging in as usernamerootusername.para Appearance: @@ -1587,19 +1605,19 @@ This is the file called 'foo2' Usage: - Two common targets in a Makefile - are all and - clean. + paraTwo common targets in a filenameMakefilefilename + are maketargetallmaketarget and + maketargetcleanmaketarget.para -Typically, invoking all will +paraTypically, invoking maketargetallmaketarget will rebuild the application, and invoking - clean will remove the temporary - files (.o for example) created by the - build process. + maketargetcleanmaketarget will remove the temporary + files (filename.ofilename for example) created by the + build process.para -clean may be controlled by a - number of variables, including CLOBBER - and RECURSE.]]> +paramaketargetcleanmaketarget may be controlled by a + number of variables, including makevarCLOBBERmakevar + and makevarRECURSEmakevar.para Appearance: @@ -1642,10 +1660,10 @@ This is the file called 'foo2' Usage: - The maxusers 10 line in the kernel + paraThe literalmaxusers 10literal 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.]]> + support.para Appearance: @@ -1675,7 +1693,7 @@ This is the file called 'foo2' Usage: - &prompt.user; man command]]> + screen&prompt.user; userinputman replaceablecommandreplaceableuserinputscreen Appearance: @@ -1693,13 +1711,13 @@ This is the file called 'foo2' Usage: - The maxusers n + paraThe literalmaxusers replaceablenreplaceableliteral 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. + support.para -For a desktop workstation, 32 is a good value - for n.]]> +paraFor a desktop workstation, literal32literal is a good value + for replaceablenreplaceable.para Appearance: @@ -1726,7 +1744,7 @@ This is the file called 'foo2' Usage: - Panic: cannot mount root]]> + screenerrornamePanic: cannot mount rooterrornamescreen Appearance: @@ -1781,8 +1799,8 @@ This is the file called 'foo2' images should be committed to the documentation repository. - Use the appropriate format for each image. It is to be - expected that documentation will have a mix of + Use the appropriate format for each image. Documentation + will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. @@ -1791,7 +1809,7 @@ This is the file called 'foo2' formats. - It is anticipated that the Documentation Project will + The Documentation Project may eventually switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes