Date: Wed, 26 Jun 2013 00:24:46 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r42053 - head/en_US.ISO8859-1/books/fdp-primer/the-website Message-ID: <201306260024.r5Q0OkB9012621@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: wblock Date: Wed Jun 26 00:24:46 2013 New Revision: 42053 URL: http://svnweb.freebsd.org/changeset/doc/42053 Log: Update "The Website" chapter to reflect current standards and writing style. Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml 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"> <title>Preparation</title> - <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> <note> - <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> </note> <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, run:</para> - <screen>&prompt.root; <userinput><command>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen> + <screen>&prompt.user; <userinput><command>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ <replaceable>~/doc</replaceable></command></userinput></screen> <para><ulink url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink> @@ -78,100 +77,69 @@ url="&url.books.handbook;/svn-mirrors.html">Subversion 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> </sect2> </sect1> <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 class="directory">en_US.ISO8859-1/htdocs</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> <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 root.</para> - <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> <sect1 id="the-website-env"> @@ -182,15 +150,15 @@ <term><makevar>ENGLISH_ONLY</makevar></term> <listitem> - <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 @@ <term><makevar>WEB_ONLY</makevar></term> <listitem> - <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 class="directory">en_US.ISO8859-1/htdocs</filename> - directory. All other directories within <filename + directory will be built or installed. All other directories within <filename class="directory">en_US.ISO8859-1</filename> (Handbook, FAQ, Tutorials) will be ignored. E.g.:</para> @@ -217,35 +185,23 @@ <term><makevar>WEB_LANG</makevar></term> <listitem> - <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 <filename - 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> </listitem> </varlistentry> - - <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> </variablelist> <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>Makefile.inc</filename>, as environment variables on - the command line, or in your dot files.</para> + the command line, or in dot files.</para> </sect1> </chapter>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306260024.r5Q0OkB9012621>