Date: Sun, 14 Oct 2012 17:32:57 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r39751 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201210141732.q9EHWvqQ009787@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201210141732.q9EHWvqQ009787>