svn commit: r44673 - head/en_US.ISO8859-1/books/handbook/cutting-edge
Dru Lavigne
dru at FreeBSD.org
Mon Apr 28 16:19:09 UTC 2014
Author: dru
Date: Mon Apr 28 16:19:09 2014
New Revision: 44673
URL: http://svnweb.freebsd.org/changeset/doc/44673
Log:
Editorial review of section on Updating the Documentation Set.
Sponsored by: iXsystems
Modified:
head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
Modified: head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml
==============================================================================
--- head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Sun Apr 27 14:09:44 2014 (r44672)
+++ head/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml Mon Apr 28 16:19:09 2014 (r44673)
@@ -716,93 +716,39 @@ before running "/usr/sbin/freebsd-update
</indexterm>
<para>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
- <link xlink:href="http://www.freebsd.org/doc/">&os; web
- site</link>, some users might have slow or no permanent
- network connectivity. There are several ways to update the
- local copy of documentation with the latest &os; Documentation
- Set.</para>
-
- <sect2 xml:id="dsvn-doc">
- <title>Using <application>Subversion</application> to Update the
- Documentation</title>
-
- <para>The &os; documentation sources can be obtained with
- <application>svn</application>. This section
- describes how to:</para>
+ system. While an up-to-date version of the &os; documentation
+ is always available on the &os; web site
+ (<link xlink:href="&url.base;/doc/">http://www.freebsd.org/doc/</link>),
+ it can be handy to have an up-to-date, local copy of the &os;
+ website, handbooks, <acronym>FAQ</acronym>, and articles.</para>
+
+ <para>This section describes how to use either source or the &os;
+ Ports Collection to keep a local copy of the &os; documentation
+ up-to-date.</para>
- <itemizedlist>
- <listitem>
- <para>Install the documentation toolchain, the tools that
- are required to rebuild the &os; documentation from its
- source.</para>
- </listitem>
-
- <listitem>
- <para>Download a copy of the documentation source at
- <filename>/usr/doc</filename>, using
- <application>svn</application>.</para>
- </listitem>
-
- <listitem>
- <para>Rebuild the &os; documentation from its source, and
- install it under
- <filename>/usr/share/doc</filename>.</para>
- </listitem>
-
- <listitem>
- <para>Recognize some of the build options that are
- supported by the build system of the documentation, such
- as the options that build only some of the different
- language translations of the documentation or the options
- that select a specific output format.</para>
- </listitem>
- </itemizedlist>
- </sect2>
+ <para>For information on editing and submitting corrections to
+ the documentation, refer to the &os; Documentation
+ Project Primer for New Contributors
+ (<link xlink:href="&url.books.fdp-primer;">http://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/</link>).</para>
- <sect2 xml:id="installing-documentation-toolchain">
- <title>Installing <application>svn</application> and the
- Documentation Toolchain</title>
+ <sect2 xml:id="updating-installed-documentation">
+ <title>Updating Documentation from Source</title>
<para>Rebuilding the &os; documentation from source requires a
- collection of tools which are not part of the &os; base system
- due to the amount of disk space these tools use. They are
- also not useful to all &os; users, only those users that are
- actively writing new documentation for &os; or are frequently
- updating their documentation from source.</para>
-
- <para>The required tools, including
- <application>svn</application>, are available in the
- <package>textproc/docproj</package> meta-port
+ collection of tools which are not part of the &os; base system.
+ The required tools, including
+ <application>svn</application>, can be installed from the
+ <package>textproc/docproj</package> package or port
developed by the &os; Documentation Project.</para>
- <note>
- <para>When no &postscript; or PDF documentation required, one
- might consider installing the
- <package>textproc/docproj-nojadetex</package> 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>
- </note>
- </sect2>
-
- <sect2 xml:id="updating-documentation-sources">
- <title>Updating the Documentation Sources</title>
-
- <para>In this example, <application>svn</application> is used to
- fetch a clean copy of the documentation sources from the
- western US mirror using the HTTPS protocol:</para>
+ <para>Once installed, use <application>svn</application> to
+ fetch a clean copy of the documentation source. Replace
+ <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>
+ with the address of the closest geographic mirror from
+ <xref linkend="svn-mirrors"/>:</para>
<screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen>
- <para>Select the closest mirror from the available
- <link linkend="svn-mirrors">Subversion mirror
- sites</link>.</para>
-
<para>The initial download of the documentation sources may take
a while. Let it run until it completes.</para>
@@ -811,24 +757,42 @@ before running "/usr/sbin/freebsd-update
<screen>&prompt.root; <userinput>svn update /usr/doc</userinput></screen>
- <para>After checking out the sources, an alternative way of
- updating the documentation is supported by the
- <filename>/usr/doc/Makefile</filename> by running the
- following commands:</para>
+ <para>Once an up-to-date snapshot of the documentation sources
+ has been fetched to <filename>/usr/doc</filename>, everything
+ is ready for an update of the installed documentation.</para>
+
+ <para>A full update of all available languages may be performed
+ by typing:</para>
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
-&prompt.root; <userinput>make update</userinput></screen>
- </sect2>
+&prompt.root; <userinput>make install clean</userinput></screen>
- <sect2 xml:id="updating-documentation-options">
- <title>Tunable Options of the Documentation Sources</title>
+ <para>If an update of only a specific language is desired,
+ <command>make</command> can be invoked in a language-specific
+ subdirectory of
+ <filename>/usr/doc</filename>:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
+&prompt.root; <userinput>make install clean</userinput></screen>
+
+ <para>An alternative way of
+ updating the documentation is to run this
+ command from <filename>/usr/doc</filename> or
+ the desired language-specific subdirectory:</para>
+
+ <screen>&prompt.root; <userinput>make update</userinput></screen>
- <para>The updating and build system of the &os; documentation
- set supports a few options that ease the process of updating
+ <para>The output formats that will be installed may be specified
+ by setting <varname>FORMATS</varname>:</para>
+
+ <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
+&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
+
+ <para>Several options are available to ease the process of updating
only parts of the documentation, or the build of specific
translations. These options can be set either as system-wide
options in <filename>/etc/make.conf</filename>, or as
- command-line options passed to &man.make.1;.</para>
+ command-line options passed to <command>make</command>.</para>
<para>The options include:</para>
@@ -850,8 +814,8 @@ before running "/usr/sbin/freebsd-update
<para>A single format or a list of output formats to be
built. Currently, <literal>html</literal>,
<literal>html-split</literal>, <literal>txt</literal>,
- <literal>ps</literal>, <literal>pdf</literal>,
- and <literal>rtf</literal> are supported.</para>
+ <literal>ps</literal>, and <literal>pdf</literal>
+ are supported.</para>
</listitem>
</varlistentry>
@@ -868,50 +832,11 @@ before running "/usr/sbin/freebsd-update
<para>For more <command>make</command> variables supported as
system-wide options in &os;, refer to
&man.make.conf.5;.</para>
-
- <para>For more <command>make</command> variables supported by
- the build system of the &os; documentation, refer to the
- <link xlink:href="&url.doc.langbase;/books/fdp-primer">&os;
- Documentation Project Primer for New
- Contributors</link>.</para>
- </sect2>
-
- <sect2 xml:id="updating-installed-documentation">
- <title>Installing the &os; Documentation from Source</title>
-
- <para>Once an up-to-date snapshot of the documentation sources
- has been fetched to <filename>/usr/doc</filename>, everything
- is ready for an update of the installed documentation.</para>
-
- <para>A full update of all the languages defined in
- <varname>DOC_LANG</varname> may be performed by typing:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
-&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>/usr/doc</filename>:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput>
-&prompt.root; <userinput>make update install clean</userinput></screen>
-
- <para>The output formats that will be installed may be specified
- by setting <varname>FORMATS</varname>:</para>
-
- <screen>&prompt.root; <userinput>cd /usr/doc</userinput>
-&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
-
- <para>For information on editing and submitting corrections to
- the documentation, refer to the
- <link xlink:href="&url.books.fdp-primer;">&os; Documentation
- Project Primer for New Contributors</link>.</para>
</sect2>
- <sect2 xml:id="doc-ports">
+ <sect2 xml:id="doc-ports-install-package">
<info>
- <title>Using Documentation Ports</title>
+ <title>Updating Documentation from Ports</title>
<authorgroup>
<author>
@@ -934,95 +859,89 @@ before running "/usr/sbin/freebsd-update
</indexterm>
<para>The previous section presented a method for updating the
- &os; documentation from sources. Source based updates may not
- be feasible or practical for all &os; systems as building the
- documentation sources requires the <emphasis>documentation
- toolchain</emphasis>, a certain level of familiarity with
- <application>svn</application> and source checkouts from a
- repository, and a few manual steps to build the checked out
- sources. This section describes an alternative method which
+ &os; documentation from sources. This section describes an alternative method which
uses the Ports Collection and makes it possible to:</para>
<itemizedlist>
<listitem>
- <para>Download and install pre-built snapshots of the
+ <para>Install pre-built packages of the
documentation, without having to locally build anything
or install the documentation toolchain.</para>
</listitem>
<listitem>
- <para>Download the documentation sources and build them
+ <para>Build the documentation sources
through the ports framework, making the checkout and build
steps a bit easier.</para>
</listitem>
</itemizedlist>
- <para>These two methods of updating the &os; documentation are
+ <para>This method of updating the &os; documentation is
supported by a set of
- <emphasis>documentation ports</emphasis>, updated by the
+ documentation ports and packages which are updated by the
&a.doceng; on a monthly basis. These are listed in the &os;
- Ports Collection, under the <link
- xlink:href="http://www.freshports.org/docs/">docs</link>
- category.</para>
-
- <sect3 xml:id="doc-ports-install-make">
- <title>Building and Installing Documentation Ports</title>
-
- <para>The documentation ports use the ports building framework
- to make documentation builds easier. They automate the
- process of checking out the documentation source, running
- &man.make.1; with the appropriate environment settings and
- command-line options, and they make the installation or
- deinstallation of documentation as easy as the installation
- of any other &os; port or package.</para>
-
- <note>
- <para>As an extra feature, when the documentation ports are
- built locally, they record a dependency to the
- <emphasis>documentation toolchain</emphasis> ports, so
- that they are also automatically installed.</para>
- </note>
+ Ports Collection, under the docs category (<link
+ xlink:href="http://www.freshports.org/docs/">http://www.freshports.org/docs/</link>).</para>
<para>Organization of the documentation ports is as
follows:</para>
<itemizedlist>
<listitem>
- <para>The <quote>master port</quote>,
- <package>misc/freebsd-doc-en</package>, which installs
- all of the English documentation ports.</para>
+ <para>The
+ <package>misc/freebsd-doc-en</package> package or port installs
+ all of the English documentation.</para>
</listitem>
<listitem>
- <para>The <quote>all in one port</quote>,
- <package>misc/freebsd-doc-all</package>, builds and
+ <para>The
+ <package>misc/freebsd-doc-all</package> meta-package or port
installs all documentation in all available
languages.</para>
</listitem>
<listitem>
- <para>There is a <quote>slave port</quote> for each
+ <para>There is a package and port for each
translation, such as
<package>misc/freebsd-doc-hu</package> for the
- Hungarian-language documents.</para>
+ Hungarian documentation.</para>
</listitem>
</itemizedlist>
- <para>For example, to build and install the English
- documentation in split <acronym>HTML</acronym> format,
- similar to the format used on <uri
- xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>,
- to <filename>/usr/local/share/doc/freebsd</filename>,
- install the following port</para>
+ <para>When binary packages are used, the &os; documentation
+ will be installed in all available
+ formats for the given language. For example, the following command will install the
+ latest package of the Hungarian
+ documentation:</para>
+
+ <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen>
+
+ <note>
+ <para>Packages use a format that differs from the
+ corresponding port's name:
+ <literal><replaceable>lang</replaceable>-freebsd-doc</literal>,
+ where <replaceable>lang</replaceable> is the short format
+ of the language code, such as <literal>hu</literal> for
+ Hungarian, or <literal>zh_cn</literal> for Simplified
+ Chinese.</para>
+ </note>
+
+ <para>To specify the format of the documentation, build the
+ port instead of installing the package. For example, to build and install the English
+ documentation:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
&prompt.root; <userinput>make install clean</userinput></screen>
- <sect4 xml:id="doc-ports-options">
- <title>Common Knobs and Options</title>
+ <para>The port provides a configuration menu where the format
+ to build and install can be specified. By default, split
+ <acronym>HTML</acronym>, similar to the format used on <uri
+ xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>,
+ and <acronym>PDF</acronym> are
+ selected.</para>
- <para>There are many options for modifying the default
- behavior of the documentation ports, including:</para>
+ <para>Alternately, several <command>make</command> options can be specified
+ when building a documentation port, including:</para>
<variablelist>
<varlistentry>
@@ -1032,8 +951,7 @@ before running "/usr/sbin/freebsd-update
<para>Builds the HTML format with 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>
+ or <filename>book.html</filename>.</para>
</listitem>
</varlistentry>
@@ -1041,11 +959,9 @@ before running "/usr/sbin/freebsd-update
<term><varname>WITH_PDF</varname></term>
<listitem>
- <para>Builds the &adobe; Portable Document Format
- (PDF). The formatted documentation is saved to a
+ <para>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>.</para>
</listitem>
</varlistentry>
@@ -1056,78 +972,25 @@ before running "/usr/sbin/freebsd-update
<para>Specifies where to install the documentation.
It defaults to
<filename>/usr/local/share/doc/freebsd</filename>.</para>
-
- <note>
- <para>The default target directory differs from the
- directory used <application>svn</application>.
- This is because ports are usually installed within
- <filename>/usr/local</filename>.
- This can be overridden by using
- <varname>PREFIX</varname>.</para>
- </note>
</listitem>
</varlistentry>
</variablelist>
<para>This example uses variables to install the Hungarian
- documentation as a PDF:</para>
+ documentation as a <acronym>PDF</acronym> in the specified
+ directory:</para>
<screen>&prompt.root; cd /usr/ports/misc/freebsd-doc-hu
&prompt.root; make -DWITH_PDF DOCBASE=share/doc/freebsd/hu install clean</screen>
- </sect4>
- </sect3>
-
- <sect3 xml: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>The &a.doceng; prepares monthly snapshots of the &os;
- documentation packages. These binary packages can be used
- with any of the bundled package tools, like &man.pkg.add.1;,
- &man.pkg.delete.1;, and so on.</para>
-
- <note>
- <para>When binary packages are used, the &os; documentation
- will be installed in <emphasis>all</emphasis> available
- 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>
-
- <screen>&prompt.root; <userinput>pkg install hu-freebsd-doc</userinput></screen>
-
- <note>
- <para>Packages use a format that differs from the
- corresponding port's name:
- <literal><replaceable>lang</replaceable>-freebsd-doc</literal>,
- where <replaceable>lang</replaceable> is the short format
- of the language code, such as <literal>hu</literal> for
- Hungarian, or <literal>zh_cn</literal> for Simplified
- Chinese.</para>
- </note>
- </sect3>
-
- <sect3 xml:id="doc-ports-update">
- <title>Updating Documentation Ports</title>
- <para>Documentation ports can be updated like any other port.
+ <para>Documentation packages or ports can be updated using the
+ instructions in <xref linkend="ports"/>.
For example, the following command updates the installed
Hungarian documentation using
<package>ports-mgmt/portmaster</package>
by using packages only:</para>
<screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen>
- </sect3>
</sect2>
</sect1>
More information about the svn-doc-all
mailing list