diff options
author | Nik Clayton <nik@FreeBSD.org> | 1999-04-29 19:55:45 +0000 |
---|---|---|
committer | Nik Clayton <nik@FreeBSD.org> | 1999-04-29 19:55:45 +0000 |
commit | d3d908e6058daa5e54dacf86930cc387b529bbf8 (patch) | |
tree | 61bbe9d164064f7139f24e2f92b781a4404d2e08 /en/tutorials | |
parent | c2e6d4a096763d09815e48ad49803bbb77f99579 (diff) |
Notes
Diffstat (limited to 'en/tutorials')
-rw-r--r-- | en/tutorials/docproj-primer/tools/chapter.sgml | 382 |
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 “James' DSSSL - 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> - - <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 - <URL:<ulink - url="http://www.w3.org/">http://www.w3.org/</ulink>>.</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> |