282 lines
9.8 KiB
Text
282 lines
9.8 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.
|
|
-->
|
|
|
|
<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 these later chapters.</para>
|
|
|
|
<important>
|
|
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
|
|
|
<para>You can save yourself a lot of time if you install the
|
|
<filename>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 that are missing from your system.</para>
|
|
|
|
<para>One of the packages that you might need is the JadeTeX macro set.
|
|
In turn, this macro set requires that TeX is 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;
|
|
|
|
<screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen>
|
|
|
|
or
|
|
|
|
<screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen>
|
|
|
|
as necessary.</para>
|
|
</important>
|
|
|
|
<sect1>
|
|
<title>Mandatory tools</title>
|
|
|
|
<sect2>
|
|
<title>Software</title>
|
|
|
|
<para>These programs are required before you can usefully work with
|
|
the FreeBSD documentation. They are all included in
|
|
<filename>textproc/docproj</filename>.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><application>SP</application>
|
|
(<filename>textproc/sp</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>A suite of applications, including a validating SGML parser,
|
|
and an SGML normaliser.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><application>Jade</application>
|
|
(<filename>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>www/tidy</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>An HTML 'pretty printer', used to reformat some of the
|
|
automatically generated HTML so that it is easier to
|
|
follow.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><application>Lynx</application>
|
|
(<filename>www/lynx-current</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>A text-mode WWW browser, &man.lynx.1; can also convert
|
|
HTML files to plain text.</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>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>LinuxDoc DTD (<filename>textproc/linuxdoc</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>Some FreeBSD documentation is marked up in LinuxDoc. The
|
|
FDP is actively migrating from LinuxDoc to DocBook.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>DocBook DTD (<filename>textproc/docbook</filename>)</term>
|
|
|
|
<listitem>
|
|
<para>DocBook is designed for marking up technical documentation,
|
|
and the FDP is migrating from LinuxDoc to DocBook. At the time
|
|
of writing, this document, and the FreeBSD Handbook are marked
|
|
up in DocBook.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>ISO 8879 entities
|
|
(<filename>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>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>
|
|
<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>print/jadetex</filename> and
|
|
<filename>print/teTeX-beta</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>editors/emacs</filename> or
|
|
<filename>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
|
|
efficient.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>If anyone has recommendations for other software that is useful
|
|
when manipulating SGML documents, please let Nik Clayton
|
|
(<email>nik@freebsd.org</email>) 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:
|
|
-->
|