Skip site navigation (1)Skip section navigation (2)
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&nbsp;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&nbsp;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>