svn commit: r39751 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Warren Block
wblock at FreeBSD.org
Sun Oct 14 17:32:57 UTC 2012
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 @@
<author>
<firstname>Jim</firstname>
<surname>Mock</surname>
- <contrib>Restructured, reorganized, and parts updated by </contrib>
+ <contrib>Restructured, reorganized, and parts updated
+ by</contrib>
</author>
<!-- Mar 2000 -->
</authorgroup>
@@ -46,17 +47,17 @@
<sect1 id="updating-upgrading-synopsis">
<title>Synopsis</title>
- <para>&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.</para>
+ <para>&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.</para>
<para>After reading this chapter, you will know:</para>
@@ -81,8 +82,8 @@
<listitem>
<para>How to keep your documentation up to date with
- <application>CVSup</application> or documentation ports<!--, and
- <application>Docsnap</application>-->.</para>
+ <application>CVSup</application> or documentation
+ ports<!--, and <application>Docsnap</application>-->.</para>
</listitem>
<listitem>
@@ -111,14 +112,15 @@
</itemizedlist>
<note>
- <para>Throughout this chapter, the <command>cvsup</command> command is
- used to obtain and update &os; sources. To use it, you will need to
- install the port or the package for <filename
- role="package">net/cvsup</filename> (if you do not want to install
- the graphical <command>cvsup</command> client, you can just install
- the port <filename>net/cvsup-without-gui</filename>).
- You may wish to substitute this
- with &man.csup.1;, which is part of the base system.</para>
+ <para>Throughout this chapter, the <command>cvsup</command>
+ command is used to obtain and update &os; sources. To use it,
+ you will need to install the port or the package for
+ <filename role="package">net/cvsup</filename> (if you do not
+ want to install the graphical <command>cvsup</command> client,
+ you can just install the port
+ <filename>net/cvsup-without-gui</filename>). You may wish to
+ substitute this with &man.csup.1;, which is part of the base
+ system.</para>
</note>
</sect1>
@@ -147,18 +149,19 @@
<see>updating-upgrading</see>
</indexterm>
- <para>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.</para>
+ <para>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.</para>
<para>This is no longer the case as &os; now includes a utility
simply called <command>freebsd-update</command>. 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.</para>
+ 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.</para>
<note>
<para>Binary updates are available for all architectures and
@@ -177,21 +180,22 @@
<sect2 id="freebsdupdate-config-file">
<title>The Configuration File</title>
- <para>Some users may wish to tweak the default configuration file
- in <filename>/etc/freebsd-update.conf</filename>,
- allowing better control of the process. The options are
- very well documented, but the following few may require a
- bit more explanation:</para>
+ <para>Some users may wish to tweak the default configuration
+ file in <filename>/etc/freebsd-update.conf</filename>,
+ allowing better control of the process. The options are very
+ well documented, but the following few may require a bit more
+ explanation:</para>
<programlisting># Components of the base system which should be kept updated.
Components src world kernel</programlisting>
- <para>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 <literal>world/games</literal> here would allow game patches to be
- applied. Using <literal>src/bin</literal> would allow the source code in
+ <para>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
+ <literal>world/games</literal> here would allow game patches
+ to be applied. Using <literal>src/bin</literal> would allow
+ the source code in
<filename class="directory">src/bin</filename> to be
updated.</para>
@@ -237,7 +241,7 @@ MergeChanges /etc/ /var/named/etc/</prog
are either accepted, open an editor, or
<command>freebsd-update</command> will abort. When in doubt,
backup <filename class="directory">/etc</filename> and just
- accept the merges. See <xref linkend="mergemaster"/> for more
+ accept the merges. See <xref linkend="mergemaster"/> for more
information about the <command>mergemaster</command>
command.</para>
@@ -278,17 +282,18 @@ MergeChanges /etc/ /var/named/etc/</prog
<para>If any kernel patches have been applied the system will
need a reboot. If all went well the system should be patched
and <command>freebsd-update</command> may be run as a nightly
- &man.cron.8; job. An entry in <filename>/etc/crontab</filename>
- would be sufficient to accomplish this task:</para>
+ &man.cron.8; job. An entry in
+ <filename>/etc/crontab</filename> would be sufficient to
+ accomplish this task:</para>
<programlisting>@daily root freebsd-update cron</programlisting>
<para>This entry states that once every day, the
- <command>freebsd-update</command> utility will be run. In this way,
- using the <option>cron</option> argument,
+ <command>freebsd-update</command> utility will be run. In
+ this way, using the <option>cron</option> argument,
<command>freebsd-update</command> 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
<username>root</username> user will be sent an email so they
may install them manually.</para>
@@ -298,50 +303,54 @@ MergeChanges /etc/ /var/named/etc/</prog
<screen>&prompt.root; <userinput>freebsd-update rollback</userinput></screen>
- <para>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.</para>
+ <para>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.</para>
<para>The <command>freebsd-update</command> utility can
- automatically update the <filename>GENERIC</filename> kernel only.
- If a custom kernel is in use, it will have to be rebuilt and
- reinstalled after <command>freebsd-update</command> finishes
- installing the rest of the updates. However,
- <command>freebsd-update</command> will detect and update the
- <filename>GENERIC</filename> kernel in <filename
- class="directory">/boot/GENERIC</filename> (if it exists), even if
- it is not the current (running) kernel of the system.</para>
+ automatically update the <filename>GENERIC</filename> kernel
+ only. If a custom kernel is in use, it will have to be
+ rebuilt and reinstalled after
+ <command>freebsd-update</command> finishes installing the rest
+ of the updates. However, <command>freebsd-update</command>
+ will detect and update the <filename>GENERIC</filename> kernel
+ in
+ <filename class="directory">/boot/GENERIC</filename> (if it
+ exists), even if it is not the current (running) kernel of the
+ system.</para>
<note>
<para>It is a good idea to always keep a copy of the
- <filename>GENERIC</filename> kernel in <filename
- class="directory">/boot/GENERIC</filename>. It will be helpful
- in diagnosing a variety of problems, and in performing version
- upgrades using <command>freebsd-update</command> as described in
+ <filename>GENERIC</filename> kernel in
+ <filename class="directory">/boot/GENERIC</filename>. It
+ will be helpful in diagnosing a variety of problems, and in
+ performing version upgrades using
+ <command>freebsd-update</command> as described in
<xref linkend="freebsdupdate-upgrade"/>.</para>
</note>
<para>Unless the default configuration in
- <filename>/etc/freebsd-update.conf</filename> has been changed,
- <command>freebsd-update</command> 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.</para>
+ <filename>/etc/freebsd-update.conf</filename> has been
+ changed, <command>freebsd-update</command> 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.</para>
<note>
- <para>The updates distributed via <command>freebsd-update</command>,
- 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
- <command>freebsd-update install</command>. However,
- <command>freebsd-update</command> will always update the
- <filename>/usr/src/sys/conf/newvers.sh</filename> file. The current
- patch level (as indicated by the <literal>-p</literal> number
- reported by <command>uname -r</command>) 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
+ <para>The updates distributed via
+ <command>freebsd-update</command>, 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 <command>freebsd-update install</command>.
+ However, <command>freebsd-update</command> will always
+ update the <filename>/usr/src/sys/conf/newvers.sh</filename>
+ file. The current patch level (as indicated by the
+ <literal>-p</literal> number reported by
+ <command>uname -r</command>) 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.</para>
</note>
</sect2>
@@ -366,27 +375,30 @@ MergeChanges /etc/ /var/named/etc/</prog
any prompts during this process, removing the need for
manual intervention during the build process.</para>
- <para>If a custom kernel is in use, the upgrade process is slightly
- more involved. A copy of the <filename>GENERIC</filename> kernel is
- needed, and it should be placed in <filename
- class="directory">/boot/GENERIC</filename>. If the
- <filename>GENERIC</filename> kernel is not already present in the
- system, it may be obtained using one of the following methods:</para>
+ <para>If a custom kernel is in use, the upgrade process is
+ slightly more involved. A copy of the
+ <filename>GENERIC</filename> kernel is needed, and it should
+ be placed in
+ <filename class="directory">/boot/GENERIC</filename>. If the
+ <filename>GENERIC</filename> kernel is not already present in
+ the system, it may be obtained using one of the following
+ methods:</para>
<itemizedlist>
<listitem>
- <para>If a custom kernel has only been built once, the kernel in
+ <para>If a custom kernel has only been built once, the
+ kernel in
<filename class="directory">/boot/kernel.old</filename> is
- actually the <filename>GENERIC</filename> one. Simply rename this
- directory to
- <filename class="directory">/boot/GENERIC</filename>.</para>
+ actually the <filename>GENERIC</filename> one. Simply
+ rename this directory to <filename
+ class="directory">/boot/GENERIC</filename>.</para>
</listitem>
<listitem>
- <para>Assuming physical access to the machine is possible, a copy
- of the <filename>GENERIC</filename> kernel can be installed from
- the CD-ROM media. Insert your installation disc and use the
- following commands:</para>
+ <para>Assuming physical access to the machine is possible, a
+ copy of the <filename>GENERIC</filename> kernel can be
+ installed from the CD-ROM media. Insert your installation
+ disc and use the following commands:</para>
<screen>&prompt.root; <userinput>mount /cdrom</userinput>
&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput>
@@ -395,30 +407,33 @@ MergeChanges /etc/ /var/named/etc/</prog
<para>Replace <filename
class="directory"><replaceable>X.Y-RELEASE</replaceable></filename>
with the actual version of the release you are using. The
- <filename>GENERIC</filename> kernel will be installed in <filename
- class="directory">/boot/GENERIC</filename> by default.</para>
+ <filename>GENERIC</filename> kernel will be installed in
+ <filename class="directory">/boot/GENERIC</filename> by
+ default.</para>
</listitem>
<listitem>
- <para>Failing all the above, the <filename>GENERIC</filename> kernel
- may be rebuilt and installed from the sources:</para>
+ <para>Failing all the above, the
+ <filename>GENERIC</filename> kernel may be rebuilt and
+ installed from the sources:</para>
<screen>&prompt.root; <userinput>cd /usr/src</userinput>
&prompt.root; <userinput>env DESTDIR=/boot/GENERIC make kernel</userinput>
&prompt.root; <userinput>mv /boot/GENERIC/boot/kernel/* /boot/GENERIC</userinput>
&prompt.root; <userinput>rm -rf /boot/GENERIC/boot</userinput></screen>
- <para>For this kernel to be picked up as <filename>GENERIC</filename>
+ <para>For this kernel to be picked up as
+ <filename>GENERIC</filename>
by <command>freebsd-update</command>, the
- <filename>GENERIC</filename> 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
- <filename>/etc/make.conf</filename>).</para>
+ <filename>GENERIC</filename> 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 <filename>/etc/make.conf</filename>).</para>
</listitem>
</itemizedlist>
- <para>Rebooting to the <filename>GENERIC</filename> kernel is not
- required at this stage.</para>
+ <para>Rebooting to the <filename>GENERIC</filename> kernel is
+ not required at this stage.</para>
<para>Major and minor version updates may be performed by
providing <command>freebsd-update</command> with a release
@@ -456,30 +471,31 @@ Does this look reasonable (y/n)? y</scre
some cases, the user may be prompted with questions regarding
what to install or how to proceed.</para>
- <para>When using a custom kernel, the above step will produce a warning
- similar to the following:</para>
+ <para>When using a custom kernel, the above step will produce a
+ warning similar to the following:</para>
<screen>WARNING: This system is running a "<replaceable>MYKERNEL</replaceable>" 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"</screen>
- <para>This warning may be safely ignored at this point. The updated
- <filename>GENERIC</filename> kernel will be used as an intermediate
- step in the upgrade process.</para>
+ <para>This warning may be safely ignored at this point. The
+ updated <filename>GENERIC</filename> kernel will be used as an
+ intermediate step in the upgrade process.</para>
<para>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
- <filename class="directory">/etc</filename> and manually merge
- important files, such as <filename>master.passwd</filename>
- or <filename>group</filename> at a later time.</para>
+ 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 <filename class="directory">/etc</filename> and
+ manually merge important files, such as
+ <filename>master.passwd</filename> or
+ <filename>group</filename> at a later time.</para>
<note>
<para>The system is not being altered yet, all patching and
@@ -490,34 +506,37 @@ before running "/usr/sbin/freebsd-update
user.</para>
</note>
- <para>Once this process is complete, the upgrade may be committed
- to disk using the following command.</para>
+ <para>Once this process is complete, the upgrade may be
+ committed to disk using the following command.</para>
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
<para>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 <filename
- class="directory">/boot/GENERIC</filename> (which was
- updated):</para>
+ 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
+ <filename class="directory">/boot/GENERIC</filename> (which
+ was updated):</para>
<screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen>
<warning>
- <para>Before rebooting with the <filename>GENERIC</filename> 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 <filename>GENERIC</filename> kernel using the
- <filename>/boot/loader.conf</filename> facility. You may also wish
- to disable non-essential services, disk and network mounts, etc.
- until the upgrade process is complete.</para>
+ <para>Before rebooting with the <filename>GENERIC</filename>
+ 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 <filename>GENERIC</filename> kernel using the
+ <filename>/boot/loader.conf</filename> facility. You may
+ also wish to disable non-essential services, disk and
+ network mounts, etc. until the upgrade process is
+ complete.</para>
</warning>
- <para>The machine should now be restarted with the updated kernel:</para>
+ <para>The machine should now be restarted with the updated
+ kernel:</para>
<screen>&prompt.root; <userinput>shutdown -r now</userinput></screen>
@@ -558,9 +577,9 @@ before running "/usr/sbin/freebsd-update
<screen>&prompt.root; <userinput>freebsd-update install</userinput></screen>
- <para>If the <filename>GENERIC</filename> kernel was temporarily used,
- this is the time to build and install a new custom kernel in the
- usual way.</para>
+ <para>If the <filename>GENERIC</filename> kernel was temporarily
+ used, this is the time to build and install a new custom
+ kernel in the usual way.</para>
<para>Reboot the machine into the new &os; version. The process
is complete.</para>
@@ -578,10 +597,11 @@ before running "/usr/sbin/freebsd-update
<screen>&prompt.root; <userinput>freebsd-update IDS >> outfile.ids</userinput></screen>
<warning>
- <para>While the command name is <acronym>IDS</acronym> it should
- in no way be a replacement for an intrusion detection system
- such as <filename role="package">security/snort</filename>.
- As <command>freebsd-update</command> stores data on disk, the
+ <para>While the command name is <acronym>IDS</acronym> it
+ should in no way be a replacement for an intrusion detection
+ system such as
+ <filename role="package">security/snort</filename>. As
+ <command>freebsd-update</command> stores data on disk, the
possibility of tampering is evident. While this possibility
may be reduced by using the
<varname>kern.securelevel</varname> setting and storing the
@@ -593,9 +613,9 @@ before running "/usr/sbin/freebsd-update
</warning>
<para>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
<filename>outfile.ids</filename> file. It scrolls by too
quickly for eye comparisons, and soon it fills up the console
buffer.</para>
@@ -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:</para>
+ 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:</para>
<screen>&prompt.root; <userinput>portsnap fetch</userinput>
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.</screen>
- <para>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.</para>
+ <para>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.</para>
- <para>When &man.portsnap.8; successfully completes
- a <command>fetch</command> operation, the Ports Collection and
+ <para>When &man.portsnap.8; successfully completes a
+ <command>fetch</command> operation, the Ports Collection and
subsequent patches exist on the local system that have passed
- verification. The first time <command>portsnap</command> is executed,
- you have to use <literal>extract</literal> to install the
- downloaded files:</para>
+ verification. The first time <command>portsnap</command> is
+ executed, you have to use <literal>extract</literal> to install
+ the downloaded files:</para>
<screen>&prompt.root; <userinput>portsnap extract</userinput>
/usr/ports/.cvsignore
@@ -698,17 +719,17 @@ Fetching 133 new ports or files... done.
/usr/ports/Mk/bsd.cmake.mk
<replaceable>...</replaceable></screen>
- <para>To update an already installed Ports Collection use the command
- <command>portsnap update</command>:</para>
+ <para>To update an already installed Ports Collection use the
+ command <command>portsnap update</command>:</para>
<screen>&prompt.root; <userinput>portsnap update</userinput></screen>
<para>The process is now complete, and applications may be
installed or upgraded using the updated Ports Collection.</para>
- <para>The <literal>fetch</literal> and <literal>extract</literal> or
- <literal>update</literal> operations may be run consecutively, as
- shown in the following example:</para>
+ <para>The <literal>fetch</literal> and <literal>extract</literal>
+ or <literal>update</literal> operations may be run
+ consecutively, as shown in the following example:</para>
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
@@ -730,15 +751,16 @@ Fetching 133 new ports or files... done.
<para>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 <ulink
- url="http://www.freebsd.org/doc/">&os; web site</ulink>, 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.</para>
+ always available on the
+ <ulink url="http://www.freebsd.org/doc/">&os; web site</ulink>,
+ 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.</para>
<sect2 id="dsvn-doc">
- <title>Using <application>Subversion</application> to Update the Documentation</title>
+ <title>Using <application>Subversion</application> to Update the
+ Documentation</title>
<para>The &os; documentation sources can be obtained with
<application>Subversion</application>. This section
@@ -747,8 +769,8 @@ Fetching 133 new ports or files... done.
<itemizedlist>
<listitem>
<para>How to install the documentation toolchain, the tools
- that are required to rebuild the &os; documentation from its
- source.</para>
+ that are required to rebuild the &os; documentation from
+ its source.</para>
</listitem>
<listitem>
@@ -759,8 +781,8 @@ Fetching 133 new ports or files... done.
<listitem>
<para>How to rebuild the &os; documentation from its source,
- and install it
- under <filename class="directory">/usr/share/doc</filename>.</para>
+ and install it under <filename
+ class="directory">/usr/share/doc</filename>.</para>
</listitem>
<listitem>
@@ -774,7 +796,8 @@ Fetching 133 new ports or files... done.
</sect2>
<sect2 id="installing-documentation-toolchain">
- <title>Installing <application>Subversion</application> and the Documentation Toolchain</title>
+ <title>Installing <application>Subversion</application> and the
+ Documentation Toolchain</title>
<para>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.</para>
<para>All the required tools are available as part of the Ports
- Collection. The <filename
- role="package">textproc/docproj</filename> 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.</para>
+ Collection. The
+ <filename role="package">textproc/docproj</filename> 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.</para>
<note>
<para>When no &postscript; or PDF documentation required, one
might consider installing the <filename
role="package">textproc/docproj-nojadetex</filename> port
- instead. This version of the documentation toolchain includes
- everything except the <application>teTeX</application>
- typesetting engine. <application>teTeX</application> is a
- very large collection of tools, so it may be quite sensible to
- omit its installation if PDF output is not really
- necessary.</para>
+ instead. This version of the documentation toolchain
+ includes everything except the
+ <application>teTeX</application> typesetting engine.
+ <application>teTeX</application> is a very large collection
+ of tools, so it may be quite sensible to omit its
+ installation if PDF output is not really necessary.</para>
</note>
<para><application>Subversion</application> is installed with
@@ -811,13 +834,14 @@ Fetching 133 new ports or files... done.
<sect2 id="updating-documentation-sources">
<title>Updating the Documentation Sources</title>
- <para>The <application>Subversion</application> program can fetch a
- clean copy of the documentation sources by typing:</para>
+ <para>The <application>Subversion</application> program can
+ fetch a clean copy of the documentation sources by
+ typing:</para>
<screen>&prompt.root; <userinput>svn checkout <literal>svn://svn.FreeBSD.org/doc/head</literal> <filename class="directory">/usr/doc</filename></userinput></screen>
- <para>The initial download of the documentation sources may take a
- while. Let it run until it completes.</para>
+ <para>The initial download of the documentation sources may take
+ a while. Let it run until it completes.</para>
<para>Future updates of the documentation sources may be fetched
by running:</para>
@@ -826,8 +850,9 @@ Fetching 133 new ports or files... done.
<para>After checking out the sources, an alternative way of
updating the documentation is supported by the
- <filename>Makefile</filename> of the <filename
- class="directory">/usr/doc</filename> directory by running:</para>
+ <filename>Makefile</filename> of the
+ <filename class="directory">/usr/doc</filename> directory by
+ running:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
&prompt.root; <userinput>make update</userinput></screen>
@@ -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 <filename>/etc/make.conf</filename> file, or as
- command-line options passed to the &man.make.1; utility.</para>
+ command-line options passed to the &man.make.1;
+ utility.</para>
<para>The following options are some of these:</para>
@@ -851,8 +877,8 @@ Fetching 133 new ports or files... done.
<listitem>
<para>The list of languages and encodings to build and
- install, e.g., <literal>en_US.ISO8859-1</literal> for the
- English documentation only.</para>
+ install, e.g., <literal>en_US.ISO8859-1</literal> for
+ the English documentation only.</para>
</listitem>
</varlistentry>
@@ -879,22 +905,23 @@ Fetching 133 new ports or files... done.
</varlistentry>
</variablelist>
- <para>For more make variables supported as system-wide options in
- &os;, see &man.make.conf.5;.</para>
+ <para>For more make variables supported as system-wide options
+ in &os;, see &man.make.conf.5;.</para>
- <para>For more make variables supported by the build system of the
- &os; documentation, please refer to
- the <ulink url="&url.doc.langbase;/books/fdp-primer">&os;
- Documentation Project Primer for New Contributors</ulink>.</para>
+ <para>For more make variables supported by the build system of
+ the &os; documentation, please refer to the
+ <ulink url="&url.doc.langbase;/books/fdp-primer">&os;
+ Documentation Project Primer for New
+ Contributors</ulink>.</para>
</sect2>
<sect2 id="updating-installed-documentation">
<title>Installing the &os; Documentation from Source</title>
- <para>When an up-to-date snapshot of the documentation sources has
- been fetched in <filename class="directory">/usr/doc</filename>,
- everything is ready for an update of the installed
- documentation.</para>
+ <para>When an up-to-date snapshot of the documentation sources
+ has been fetched in
+ <filename class="directory">/usr/doc</filename>, everything is
+ ready for an update of the installed documentation.</para>
<para>A full update of all the languages defined in
the <makevar>DOC_LANG</makevar> makefile option may be done by
@@ -904,8 +931,9 @@ Fetching 133 new ports or files... done.
&prompt.root; <userinput>make install clean</userinput></screen>
<para>If an update of only a specific language is desired,
- &man.make.1; can be invoked in a language specific subdirectory
- of <filename class="directory">/usr/doc</filename>, i.e.:</para>
+ &man.make.1; can be invoked in a language specific
+ subdirectory of
+ <filename class="directory">/usr/doc</filename>, i.e.:</para>
<screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
&prompt.root; <userinput>make update install clean</userinput></screen>
@@ -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
- <emphasis>documentation toolchain</emphasis>, a certain level of
- familiarity with <application>Subversion</application> 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:</para>
+ <emphasis>documentation toolchain</emphasis>, a certain level
+ of familiarity with <application>Subversion</application> 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:</para>
<itemizedlist>
<listitem>
@@ -967,10 +995,10 @@ Fetching 133 new ports or files... done.
</itemizedlist>
<para>These two methods of updating the &os; documentation are
- supported by a set of <emphasis>documentation ports</emphasis>,
- updated by the &a.doceng; on a monthly basis. These are listed
- in the &os; Ports Collection, under the virtual category
- named <ulink
+ supported by a set of
+ <emphasis>documentation ports</emphasis>, updated by the
+ &a.doceng; on a monthly basis. These are listed in the &os;
+ Ports Collection, under the virtual category named <ulink
url="http://www.freshports.org/docs/">docs</ulink>.</para>
<sect3 id="doc-ports-install-make">
@@ -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.</para>
+ deinstallation of documentation as easy as the installation
+ of any other &os; port or package.</para>
<note>
<para>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.</para>
</note>
- <para>Organization of the documentation ports is as follows:</para>
+ <para>Organization of the documentation ports is as
+ follows:</para>
<itemizedlist>
<listitem>
- <para>There is a <quote>master port</quote>, <filename
- role="package">misc/freebsd-doc-en</filename>, where the
- documentation port files can be found. It is the base of
- all documentation ports. By default, it builds the
- English documentation only.</para>
+ <para>There is a <quote>master port</quote>,
+ <filename role="package">misc/freebsd-doc-en</filename>,
+ where the documentation port files can be found. It is
+ the base of all documentation ports. By default, it
+ builds the English documentation only.</para>
</listitem>
<listitem>
- <para>There is an <quote>all in one port</quote>, <filename
+ <para>There is an <quote>all in one port</quote>,
+ <filename
role="package">misc/freebsd-doc-all</filename>, and it
builds and installs all documentation in all available
languages.</para>
@@ -1026,8 +1056,9 @@ Fetching 133 new ports or files... done.
&prompt.root; <userinput>make install clean</userinput></screen>
<para>This will build and install the English documentation in
- split <acronym>HTML</acronym> format (the same as used on <ulink
- url="http://www.FreeBSD.org"></ulink>) in the <filename
+ split <acronym>HTML</acronym> format (the same as used on
+ <ulink url="http://www.FreeBSD.org"></ulink>) in the
+ <filename
class="directory">/usr/local/share/doc/freebsd</filename>
directory.</para>
@@ -1035,17 +1066,17 @@ Fetching 133 new ports or files... done.
<title>Common Knobs and Options</title>
<para>There are many options for modifying the default
- behavior of the documentation ports. The following is just
- a short list:</para>
+ behavior of the documentation ports. The following is
+ just a short list:</para>
<variablelist>
<varlistentry>
<term><makevar>WITH_HTML</makevar></term>
<listitem>
- <para>Allows the build of the HTML format: a single HTML
- file per document. The formatted documentation is
- saved to a file called
+ <para>Allows the build of the HTML format: a single
+ HTML file per document. The formatted documentation
+ is saved to a file called
<filename>article.html</filename>, or
<filename>book.html</filename>, as appropriate, plus
images.</para>
@@ -1056,12 +1087,14 @@ Fetching 133 new ports or files... done.
<term><makevar>WITH_PDF</makevar></term>
<listitem>
- <para>Allows the build of the &adobe; Portable Document
- Format, for use with &adobe; &acrobat.reader;,
+ <para>Allows the build of the &adobe; Portable
+ Document Format, for use with &adobe;
+ &acrobat.reader;,
<application>Ghostscript</application> or other PDF
readers. The formatted documentation is saved to a
file called <filename>article.pdf</filename> or
- <filename>book.pdf</filename>, as appropriate.</para>
+ <filename>book.pdf</filename>, as
+ appropriate.</para>
</listitem>
</varlistentry>
@@ -1076,11 +1109,11 @@ Fetching 133 new ports or files... done.
<note>
<para>Notice that the default target directory
differs from the directory used by the
- <application>Subversion</application> method. This is
- because we are installing a port, and ports are
- usually installed under the <filename
- class="directory">/usr/local</filename> directory.
- This can be overridden by adding the
+ <application>Subversion</application> method.
+ This is because we are installing a port, and
+ ports are usually installed under the <filename
+ class="directory">/usr/local</filename>
+ directory. This can be overridden by adding the
<makevar>PREFIX</makevar> variable.</para>
</note>
</listitem>
@@ -1099,13 +1132,14 @@ Fetching 133 new ports or files... done.
<sect3 id="doc-ports-install-package">
<title>Using Documentation Packages</title>
- <para>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.</para>
+ <para>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.</para>
<para>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.</para>
</note>
- <para>For example, the following command will install the latest
- pre-built package of the Hungarian documentation:</para>
+ <para>For example, the following command will install the
+ latest pre-built package of the Hungarian
+ documentation:</para>
<screen>&prompt.root; <userinput>pkg_add -r hu-freebsd-doc</userinput></screen>
@@ -1127,8 +1162,8 @@ Fetching 133 new ports or files... done.
<para>Packages have the following name format that differs
from the corresponding port's name:
<literal><replaceable>lang</replaceable>-freebsd-doc</literal>.
- Here <replaceable>lang</replaceable> is the short format of
- the language code, i.e., <literal>hu</literal> for
+ Here <replaceable>lang</replaceable> is the short format
+ of the language code, i.e., <literal>hu</literal> for
Hungarian, or <literal>zh_cn</literal> for Simplified
Chinese.</para>
</note>
@@ -1138,11 +1173,11 @@ Fetching 133 new ports or files... done.
<title>Updating Documentation Ports</title>
<para>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 <filename
- role="package">ports-mgmt/portupgrade</filename> tool by
- using packages only:</para>
+ tool suitable for updating ports is sufficient. For
+ example, the following command updates the installed
+ Hungarian documentation via the
+ <filename role="package">ports-mgmt/portupgrade</filename>
+ tool by using packages only:</para>
<screen>&prompt.root; <userinput>portupgrade -PP hu-freebsd-doc</userinput></screen>
</sect3>
@@ -1173,10 +1208,11 @@ Fetching 133 new ports or files... done.
<para><application>Docsnap</application> is an &man.rsync.1;
repository for updating installed &os; Documentation in a
relatively easy and fast way. A
- <quote><application>Docsnap</application> server</quote> tracks
- the documentation sources, and builds them in HTML format every
- hour. The <filename role="package">textproc/docproj</filename>
- is unneeded with <application>Docsnap</application> as only
+ <quote><application>Docsnap</application> server</quote>
+ tracks the documentation sources, and builds them in HTML
+ format every hour. The
+ <filename role="package">textproc/docproj</filename> is
+ unneeded with <application>Docsnap</application> as only
patches to the built documentation exist.</para>
<para>The only requirement for using this technique is
@@ -1187,11 +1223,11 @@ Fetching 133 new ports or files... done.
<note>
<para><application>Docsnap</application> has been originally
- developed for updating documentation installed
- to <filename class="directory">/usr/share/doc</filename>, but
- the following examples could be adapted for other directories
- as well. For user directories, it does not require
- <username>root</username> privileges.</para>
+ developed for updating documentation installed to
+ <filename class="directory">/usr/share/doc</filename>, but
+ the following examples could be adapted for other
+ directories as well. For user directories, it does not
+ require <username>root</username> privileges.</para>
</note>
<para>To update the documentation set, issue the following
@@ -1206,12 +1242,11 @@ Fetching 133 new ports or files... done.
above.</para>
</note>
- <para>Do not use the <option>--delete</option> flag here as there
- are some items installed
- into <filename class="directory">/usr/share/doc</filename>
- during <command>make installworld</command>, which would
- accidentally be removed. To clean up, use this command
- instead:</para>
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-head
mailing list