Date: Sun, 20 May 2012 20:07:11 +0000 (UTC) From: Glen Barber <gjb@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r38856 - head/en_US.ISO8859-1/books/fdp-primer/the-website Message-ID: <201205202007.q4KK7BHY013352@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: gjb Date: Sun May 20 20:07:11 2012 New Revision: 38856 URL: http://svn.freebsd.org/changeset/doc/38856 Log: Update the FDP Primer "The Website" chapter for the CVS->SVN repository conversion: - Replace the 'the-website-csup' and 'the-website-cvsup' sections with a 'the-website-svn' section - Replace 'www/en' with 'en_US.ISO8859-1/htdocs' as the starting directory in the website build - Remove the documented CVSROOT environment variable - Update the WEB_LANG example to reflect the new repository layout - Add a 'tip' section, noting that if the initial 'svn checkout' command is not run as the root user, be sure that /usr/build is writable by the current user, or use a different checkout location Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml Modified: head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml Sun May 20 19:56:00 2012 (r38855) +++ head/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml Sun May 20 20:07:11 2012 (r38856) @@ -39,7 +39,7 @@ <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 SGML tools, a - subset of the <application>CVS</application> tree, temporary + subset of the <application>svn</application> tree, temporary build space and the installed web pages.</para> <note> @@ -52,205 +52,49 @@ <screen>&prompt.root; <userinput><command>pkg_delete</command> jade-1.1</userinput></screen> </note> - <para>There are two methods to get the files required for the - website build:</para> + <sect2 id="the-website-svn"> + <title>Using <command>svn</command></title> - <itemizedlist> - <listitem> - <para>Use <command>csup</command> to get a local copy of the - files from a <application>CVSup</application> server. This - is the easiest method, and does not require installation of - additional software. The supfile presented in the next - section will always checkout the latest version of the - required files. This is sufficient if you are simply - rebuilding the website and do not intend to commit any - changes.</para> - </listitem> - - <listitem> - <para>Use <command>cvsup</command> in <quote>cvs</quote> mode - to create and maintain a local - <application>CVS</application> repository with the required - files. This will require you to install a program like - <filename>net/cvsup-without-gui</filename>, - but it is a more flexible method if you need to have quick - access to different revisions of the doc/www files, revision - histories, or if you intend to commit changes to the central - &os; <application>CVS</application> repository.</para> - </listitem> - </itemizedlist> - - <sect2 id="the-website-csup"> - <title>Simple Method: Using <command>csup</command></title> - - <para><command>csup</command> is part of the base system and - already used extensively by most people for updating the - Ports Collection. The following sample supfile can be - used to obtain a checkout of the files required for the - website build:</para> - - <programlisting># -# This file checks out all collections required to rebuild -# the FreeBSD website -# -# Use the nearest CVSup mirror -# listed at http://www.freebsd.org/doc/handbook/mirrors.html. - -*default host=<replaceable>cvsup10.FreeBSD.org</replaceable> -*default base=/var/db -*default prefix=<replaceable>/usr/build</replaceable> -*default release=cvs tag=. -*default delete use-rel-suffix -*default compress - -# This will retrieve the entire doc branch of the FreeBSD repository. - -doc-all - -# This will retrieve the files required for the website - -www - -# This will retrieve some basic ports info required for the build - -ports-base</programlisting> - - <para>You should, of course, change the <literal>default - host</literal> entry to a <application>CVSup</application> - mirror near your location, and the <literal>default - prefix</literal> entry to the location where you intend to - store the checked out files. Save this file as e.g. - <filename><replaceable>doc-www-supfile</replaceable></filename>, - and then execute the following command:</para> - - <screen>&prompt.root; <userinput><command>csup</command> <option>-g</option> <option>-L2</option> <replaceable>doc-www-supfile</replaceable></userinput></screen> - - <para>When this command finishes, you will find the directories - <filename class="directory">doc/</filename>, <filename - class="directory">www/</filename> and <filename - class="directory">ports/</filename> under the directory you - specified in <literal>default prefix</literal> (<filename - class="directory"><replaceable>/usr/build</replaceable></filename> - in our example). We will use this same directory for the - build process itself, so it would be better to use a - filesystem with sufficient free space.</para> + <para><command>svn</command> is necessary to <quote>check + out</quote> the necessary 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, + run:</para> + + <screen>&prompt.root; <userinput><command>svn checkout svn://svn.FreeBSD.org/doc/head/ <replaceable>/usr/build</replaceable></command></userinput></screen> + + <tip> + <para>If <command>svn</command> is not run as the + <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> </sect2> - - <sect2 id="the-website-cvsup"> - <title>Advanced Method: Maintaining a Local - <application>CVS</application> <literal>doc/www</literal> - Repository</title> - - <para>This method will give you more advanced options, but will - require you to install the - <filename>net/cvsup-without-gui</filename> port or - package.</para> - - <note> - <para>The <filename>net/cvsup-without-gui</filename> port has - a build dependency on <filename - role="package">lang/ezm3</filename>, a Modula 3 - compiler. This compiler takes quite some time to build, - and since most people will not need it for anything else, it - is perhaps best to use a package to install - <application>CVSup</application>.</para> - </note> - - <para>The <application>CVSup</application> utility has a special - <quote>cvs</quote> mode that allows the retrieval of the - <quote>,v</quote> files that make up a - <application>CVS</application> repository. This function is - not currently available in <application>csup</application>. - For detailed information on <application>CVSup</application>, - please read the <ulink - url="&url.books.handbook;/synching.html#CVSUP">CVSup - introduction</ulink> in the &os; Handbook.</para> - - <para>The supfile shown below will fetch the cvs collections - required for the website build, and create a local - <application>CVS</application> repository:</para> - - <programlisting># -# This file will create a local CVS repository -# with the collections required for a complete -# FreeBSD website rebuild. It should be used with -# cvsup *only* (csup will not work) - -*default host=<replaceable>cvsup10.FreeBSD.org</replaceable> -*default base=/var/db -*default prefix=<replaceable>/usr/dcvs</replaceable> -*default release=cvs -*default delete use-rel-suffix -*default compress - -# The following collections are needed -# for the website build - -ports-base -doc-all -www - -# These collections are needed -# for CVS functionality - -cvsroot-common -cvsroot-ports -cvsroot-doc</programlisting> - - <para>You should, of course, change the <literal>default - host</literal> entry to a <application>CVSup</application> - mirror near your location, and the <literal>default - prefix</literal> entry to the location where you intend to - store the repository files. Save this file as e.g. - <filename><replaceable>doc-www-cvsfile</replaceable></filename>, - and then execute the following command:</para> - - <screen>&prompt.root; <userinput><command>cvsup</command> <option>-g</option> <option>-L2</option> <replaceable>doc-www-cvsfile</replaceable></userinput></screen> - - <para>It is also advisable to set the <envar>CVSROOT</envar> - environment variable in your shell's startup files. For - example, use the following entry in - <filename>~/.cshrc</filename>:</para> - - <programlisting>setenv <envar>CVSROOT</envar> <replaceable>/usr/dcvs</replaceable></programlisting> - - <para>If you set this variable, you may omit the - <option>-d</option> argument (shown below) when performing - repository operations using <command>cvs</command>.</para> - - <para>Currently, you will need more than 400 MB of free - space to host the repository files. An additional 200 MB - will be needed for the temporary build space. Once - <command>cvsup</command> completes, you are ready to check out - the files to your build directory:</para> - - <screen>&prompt.root; <userinput><command>mkdir</command> <replaceable>/usr/build</replaceable></userinput> -&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build</replaceable></userinput> -&prompt.root; <userinput><command>cvs</command> <option>-d</option> <replaceable>/usr/dcvs</replaceable> <option>-R</option> co <option>-AP</option> doc www ports</userinput></screen> - - <para>The above command is consistent with the way - <application>csup</application> checks out the files from the - <application>CVSup</application> servers. When it completes, - you will have a build directory with similar contents to the - one used in the simple <application>csup</application> - method.</para> - - <para>You can continue to use <command>cvsup</command> as shown - above, to update your local <application>CVS</application> - repository on a regular basis. After the initial somewhat - lengthy download, regular updates will only take a few - minutes.</para> - </sect2> </sect1> <sect1 id="the-website-build"> <title>Build the Web Pages from Scratch</title> - <para>Having completed either of the two methods, you will be - ready to start the website build. In our example, the build + <para>Having completed the necessary steps to obtain the website + source files, the website can be built. In our example, the build directory is <filename class="directory"><replaceable>/usr/build</replaceable></filename> and all the required files are already in place.</para> @@ -264,11 +108,11 @@ cvsroot-doc</programlisting> <step> <para>The website build starts from the <filename - class="directory">www/en</filename> directory by executing + 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> www/en</userinput> + <screen>&prompt.root; <userinput><command>cd</command> en_US.ISO8859-1/htdocs</userinput> &prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen> </step> </procedure> @@ -280,10 +124,10 @@ cvsroot-doc</programlisting> <procedure> <step> <para>If you have moved out of the <filename - class="directory">en</filename> directory, change back to + class="directory">en_US.ISO8859-1/htdocs</filename> directory, change back to it.</para> - <screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/www/en</replaceable></userinput></screen> + <screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/en_US.ISO8859-1/htdocs</replaceable></userinput></screen> </step> <step> @@ -316,25 +160,6 @@ cvsroot-doc</programlisting> <variablelist> <varlistentry> - <term><envar>CVSROOT</envar></term> - - <listitem> - <para>Location of the CVS tree. We suggest you set this - variable, if you use the <application>CVSup</application> - method:</para> - - <screen><userinput>&prompt.root; <makevar>CVSROOT</makevar>=<replaceable>/usr/dcvs</replaceable>; <command>export</command> <makevar>CVSROOT</makevar></userinput></screen> - - <para><envar>CVSROOT</envar> is an environment variable. - You must set it on the command line or in your dot files - (e.g., <filename>~/.profile</filename>). The exact syntax - will differ depending on your shell (the above example is - for <application>bash</application> and bash-like - shells).</para> - </listitem> - </varlistentry> - - <varlistentry> <term><makevar>ENGLISH_ONLY</makevar></term> <listitem> @@ -359,10 +184,10 @@ cvsroot-doc</programlisting> <listitem> <para>If set and not empty, the Makefiles will build and install only the HTML pages from the <filename - class="directory">www</filename> directory. All - documents from the <filename - class="directory">doc</filename> - directory (Handbook, FAQ, Tutorials) will be ignored. + class="directory">en_US.ISO8859-1/htdocs</filename> directory. + All other directories within <filename + class="directory">en_US.ISO8859-1</filename> + (Handbook, FAQ, Tutorials) will be ignored. E.g.:</para> <screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen> @@ -375,11 +200,11 @@ cvsroot-doc</programlisting> <listitem> <para>If set, the Makefiles will build and install only for the languages specified by this variable inside the - <filename class="directory">www</filename> directory. All + <filename class="directory"><replaceable>/usr/build</replaceable></filename> directory. All other languages except English will be ignored. E.g.:</para> - <screen>&prompt.root; <userinput>make WEB_LANG="el es hu nl" all install</userinput></screen> + <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>
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201205202007.q4KK7BHY013352>