Add a subsection on using the documentation ports.
Co-authored by: keramida Reviewed by: rene, manolis, trhodes, gabor, Ben Kaduk [1], keramida [1] minimarmot (at) gmail (dot) com
This commit is contained in:
Gabor Pali
parent
9948e825ef
commit
e49b2d81d9
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=34160
1 changed files with 231 additions and 1 deletions
|
|
@ -80,7 +80,7 @@
|
|||
|
||||
<listitem>
|
||||
<para>How to keep your documentation up to date with
|
||||
<application>CVSup</application><!-- and
|
||||
<application>CVSup</application> or documentation ports<!--, and
|
||||
<application>Docsnap</application>-->.</para>
|
||||
</listitem>
|
||||
|
||||
|
|
@ -959,6 +959,236 @@ DOCSUPFILE?= /usr/share/examples/cvsup/doc-supfile</programlisting>
|
|||
&prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen>
|
||||
</sect2>
|
||||
|
||||
<sect2 id="doc-ports">
|
||||
<sect2info>
|
||||
<authorgroup>
|
||||
<author>
|
||||
<firstname>Marc</firstname>
|
||||
<surname>Fonvieille</surname>
|
||||
<contrib>Based on the work of </contrib>
|
||||
</author>
|
||||
</authorgroup>
|
||||
</sect2info>
|
||||
|
||||
<title>Using Documentation Ports</title>
|
||||
|
||||
<indexterm><primary>Updating and Upgrading</primary></indexterm>
|
||||
|
||||
<indexterm>
|
||||
<primary>documentation package</primary>
|
||||
<see>Updating and Upgrading</see>
|
||||
</indexterm>
|
||||
|
||||
<para>In the previous section, we have presented a method for
|
||||
updating the &os; documentation from sources. Sources based on
|
||||
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>CVS</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>
|
||||
<para>Download and install pre-built snaphots of the
|
||||
documentation, without having to locally build anything
|
||||
(eliminating this way the need for an installation of the
|
||||
entire documentation toolchain).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Download the documentation sources and build them
|
||||
through the ports framework (making the checkout and build
|
||||
steps a bit eaiser).</para>
|
||||
</listitem>
|
||||
</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
|
||||
url="http://www.freshports.org/docs/">docs</ulink>.</para>
|
||||
|
||||
<sect3 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 the
|
||||
latter is automatically installed too.</para>
|
||||
</note>
|
||||
|
||||
<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>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Finally, there is a <quote>slave port</quote> for
|
||||
each translation, e.g.: <filename
|
||||
role="package">misc/freebsd-doc-hu</filename> for the
|
||||
Hungarian-language documents. All of them depend on the
|
||||
master port and install the translated documentation of
|
||||
the respective language.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>To install a documentation port from source, issue the
|
||||
following commands (as <username>root</username>):</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput>
|
||||
&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
|
||||
class="directory">/usr/local/share/doc/freebsd</filename>
|
||||
directory.</para>
|
||||
|
||||
<sect4 id="doc-ports-options">
|
||||
<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>
|
||||
|
||||
<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
|
||||
<filename>article.html</filename>, or
|
||||
<filename>book.html</filename>, as appropriate, plus
|
||||
images.</para>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><makevar>WITH_PDF</makevar></term>
|
||||
|
||||
<listitem>
|
||||
<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>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
|
||||
<varlistentry>
|
||||
<term><makevar>DOCBASE</makevar></term>
|
||||
|
||||
<listitem>
|
||||
<para>Where to install the documentation. It defaults
|
||||
to <filename
|
||||
class="directory">/usr/local/share/doc/freebsd</filename>.</para>
|
||||
|
||||
<note>
|
||||
<para>Notice that the default target directory
|
||||
differs from the directory used by the
|
||||
<application>CVSup</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 overriden, by adding the
|
||||
<makevar>PREFIX</makevar> variable.</para>
|
||||
</note>
|
||||
</listitem>
|
||||
</varlistentry>
|
||||
</variablelist>
|
||||
|
||||
<para>Here is a brief example on how to use the variables
|
||||
mentioned above to install the Hungarian documentation in
|
||||
Portable Document Format:</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 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_add -r hu-freebsd-doc</userinput></screen>
|
||||
|
||||
<note>
|
||||
<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
|
||||
Hungarian, or <literal>zh_cn</literal> for Simplified
|
||||
Chinese.</para>
|
||||
</note>
|
||||
</sect3>
|
||||
|
||||
<sect3 id="doc-ports-update">
|
||||
<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>
|
||||
|
||||
<screen>&prompt.root; <userinput>portupgrade -PP hu-freebsd-doc</userinput></screen>
|
||||
</sect3>
|
||||
</sect2>
|
||||
|
||||
<!-- FIXME: Waiting for a working docsnap server... -->
|
||||
<![ IGNORE [
|
||||
<sect2 id="docsnap">
|
||||
|
|
|
|||
Loading…
Reference in a new issue