Add a section on updating the documentation set. It describes some
methods for updating, like using CVSup and rebuilding the documentation from source, and using Docsnap. Of course, other methods can be added later on, you can think of it as a stub for such methods. Note: The sub-section about Docsnap is temporarly disabled as there is no active Docsnap server at the moment. Co-authored by: keramida Reviewed by: keramida, manolis, murray, rene, trhodes
This commit is contained in:
Gabor Pali
parent
8bbbe9fa78
commit
b8f42eff83
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=33663
1 changed files with 327 additions and 0 deletions
|
|
@ -78,6 +78,12 @@
|
|||
a known pristine copy.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>How to keep your documentation up to date with
|
||||
<application>CVSup</application><!-- and
|
||||
<application>Docsnap</application>-->.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The difference between the two development
|
||||
branches: &os.stable; and &os.current;.</para>
|
||||
|
|
@ -698,6 +704,327 @@ Fetching 133 new ports or files... done.</screen>
|
|||
<screen>&prompt.root; <userinput>portsnap fetch update</userinput></screen>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="updating-upgrading-documentation">
|
||||
<title>Updating the Documentation Set</title>
|
||||
|
||||
<indexterm><primary>Updating and Upgrading</primary></indexterm>
|
||||
|
||||
<indexterm>
|
||||
<primary>Documentation</primary>
|
||||
<see>Updating and Upgrading</see>
|
||||
</indexterm>
|
||||
|
||||
<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>
|
||||
|
||||
<sect2 id="csup-doc">
|
||||
<title>Using CVSup to Update the Documentation</title>
|
||||
|
||||
<para>The sources and the installed copy of the &os; documentation
|
||||
can be updated with <application>CVSup</application>, using a
|
||||
mechanism similar to the one employed for the base system
|
||||
sources (c.f. <xref linkend="makeworld">). This section
|
||||
describes:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>How to install the documentation toolchain, the tools
|
||||
that are required to rebuild the &os; documentation from its
|
||||
source.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>How to download a copy of the documentation source
|
||||
at <filename class="directory">/usr/doc</filename>,
|
||||
using <application>CVSup</application>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>How to rebuild the &os; documentation from its source,
|
||||
and install it
|
||||
under <filename class="directory">/usr/share/doc</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Some of the build options that are supported by the
|
||||
build system of the documentation, i.e. 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>
|
||||
|
||||
<sect2 id="installing-documentation-toolchain">
|
||||
<title>Installing CVSup 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
|
||||
the &os; base system, because they need a large amount of disk
|
||||
space and they are not useful to all &os; users; they are only
|
||||
useful to those users that are actively writing new
|
||||
documentation for &os; or are frequently updating their
|
||||
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>
|
||||
|
||||
<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>
|
||||
</note>
|
||||
|
||||
<para>For more information on installing and using
|
||||
<application>CVSup</application>, see <link
|
||||
linkend="cvsup">Using CVSup</link>.</para>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="updating-documentation-sources">
|
||||
<title>Updating the Documentation Sources</title>
|
||||
|
||||
<para>The <application>CVSup</application> utility can fetch a
|
||||
clean copy of the documentation sources, using
|
||||
the <filename>/usr/share/examples/cvsup/doc-supfile</filename>
|
||||
file as a configuration template. The default update host is
|
||||
set to a placeholder value in <filename>doc-supfile</filename>,
|
||||
but &man.cvsup.1; accepts a host name through the command line,
|
||||
so the documentation sources can be fetched from one of the
|
||||
<application>CVSup</application> servers by typing:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cvsup -h <replaceable>cvsup.FreeBSD.org</replaceable> -g -L 2 <filename>/usr/share/examples/cvsup/doc-supfile</filename></userinput></screen>
|
||||
|
||||
<para>Change <replaceable>cvsup.FreeBSD.org</replaceable> to the
|
||||
nearest <application>CVSup</application> server. See <xref
|
||||
linkend="cvsup-mirrors"> for a complete listing of mirror
|
||||
sites.</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 the same command.
|
||||
The <application>CVSup</application> utility downloads and
|
||||
copies only the updates since the last time it ran, so every run
|
||||
of <application>CVSup</application> after the first complete run
|
||||
should be pretty fast.</para>
|
||||
|
||||
<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 setting
|
||||
<makevar>SUP_UPDATE</makevar>, <makevar>SUPHOST</makevar> and
|
||||
<makevar>DOCSUPFILE</makevar> in the
|
||||
<filename>/etc/make.conf</filename> file, it is possible to
|
||||
run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
|
||||
&prompt.root; <userinput>make update</userinput></screen>
|
||||
|
||||
<para>A typical set of these &man.make.1; options
|
||||
for <filename>/etc/make.conf</filename> is:</para>
|
||||
|
||||
<programlisting>SUP_UPDATE= yes
|
||||
SUPHOST?= cvsup.freebsd.org
|
||||
DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
|
||||
|
||||
<note>
|
||||
<para>Setting the <makevar>SUPHOST</makevar>
|
||||
and <makevar>DOCSUPFILE</makevar> value
|
||||
with <literal>?=</literal> permits overriding them in the
|
||||
command-line of make. This is the recommended way of adding
|
||||
options to <filename>make.conf</filename>, to avoid having to
|
||||
edit the file every time a different option value has to be
|
||||
tested.</para>
|
||||
</note>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="updating-documentation-options">
|
||||
<title>Tunable Options of the Documentation Sources</title>
|
||||
|
||||
<para>The updating and build system of the &os; documentation
|
||||
supports a few options that 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 the <filename>/etc/make.conf</filename> file, or as
|
||||
command-line options passed to the &man.make.1; utility.</para>
|
||||
|
||||
<para>The following options are some of these:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><makevar>DOC_LANG</makevar></term>
|
||||
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><makevar>FORMATS</makevar></term>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><makevar>SUPHOST</makevar></term>
|
||||
|
||||
<listitem>
|
||||
<para>The hostname of the <application>CVSup</application>
|
||||
server to use when updating.</para>
|
||||
</listitem>
|
||||
</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 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>A full update of all the languages defined in
|
||||
the <makevar>DOC_LANG</makevar> makefile option may be done by
|
||||
typing:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
|
||||
&prompt.root; <userinput>make install clean</userinput></screen>
|
||||
|
||||
<para>If <filename>make.conf</filename> has been set up with the
|
||||
correct <makevar>DOCSUPFILE</makevar>, <makevar>SUPHOST</makevar>
|
||||
and <makevar>SUP_UPDATE</makevar> options, the install step may
|
||||
be combined with an update of the documentation sources by
|
||||
typing:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
|
||||
&prompt.root; <userinput>make update 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>
|
||||
|
||||
<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 the <makevar>FORMATS</makevar> make variable,
|
||||
i.e.:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/doc</userinput>
|
||||
&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
|
||||
</sect2>
|
||||
|
||||
<!-- FIXME: Waiting for a working docsnap server... -->
|
||||
<![ IGNORE [
|
||||
<sect2 id="docsnap">
|
||||
<sect2info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Pav</firstname>
|
||||
<surname>Lucistnik</surname>
|
||||
<contrib>Based on information provided by </contrib>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</sect2info>
|
||||
|
||||
<title>Using Docsnap</title>
|
||||
|
||||
<indexterm><primary>Updating and Upgrading</primary></indexterm>
|
||||
|
||||
<indexterm>
|
||||
<primary>Docsnap</primary>
|
||||
<see>Updating and Upgrading</see>
|
||||
</indexterm>
|
||||
|
||||
<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
|
||||
patches to the built documentation exist.</para>
|
||||
|
||||
<para>The only requirement for using this technique is
|
||||
the <filename role="package">net/rsync</filename> port or
|
||||
package. To add it, use the following command:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>pkg_add -r rsync</userinput></screen>
|
||||
|
||||
<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>
|
||||
</note>
|
||||
|
||||
<para>To update the documentation set, issue the following
|
||||
command:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap <replaceable>/usr/share/doc</replaceable></userinput></screen>
|
||||
|
||||
<note>
|
||||
<para>There is only one <application>Docsnap</application>
|
||||
server at the moment;
|
||||
the <hostid>docsnap.sk.FreeBSD.org</hostid> shown
|
||||
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>
|
||||
|
||||
<screen>&prompt.root; <userinput>rsync -rltvz --delete <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/??_??\.\* <replaceable>/usr/share/doc</replaceable></userinput></screen>
|
||||
|
||||
<para>If a subset of documentation needs to be updated, for
|
||||
example, the English documentation only, the following command
|
||||
should be used:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>rsync -rltvz <replaceable>docsnap.sk.FreeBSD.org</replaceable>::docsnap/en_US.ISO8859-1 <replaceable>/usr/share/doc</replaceable></userinput></screen>
|
||||
</sect2>
|
||||
]]>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="current-stable">
|
||||
<title>Tracking a Development Branch</title>
|
||||
<indexterm><primary>-CURRENT</primary></indexterm>
|
||||
|
|
|
|||
Loading…
Reference in a new issue