Update the Tools chapter. Simplify, remove irrelevant and outdated
information.
This commit is contained in:
Warren Block
parent
c102a85daa
commit
34d4eab35a
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42305
1 changed files with 48 additions and 138 deletions
|
|
@ -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>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>
|
||||
|
||||
<para>All these tools are available as FreeBSD Ports and Packages,
|
||||
greatly simplifying the work you have to do to install
|
||||
them.</para>
|
||||
<sect1 id="tools-required">
|
||||
<title>Required Tools</title>
|
||||
|
||||
<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>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>
|
||||
<title><acronym>DTD</acronym>s and <acronym>Entities</acronym></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>
|
||||
<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><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>
|
||||
|
||||
<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
|
||||
<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>
|
||||
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>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
|
|
|
|||
Loading…
Reference in a new issue