path: root/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
diff options
authorWarren Block <wblock@FreeBSD.org>2013-07-17 00:02:19 +0000
committerWarren Block <wblock@FreeBSD.org>2013-07-17 00:02:19 +0000
commit34d4eab35a98932e8ffac2f2e01053e8cc3ac5c4 (patch)
tree9ae2314386c30fb18ced5e55e031b5a7564dfdab /en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml
parentc102a85daa05cceb1ceea4c42b066b6e8d65817d (diff)
Update the Tools chapter. Simplify, remove irrelevant and outdated
Notes: svn path=/head/; revision=42305
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml')
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">
- <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>
- <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>
- <term>XHTML DTD (<filename
+ <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<filename
- <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
- <term>DocBook DTD (<filename
+ <term>DocBook <acronym>DTD</acronym> (<filename
<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>
@@ -170,8 +89,8 @@
- <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
@@ -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>
@@ -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>
@@ -232,22 +150,14 @@
<filename role="package">editors/xemacs</filename>)</term>
- <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
- <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>
- <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>