From owner-svn-doc-all@FreeBSD.ORG Sun Oct 14 17:32:57 2012 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [69.147.83.52]) by hub.freebsd.org (Postfix) with ESMTP id A6C2735C; Sun, 14 Oct 2012 17:32:57 +0000 (UTC) (envelope-from wblock@FreeBSD.org) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:4f8:fff6::2c]) by mx1.freebsd.org (Postfix) with ESMTP id 8C3A28FC12; Sun, 14 Oct 2012 17:32:57 +0000 (UTC) Received: from svn.freebsd.org (localhost [127.0.0.1]) by svn.freebsd.org (8.14.4/8.14.4) with ESMTP id q9EHWv4x009790; Sun, 14 Oct 2012 17:32:57 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.4/8.14.4/Submit) id q9EHWvqQ009787; Sun, 14 Oct 2012 17:32:57 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201210141732.q9EHWvqQ009787@svn.freebsd.org> From: Warren Block Date: Sun, 14 Oct 2012 17:32:57 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39751 - 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.14 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: Sun, 14 Oct 2012 17:32:57 -0000 Author: wblock Date: Sun Oct 14 17:32:56 2012 New Revision: 39751 URL: http://svn.freebsd.org/changeset/doc/39751 Log: Whitespace-only cleanups. Translators, please ignore. 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 Oct 14 16:01:08 2012 (r39750) +++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Oct 14 17:32:56 2012 (r39751) @@ -11,7 +11,8 @@ Jim Mock - Restructured, reorganized, and parts updated by + Restructured, reorganized, and parts updated + by @@ -46,17 +47,17 @@ Synopsis - &os; is under constant development between releases. Some people - prefer to use the officially released versions, while others prefer - to keep in sync with the latest developments. However, even official - releases are often updated with security and other critical fixes. - Regardless of the version used, &os; provides all necessary tools - to keep your system updated, and also allows for easy upgrades between - versions. - This chapter will help you decide if you want to track the - development system, or stick with one of the released - versions. The basic tools for keeping your system up to date are - also presented. + &os; is under constant development between releases. Some + people prefer to use the officially released versions, while + others prefer to keep in sync with the latest developments. + However, even official releases are often updated with security + and other critical fixes. Regardless of the version used, &os; + provides all necessary tools to keep your system updated, and + also allows for easy upgrades between versions. This chapter + will help you decide if you want to track the development + system, or stick with one of the released versions. The basic + tools for keeping your system up to date are also + presented. After reading this chapter, you will know: @@ -81,8 +82,8 @@ How to keep your documentation up to date with - CVSup or documentation ports. + CVSup or documentation + ports. @@ -111,14 +112,15 @@ - Throughout this chapter, the cvsup command is - used to obtain and update &os; sources. To use it, you will need to - install the port or the package for net/cvsup (if you do not want to install - the graphical cvsup client, you can just install - the port net/cvsup-without-gui). - You may wish to substitute this - with &man.csup.1;, which is part of the base system. + Throughout this chapter, the cvsup + command is used to obtain and update &os; sources. To use it, + you will need to install the port or the package for + net/cvsup (if you do not + want to install the graphical cvsup client, + you can just install the port + net/cvsup-without-gui). You may wish to + substitute this with &man.csup.1;, which is part of the base + system. @@ -147,18 +149,19 @@ updating-upgrading - Applying security patches is an important part of maintaining - computer software, especially the operating system. For the - longest time on &os; this process was not an easy one. Patches - had to be applied to the source code, the code rebuilt into - binaries, and then the binaries had to be re-installed. + Applying security patches is an important part of + maintaining computer software, especially the operating system. + For the longest time on &os; this process was not an easy one. + Patches had to be applied to the source code, the code rebuilt + into binaries, and then the binaries had to be + re-installed. This is no longer the case as &os; now includes a utility simply called freebsd-update. This utility provides two separate functions. First, it allows for binary - security and errata updates to be applied to the &os; base system - without the build and install requirements. Second, the utility - supports minor and major release upgrades. + security and errata updates to be applied to the &os; base + system without the build and install requirements. Second, the + utility supports minor and major release upgrades. Binary updates are available for all architectures and @@ -177,21 +180,22 @@ The Configuration File - Some users may wish to tweak the default configuration file - in /etc/freebsd-update.conf, - allowing better control of the process. The options are - very well documented, but the following few may require a - bit more explanation: + Some users may wish to tweak the default configuration + file in /etc/freebsd-update.conf, + allowing better control of the process. The options are very + well documented, but the following few may require a bit more + explanation: # Components of the base system which should be kept updated. Components src world kernel - This parameter controls what parts of &os; will be kept - up to date. The default is to update the source code, the - entire base system, and the kernel. Components are the - same as those available during the install, for instance, - adding world/games here would allow game patches to be - applied. Using src/bin would allow the source code in + This parameter controls what parts of &os; will be kept up + to date. The default is to update the source code, the entire + base system, and the kernel. Components are the same as those + available during the install, for instance, adding + world/games here would allow game patches + to be applied. Using src/bin would allow + the source code in src/bin to be updated. @@ -237,7 +241,7 @@ MergeChanges /etc/ /var/named/etc/freebsd-update will abort. When in doubt, backup /etc and just - accept the merges. See for more + accept the merges. See for more information about the mergemaster command. @@ -278,17 +282,18 @@ MergeChanges /etc/ /var/named/etc/If any kernel patches have been applied the system will need a reboot. If all went well the system should be patched and freebsd-update may be run as a nightly - &man.cron.8; job. An entry in /etc/crontab - would be sufficient to accomplish this task: + &man.cron.8; job. An entry in + /etc/crontab would be sufficient to + accomplish this task: @daily root freebsd-update cron This entry states that once every day, the - freebsd-update utility will be run. In this way, - using the argument, + freebsd-update utility will be run. In + this way, using the argument, freebsd-update will only check if updates - exist. If patches exist, they will automatically be downloaded - to the local disk but not applied. The + exist. If patches exist, they will automatically be + downloaded to the local disk but not applied. The root user will be sent an email so they may install them manually. @@ -298,50 +303,54 @@ MergeChanges /etc/ /var/named/etc/&prompt.root; freebsd-update rollback - Once complete, the system should be restarted if the kernel - or any kernel modules were modified. This will allow &os; to - load the new binaries into memory. + Once complete, the system should be restarted if the + kernel or any kernel modules were modified. This will allow + &os; to load the new binaries into memory. The freebsd-update utility can - automatically update the GENERIC kernel only. - If a custom kernel is in use, it will have to be rebuilt and - reinstalled after freebsd-update finishes - installing the rest of the updates. However, - freebsd-update will detect and update the - GENERIC kernel in /boot/GENERIC (if it exists), even if - it is not the current (running) kernel of the system. + automatically update the GENERIC kernel + only. If a custom kernel is in use, it will have to be + rebuilt and reinstalled after + freebsd-update finishes installing the rest + of the updates. However, freebsd-update + will detect and update the GENERIC kernel + in + /boot/GENERIC (if it + exists), even if it is not the current (running) kernel of the + system. It is a good idea to always keep a copy of the - GENERIC kernel in /boot/GENERIC. It will be helpful - in diagnosing a variety of problems, and in performing version - upgrades using freebsd-update as described in + GENERIC kernel in + /boot/GENERIC. It + will be helpful in diagnosing a variety of problems, and in + performing version upgrades using + freebsd-update as described in . Unless the default configuration in - /etc/freebsd-update.conf has been changed, - freebsd-update will install the updated kernel - sources along with the rest of the updates. Rebuilding and - reinstalling your new custom kernel can then be performed in the usual - way. + /etc/freebsd-update.conf has been + changed, freebsd-update will install the + updated kernel sources along with the rest of the updates. + Rebuilding and reinstalling your new custom kernel can then be + performed in the usual way. - The updates distributed via freebsd-update, - do not always involve the kernel. It will not be necessary to - rebuild your custom kernel if the kernel sources have not been - modified by the execution of - freebsd-update install. However, - freebsd-update will always update the - /usr/src/sys/conf/newvers.sh file. The current - patch level (as indicated by the -p number - reported by uname -r) is - obtained from this file. Rebuilding your custom kernel, even if - nothing else changed, will allow &man.uname.1; to accurately report - the current patch level of the system. This is particularly - helpful when maintaining multiple systems, as it allows for a quick + The updates distributed via + freebsd-update, do not always involve the + kernel. It will not be necessary to rebuild your custom + kernel if the kernel sources have not been modified by the + execution of freebsd-update install. + However, freebsd-update will always + update the /usr/src/sys/conf/newvers.sh + file. The current patch level (as indicated by the + -p number reported by + uname -r) is obtained from this file. + Rebuilding your custom kernel, even if nothing else changed, + will allow &man.uname.1; to accurately report the current + patch level of the system. This is particularly helpful + when maintaining multiple systems, as it allows for a quick assessment of the updates installed in each one. @@ -366,27 +375,30 @@ MergeChanges /etc/ /var/named/etc/ - If a custom kernel is in use, the upgrade process is slightly - more involved. A copy of the GENERIC kernel is - needed, and it should be placed in /boot/GENERIC. If the - GENERIC kernel is not already present in the - system, it may be obtained using one of the following methods: + If a custom kernel is in use, the upgrade process is + slightly more involved. A copy of the + GENERIC kernel is needed, and it should + be placed in + /boot/GENERIC. If the + GENERIC kernel is not already present in + the system, it may be obtained using one of the following + methods: - If a custom kernel has only been built once, the kernel in + If a custom kernel has only been built once, the + kernel in /boot/kernel.old is - actually the GENERIC one. Simply rename this - directory to - /boot/GENERIC. + actually the GENERIC one. Simply + rename this directory to /boot/GENERIC. - Assuming physical access to the machine is possible, a copy - of the GENERIC kernel can be installed from - the CD-ROM media. Insert your installation disc and use the - following commands: + Assuming physical access to the machine is possible, a + copy of the GENERIC kernel can be + installed from the CD-ROM media. Insert your installation + disc and use the following commands: &prompt.root; mount /cdrom &prompt.root; cd /cdrom/X.Y-RELEASE/kernels @@ -395,30 +407,33 @@ MergeChanges /etc/ /var/named/etc/Replace X.Y-RELEASE with the actual version of the release you are using. The - GENERIC kernel will be installed in /boot/GENERIC by default. + GENERIC kernel will be installed in + /boot/GENERIC by + default. - Failing all the above, the GENERIC kernel - may be rebuilt and installed from the sources: + Failing all the above, the + GENERIC kernel may be rebuilt and + installed from the sources: &prompt.root; cd /usr/src &prompt.root; env DESTDIR=/boot/GENERIC make kernel &prompt.root; mv /boot/GENERIC/boot/kernel/* /boot/GENERIC &prompt.root; rm -rf /boot/GENERIC/boot - For this kernel to be picked up as GENERIC + For this kernel to be picked up as + GENERIC by freebsd-update, the - GENERIC configuration file must not have been - modified in any way. It is also suggested that it is built - without any other special options (preferably with an empty - /etc/make.conf). + GENERIC configuration file must not + have been modified in any way. It is also suggested that + it is built without any other special options (preferably + with an empty /etc/make.conf). - Rebooting to the GENERIC kernel is not - required at this stage. + Rebooting to the GENERIC kernel is + not required at this stage. Major and minor version updates may be performed by providing freebsd-update with a release @@ -456,30 +471,31 @@ Does this look reasonable (y/n)? y - When using a custom kernel, the above step will produce a warning - similar to the following: + When using a custom kernel, the above step will produce a + warning similar to the following: WARNING: This system is running a "MYKERNEL" kernel, which is not a kernel configuration distributed as part of FreeBSD 8.0-RELEASE. This kernel will not be updated: you MUST update the kernel manually before running "/usr/sbin/freebsd-update install" - This warning may be safely ignored at this point. The updated - GENERIC kernel will be used as an intermediate - step in the upgrade process. + This warning may be safely ignored at this point. The + updated GENERIC kernel will be used as an + intermediate step in the upgrade process. After all patches have been downloaded to the local - system, they will then be applied. This process may take - a while depending on the speed and workload of the machine. + system, they will then be applied. This process may take a + while depending on the speed and workload of the machine. Configuration files will then be merged — this part - of the process requires some user intervention as a file may be - merged or an editor may appear on screen for a manual merge. - The results of every successful merge will be shown to the user - as the process continues. A failed or ignored merge will cause - the process to abort. Users may wish to make a backup of - /etc and manually merge - important files, such as master.passwd - or group at a later time. + of the process requires some user intervention as a file may + be merged or an editor may appear on screen for a manual + merge. The results of every successful merge will be shown to + the user as the process continues. A failed or ignored merge + will cause the process to abort. Users may wish to make a + backup of /etc and + manually merge important files, such as + master.passwd or + group at a later time. The system is not being altered yet, all patching and @@ -490,34 +506,37 @@ before running "/usr/sbin/freebsd-update user. - Once this process is complete, the upgrade may be committed - to disk using the following command. + Once this process is complete, the upgrade may be + committed to disk using the following command. &prompt.root; freebsd-update install The kernel and kernel modules will be patched first. At - this point the machine must be rebooted. If the system was running - with a custom kernel, use the &man.nextboot.8; command to set the - kernel for the next boot to /boot/GENERIC (which was - updated): + this point the machine must be rebooted. If the system was + running with a custom kernel, use the &man.nextboot.8; command + to set the kernel for the next boot to + /boot/GENERIC (which + was updated): &prompt.root; nextboot -k GENERIC - Before rebooting with the GENERIC kernel, - make sure it contains all drivers required for your system to boot - properly (and connect to the network, if the machine that is being - updated is accessed remotely). In particular, if the previously - running custom kernel contained built-in functionality usually - provided by kernel modules, make sure to temporarily load these - modules into the GENERIC kernel using the - /boot/loader.conf facility. You may also wish - to disable non-essential services, disk and network mounts, etc. - until the upgrade process is complete. + Before rebooting with the GENERIC + kernel, make sure it contains all drivers required for your + system to boot properly (and connect to the network, if the + machine that is being updated is accessed remotely). In + particular, if the previously running custom kernel + contained built-in functionality usually provided by kernel + modules, make sure to temporarily load these modules into + the GENERIC kernel using the + /boot/loader.conf facility. You may + also wish to disable non-essential services, disk and + network mounts, etc. until the upgrade process is + complete. - The machine should now be restarted with the updated kernel: + The machine should now be restarted with the updated + kernel: &prompt.root; shutdown -r now @@ -558,9 +577,9 @@ before running "/usr/sbin/freebsd-update &prompt.root; freebsd-update install - If the GENERIC kernel was temporarily used, - this is the time to build and install a new custom kernel in the - usual way. + If the GENERIC kernel was temporarily + used, this is the time to build and install a new custom + kernel in the usual way. Reboot the machine into the new &os; version. The process is complete. @@ -578,10 +597,11 @@ before running "/usr/sbin/freebsd-update &prompt.root; freebsd-update IDS >> outfile.ids - While the command name is IDS it should - in no way be a replacement for an intrusion detection system - such as security/snort. - As freebsd-update stores data on disk, the + While the command name is IDS it + should in no way be a replacement for an intrusion detection + system such as + security/snort. As + freebsd-update stores data on disk, the possibility of tampering is evident. While this possibility may be reduced by using the kern.securelevel setting and storing the @@ -593,9 +613,9 @@ before running "/usr/sbin/freebsd-update The system will now be inspected, and a list of files - along with their &man.sha256.1; hash values, both the known value - in the release and the current installed value, will be printed. This is why - the output has been sent to the + along with their &man.sha256.1; hash values, both the known + value in the release and the current installed value, will be + printed. This is why the output has been sent to the outfile.ids file. It scrolls by too quickly for eye comparisons, and soon it fills up the console buffer. @@ -655,9 +675,10 @@ before running "/usr/sbin/freebsd-update the Ports Collection too: the &man.portsnap.8; utility. Upon execution, it will connect to a remote site, verify the secure key, and download a new copy of the Ports Collection. The key - is used to verify the integrity of all downloaded files, ensuring - they have not been modified in-flight. To download the latest - Ports Collection files, issue the following command: + is used to verify the integrity of all downloaded files, + ensuring they have not been modified in-flight. To download the + latest Ports Collection files, issue the following + command: &prompt.root; portsnap fetch Looking up portsnap.FreeBSD.org mirrors... 9 mirrors found. @@ -671,18 +692,18 @@ Fetching 90 patches.....10....20....30.. Applying patches... done. Fetching 133 new ports or files... done. - What this example shows is that &man.portsnap.8; - has found and verified - several patches to the current ports data. This also indicates - that the utility was run previously, if it was a first time - run, the collection would have simply been downloaded. + What this example shows is that &man.portsnap.8; has found + and verified several patches to the current ports data. This + also indicates that the utility was run previously, if it was a + first time run, the collection would have simply been + downloaded. - When &man.portsnap.8; successfully completes - a fetch operation, the Ports Collection and + When &man.portsnap.8; successfully completes a + fetch operation, the Ports Collection and subsequent patches exist on the local system that have passed - verification. The first time portsnap is executed, - you have to use extract to install the - downloaded files: + verification. The first time portsnap is + executed, you have to use extract to install + the downloaded files: &prompt.root; portsnap extract /usr/ports/.cvsignore @@ -698,17 +719,17 @@ Fetching 133 new ports or files... done. /usr/ports/Mk/bsd.cmake.mk ... - To update an already installed Ports Collection use the command - portsnap update: + To update an already installed Ports Collection use the + command portsnap update: &prompt.root; portsnap update The process is now complete, and applications may be installed or upgraded using the updated Ports Collection. - The fetch and extract or - update operations may be run consecutively, as - shown in the following example: + The fetch and extract + or update operations may be run + consecutively, as shown in the following example: &prompt.root; portsnap fetch update @@ -730,15 +751,16 @@ Fetching 133 new ports or files... done. Besides the base system and the Ports Collection, 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 at all. - Fortunately, there are several ways to update the documentation - shipped with each release by maintaining a local copy of the - latest &os; Documentation Set. + always available on the + &os; web site, + some users might have slow or no permanent network connectivity + at all. Fortunately, there are several ways to update the + documentation shipped with each release by maintaining a local + copy of the latest &os; Documentation Set. - Using <application>Subversion</application> to Update the Documentation + Using <application>Subversion</application> to Update the + Documentation The &os; documentation sources can be obtained with Subversion. This section @@ -747,8 +769,8 @@ Fetching 133 new ports or files... done. How to install the documentation toolchain, the tools - that are required to rebuild the &os; documentation from its - source. + that are required to rebuild the &os; documentation from + its source. @@ -759,8 +781,8 @@ Fetching 133 new ports or files... done. How to rebuild the &os; documentation from its source, - and install it - under /usr/share/doc. + and install it under /usr/share/doc. @@ -774,7 +796,8 @@ Fetching 133 new ports or files... done. - Installing <application>Subversion</application> and the Documentation Toolchain + Installing <application>Subversion</application> and the + Documentation Toolchain Rebuilding the &os; documentation from source requires a fairly large collection of tools. These tools are not part of @@ -785,22 +808,22 @@ Fetching 133 new ports or files... done. documentation from source. All the required tools are available as part of the Ports - Collection. The textproc/docproj port is a master - port that has been developed by the &os; Documentation Project, - to ease the initial installation and future updates of these - tools. + Collection. The + textproc/docproj port is a + master port that has been developed by the &os; Documentation + Project, to ease the initial installation and future updates + of these tools. 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. + 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. Subversion is installed with @@ -811,13 +834,14 @@ Fetching 133 new ports or files... done. Updating the Documentation Sources - The Subversion program can fetch a - clean copy of the documentation sources by typing: + The Subversion program can + fetch a clean copy of the documentation sources by + typing: &prompt.root; svn checkout svn://svn.FreeBSD.org/doc/head /usr/doc - The initial download of the documentation sources may take a - while. Let it run until it completes. + The initial download of the documentation sources may take + a while. Let it run until it completes. Future updates of the documentation sources may be fetched by running: @@ -826,8 +850,9 @@ Fetching 133 new ports or files... done. After checking out the sources, an alternative way of updating the documentation is supported by the - Makefile of the /usr/doc directory by running: + Makefile of the + /usr/doc directory by + running: &prompt.root; cd /usr/doc &prompt.root; make update @@ -841,7 +866,8 @@ Fetching 133 new ports or files... done. parts of the documentation, or the build of specific translations. These options can be set either as system-wide options in the /etc/make.conf file, or as - command-line options passed to the &man.make.1; utility. + command-line options passed to the &man.make.1; + utility. The following options are some of these: @@ -851,8 +877,8 @@ Fetching 133 new ports or files... done. The list of languages and encodings to build and - install, e.g., en_US.ISO8859-1 for the - English documentation only. + install, e.g., en_US.ISO8859-1 for + the English documentation only. @@ -879,22 +905,23 @@ Fetching 133 new ports or files... done. - For more make variables supported as system-wide options in - &os;, see &man.make.conf.5;. + For more make variables supported as system-wide options + in &os;, see &man.make.conf.5;. - For more make variables supported by the build system of the - &os; documentation, please refer to - the &os; - Documentation Project Primer for New Contributors. + For more make variables supported by the build system of + the &os; documentation, please refer to the + &os; + Documentation Project Primer for New + Contributors. Installing the &os; Documentation from Source - When an up-to-date snapshot of the documentation sources has - been fetched in /usr/doc, - everything is ready for an update of the installed - documentation. + When an up-to-date snapshot of the documentation sources + has been fetched in + /usr/doc, everything is + ready for an update of the installed documentation. A full update of all the languages defined in the DOC_LANG makefile option may be done by @@ -904,8 +931,9 @@ Fetching 133 new ports or files... done. &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, i.e.: + &man.make.1; can be invoked in a language specific + subdirectory of + /usr/doc, i.e.: &prompt.root; cd /usr/doc/en_US.ISO8859-1 &prompt.root; make update install clean @@ -943,13 +971,13 @@ Fetching 133 new ports or files... done. updates may not be feasible or practical for all &os; systems though. Building the documentation sources requires a fairly large collection of tools and utilities, the - documentation toolchain, a certain level of - familiarity with Subversion and source - checkouts from a repository, and a few manual steps to build the - checked out sources. In this section, we describe an - alternative way of updating the installed copies of the &os; - documentation; one that uses the Ports Collection and makes - it possible to: + documentation toolchain, a certain level + of familiarity with Subversion and + source checkouts from a repository, and a few manual steps to + build the checked out sources. In this section, we describe + an alternative way of updating the installed copies of the + &os; documentation; one that uses the Ports Collection + and makes it possible to: @@ -967,10 +995,10 @@ Fetching 133 new ports or files... done. These two methods of updating the &os; documentation are - supported by a set of documentation ports, - updated by the &a.doceng; on a monthly basis. These are listed - in the &os; Ports Collection, under the virtual category - named documentation ports, updated by the + &a.doceng; on a monthly basis. These are listed in the &os; + Ports Collection, under the virtual category named docs. @@ -981,8 +1009,8 @@ Fetching 133 new ports or files... done. 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. + deinstallation of documentation as easy as the installation + of any other &os; port or package. As an extra feature, when the documentation ports are @@ -991,19 +1019,21 @@ Fetching 133 new ports or files... done. latter is automatically installed too. - Organization of the documentation ports is as follows: + Organization of the documentation ports is as + follows: - There is a master port, misc/freebsd-doc-en, where the - documentation port files can be found. It is the base of - all documentation ports. By default, it builds the - English documentation only. + There is a master port, + misc/freebsd-doc-en, + where the documentation port files can be found. It is + the base of all documentation ports. By default, it + builds the English documentation only. - There is an all in one port, There is an all in one port, + misc/freebsd-doc-all, and it builds and installs all documentation in all available languages. @@ -1026,8 +1056,9 @@ Fetching 133 new ports or files... done. &prompt.root; make install clean This will build and install the English documentation in - split HTML format (the same as used on ) in the HTML format (the same as used on + ) in the + /usr/local/share/doc/freebsd directory. @@ -1035,17 +1066,17 @@ Fetching 133 new ports or files... done. Common Knobs and Options There are many options for modifying the default - behavior of the documentation ports. The following is just - a short list: + behavior of the documentation ports. The following is + just a short list: WITH_HTML - Allows the build of the HTML format: a single HTML - file per document. The formatted documentation is - saved to a file called + Allows the build of the HTML format: a single + HTML file per document. The formatted documentation + is saved to a file called article.html, or book.html, as appropriate, plus images. @@ -1056,12 +1087,14 @@ Fetching 133 new ports or files... done. WITH_PDF - Allows the build of the &adobe; Portable Document - Format, for use with &adobe; &acrobat.reader;, + Allows the build of the &adobe; Portable + Document Format, for use with &adobe; + &acrobat.reader;, Ghostscript or other PDF readers. The formatted documentation is saved to a file called article.pdf or - book.pdf, as appropriate. + book.pdf, as + appropriate. @@ -1076,11 +1109,11 @@ Fetching 133 new ports or files... done. Notice that the default target directory differs from the directory used by the - Subversion method. This is - because we are installing a port, and ports are - usually installed under the /usr/local directory. - This can be overridden by adding the + Subversion method. + This is because we are installing a port, and + ports are usually installed under the /usr/local + directory. This can be overridden by adding the PREFIX variable. @@ -1099,13 +1132,14 @@ Fetching 133 new ports or files... done. 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. + 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 @@ -1118,8 +1152,9 @@ Fetching 133 new ports or files... done. formats for the given language. - For example, the following command will install the latest - pre-built package of the Hungarian documentation: + For example, the following command will install the + latest pre-built package of the Hungarian + documentation: &prompt.root; pkg_add -r hu-freebsd-doc @@ -1127,8 +1162,8 @@ Fetching 133 new ports or files... done. Packages have the following name format that differs from the corresponding port's name: lang-freebsd-doc. - Here lang is the short format of - the language code, i.e., hu for + Here lang is the short format + of the language code, i.e., hu for Hungarian, or zh_cn for Simplified Chinese. @@ -1138,11 +1173,11 @@ Fetching 133 new ports or files... done. Updating Documentation Ports To update a previously installed documentation port, any - tool suitable for updating ports is sufficient. For example, - the following command updates the installed Hungarian - documentation via the ports-mgmt/portupgrade tool by - using packages only: + tool suitable for updating ports is sufficient. For + example, the following command updates the installed + Hungarian documentation via the + ports-mgmt/portupgrade + tool by using packages only: &prompt.root; portupgrade -PP hu-freebsd-doc @@ -1173,10 +1208,11 @@ Fetching 133 new ports or files... done. Docsnap is an &man.rsync.1; repository for updating installed &os; Documentation in a relatively easy and fast way. A - Docsnap server tracks - the documentation sources, and builds them in HTML format every - hour. The textproc/docproj - is unneeded with Docsnap as only + Docsnap server + tracks the documentation sources, and builds them in HTML + format every hour. The + textproc/docproj is + unneeded with Docsnap as only patches to the built documentation exist. The only requirement for using this technique is @@ -1187,11 +1223,11 @@ Fetching 133 new ports or files... done. Docsnap has been originally - developed for updating documentation installed - to /usr/share/doc, but - the following examples could be adapted for other directories - as well. For user directories, it does not require - root privileges. + developed for updating documentation installed to + /usr/share/doc, but + the following examples could be adapted for other + directories as well. For user directories, it does not + require root privileges. To update the documentation set, issue the following @@ -1206,12 +1242,11 @@ Fetching 133 new ports or files... done. above. - Do not use the flag here as there - are some items installed - into /usr/share/doc - during make installworld, which would - accidentally be removed. To clean up, use this command - instead: *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***