svn commit: r42333 - head/en_US.ISO8859-1/books/fdp-primer/docbook-markup

[Warren Block]

Author: wblock
Date: Sun Jul 21 00:35:30 2013
New Revision: 42333
URL: http://svnweb.freebsd.org/changeset/doc/42333

Log:
  Add more entity definitions and a section on using acronym elements.

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	Sat Jul 20 20:46:28 2013	(r42332)
+++ head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml	Sun Jul 21 00:35:30 2013	(r42333)
@@ -125,7 +125,12 @@
     <sect2 id="docbook-markup-freebsd-extensions-entities">
       <title>&os; Entities</title>
 
-      <table frame="none">
+      <para>These tables show some of the most useful entities
+	available in the <acronym>FDP</acronym>.  For a complete list,
+	see the <filename>*.ent</filename> files in
+	<filename class="directory">doc/share/xml</filename>.</para>
+
+      <table frame="none" pgwide="0">
 	<title>&os; Name Entities</title>
 
 	<tgroup cols="2">
@@ -155,7 +160,48 @@
 	</tgroup>
       </table>
 
-      <table frame="none">
+      <table frame="none" pgwide="0">
+	<title>Manual Page Entities</title>
+
+	<tgroup cols="3">
+	  <thead>
+	    <row>
+	      <entry>Name</entry>
+	      <entry>Expands To</entry>
+	      <entry>Notes</entry>
+	    </row>
+	  </thead>
+
+	  <tbody>
+	    <row>
+	      <entry><literal>&man.ls.1;</literal></entry>
+	      <entry>&man.ls.1;</entry>
+	      <entry>
+		<programlisting>Usage: &man.ls.1; is the manual page for <sgmltag class="starttag">command</sgmltag>ls<sgmltag class="endtag">command</sgmltag>.</programlisting></entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>&man.cp.1;</literal></entry>
+	      <entry>&man.cp.1;</entry>
+	      <entry>
+		<programlisting>Usage: The manual page for <sgmltag class="starttag">command</sgmltag>cp<sgmltag class="endtag">command</sgmltag> is &man.cp.1;.</programlisting></entry>
+	    </row>
+
+	    <row>
+	      <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry>
+	      <entry><emphasis>link to
+		<replaceable>command</replaceable> manual page in
+		section
+		<replaceable>sectionnumber</replaceable></emphasis></entry>
+	      <entry>Entities are defined for all the <ulink
+		  url="&url.base;/cgi/man.cgi">&os; manual
+		  pages</ulink>.</entry>
+	    </row>
+	  </tbody>
+	</tgroup>
+      </table>
+
+      <table frame="none" pgwide="0">
 	<title>&os; Mailing List Entities</title>
 
 	<tgroup cols="3">
@@ -194,7 +240,7 @@
 	</tgroup>
       </table>
 
-      <table frame="none">
+      <table frame="none" pgwide="0">
 	<title>&os; Document Links</title>
 
 	<tgroup cols="3">
@@ -242,7 +288,7 @@
 	</tgroup>
       </table>
 
-      <table frame="none">
+      <table frame="none" pgwide="0">
 	<title>Other Operating System Name Entities</title>
 
 	<tgroup cols="3">
@@ -276,7 +322,7 @@
 	</tgroup>
       </table>
 
-      <table frame="none">
+      <table frame="none" pgwide="0">
 	<title>Miscellaneous Entities</title>
 
 	<tgroup cols="3">
@@ -1285,13 +1331,44 @@ This is the file called 'foo2'</screen>
 
 	<programlisting><sgmltag class="starttag">para</sgmltag>However, make sure that the search does not go beyond the
   <sgmltag class="starttag">quote</sgmltag>boundary between local and public administration<sgmltag class="endtag">quote</sgmltag>,
-  as RFC 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting>
+  as <sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag> 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting>
 
 	<para>Appearance:</para>
 
 	<para>However, make sure that the search does not go beyond
 	  the <quote>boundary between local and public
-	    administration</quote>, as RFC 1535 calls it.</para>
+	    administration</quote>, as <acronym>RFC</acronym> 1535 calls it.</para>
+      </example>
+    </sect2>
+
+    <sect2 id="docbook-markup-acronyms">
+      <title>Acronyms</title>
+
+      <para>Many computer terms are <emphasis>acronyms</emphasis>,
+	words formed from the first letter of each word in a
+	phrase.  Acronyms are marked up into
+	<sgmltag>acronym</sgmltag> elements.  It is helpful to the
+	reader when an acronym is defined on the first use, as shown
+	in the example below.</para>
+
+      <example>
+	<title>Acronyms</title>
+
+	<para>Usage:</para>
+
+	<programlisting><sgmltag class="starttag">para</sgmltag>Request For Comments (<sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag>) 1149
+  defined the use of avian carriers for transmission of
+  Internet Protocol (<sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag>) data
+  transmission.  The quantity of <sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag> data
+  transmitted since then is unknown.<sgmltag class="endtag">para</sgmltag></programlisting>
+
+	<para>Appearance:</para>
+
+	<para>Request For Comments (<acronym>RFC</acronym>) 1149
+	  defined the use of avian carriers for transmission of
+	  Internet Protocol (<acronym>IP</acronym>) data
+	  transmission.  The quantity of <acronym>IP</acronym> data
+	  transmitted since then is unknown.</para>
       </example>
     </sect2>