From owner-svn-doc-all@FreeBSD.ORG Mon Apr 28 16:19:09 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id A3D39190; Mon, 28 Apr 2014 16:19:09 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 840AF11BE; Mon, 28 Apr 2014 16:19:09 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s3SGJ9Lw020277; Mon, 28 Apr 2014 16:19:09 GMT (envelope-from dru@svn.freebsd.org) Received: (from dru@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s3SGJ9or020276; Mon, 28 Apr 2014 16:19:09 GMT (envelope-from dru@svn.freebsd.org) Message-Id: <201404281619.s3SGJ9or020276@svn.freebsd.org> From: Dru Lavigne Date: Mon, 28 Apr 2014 16:19:09 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44673 - head/en_US.ISO8859-1/books/handbook/cutting-edge X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 28 Apr 2014 16:19:09 -0000 Author: dru Date: Mon Apr 28 16:19:09 2014 New Revision: 44673 URL: http://svnweb.freebsd.org/changeset/doc/44673 Log: Editorial review of section on Updating the Documentation Set. Sponsored by: iXsystems Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml ============================================================================== --- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Apr 27 14:09:44 2014 (r44672) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Mon Apr 28 16:19:09 2014 (r44673) @@ -716,93 +716,39 @@ before running "/usr/sbin/freebsd-update Documentation is an integral part of the &os; operating - system. While an up-to-date version of the &os; Documentation - Set is always available on the - &os; web - site, some users might have slow or no permanent - network connectivity. There are several ways to update the - local copy of documentation with the latest &os; Documentation - Set. - - - Using <application>Subversion</application> to Update the - Documentation - - The &os; documentation sources can be obtained with - svn. This section - describes how to: + system. While an up-to-date version of the &os; documentation + is always available on the &os; web site + (http://www.freebsd.org/doc/), + it can be handy to have an up-to-date, local copy of the &os; + website, handbooks, FAQ, and articles. + + This section describes how to use either source or the &os; + Ports Collection to keep a local copy of the &os; documentation + up-to-date. - - - Install the documentation toolchain, the tools that - are required to rebuild the &os; documentation from its - source. - - - - Download a copy of the documentation source at - /usr/doc, using - svn. - - - - Rebuild the &os; documentation from its source, and - install it under - /usr/share/doc. - - - - Recognize some of the build options that are - supported by the build system of the documentation, such - as the options that build only some of the different - language translations of the documentation or the options - that select a specific output format. - - - + For information on editing and submitting corrections to + the documentation, refer to the &os; Documentation + Project Primer for New Contributors + (http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/). - - Installing <application>svn</application> and the - Documentation Toolchain + + Updating Documentation from Source Rebuilding the &os; documentation from source requires a - collection of tools which are not part of the &os; base system - due to the amount of disk space these tools use. They are - also not useful to all &os; users, only those users that are - actively writing new documentation for &os; or are frequently - updating their documentation from source. - - The required tools, including - svn, are available in the - textproc/docproj meta-port + collection of tools which are not part of the &os; base system. + The required tools, including + svn, can be installed from the + textproc/docproj package or port developed by the &os; Documentation Project. - - When no &postscript; or PDF documentation required, one - might consider installing the - textproc/docproj-nojadetex port instead. - This version of the documentation toolchain includes - everything except the teTeX - typesetting engine. teTeX is a - very large collection of tools, so it may be quite sensible - to omit its installation if PDF output is not really - necessary. - - - - - Updating the Documentation Sources - - In this example, svn is used to - fetch a clean copy of the documentation sources from the - western US mirror using the HTTPS protocol: + Once installed, use svn to + fetch a clean copy of the documentation source. Replace + https://svn0.us-west.FreeBSD.org + with the address of the closest geographic mirror from + : &prompt.root; svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc - Select the closest mirror from the available - Subversion mirror - sites. - The initial download of the documentation sources may take a while. Let it run until it completes. @@ -811,24 +757,42 @@ before running "/usr/sbin/freebsd-update &prompt.root; svn update /usr/doc - After checking out the sources, an alternative way of - updating the documentation is supported by the - /usr/doc/Makefile by running the - following commands: + Once an up-to-date snapshot of the documentation sources + has been fetched to /usr/doc, everything + is ready for an update of the installed documentation. + + A full update of all available languages may be performed + by typing: &prompt.root; cd /usr/doc -&prompt.root; make update - +&prompt.root; make install clean - - Tunable Options of the Documentation Sources + If an update of only a specific language is desired, + make can be invoked in a language-specific + subdirectory of + /usr/doc: + + &prompt.root; cd /usr/doc/en_US.ISO8859-1 +&prompt.root; make install clean + + An alternative way of + updating the documentation is to run this + command from /usr/doc or + the desired language-specific subdirectory: + + &prompt.root; make update - The updating and build system of the &os; documentation - set supports a few options that ease the process of updating + The output formats that will be installed may be specified + by setting FORMATS: + + &prompt.root; cd /usr/doc +&prompt.root; make FORMATS='html html-split' install clean + + Several options are available to ease the process of updating only parts of the documentation, or the build of specific translations. These options can be set either as system-wide options in /etc/make.conf, or as - command-line options passed to &man.make.1;. + command-line options passed to make. The options include: @@ -850,8 +814,8 @@ before running "/usr/sbin/freebsd-update A single format or a list of output formats to be built. Currently, html, html-split, txt, - ps, pdf, - and rtf are supported. + ps, and pdf + are supported. @@ -868,50 +832,11 @@ before running "/usr/sbin/freebsd-update For more make variables supported as system-wide options in &os;, refer to &man.make.conf.5;. - - For more make variables supported by - the build system of the &os; documentation, refer to the - &os; - Documentation Project Primer for New - Contributors. - - - - Installing the &os; Documentation from Source - - Once an up-to-date snapshot of the documentation sources - has been fetched to /usr/doc, everything - is ready for an update of the installed documentation. - - A full update of all the languages defined in - DOC_LANG may be performed by typing: - - &prompt.root; cd /usr/doc -&prompt.root; make install clean - - If an update of only a specific language is desired, - &man.make.1; can be invoked in a language specific - subdirectory of - /usr/doc: - - &prompt.root; cd /usr/doc/en_US.ISO8859-1 -&prompt.root; make update install clean - - The output formats that will be installed may be specified - by setting FORMATS: - - &prompt.root; cd /usr/doc -&prompt.root; make FORMATS='html html-split' install clean - - For information on editing and submitting corrections to - the documentation, refer to the - &os; Documentation - Project Primer for New Contributors. - + - Using Documentation Ports + Updating Documentation from Ports @@ -934,95 +859,89 @@ before running "/usr/sbin/freebsd-update The previous section presented a method for updating the - &os; documentation from sources. Source based updates may not - be feasible or practical for all &os; systems as building the - documentation sources requires the documentation - toolchain, a certain level of familiarity with - svn and source checkouts from a - repository, and a few manual steps to build the checked out - sources. This section describes an alternative method which + &os; documentation from sources. This section describes an alternative method which uses the Ports Collection and makes it possible to: - Download and install pre-built snapshots of the + Install pre-built packages of the documentation, without having to locally build anything or install the documentation toolchain. - Download the documentation sources and build them + Build the documentation sources through the ports framework, making the checkout and build steps a bit easier. - These two methods of updating the &os; documentation are + This method of updating the &os; documentation is supported by a set of - documentation ports, updated by the + documentation ports and packages which are updated by the &a.doceng; on a monthly basis. These are listed in the &os; - Ports Collection, under the docs - category. - - - Building and Installing Documentation Ports - - The documentation ports use the ports building framework - to make documentation builds easier. They automate the - process of checking out the documentation source, running - &man.make.1; with the appropriate environment settings and - command-line options, and they make the installation or - deinstallation of documentation as easy as the installation - of any other &os; port or package. - - - As an extra feature, when the documentation ports are - built locally, they record a dependency to the - documentation toolchain ports, so - that they are also automatically installed. - + Ports Collection, under the docs category (http://www.freshports.org/docs/). Organization of the documentation ports is as follows: - The master port, - misc/freebsd-doc-en, which installs - all of the English documentation ports. + The + misc/freebsd-doc-en package or port installs + all of the English documentation. - The all in one port, - misc/freebsd-doc-all, builds and + The + misc/freebsd-doc-all meta-package or port installs all documentation in all available languages. - There is a slave port for each + There is a package and port for each translation, such as misc/freebsd-doc-hu for the - Hungarian-language documents. + Hungarian documentation. - For example, to build and install the English - documentation in split HTML format, - similar to the format used on http://www.FreeBSD.org, - to /usr/local/share/doc/freebsd, - install the following port + When binary packages are used, the &os; documentation + will be installed in all available + formats for the given language. For example, the following command will install the + latest package of the Hungarian + documentation: + + &prompt.root; pkg install hu-freebsd-doc + + + Packages use a format that differs from the + corresponding port's name: + lang-freebsd-doc, + where lang is the short format + of the language code, such as hu for + Hungarian, or zh_cn for Simplified + Chinese. + + + To specify the format of the documentation, build the + port instead of installing the package. For example, to build and install the English + documentation: &prompt.root; cd /usr/ports/misc/freebsd-doc-en &prompt.root; make install clean - - Common Knobs and Options + The port provides a configuration menu where the format + to build and install can be specified. By default, split + HTML, similar to the format used on http://www.FreeBSD.org, + and PDF are + selected. - There are many options for modifying the default - behavior of the documentation ports, including: + Alternately, several make options can be specified + when building a documentation port, including: @@ -1032,8 +951,7 @@ before running "/usr/sbin/freebsd-update Builds the HTML format with a single HTML file per document. The formatted documentation is saved to a file called article.html, - or book.html, as appropriate, - plus images. + or book.html. @@ -1041,11 +959,9 @@ before running "/usr/sbin/freebsd-update WITH_PDF - Builds the &adobe; Portable Document Format - (PDF). The formatted documentation is saved to a + The formatted documentation is saved to a file called article.pdf or - book.pdf, as - appropriate. + book.pdf. @@ -1056,78 +972,25 @@ before running "/usr/sbin/freebsd-update Specifies where to install the documentation. It defaults to /usr/local/share/doc/freebsd. - - - The default target directory differs from the - directory used svn. - This is because ports are usually installed within - /usr/local. - This can be overridden by using - PREFIX. - This example uses variables to install the Hungarian - documentation as a PDF: + documentation as a PDF in the specified + directory: &prompt.root; cd /usr/ports/misc/freebsd-doc-hu &prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean - - - - - Using Documentation Packages - - Building the documentation ports from source, as - described in the previous section, requires a local - installation of the documentation toolchain and a bit of - disk space for the build of the ports. When resources are - not available to install the documentation toolchain, or - because the build from sources would take too much disk - space, it is still possible to install pre-built snapshots - of the documentation ports. - - The &a.doceng; prepares monthly snapshots of the &os; - documentation packages. These binary packages can be used - with any of the bundled package tools, like &man.pkg.add.1;, - &man.pkg.delete.1;, and so on. - - - When binary packages are used, the &os; documentation - will be installed in all available - formats for the given language. - - - For example, the following command will install the - latest pre-built package of the Hungarian - documentation: - - &prompt.root; pkg install hu-freebsd-doc - - - Packages use a format that differs from the - corresponding port's name: - lang-freebsd-doc, - where lang is the short format - of the language code, such as hu for - Hungarian, or zh_cn for Simplified - Chinese. - - - - - Updating Documentation Ports - Documentation ports can be updated like any other port. + Documentation packages or ports can be updated using the + instructions in . For example, the following command updates the installed Hungarian documentation using ports-mgmt/portmaster by using packages only: &prompt.root; portmaster -PP hu-freebsd-doc -