Re-write. Fill in the missing gaps, order it better, make it complete.
This commit is contained in:
Nik Clayton
parent
c2e6d4a096
commit
d3d908e605
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=4775
3 changed files with 669 additions and 453 deletions
|
|
@ -1,9 +1,48 @@
|
||||||
<chapter id="tools">
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
|
||||||
<title>* Tools</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a number of tools to assist in the
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
||||||
production of documentation. You will need to install some or all of these
|
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
|
||||||
tools before you will be able to make changes.</para>
|
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>
|
<important>
|
||||||
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
||||||
|
|
@ -35,166 +74,199 @@
|
||||||
</important>
|
</important>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Software</title>
|
<title>Mandatory tools</title>
|
||||||
|
|
||||||
<para>The project uses the following applications;</para>
|
<sect2>
|
||||||
|
<title>Software</title>
|
||||||
|
|
||||||
<variablelist>
|
<para>These programs are required before you can usefully work with
|
||||||
<varlistentry>
|
the FreeBSD documentation. They are all included in
|
||||||
<term><application>Jade</application> and
|
<filename>textproc/docproj</filename>.</para>
|
||||||
<application>SP</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>These are two application suites by James Clark, who has
|
<varlistentry>
|
||||||
produced many useful SGML-processing applications.
|
<term><application>SP</application>
|
||||||
<application>Jade</application> is “James' DSSSL
|
(<filename>textproc/sp</filename>)</term>
|
||||||
Engine”, a system that takes SGML documentation and a DSSSL
|
|
||||||
stylesheet and produces converted output.
|
|
||||||
<application>SP</application> contains a number of useful
|
|
||||||
applications to manipulate, normalise, and interrogate SGML
|
|
||||||
documents.</para>
|
|
||||||
|
|
||||||
<para>Don't be concerned if these terms are unfamliar to you.</para>
|
<listitem>
|
||||||
|
<para>A suite of applications, including a validating SGML parser,
|
||||||
|
and an SGML normaliser.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>They can be found in the ports system as
|
<varlistentry>
|
||||||
<filename>textproc/jade</filename> and
|
<term><application>Jade</application>
|
||||||
<filename>textproc/sp</filename> respectively.</para>
|
(<filename>textproc/jade</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Installed as part of
|
<para>A DSSSL implementation. Used for converting marked up
|
||||||
<filename>textproc/docproj</filename>.</para>
|
documents to other formats, including HTML and TeX.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><application>teTeX</application></term>
|
<term><application>Tidy</application>
|
||||||
|
(<filename>www/tidy</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para><application>teTeX</application> is a distrubution of the TeX
|
<para>An HTML 'pretty printer', used to reformat some of the
|
||||||
typesetting system, and is used (in conjunction with Jade) to
|
automatically generated HTML so that it is easier to
|
||||||
produce the Postscript and PDF output formats.</para>
|
follow.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>v0.9 of <application>teTeX</application> is required, which is
|
<varlistentry>
|
||||||
currently in the ports collection as
|
<term><application>Lynx</application>
|
||||||
<filename>print/teTeX-beta</filename>.</para>
|
(<filename>www/lynx-current</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Might be installed as part of
|
<para>A text-mode WWW browser, &man.lynx.1; can also convert
|
||||||
<filename>textproc/docproj</filename>, depending on the
|
HTML files to plain text.</para>
|
||||||
<makevar>JADETEX</makevar> setting.</para>
|
</listitem>
|
||||||
</note>
|
</varlistentry>
|
||||||
</listitem>
|
</variablelist>
|
||||||
</varlistentry>
|
</sect2>
|
||||||
|
|
||||||
<varlistentry>
|
<sect2>
|
||||||
<term><application>Emacs</application> or
|
<title>DTDs and Entities</title>
|
||||||
<application>Xemacs</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<para>These are the DTDs and entity sets used by the FDP. They need to
|
||||||
<para>Neither of these programs is required. However, both of them
|
be installed before you can work with any of the documentation.</para>
|
||||||
feature PSGML-MODE, a useful extension when dealing with SGML
|
|
||||||
documents that can reduce the amount of typing you need to do, and
|
|
||||||
remove some of the more obvious errors.</para>
|
|
||||||
|
|
||||||
<para>They can be found in <filename>editor/emacs20</filename> and
|
<variablelist>
|
||||||
<filename>editor/xemacs20</filename>.</para>
|
<varlistentry>
|
||||||
|
<term>HTML DTD (<filename>textproc/html</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Not installed as part of
|
<para>HTML is the markup language of choice for the World Wide
|
||||||
<filename>textproc/docproj</filename>.</para>
|
Web, and is used throughout the FreeBSD web site.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
<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>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Document Type Definitions (DTDs)</title>
|
<title>Optional tools</title>
|
||||||
|
|
||||||
<para>The project uses the following DTDs;</para>
|
<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>
|
||||||
|
|
||||||
<variablelist>
|
<sect2>
|
||||||
<varlistentry>
|
<title>Software</title>
|
||||||
<term>HTML</term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>HTML, the HyperText Markup Language, is the markup language of
|
<varlistentry>
|
||||||
choice on the World Wide Web. More information can be found at
|
<term><application>JadeTeX</application> and
|
||||||
<URL:<ulink
|
<application>teTeX</application>
|
||||||
url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para>
|
(<filename>print/jadetex</filename> and
|
||||||
|
<filename>print/teTeX-beta</filename>)</term>
|
||||||
|
|
||||||
<para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
|
<listitem>
|
||||||
and the latest, 4.0 (available in both <emphasis>strict</emphasis>
|
<para><application>Jade</application> and
|
||||||
and <emphasis>loose</emphasis> variants).</para>
|
<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>The HTML DTDs are available from the ports collection in the
|
<para>If you do not intend to convert your documentation to one of
|
||||||
<filename>textproc/html</filename> category.</para>
|
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>
|
||||||
|
|
||||||
<note>
|
<important>
|
||||||
<para>Installed as part of
|
<para>If you decide to install
|
||||||
<filename>textproc/docproj</filename>.</para>
|
<application>JadeTeX</application> and
|
||||||
</note>
|
<application>teTeX</application> then you will need to
|
||||||
</listitem>
|
configure <application>teTeX</application> after
|
||||||
</varlistentry>
|
<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>
|
<varlistentry>
|
||||||
<term>LinuxDoc</term>
|
<term><application>Emacs</application> or
|
||||||
|
<application>xemacs</application>
|
||||||
|
(<filename>editors/emacs</filename> or
|
||||||
|
<filename>editors/xemacs</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
|
<para>Both these editors include a special mode for editing
|
||||||
the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
|
documents marked up according to an SGML DTD. This mode
|
||||||
Project</ulink>, and subsequently adopted by the FreeBSD
|
includes commands to reduce the amount of typing you need, and
|
||||||
Documentation Project.</para>
|
help reduce the possibility of errors.</para>
|
||||||
|
|
||||||
<para>The LinuxDoc DTD contains primarily appearance related markup
|
<para>You do not need to use them, any text editor can be used to
|
||||||
rather than content related markup (i.e., it describes what
|
edit marked up documents. Yoy may find they make you
|
||||||
something looks like rather than what it is).</para>
|
efficient.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
<para>Both the FreeBSD Documentation Project and the Linux
|
<para>If anyone has recommendations for other software that is useful
|
||||||
Documentation Project are migrating from the LinuxDoc DTD to the
|
when manipulating SGML documents, please let Nik Clayton
|
||||||
DocBook DTD.</para>
|
(<email>nik@freebsd.org</email>) know, so they can be added to this
|
||||||
|
list.</para>
|
||||||
<para>The LinuxDoc DTD is available from the ports collection in the
|
</sect2>
|
||||||
<filename>textproc/linuxdoc</filename> category.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>DocBook</term>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>DocBook was designed by the <ulink
|
|
||||||
url="http://www.oreilly.com/davenport/">Davenport Group</ulink>
|
|
||||||
to be a DTD for writing technical documentation. As such, it
|
|
||||||
contains XXX</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1>
|
|
||||||
<title>DSSSL Stylesheets</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a slightly customised version of
|
|
||||||
Norm Walsh's modular DocBook stylesheets.</para>
|
|
||||||
|
|
||||||
<para>These can be found in
|
|
||||||
<filename>textproc/dsssl-docbook-modular</filename>.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</sect1>
|
</sect1>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,48 @@
|
||||||
<chapter id="tools">
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
|
||||||
<title>* Tools</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a number of tools to assist in the
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
||||||
production of documentation. You will need to install some or all of these
|
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
|
||||||
tools before you will be able to make changes.</para>
|
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>
|
<important>
|
||||||
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
||||||
|
|
@ -35,166 +74,199 @@
|
||||||
</important>
|
</important>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Software</title>
|
<title>Mandatory tools</title>
|
||||||
|
|
||||||
<para>The project uses the following applications;</para>
|
<sect2>
|
||||||
|
<title>Software</title>
|
||||||
|
|
||||||
<variablelist>
|
<para>These programs are required before you can usefully work with
|
||||||
<varlistentry>
|
the FreeBSD documentation. They are all included in
|
||||||
<term><application>Jade</application> and
|
<filename>textproc/docproj</filename>.</para>
|
||||||
<application>SP</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>These are two application suites by James Clark, who has
|
<varlistentry>
|
||||||
produced many useful SGML-processing applications.
|
<term><application>SP</application>
|
||||||
<application>Jade</application> is “James' DSSSL
|
(<filename>textproc/sp</filename>)</term>
|
||||||
Engine”, a system that takes SGML documentation and a DSSSL
|
|
||||||
stylesheet and produces converted output.
|
|
||||||
<application>SP</application> contains a number of useful
|
|
||||||
applications to manipulate, normalise, and interrogate SGML
|
|
||||||
documents.</para>
|
|
||||||
|
|
||||||
<para>Don't be concerned if these terms are unfamliar to you.</para>
|
<listitem>
|
||||||
|
<para>A suite of applications, including a validating SGML parser,
|
||||||
|
and an SGML normaliser.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>They can be found in the ports system as
|
<varlistentry>
|
||||||
<filename>textproc/jade</filename> and
|
<term><application>Jade</application>
|
||||||
<filename>textproc/sp</filename> respectively.</para>
|
(<filename>textproc/jade</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Installed as part of
|
<para>A DSSSL implementation. Used for converting marked up
|
||||||
<filename>textproc/docproj</filename>.</para>
|
documents to other formats, including HTML and TeX.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><application>teTeX</application></term>
|
<term><application>Tidy</application>
|
||||||
|
(<filename>www/tidy</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para><application>teTeX</application> is a distrubution of the TeX
|
<para>An HTML 'pretty printer', used to reformat some of the
|
||||||
typesetting system, and is used (in conjunction with Jade) to
|
automatically generated HTML so that it is easier to
|
||||||
produce the Postscript and PDF output formats.</para>
|
follow.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>v0.9 of <application>teTeX</application> is required, which is
|
<varlistentry>
|
||||||
currently in the ports collection as
|
<term><application>Lynx</application>
|
||||||
<filename>print/teTeX-beta</filename>.</para>
|
(<filename>www/lynx-current</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Might be installed as part of
|
<para>A text-mode WWW browser, &man.lynx.1; can also convert
|
||||||
<filename>textproc/docproj</filename>, depending on the
|
HTML files to plain text.</para>
|
||||||
<makevar>JADETEX</makevar> setting.</para>
|
</listitem>
|
||||||
</note>
|
</varlistentry>
|
||||||
</listitem>
|
</variablelist>
|
||||||
</varlistentry>
|
</sect2>
|
||||||
|
|
||||||
<varlistentry>
|
<sect2>
|
||||||
<term><application>Emacs</application> or
|
<title>DTDs and Entities</title>
|
||||||
<application>Xemacs</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<para>These are the DTDs and entity sets used by the FDP. They need to
|
||||||
<para>Neither of these programs is required. However, both of them
|
be installed before you can work with any of the documentation.</para>
|
||||||
feature PSGML-MODE, a useful extension when dealing with SGML
|
|
||||||
documents that can reduce the amount of typing you need to do, and
|
|
||||||
remove some of the more obvious errors.</para>
|
|
||||||
|
|
||||||
<para>They can be found in <filename>editor/emacs20</filename> and
|
<variablelist>
|
||||||
<filename>editor/xemacs20</filename>.</para>
|
<varlistentry>
|
||||||
|
<term>HTML DTD (<filename>textproc/html</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Not installed as part of
|
<para>HTML is the markup language of choice for the World Wide
|
||||||
<filename>textproc/docproj</filename>.</para>
|
Web, and is used throughout the FreeBSD web site.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
<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>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Document Type Definitions (DTDs)</title>
|
<title>Optional tools</title>
|
||||||
|
|
||||||
<para>The project uses the following DTDs;</para>
|
<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>
|
||||||
|
|
||||||
<variablelist>
|
<sect2>
|
||||||
<varlistentry>
|
<title>Software</title>
|
||||||
<term>HTML</term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>HTML, the HyperText Markup Language, is the markup language of
|
<varlistentry>
|
||||||
choice on the World Wide Web. More information can be found at
|
<term><application>JadeTeX</application> and
|
||||||
<URL:<ulink
|
<application>teTeX</application>
|
||||||
url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para>
|
(<filename>print/jadetex</filename> and
|
||||||
|
<filename>print/teTeX-beta</filename>)</term>
|
||||||
|
|
||||||
<para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
|
<listitem>
|
||||||
and the latest, 4.0 (available in both <emphasis>strict</emphasis>
|
<para><application>Jade</application> and
|
||||||
and <emphasis>loose</emphasis> variants).</para>
|
<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>The HTML DTDs are available from the ports collection in the
|
<para>If you do not intend to convert your documentation to one of
|
||||||
<filename>textproc/html</filename> category.</para>
|
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>
|
||||||
|
|
||||||
<note>
|
<important>
|
||||||
<para>Installed as part of
|
<para>If you decide to install
|
||||||
<filename>textproc/docproj</filename>.</para>
|
<application>JadeTeX</application> and
|
||||||
</note>
|
<application>teTeX</application> then you will need to
|
||||||
</listitem>
|
configure <application>teTeX</application> after
|
||||||
</varlistentry>
|
<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>
|
<varlistentry>
|
||||||
<term>LinuxDoc</term>
|
<term><application>Emacs</application> or
|
||||||
|
<application>xemacs</application>
|
||||||
|
(<filename>editors/emacs</filename> or
|
||||||
|
<filename>editors/xemacs</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
|
<para>Both these editors include a special mode for editing
|
||||||
the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
|
documents marked up according to an SGML DTD. This mode
|
||||||
Project</ulink>, and subsequently adopted by the FreeBSD
|
includes commands to reduce the amount of typing you need, and
|
||||||
Documentation Project.</para>
|
help reduce the possibility of errors.</para>
|
||||||
|
|
||||||
<para>The LinuxDoc DTD contains primarily appearance related markup
|
<para>You do not need to use them, any text editor can be used to
|
||||||
rather than content related markup (i.e., it describes what
|
edit marked up documents. Yoy may find they make you
|
||||||
something looks like rather than what it is).</para>
|
efficient.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
<para>Both the FreeBSD Documentation Project and the Linux
|
<para>If anyone has recommendations for other software that is useful
|
||||||
Documentation Project are migrating from the LinuxDoc DTD to the
|
when manipulating SGML documents, please let Nik Clayton
|
||||||
DocBook DTD.</para>
|
(<email>nik@freebsd.org</email>) know, so they can be added to this
|
||||||
|
list.</para>
|
||||||
<para>The LinuxDoc DTD is available from the ports collection in the
|
</sect2>
|
||||||
<filename>textproc/linuxdoc</filename> category.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>DocBook</term>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>DocBook was designed by the <ulink
|
|
||||||
url="http://www.oreilly.com/davenport/">Davenport Group</ulink>
|
|
||||||
to be a DTD for writing technical documentation. As such, it
|
|
||||||
contains XXX</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1>
|
|
||||||
<title>DSSSL Stylesheets</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a slightly customised version of
|
|
||||||
Norm Walsh's modular DocBook stylesheets.</para>
|
|
||||||
|
|
||||||
<para>These can be found in
|
|
||||||
<filename>textproc/dsssl-docbook-modular</filename>.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</sect1>
|
</sect1>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -1,9 +1,48 @@
|
||||||
<chapter id="tools">
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
|
||||||
<title>* Tools</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a number of tools to assist in the
|
Redistribution and use in source (SGML DocBook) and 'compiled' forms
|
||||||
production of documentation. You will need to install some or all of these
|
(SGML, HTML, PDF, PostScript, RTF and so forth) with or without
|
||||||
tools before you will be able to make changes.</para>
|
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>
|
<important>
|
||||||
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
<title>Use <filename>textproc/docproj</filename> if possible</title>
|
||||||
|
|
@ -35,166 +74,199 @@
|
||||||
</important>
|
</important>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Software</title>
|
<title>Mandatory tools</title>
|
||||||
|
|
||||||
<para>The project uses the following applications;</para>
|
<sect2>
|
||||||
|
<title>Software</title>
|
||||||
|
|
||||||
<variablelist>
|
<para>These programs are required before you can usefully work with
|
||||||
<varlistentry>
|
the FreeBSD documentation. They are all included in
|
||||||
<term><application>Jade</application> and
|
<filename>textproc/docproj</filename>.</para>
|
||||||
<application>SP</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>These are two application suites by James Clark, who has
|
<varlistentry>
|
||||||
produced many useful SGML-processing applications.
|
<term><application>SP</application>
|
||||||
<application>Jade</application> is “James' DSSSL
|
(<filename>textproc/sp</filename>)</term>
|
||||||
Engine”, a system that takes SGML documentation and a DSSSL
|
|
||||||
stylesheet and produces converted output.
|
|
||||||
<application>SP</application> contains a number of useful
|
|
||||||
applications to manipulate, normalise, and interrogate SGML
|
|
||||||
documents.</para>
|
|
||||||
|
|
||||||
<para>Don't be concerned if these terms are unfamliar to you.</para>
|
<listitem>
|
||||||
|
<para>A suite of applications, including a validating SGML parser,
|
||||||
|
and an SGML normaliser.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>They can be found in the ports system as
|
<varlistentry>
|
||||||
<filename>textproc/jade</filename> and
|
<term><application>Jade</application>
|
||||||
<filename>textproc/sp</filename> respectively.</para>
|
(<filename>textproc/jade</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Installed as part of
|
<para>A DSSSL implementation. Used for converting marked up
|
||||||
<filename>textproc/docproj</filename>.</para>
|
documents to other formats, including HTML and TeX.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
<varlistentry>
|
||||||
<term><application>teTeX</application></term>
|
<term><application>Tidy</application>
|
||||||
|
(<filename>www/tidy</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para><application>teTeX</application> is a distrubution of the TeX
|
<para>An HTML 'pretty printer', used to reformat some of the
|
||||||
typesetting system, and is used (in conjunction with Jade) to
|
automatically generated HTML so that it is easier to
|
||||||
produce the Postscript and PDF output formats.</para>
|
follow.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
|
||||||
<para>v0.9 of <application>teTeX</application> is required, which is
|
<varlistentry>
|
||||||
currently in the ports collection as
|
<term><application>Lynx</application>
|
||||||
<filename>print/teTeX-beta</filename>.</para>
|
(<filename>www/lynx-current</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Might be installed as part of
|
<para>A text-mode WWW browser, &man.lynx.1; can also convert
|
||||||
<filename>textproc/docproj</filename>, depending on the
|
HTML files to plain text.</para>
|
||||||
<makevar>JADETEX</makevar> setting.</para>
|
</listitem>
|
||||||
</note>
|
</varlistentry>
|
||||||
</listitem>
|
</variablelist>
|
||||||
</varlistentry>
|
</sect2>
|
||||||
|
|
||||||
<varlistentry>
|
<sect2>
|
||||||
<term><application>Emacs</application> or
|
<title>DTDs and Entities</title>
|
||||||
<application>Xemacs</application></term>
|
|
||||||
|
|
||||||
<listitem>
|
<para>These are the DTDs and entity sets used by the FDP. They need to
|
||||||
<para>Neither of these programs is required. However, both of them
|
be installed before you can work with any of the documentation.</para>
|
||||||
feature PSGML-MODE, a useful extension when dealing with SGML
|
|
||||||
documents that can reduce the amount of typing you need to do, and
|
|
||||||
remove some of the more obvious errors.</para>
|
|
||||||
|
|
||||||
<para>They can be found in <filename>editor/emacs20</filename> and
|
<variablelist>
|
||||||
<filename>editor/xemacs20</filename>.</para>
|
<varlistentry>
|
||||||
|
<term>HTML DTD (<filename>textproc/html</filename>)</term>
|
||||||
|
|
||||||
<note>
|
<listitem>
|
||||||
<para>Not installed as part of
|
<para>HTML is the markup language of choice for the World Wide
|
||||||
<filename>textproc/docproj</filename>.</para>
|
Web, and is used throughout the FreeBSD web site.</para>
|
||||||
</note>
|
</listitem>
|
||||||
</listitem>
|
</varlistentry>
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
<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>
|
||||||
|
|
||||||
<sect1>
|
<sect1>
|
||||||
<title>Document Type Definitions (DTDs)</title>
|
<title>Optional tools</title>
|
||||||
|
|
||||||
<para>The project uses the following DTDs;</para>
|
<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>
|
||||||
|
|
||||||
<variablelist>
|
<sect2>
|
||||||
<varlistentry>
|
<title>Software</title>
|
||||||
<term>HTML</term>
|
|
||||||
|
|
||||||
<listitem>
|
<variablelist>
|
||||||
<para>HTML, the HyperText Markup Language, is the markup language of
|
<varlistentry>
|
||||||
choice on the World Wide Web. More information can be found at
|
<term><application>JadeTeX</application> and
|
||||||
<URL:<ulink
|
<application>teTeX</application>
|
||||||
url="http://www.w3.org/">http://www.w3.org/</ulink>>.</para>
|
(<filename>print/jadetex</filename> and
|
||||||
|
<filename>print/teTeX-beta</filename>)</term>
|
||||||
|
|
||||||
<para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
|
<listitem>
|
||||||
and the latest, 4.0 (available in both <emphasis>strict</emphasis>
|
<para><application>Jade</application> and
|
||||||
and <emphasis>loose</emphasis> variants).</para>
|
<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>The HTML DTDs are available from the ports collection in the
|
<para>If you do not intend to convert your documentation to one of
|
||||||
<filename>textproc/html</filename> category.</para>
|
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>
|
||||||
|
|
||||||
<note>
|
<important>
|
||||||
<para>Installed as part of
|
<para>If you decide to install
|
||||||
<filename>textproc/docproj</filename>.</para>
|
<application>JadeTeX</application> and
|
||||||
</note>
|
<application>teTeX</application> then you will need to
|
||||||
</listitem>
|
configure <application>teTeX</application> after
|
||||||
</varlistentry>
|
<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>
|
<varlistentry>
|
||||||
<term>LinuxDoc</term>
|
<term><application>Emacs</application> or
|
||||||
|
<application>xemacs</application>
|
||||||
|
(<filename>editors/emacs</filename> or
|
||||||
|
<filename>editors/xemacs</filename>)</term>
|
||||||
|
|
||||||
<listitem>
|
<listitem>
|
||||||
<para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
|
<para>Both these editors include a special mode for editing
|
||||||
the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
|
documents marked up according to an SGML DTD. This mode
|
||||||
Project</ulink>, and subsequently adopted by the FreeBSD
|
includes commands to reduce the amount of typing you need, and
|
||||||
Documentation Project.</para>
|
help reduce the possibility of errors.</para>
|
||||||
|
|
||||||
<para>The LinuxDoc DTD contains primarily appearance related markup
|
<para>You do not need to use them, any text editor can be used to
|
||||||
rather than content related markup (i.e., it describes what
|
edit marked up documents. Yoy may find they make you
|
||||||
something looks like rather than what it is).</para>
|
efficient.</para>
|
||||||
|
</listitem>
|
||||||
|
</varlistentry>
|
||||||
|
</variablelist>
|
||||||
|
|
||||||
<para>Both the FreeBSD Documentation Project and the Linux
|
<para>If anyone has recommendations for other software that is useful
|
||||||
Documentation Project are migrating from the LinuxDoc DTD to the
|
when manipulating SGML documents, please let Nik Clayton
|
||||||
DocBook DTD.</para>
|
(<email>nik@freebsd.org</email>) know, so they can be added to this
|
||||||
|
list.</para>
|
||||||
<para>The LinuxDoc DTD is available from the ports collection in the
|
</sect2>
|
||||||
<filename>textproc/linuxdoc</filename> category.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
|
|
||||||
<varlistentry>
|
|
||||||
<term>DocBook</term>
|
|
||||||
|
|
||||||
<listitem>
|
|
||||||
<para>DocBook was designed by the <ulink
|
|
||||||
url="http://www.oreilly.com/davenport/">Davenport Group</ulink>
|
|
||||||
to be a DTD for writing technical documentation. As such, it
|
|
||||||
contains XXX</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of
|
|
||||||
<filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</listitem>
|
|
||||||
</varlistentry>
|
|
||||||
</variablelist>
|
|
||||||
</sect1>
|
|
||||||
|
|
||||||
<sect1>
|
|
||||||
<title>DSSSL Stylesheets</title>
|
|
||||||
|
|
||||||
<para>The Documentation Project uses a slightly customised version of
|
|
||||||
Norm Walsh's modular DocBook stylesheets.</para>
|
|
||||||
|
|
||||||
<para>These can be found in
|
|
||||||
<filename>textproc/dsssl-docbook-modular</filename>.</para>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>Installed as part of <filename>textproc/docproj</filename>.</para>
|
|
||||||
</note>
|
|
||||||
</sect1>
|
</sect1>
|
||||||
</chapter>
|
</chapter>
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue