From owner-svn-doc-head@FreeBSD.ORG Wed Jul 17 00:02:20 2013 Return-Path: Delivered-To: svn-doc-head@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by hub.freebsd.org (Postfix) with ESMTP id 5DA41E4C; Wed, 17 Jul 2013 00:02:20 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) by mx1.freebsd.org (Postfix) with ESMTP id 3FA0E95F; Wed, 17 Jul 2013 00:02:20 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.7/8.14.7) with ESMTP id r6H02KnQ050089; Wed, 17 Jul 2013 00:02:20 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.7/8.14.5/Submit) id r6H02KvD050087; Wed, 17 Jul 2013 00:02:20 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201307170002.r6H02KvD050087@svn.freebsd.org> From: Warren Block Date: Wed, 17 Jul 2013 00:02:20 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 17 Jul 2013 00:02:20 -0000 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 @@ Tools - 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. - - All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them. - - 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. - - - Use <filename role="package">textproc/docproj</filename> If - Possible - - You can save yourself a lot of time if you install the - textproc/docproj port. This - is a meta-port which does not contain any - software itself. Instead, it depends on various other ports - being installed correctly. Installing this port - should automatically download and install - all of the packages listed in this chapter that you need. - - One of the packages that you might need is the - JadeTeX 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. - - 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: - - &prompt.root; make JADETEX=yes install - - or - - &prompt.root; make JADETEX=no install - - as necessary. Alternatively you may install - textproc/docproj-jadetex or - textproc/docproj-nojadetex. - These slave ports define the JADETEX 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 - JadeTeX. PostScript or PDF output - requires &tex;. - - - - Mandatory Tools - - - Software - - 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 textproc/docproj. - - - - Jade - (textproc/jade) - - - A DSSSL implementation. Used for converting marked - up documents to other formats, including HTML and - &tex;. - - - - - Links - (www/links) - - - A text-mode WWW browser that can also convert - XHTML files to plain text. - - - - - peps - (graphics/peps) - - - 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. - - - - + 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. + + + Required Tools + + Install + textproc/docproj from the + Ports Collection. This meta-port installs + all the applications required to do useful work with the &os; + documentation. Some further notes on particular components are + given below. - DTDs and Entities + <acronym>DTD</acronym>s and <acronym>Entities</acronym> - 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. + &os; documentation uses several Document Type Definitions + (DTDs) and sets of XML + entities. These are all installed by the + textproc/docproj + port. - XHTML DTD (XHTML DTD (textproc/xhtml) - XHTML is the markup language of choice for the World - Wide Web, and is used throughout the FreeBSD web + XHTML is the markup language of choice for the World + Wide Web, and is used throughout the &os; web site. - DocBook DTD (DocBook DTD (textproc/docbook-xml-450) DocBook is designed for marking up technical - documentation. All the FreeBSD documentation is written + documentation. Most of the &os; documentation is written in DocBook. @@ -170,8 +89,8 @@ role="package">textproc/iso8879) - 19 of the ISO 8879:1986 character entity sets used - by many DTDs. Includes named mathematical symbols, + Character entities from the ISO 8879:1986 standard used + by many DTDs. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols. @@ -184,10 +103,8 @@ Optional Tools - 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. + These applications are not required, but can make working on + the documentation easier or add capabilities. Software @@ -205,23 +122,24 @@ teTeX and Modular DocBook Stylesheets are used to convert DocBook documents to DVI, Postscript, and PDF formats. The JadeTeX macros are needed - in order to do this. + to do this. - 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. - - - If you decide to install - JadeTeX and - teTeX then you will need to - configure teTeX after - JadeTeX has been installed. - print/jadetex/pkg-message - contains detailed instructions explaining what you - need to do. - + If XHTML and plain text output + formats are adequate, then this program is not needed + and the option to install it from the + textproc/docproj + configuration screen can be disabled. + + + + + Vim + (editors/vim) + + + A popular editor for working with + XML and derived documents, like + DocBook XML. @@ -232,22 +150,14 @@ editors/xemacs) - Both these editors include a special mode for - editing documents marked up according to an SGML DTD. + Both of these editors include a special mode for + editing documents marked up according to an XML DTD. 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. - - 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. - - 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.