Update the Tools chapter. Simplify, remove irrelevant and outdated

information.

1 files changed, 52 insertions, 142 deletions

diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
index f18f63a6ae..40e197584c 100644
--- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
@@ -34,132 +34,51 @@
 <chapter id="tools">
   <title>Tools</title>
 
-  <para>The FDP uses a number of different software tools to help
-    manage the FreeBSD documentation, convert it to different output
-    formats, and so on.  You will need to use these tools yourself if
-    you are to work with the FreeBSD documentation.</para>
-
-  <para>All these tools are available as FreeBSD Ports and Packages,
-    greatly simplifying the work you have to do to install
-    them.</para>
-
-  <para>You will need to install these tools before you work through
-    any of the examples in later chapters.  The actual usage of these
-    tools is covered in later chapters.</para>
-
-  <tip>
-    <title>Use <filename role="package">textproc/docproj</filename> If
-      Possible</title>
-
-    <para>You can save yourself a lot of time if you install the
-      <filename role="package">textproc/docproj</filename> port.  This
-      is a <emphasis>meta-port</emphasis> which does not contain any
-      software itself.  Instead, it depends on various other ports
-      being installed correctly.  Installing this port
-      <emphasis>should</emphasis> automatically download and install
-      all of the packages listed in this chapter that you need.</para>
-
-    <para>One of the packages that you might need is the
-      <application>JadeTeX</application> macro set.  In turn, this
-      macro set requires &tex; to be installed.  &tex; is a large
-      package, and you only need it if you want to produce Postscript
-      or PDF output.</para>
-
-    <para>To save yourself time and space you must specify whether or
-      not you want <application>JadeTeX</application> (and therefore
-      &tex;) installed when you install this port.  Either do:</para>
-
-    <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
-
-    <para>or</para>
-
-    <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
-
-    <para>as necessary.  Alternatively you may install
-      <filename role="package">textproc/docproj-jadetex</filename> or
-      <filename role="package">textproc/docproj-nojadetex</filename>.
-      These slave ports define the <makevar>JADETEX</makevar> variable
-      for you, therefore they will install the same suite of
-      applications on your machine.  Note that you can produce only
-      XHTML or ASCII text output if you do not install
-      <application>JadeTeX</application>.  PostScript or PDF output
-      requires &tex;.</para>
-  </tip>
-
-  <sect1 id="tools-mandatory">
-    <title>Mandatory Tools</title>
+  <para>Several software tools are used to
+    manage the FreeBSD documentation and render it to different output
+    formats.  Some of these tools are required and must be installed
+    before working through the examples in the following chapters.
+    Some are optional, adding capabilities or making the job of
+    creating documentation less demanding.</para>
+
+  <sect1 id="tools-required">
+    <title>Required Tools</title>
+
+    <para>Install
+      <filename role="package">textproc/docproj</filename> from the
+      Ports Collection.  This <emphasis>meta-port</emphasis> installs
+      all the applications required to do useful work with the &os;
+      documentation.  Some further notes on particular components are
+      given below.</para>
 
     <sect2>
-      <title>Software</title>
-
-      <para>These programs are required before you can usefully work
-	with the FreeBSD documentation, and they will allow you to
-	convert the documentation to XHTML, plain text, and RTF
-	formats.  They are all included in <filename
-	  role="package">textproc/docproj</filename>.</para>
-
-      <variablelist>
-	<varlistentry>
-	  <term><application>Jade</application>
-	    (<filename role="package">textproc/jade</filename>)</term>
-
-	  <listitem>
-	    <para>A DSSSL implementation.  Used for converting marked
-	      up documents to other formats, including HTML and
-	      &tex;.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><application>Links</application>
-	    (<filename role="package">www/links</filename>)</term>
-
-	  <listitem>
-	    <para>A text-mode WWW browser that can also convert
-	      XHTML files to plain text.</para>
-	  </listitem>
-	</varlistentry>
-
-	<varlistentry>
-	  <term><application>peps</application>
-	    (<filename role="package">graphics/peps</filename>)</term>
+      <title><acronym>DTD</acronym>s and <acronym>Entities</acronym></title>
 
-	  <listitem>
-	    <para>Some of the documentation includes images, some of
-	      which are stored as EPS files.  These must be converted
-	      to PNG before most web browsers will display
-	      them.</para>
-	  </listitem>
-	</varlistentry>
-      </variablelist>
-    </sect2>
-
-    <sect2>
-      <title>DTDs and Entities</title>
-
-      <para>These are the DTDs and entity sets used by the FDP.  They
-	need to be installed before you can work with any of the
-	documentation.</para>
+      <para>&os; documentation uses several Document Type Definitions
+	(<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym>
+	entities.  These are all installed by the
+	<filename role="package">textproc/docproj</filename>
+	port.</para>
 
       <variablelist>
 	<varlistentry>
-	  <term>XHTML DTD (<filename
+	  <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<filename
 	      role="package">textproc/xhtml</filename>)</term>
 
 	  <listitem>
-	    <para>XHTML is the markup language of choice for the World
-	      Wide Web, and is used throughout the FreeBSD web
+	    <para><acronym>XHTML</acronym> is the markup language of choice for the World
+	      Wide Web, and is used throughout the &os; web
 	      site.</para>
 	  </listitem>
 	</varlistentry>
 
 	<varlistentry>
-	  <term>DocBook DTD (<filename
+	  <term>DocBook <acronym>DTD</acronym> (<filename
 	      role="package">textproc/docbook-xml-450</filename>)</term>
 
 	  <listitem>
 	    <para>DocBook is designed for marking up technical
-	      documentation.  All the FreeBSD documentation is written
+	      documentation.  Most of the &os; documentation is written
 	      in DocBook.</para>
 	  </listitem>
 	</varlistentry>
@@ -170,8 +89,8 @@
 	      role="package">textproc/iso8879</filename>)</term>
 
 	  <listitem>
-	    <para>19 of the ISO 8879:1986 character entity sets used
-	      by many DTDs.  Includes named mathematical symbols,
+	    <para>Character entities from the ISO 8879:1986 standard used
+	      by many <acronym>DTD</acronym>s.  Includes named mathematical symbols,
 	      additional characters in the Latin character set
 	      (accents, diacriticals, and so on), and Greek
 	      symbols.</para>
@@ -184,10 +103,8 @@
   <sect1 id="tools-optional">
     <title>Optional Tools</title>
 
-    <para>You do not need to have any of the following installed.
-      However, you may find it easier to work with the documentation
-      if you do, and they may give you more flexibility in the output
-      formats that can be generated.</para>
+    <para>These applications are not required, but can make working on
+      the documentation easier or add capabilities.</para>
 
     <sect2>
       <title>Software</title>
@@ -205,23 +122,24 @@
 	      <application>teTeX</application> and Modular DocBook Stylesheets are used to convert
 	      DocBook documents to DVI, Postscript, and PDF formats.
 	      The <application>JadeTeX</application> macros are needed
-	      in order to do this.</para>
-
-	    <para>If you do not intend to convert your documentation
-	      to one of these formats (i.e., HTML and plain text
-	      are sufficient) then you do not need to install
-	      these.</para>
-
-	    <important>
-	      <para>If you decide to install
-		<application>JadeTeX</application> and
-		<application>teTeX</application> then you will need to
-		configure <application>teTeX</application> after
-		<application>JadeTeX</application> has been installed.
-		<filename>print/jadetex/pkg-message</filename>
-		contains detailed instructions explaining what you
-		need to do.</para>
-	    </important>
+	      to do this.</para>
+
+	    <para>If <acronym>XHTML</acronym> and plain text output
+	      formats are adequate, then this program is not needed
+	      and the option to install it from the
+	      <filename role="package">textproc/docproj</filename>
+	      configuration screen can be disabled.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>Vim</application>
+	  (<filename role="package">editors/vim</filename>)</term>
+
+	  <listitem>
+	    <para>A popular editor for working with
+	      <acronym>XML</acronym> and derived documents, like
+	      DocBook <acronym>XML</acronym>.</para>
 	  </listitem>
 	</varlistentry>
 
@@ -232,22 +150,14 @@
 	    <filename role="package">editors/xemacs</filename>)</term>
 
 	  <listitem>
-	    <para>Both these editors include a special mode for
-	      editing documents marked up according to an SGML DTD.
+	    <para>Both of these editors include a special mode for
+	      editing documents marked up according to an <acronym>XML</acronym> <acronym>DTD</acronym>.
 	      This mode includes commands to reduce the amount of
-	      typing you need, and help reduce the possibility of
+	      typing needed, and help reduce the possibility of
 	      errors.</para>
-
-	    <para>You do not need to use them; any text editor can be
-	      used to edit marked up documents.  You may find they
-	      make you more efficient.</para>
 	  </listitem>
 	</varlistentry>
       </variablelist>
-
-      <para>If anyone has recommendations for other software that is
-	useful when manipulating XML documents, please let &a.doceng;
-	know, so they can be added to this list.</para>
     </sect2>
   </sect1>
 </chapter>