aboutsummaryrefslogtreecommitdiff
path: root/en/tutorials
diff options
context:
space:
mode:
authorNik Clayton <nik@FreeBSD.org>1999-04-29 19:55:45 +0000
committerNik Clayton <nik@FreeBSD.org>1999-04-29 19:55:45 +0000
commitd3d908e6058daa5e54dacf86930cc387b529bbf8 (patch)
tree61bbe9d164064f7139f24e2f92b781a4404d2e08 /en/tutorials
parentc2e6d4a096763d09815e48ad49803bbb77f99579 (diff)
Notes
Diffstat (limited to 'en/tutorials')
-rw-r--r--en/tutorials/docproj-primer/tools/chapter.sgml382
1 files changed, 227 insertions, 155 deletions
diff --git a/en/tutorials/docproj-primer/tools/chapter.sgml b/en/tutorials/docproj-primer/tools/chapter.sgml
index 2080134fad..92c310a37e 100644
--- a/en/tutorials/docproj-primer/tools/chapter.sgml
+++ b/en/tutorials/docproj-primer/tools/chapter.sgml
@@ -1,9 +1,48 @@
+<!-- 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>
+ <title>Tools</title>
- <para>The Documentation Project uses a number of tools to assist in the
- production of documentation. You will need to install some or all of these
- tools before you will be able to make changes.</para>
+ <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>
@@ -33,168 +72,201 @@
as necessary.</para>
</important>
-
+
<sect1>
- <title>Software</title>
-
- <para>The project uses the following applications;</para>
-
- <variablelist>
- <varlistentry>
- <term><application>Jade</application> and
- <application>SP</application></term>
+ <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>
- <listitem>
- <para>These are two application suites by James Clark, who has
- produced many useful SGML-processing applications.
- <application>Jade</application> is &ldquo;James' DSSSL
- Engine&rdquo;, 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>
-
- <para>They can be found in the ports system as
- <filename>textproc/jade</filename> and
- <filename>textproc/sp</filename> respectively.</para>
-
- <note>
- <para>Installed as part of
- <filename>textproc/docproj</filename>.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>teTeX</application></term>
+ <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>
- <listitem>
- <para><application>teTeX</application> is a distrubution of the TeX
- typesetting system, and is used (in conjunction with Jade) to
- produce the Postscript and PDF output formats.</para>
-
- <para>v0.9 of <application>teTeX</application> is required, which is
- currently in the ports collection as
- <filename>print/teTeX-beta</filename>.</para>
-
- <note>
- <para>Might be installed as part of
- <filename>textproc/docproj</filename>, depending on the
- <makevar>JADETEX</makevar> setting.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><application>Emacs</application> or
- <application>Xemacs</application></term>
+ <varlistentry>
+ <term><application>Tidy</application>
+ (<filename>www/tidy</filename>)</term>
- <listitem>
- <para>Neither of these programs is required. However, both of them
- 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
- <filename>editor/xemacs20</filename>.</para>
-
- <note>
- <para>Not installed as part of
- <filename>textproc/docproj</filename>.</para>
- </note>
- </listitem>
- </varlistentry>
- </variablelist>
- </sect1>
-
- <sect1>
- <title>Document Type Definitions (DTDs)</title>
-
- <para>The project uses the following DTDs;</para>
-
- <variablelist>
- <varlistentry>
- <term>HTML</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>
- <listitem>
- <para>HTML, the HyperText Markup Language, is the markup language of
- choice on the World Wide Web. More information can be found at
- &lt;URL:<ulink
- url="http://www.w3.org/">http://www.w3.org/</ulink>&gt;.</para>
-
- <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
- and the latest, 4.0 (available in both <emphasis>strict</emphasis>
- and <emphasis>loose</emphasis> variants).</para>
+ <varlistentry>
+ <term><application>Lynx</application>
+ (<filename>www/lynx-current</filename>)</term>
- <para>The HTML DTDs are available from the ports collection in the
- <filename>textproc/html</filename> category.</para>
-
- <note>
- <para>Installed as part of
- <filename>textproc/docproj</filename>.</para>
- </note>
- </listitem>
- </varlistentry>
+ <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>
- <varlistentry>
- <term>LinuxDoc</term>
+ <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>
- <listitem>
- <para>LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
- the <ulink url="http://sunsite.unc.edu/LDP/">Linux Documentation
- Project</ulink>, and subsequently adopted by the FreeBSD
- Documentation Project.</para>
-
- <para>The LinuxDoc DTD contains primarily appearance related markup
- rather than content related markup (i.e., it describes what
- something looks like rather than what it is).</para>
-
- <para>Both the FreeBSD Documentation Project and the Linux
- Documentation Project are migrating from the LinuxDoc DTD to the
- DocBook DTD.</para>
-
- <para>The LinuxDoc DTD is available from the ports collection in the
- <filename>textproc/linuxdoc</filename> category.</para>
-
- <note>
- <para>Installed as part of
- <filename>textproc/docproj</filename>.</para>
- </note>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>DocBook</term>
+ <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>
- <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>
+ <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>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>
+ <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. Yoy 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>