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">
|
<chapter id="tools">
|
||||||
<title>Tools</title>
|
<title>Tools</title>
|
||||||
|
|
||||||
<para>The FDP uses a number of different software tools to help
|
<para>Several software tools are used to
|
||||||
manage the FreeBSD documentation, convert it to different output
|
manage the FreeBSD documentation and render it to different output
|
||||||
formats, and so on. You will need to use these tools yourself if
|
formats. Some of these tools are required and must be installed
|
||||||
you are to work with the FreeBSD documentation.</para>
|
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,
|
<sect1 id="tools-required">
|
||||||
greatly simplifying the work you have to do to install
|
<title>Required Tools</title>
|
||||||
them.</para>
|
|
||||||
|
|
||||||
<para>You will need to install these tools before you work through
|
<para>Install
|
||||||
any of the examples in later chapters. The actual usage of these
|
<filename role="package">textproc/docproj</filename> from the
|
||||||
tools is covered in later chapters.</para>
|
Ports Collection. This <emphasis>meta-port</emphasis> installs
|
||||||
|
all the applications required to do useful work with the &os;
|
||||||
<tip>
|
documentation. Some further notes on particular components are
|
||||||
<title>Use <filename role="package">textproc/docproj</filename> If
|
given below.</para>
|
||||||
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>
|
<sect2>
|
||||||
<title>Software</title>
|
<title><acronym>DTD</acronym>s and <acronym>Entities</acronym></title>
|
||||||
|
|
||||||
<para>These programs are required before you can usefully work
|
<para>&os; documentation uses several Document Type Definitions
|
||||||
with the FreeBSD documentation, and they will allow you to
|
(<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym>
|
||||||
convert the documentation to XHTML, plain text, and RTF
|
entities. These are all installed by the
|
||||||
formats. They are all included in <filename
|
<filename role="package">textproc/docproj</filename>
|
||||||
role="package">textproc/docproj</filename>.</para>
|
port.</para>
|
||||||
|
|
||||||
<variablelist>
|
<variablelist>
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><application>Jade</application>
|
<term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<filename
|
||||||
(<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
|
|
||||||
role="package">textproc/xhtml</filename>)</term>
|
role="package">textproc/xhtml</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>XHTML is the markup language of choice for the World
|
<para><acronym>XHTML</acronym> is the markup language of choice for the World
|
||||||
Wide Web, and is used throughout the FreeBSD web
|
Wide Web, and is used throughout the &os; web
|
||||||
site.</para>
|
site.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term>DocBook DTD (<filename
|
<term>DocBook <acronym>DTD</acronym> (<filename
|
||||||
role="package">textproc/docbook-xml-450</filename>)</term>
|
role="package">textproc/docbook-xml-450</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>DocBook is designed for marking up technical
|
<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>
|
in DocBook.</para>
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
@ -170,8 +89,8 @@
|
||||||
role="package">textproc/iso8879</filename>)</term>
|
role="package">textproc/iso8879</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>19 of the ISO 8879:1986 character entity sets used
|
<para>Character entities from the ISO 8879:1986 standard used
|
||||||
by many DTDs. Includes named mathematical symbols,
|
by many <acronym>DTD</acronym>s. Includes named mathematical symbols,
|
||||||
additional characters in the Latin character set
|
additional characters in the Latin character set
|
||||||
(accents, diacriticals, and so on), and Greek
|
(accents, diacriticals, and so on), and Greek
|
||||||
symbols.</para>
|
symbols.</para>
|
||||||
|
|
@ -184,10 +103,8 @@
|
||||||
<sect1 id="tools-optional">
|
<sect1 id="tools-optional">
|
||||||
<title>Optional Tools</title>
|
<title>Optional Tools</title>
|
||||||
|
|
||||||
<para>You do not need to have any of the following installed.
|
<para>These applications are not required, but can make working on
|
||||||
However, you may find it easier to work with the documentation
|
the documentation easier or add capabilities.</para>
|
||||||
if you do, and they may give you more flexibility in the output
|
|
||||||
formats that can be generated.</para>
|
|
||||||
|
|
||||||
<sect2>
|
<sect2>
|
||||||
<title>Software</title>
|
<title>Software</title>
|
||||||
|
|
@ -205,23 +122,24 @@
|
||||||
<application>teTeX</application> and Modular DocBook Stylesheets are used to convert
|
<application>teTeX</application> and Modular DocBook Stylesheets are used to convert
|
||||||
DocBook documents to DVI, Postscript, and PDF formats.
|
DocBook documents to DVI, Postscript, and PDF formats.
|
||||||
The <application>JadeTeX</application> macros are needed
|
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
|
<para>If <acronym>XHTML</acronym> and plain text output
|
||||||
to one of these formats (i.e., HTML and plain text
|
formats are adequate, then this program is not needed
|
||||||
are sufficient) then you do not need to install
|
and the option to install it from the
|
||||||
these.</para>
|
<filename role="package">textproc/docproj</filename>
|
||||||
|
configuration screen can be disabled.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<important>
|
<varlistentry>
|
||||||
<para>If you decide to install
|
<term><application>Vim</application>
|
||||||
<application>JadeTeX</application> and
|
(<filename role="package">editors/vim</filename>)</term>
|
||||||
<application>teTeX</application> then you will need to
|
|
||||||
configure <application>teTeX</application> after
|
<listitem>
|
||||||
<application>JadeTeX</application> has been installed.
|
<para>A popular editor for working with
|
||||||
<filename>print/jadetex/pkg-message</filename>
|
<acronym>XML</acronym> and derived documents, like
|
||||||
contains detailed instructions explaining what you
|
DocBook <acronym>XML</acronym>.</para>
|
||||||
need to do.</para>
|
|
||||||
</important>
|
|
||||||
</listitem>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
|
|
||||||
|
|
@ -232,22 +150,14 @@
|
||||||
<filename role="package">editors/xemacs</filename>)</term>
|
<filename role="package">editors/xemacs</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>Both these editors include a special mode for
|
<para>Both of these editors include a special mode for
|
||||||
editing documents marked up according to an SGML DTD.
|
editing documents marked up according to an <acronym>XML</acronym> <acronym>DTD</acronym>.
|
||||||
This mode includes commands to reduce the amount of
|
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>
|
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>
|
</listitem>
|
||||||
</varlistentry>
|
</varlistentry>
|
||||||
</variablelist>
|
</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>
|
</sect2>
|
||||||
</sect1>
|
</sect1>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue