svn commit: r42053 - head/en_US.ISO8859-1/books/fdp-primer/the-website

Warren Block wblock at
Wed Jun 26 00:24:47 UTC 2013

Author: wblock
Date: Wed Jun 26 00:24:46 2013
New Revision: 42053

  Update "The Website" chapter to reflect current standards and writing


Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
--- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml	Tue Jun 25 23:46:46 2013	(r42052)
+++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml	Wed Jun 26 00:24:46 2013	(r42053)
@@ -37,38 +37,37 @@
   <sect1 id="the-website-prep">
-    <para>Use a disk with sufficient free space.  You may need
-      anything from 200 MB to over 500 MB, depending on the
-      method you choose.  This space will hold the XML tools, a
-      subset of the <application>svn</application> tree, temporary
+    <para>Use a disk with sufficient free space.  A full copy of
+      the documentation and web site files takes over 700 MB.
+      Allowing a full gigabyte provides some breathing room.
+      This space will hold the XML tools, the
+      documentation tree, temporary
       build space and the installed web pages.</para>
-      <para>Make sure your documentation ports are up to date!  When
-	in doubt, remove the old ports using &man.pkg.delete.1;
-	command before installing the port.  For example, we currently
-	depend on jade-1.2 and if you have installed jade-1.1, please
-	do:</para>
-      <screen>&prompt.root; <userinput><command>pkg_delete</command> jade-1.1</userinput></screen>
+      <para>Make sure the documentation ports are updated to the
+	latest version.  See <ulink
+	  url="&url.books.handbook;/ports.html#ports-using">the
+	  Handbook section on ports</ulink>
+	for more information.</para>
     <sect2 id="the-website-svn">
       <title>Using <command>svn</command></title>
-      <para><command>svn</command> is necessary to <quote>check
-	  out</quote> the necessary files from the
-	<literal>doc/</literal> Subversion repository.
+      <para><command>svn</command> is needed to check
+	out the documentation and web site files from the
+	<literal>doc</literal> Subversion repository.
 	<command>svn</command> can be installed with &man.pkg.add.1;
 	or from the &os; Ports Collection by running:</para>
       <screen>&prompt.root; <userinput><command>cd /usr/ports/devel/subversion</command></userinput>
 &prompt.root; <userinput><command>make</command> <maketarget>install clean</maketarget></userinput></screen>
-      <para>To check out the full source files for the &os; website,
+      <para>To check out the source files for the &os; web site and the rest of the documentation,
-      <screen>&prompt.root; <userinput><command>svn checkout <replaceable></replaceable>/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen>
+      <screen>&prompt.user; <userinput><command>svn checkout <replaceable></replaceable>/doc/head/ <replaceable>~/doc</replaceable></command></userinput></screen>
@@ -78,100 +77,69 @@
 	mirror sites</ulink>.</para>
-      <tip>
-	<para>If <command>svn</command> is not run as
-	  <username>root</username>, be sure <filename
-	    class="directory">/usr/build</filename> has the proper
-	  permissions for the current user.  If changing the
-	  permissions is not possible, use a different target
-	  directory for the website files.</para>
-      </tip>
-      <para>When <command>svn</command> finishes, the current version
-	of the &os; website will exist within <filename
-	  class="directory">/usr/build</filename>.  If a different
-	target directory was used, replace <filename
-	  class="directory">/usr/build</filename> appropriately
-	throughout the remainder of this document.</para>
-      <para>That's it! You can now proceed with the
-	<link linkend="the-website-build">website build</link>.</para>
+      <para>After the checkout completes, the current version
+	of the &os; documentation, including the web site files, will be present in <filename
+	  class="directory">~/doc</filename>.</para>
   <sect1 id="the-website-build">
-    <title>Build the Web Pages from Scratch</title>
+    <title>Build the Web Pages</title>
-    <para>Having completed the necessary steps to obtain the website
-      source files, the website can be built.  In our example, the
+    <para>Having obtained the documentation and web site
+      source files, the web site can be built.  In this example, the
       build directory is <filename
-	class="directory"><replaceable>/usr/build</replaceable></filename>
+	class="directory"><replaceable>~/doc</replaceable></filename>
       and all the required files are already in place.</para>
-    <procedure>
-      <step>
-	<para>Change into the build directory:</para>
-	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput></screen>
-      </step>
-      <step>
-	<para>The website build starts from the <filename
+    <para>The web site is built from the <filename
-	  directory by executing the &man.make.1;
-	  <maketarget>all</maketarget> target, to create the web
-	  pages.</para>
-	<screen>&prompt.root; <userinput><command>cd</command> en_US.ISO8859-1/htdocs</userinput>
-&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
-	<tip>
-	  <para>The build requires a few files from the Ports Collection
-	    and may fail without a properly configured Ports CVS
-	    mirror.  Set the <makevar>NOPORTSCVS</makevar> environment
-	    variable as described in <xref linkend="the-website-env"/>
-	    to use your local Ports Collection (typically <filename
-	      class="directory">/usr/ports</filename>) instead.</para>
-	</tip>
-      </step>
-    </procedure>
+	  subdirectory of the document tree directory,
+	  <filename class="directory">~/doc</filename> in this example.
+	  Change to the build directory and start the build by executing <command>make all</command>.</para>
+    <screen>&prompt.user; <userinput><command>cd</command> ~/doc/en_US.ISO8859-1/htdocs</userinput>
+&prompt.user; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
+    <tip>
+      <para>The web site build uses the <filename>INDEX</filename> from the Ports Collection
+	    and may fail if that file or <filename class="directory">/usr/ports</filename>
+	    is not present.  The simplest approach is to install the
+	    <ulink
+	      url="&url.books.handbook;/ports.html#ports-tree">Ports Collection</ulink>.</para>
+    </tip>
   <sect1 id="the-website-install">
-    <title>Install the Web Pages into Your Web Server</title>
-    <procedure>
-      <step>
-	<para>If you have moved out of the <filename
-	    class="directory">en_US.ISO8859-1/htdocs</filename>
-	  directory, change back to it.</para>
-	<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</replaceable></userinput></screen>
-      </step>
+    <title>Install the Web Pages</title>
-      <step>
-	<para>Run the &man.make.1; <maketarget>install</maketarget>
-	  target, setting the <makevar>DESTDIR</makevar> variable to
-	  the name of the directory you want to install the files to.
-	  The actual files are installed under <filename
-	    class="directory">$DESTDIR/data</filename>
-	  which should be configured as your web server's document
+    <para>Run <command>make install</command>,
+	  setting <makevar>DESTDIR</makevar> to
+	  the target directory for the web site files.
+	  The files will be installed in <filename
+	    class="directory">$DESTDIR/data</filename>,
+	  which is expected to be the web server's document
-	<screen>&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen>
-      </step>
-      <step>
-	<para>If you have previously installed the web pages into the
-	  same directory the install process will not have deleted any
-	  old or outdated pages.  For example, if you build and
-	  install a new copy of the site every day, this command will
+    <para>This installation is run as the
+	  <username>root</username> user because the permissions on
+	  the web server directory will not allow files to be
+	  installed by an unprivileged user.  In this example, the web site
+	  files were built by user <username>jru</username> in their
+	  home directory, <filename
+	    class="directory">/usr/home/jru/doc</filename>.</para>
+    <screen>&prompt.root; <userinput><command>cd</command> /home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
+&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen>
+    <para>The install process will not delete any old or outdated files
+	  that existed previously in the same directory.
+	  If a new copy of the site is built and
+	  installed every day, this command will
 	  find and delete all files that have not been updated in
 	  three days.</para>
-	<screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-print0</option> | <command>xargs</command> <option>-0</option> <command>rm</command></userinput></screen>
-      </step>
-    </procedure>
+    <screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-delete</option></userinput></screen>
   <sect1 id="the-website-env">
@@ -182,15 +150,15 @@
-	  <para>If set and not empty, the makefiles will build and
-	    install only the English documents.  All translations will
+	  <para>If set and not empty, only the English documents will
+	    be built or installed.  All translations will
 	    be ignored.  E.g.:</para>
 	  <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>
-	  <para>If you want to unset the variable
-	    <makevar>ENGLISH_ONLY</makevar> and build all pages,
-	    including translations, set the variable
+	  <para>To unset the variable
+	    and build all pages,
+	    including translations, set
 	    <makevar>ENGLISH_ONLY</makevar> to an empty value:</para>
 	  <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=""</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen>
@@ -201,10 +169,10 @@
-	  <para>If set and not empty, the Makefiles will build and
-	    install only the HTML pages from the <filename
+	  <para>If set and not empty, only the <acronym>HTML</acronym>
+	    pages from the <filename
-	    directory.  All other directories within <filename
+	    directory will be built or installed.  All other directories within <filename
 	    (Handbook, FAQ, Tutorials) will be ignored.
@@ -217,35 +185,23 @@
-	  <para>If set, the Makefiles will build and install only for
+	  <para>If set, build or install only for
 	    the languages specified by this variable inside the
-	      class="directory"><replaceable>/usr/build</replaceable></filename>
+	      class="directory"><replaceable>~/doc</replaceable></filename>
 	    directory.  All other languages except English will be
 	    ignored. E.g.:</para>
 	  <screen>&prompt.root; <userinput>make WEB_LANG="el_GR.ISO8859-7 es_ES.ISO8859-1 hu_HU.ISO8859-2 nl_NL.ISO8859-1" all install</userinput></screen>
-      <varlistentry>
-	<term><makevar>NOPORTSCVS</makevar></term>
-	<listitem>
-	  <para>If set, the Makefiles will not checkout files from the
-	    ports CVS repository.  Instead, it will copy the files
-	    from <filename class="directory">/usr/ports</filename> (or
-	    where the variable <envar>PORTSBASE</envar> points
-	    to).</para>
-	</listitem>
-      </varlistentry>
     <para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>,
-      <makevar>ENGLISH_ONLY</makevar> and
-      <makevar>NOPORTSCVS</makevar> are make variables.  You can set
-      the variables in <filename>/etc/make.conf</filename>,
+      and <makevar>ENGLISH_ONLY</makevar>
+      are &man.make.1; variables and
+      can be set in <filename>/etc/make.conf</filename>,
       <filename></filename>, as environment variables on
-      the command line, or in your dot files.</para>
+      the command line, or in dot files.</para>

More information about the svn-doc-all mailing list