Editorial review of section on Updating the Documentation Set.
Sponsored by: iXsystems
This commit is contained in:
Dru Lavigne
parent
bb8526666d
commit
9334240a44
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44673
1 changed files with 132 additions and 269 deletions
|
|
@ -716,93 +716,39 @@ before running "/usr/sbin/freebsd-update install"</screen>
|
|||
</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>
|
||||
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>
|
||||
|
||||
<sect2 xml:id="dsvn-doc">
|
||||
<title>Using <application>Subversion</application> to Update the
|
||||
Documentation</title>
|
||||
<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>
|
||||
|
||||
<para>The &os; documentation sources can be obtained with
|
||||
<application>svn</application>. This section
|
||||
describes how to:</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>
|
||||
|
||||
<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 install"</screen>
|
|||
|
||||
<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>
|
||||
|
||||
<para>The updating and build system of the &os; documentation
|
||||
set supports a few options that ease the process of updating
|
||||
<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 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 install"</screen>
|
|||
<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 install"</screen>
|
|||
<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,174 +859,59 @@ before running "/usr/sbin/freebsd-update install"</screen>
|
|||
</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>
|
||||
|
||||
<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>There are many options for modifying the default
|
||||
behavior of the documentation ports, including:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><varname>WITH_HTML</varname></term>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>WITH_PDF</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>Builds the &adobe; Portable Document Format
|
||||
(PDF). The formatted documentation is saved to a
|
||||
file called <filename>article.pdf</filename> or
|
||||
<filename>book.pdf</filename>, as
|
||||
appropriate.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>DOCBASE</varname></term>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
|
||||
<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
|
||||
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>
|
||||
|
|
@ -1115,19 +925,72 @@ before running "/usr/sbin/freebsd-update install"</screen>
|
|||
Hungarian, or <literal>zh_cn</literal> for Simplified
|
||||
Chinese.</para>
|
||||
</note>
|
||||
</sect3>
|
||||
|
||||
<sect3 xml:id="doc-ports-update">
|
||||
<title>Updating Documentation Ports</title>
|
||||
<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>
|
||||
|
||||
<para>Documentation ports can be updated like any other port.
|
||||
<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
|
||||
&prompt.root; <userinput>make install clean</userinput></screen>
|
||||
|
||||
<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>Alternately, several <command>make</command> options can be specified
|
||||
when building a documentation port, including:</para>
|
||||
|
||||
<variablelist>
|
||||
<varlistentry>
|
||||
<term><varname>WITH_HTML</varname></term>
|
||||
|
||||
<listitem>
|
||||
<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>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>WITH_PDF</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>The formatted documentation is saved to a
|
||||
file called <filename>article.pdf</filename> or
|
||||
<filename>book.pdf</filename>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><varname>DOCBASE</varname></term>
|
||||
|
||||
<listitem>
|
||||
<para>Specifies where to install the documentation.
|
||||
It defaults to
|
||||
<filename>/usr/local/share/doc/freebsd</filename>.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>This example uses variables to install the Hungarian
|
||||
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>
|
||||
|
||||
<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>
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue