- Rename .sgml files to .xml

- Reflect the rename in referencing files

Approved by:	doceng (implicit)

1 files changed, 289 insertions, 0 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
new file mode 100644
index 0000000000..979b907ffd
--- /dev/null
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
@@ -0,0 +1,289 @@
+<?xml version="1.0" encoding="iso-8859-1" standalone="no"?>
+<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
+
+     Redistribution and use in source (SGML DocBook) and 'compiled' forms
+     (SGML, HTML, PDF, PostScript, RTF and so forth) with or without
+     modification, are permitted provided that the following conditions
+     are met:
+
+      1. Redistributions of source code (SGML DocBook) must retain the above
+         copyright notice, this list of conditions and the following
+         disclaimer as the first lines of this file unmodified.
+
+      2. Redistributions in compiled form (transformed to other DTDs,
+         converted to PDF, PostScript, RTF and other formats) must reproduce
+         the above copyright notice, this list of conditions and the
+         following disclaimer in the documentation and/or other materials
+         provided with the distribution.
+
+     THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
+     OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+     DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
+     INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+     (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+     SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+     HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+     STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+     ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
+     POSSIBILITY OF SUCH DAMAGE.
+
+     $FreeBSD$
+-->
+
+<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>
+
+    <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>Tidy</application>
+	    (<filename role="package">www/tidy</filename>)</term>
+
+	  <listitem>
+	    <para>An (X)HTML <quote>pretty printer</quote>, used to
+	      reformat some of the automatically generated pages so
+	      that it is easier to follow.</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>
+
+	  <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>
+
+      <variablelist>
+	<varlistentry>
+	  <term>XHTML DTD (<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
+	      site.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>DocBook DTD (<filename
+	      role="package">textproc/docbook</filename>)</term>
+
+	  <listitem>
+	    <para>DocBook is designed for marking up technical
+	      documentation.  All the FreeBSD documentation is written
+	      in DocBook.</para>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term>ISO 8879 entities
+	    (<filename
+	      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,
+	      additional characters in the Latin character set
+	      (accents, diacriticals, and so on), and Greek
+	      symbols.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+
+    <sect2>
+      <title>Stylesheets</title>
+
+      <para>The stylesheets are used when converting and formatting
+	the documentation for display on screen, printing, and so
+	on.</para>
+
+      <variablelist>
+	<varlistentry>
+	  <term>Modular DocBook Stylesheets
+	    (<filename
+	      role="package">textproc/dsssl-docbook-modular</filename>)</term>
+
+	  <listitem>
+	    <para>The Modular DocBook Stylesheets are used when
+	      converting documentation marked up in DocBook to other
+	      formats, such as HTML or RTF.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect2>
+  </sect1>
+
+  <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>
+
+    <sect2>
+      <title>Software</title>
+
+      <variablelist>
+	<varlistentry>
+	  <term><application>JadeTeX</application> and
+	    <application>teTeX</application>
+	    (<filename role="package">print/jadetex</filename> and
+	    <filename role="package">print/teTeX</filename>)</term>
+
+	  <listitem>
+	    <para><application>Jade</application> and
+	      <application>teTeX</application> 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, plain text, and RTF
+	      are sufficient) then you do not need to install
+	      <application>JadeTeX</application> and
+	      <application>teTeX</application>.  This can be a
+	      significant space and time saver, as
+	      <application>teTeX</application> is over 30MB in
+	      size.</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>
+	  </listitem>
+	</varlistentry>
+
+	<varlistentry>
+	  <term><application>Emacs</application> or
+	    <application>XEmacs</application>
+	    (<filename role="package">editors/emacs</filename> or
+	    <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.
+	      This mode includes commands to reduce the amount of
+	      typing you need, 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>