Date: Wed, 17 Jul 2013 00:02:20 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42305 - head/en_US.ISO8859-1/books/fdp-primer/tools Message-ID: <201307170002.r6H02KvD050087@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Wed Jul 17 00:02:19 2013 New Revision: 42305 URL: http://svnweb.freebsd.org/changeset/doc/42305 Log: Update the Tools chapter. Simplify, remove irrelevant and outdated information. Modified: head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml Modified: head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml Tue Jul 16 21:44:21 2013 (r42304) +++ head/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml Wed Jul 17 00:02:19 2013 (r42305) @@ -34,132 +34,51 @@ <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 - <application>JadeTeX</application> 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 <application>JadeTeX</application> (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 - XHTML or ASCII text output if you do not install - <application>JadeTeX</application>. PostScript or PDF output - requires &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 XHTML, 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>Links</application> - (<filename role="package">www/links</filename>)</term> - - <listitem> - <para>A text-mode WWW browser that can also convert - XHTML 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> + <para>Several software tools are used to + manage the FreeBSD documentation and render it to different output + formats. Some of these tools are required and must be installed + before working through the examples in the following chapters. + Some are optional, adding capabilities or making the job of + creating documentation less demanding.</para> + + <sect1 id="tools-required"> + <title>Required Tools</title> + + <para>Install + <filename role="package">textproc/docproj</filename> from the + Ports Collection. This <emphasis>meta-port</emphasis> installs + all the applications required to do useful work with the &os; + documentation. Some further notes on particular components are + given below.</para> <sect2> - <title>DTDs and Entities</title> + <title><acronym>DTD</acronym>s and <acronym>Entities</acronym></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> + <para>&os; documentation uses several Document Type Definitions + (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym> + entities. These are all installed by the + <filename role="package">textproc/docproj</filename> + port.</para> <variablelist> <varlistentry> - <term>XHTML DTD (<filename + <term><acronym>XHTML</acronym> <acronym>DTD</acronym> (<filename role="package">textproc/xhtml</filename>)</term> <listitem> - <para>XHTML is the markup language of choice for the World - Wide Web, and is used throughout the FreeBSD web + <para><acronym>XHTML</acronym> is the markup language of choice for the World + Wide Web, and is used throughout the &os; web site.</para> </listitem> </varlistentry> <varlistentry> - <term>DocBook DTD (<filename + <term>DocBook <acronym>DTD</acronym> (<filename role="package">textproc/docbook-xml-450</filename>)</term> <listitem> <para>DocBook is designed for marking up technical - documentation. All the FreeBSD documentation is written + documentation. Most of the &os; documentation is written in DocBook.</para> </listitem> </varlistentry> @@ -170,8 +89,8 @@ 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, + <para>Character entities from the ISO 8879:1986 standard used + by many <acronym>DTD</acronym>s. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols.</para> @@ -184,10 +103,8 @@ <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> + <para>These applications are not required, but can make working on + the documentation easier or add capabilities.</para> <sect2> <title>Software</title> @@ -205,23 +122,24 @@ <application>teTeX</application> and Modular DocBook Stylesheets 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> + to do this.</para> - <para>If you do not intend to convert your documentation - to one of these formats (i.e., HTML and plain text - are sufficient) then you do not need to install - these.</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> + <para>If <acronym>XHTML</acronym> and plain text output + formats are adequate, then this program is not needed + and the option to install it from the + <filename role="package">textproc/docproj</filename> + configuration screen can be disabled.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Vim</application> + (<filename role="package">editors/vim</filename>)</term> + + <listitem> + <para>A popular editor for working with + <acronym>XML</acronym> and derived documents, like + DocBook <acronym>XML</acronym>.</para> </listitem> </varlistentry> @@ -232,22 +150,14 @@ <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. + <para>Both of these editors include a special mode for + editing documents marked up according to an <acronym>XML</acronym> <acronym>DTD</acronym>. This mode includes commands to reduce the amount of - typing you need, and help reduce the possibility of + typing needed, 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 XML documents, please let &a.doceng; - know, so they can be added to this list.</para> </sect2> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201307170002.r6H02KvD050087>