4f09d6756f
installed by the current docproj port, and in fact it conflicts with jade so one cannot install it along side the normal docproj port. Reported by: Alejandro Pulver
281 lines
10 KiB
Text
281 lines
10 KiB
Text
<!-- 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 JadeTeX 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 JadeTeX (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 HTML or ASCII
|
|
text output if you do not install <application>JadeTeX</application>.
|
|
PostScript or PDF output require &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 HTML, 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 HTML <quote>pretty printer</quote>, used to reformat some of the
|
|
automatically generated HTML 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
|
|
HTML 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>HTML DTD (<filename role="package">textproc/html</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>HTML 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 SGML documents, please let &a.doceng; know, so they
|
|
can be added to this list.</para>
|
|
</sect2>
|
|
</sect1>
|
|
</chapter>
|
|
|
|
<!--
|
|
Local Variables:
|
|
mode: sgml
|
|
sgml-declaration: "../chapter.decl"
|
|
sgml-indent-data: t
|
|
sgml-omittag: nil
|
|
sgml-always-quote-attributes: t
|
|
sgml-parent-document: ("../book.sgml" "part" "chapter")
|
|
End:
|
|
-->
|