Date: Mon, 28 Apr 2014 16:19:09 +0000 (UTC) From: Dru Lavigne <dru@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44673 - head/en_US.ISO8859-1/books/handbook/cutting-edge Message-ID: <201404281619.s3SGJ9or020276@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201404281619.s3SGJ9or020276>