aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/the-website
diff options
context:
space:
mode:
authorGlen Barber <gjb@FreeBSD.org>2012-02-22 07:05:01 +0000
committerGlen Barber <gjb@FreeBSD.org>2012-02-22 07:05:01 +0000
commitd7d10855dd6f90ae8f164bf620122180e5bc7751 (patch)
tree4f18c5863e331c6058c927676c843ef810f5c094 /en_US.ISO8859-1/books/fdp-primer/the-website
parent0c8f0a640e85fc9e56bb7fcc0e9f4f67db955874 (diff)
downloaddoc-d7d10855dd6f90ae8f164bf620122180e5bc7751.tar.gz
doc-d7d10855dd6f90ae8f164bf620122180e5bc7751.zip
- Rewrap long lines
- Translators, please ignore this commit With help from: textproc/igor
Notes
Notes: svn path=/head/; revision=38528
Diffstat (limited to 'en_US.ISO8859-1/books/fdp-primer/the-website')
-rw-r--r--en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml279
1 files changed, 149 insertions, 130 deletions
diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
index eccc7ffa8c..152e8c8495 100644
--- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.sgml
@@ -36,45 +36,47 @@
<sect1 id="the-website-prep">
<title>Preparation</title>
- <para>Use a disk with sufficient free space. You may need anything from
- 200&nbsp;MB to over 500&nbsp;MB, depending on the method you choose.
- This space will hold the SGML tools, a subset of the
- <application>CVS</application> tree, temporary build space and the
- installed web pages.</para>
+ <para>Use a disk with sufficient free space. You may need
+ anything from 200&nbsp;MB to over 500&nbsp;MB, depending on the
+ method you choose. This space will hold the SGML tools, a
+ subset of the <application>CVS</application> 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>
+ <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>
</note>
- <para>There are two methods to get the files required for the website
- build:</para>
+ <para>There are two methods to get the files required for the
+ website build:</para>
<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>
+ <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 role="package">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>
+ <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 role="package">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>
@@ -83,8 +85,9 @@
<para><command>csup</command> is part of the base system and
already used extensively by most people for updating the
- Ports&nbsp;Collection. The following sample supfile can be used to
- obtain a checkout of the files required for the website build:</para>
+ Ports&nbsp;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
@@ -112,26 +115,25 @@ www
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>
+ <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
+ <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>
+ 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>That's it! You can now proceed with the
<link linkend="the-website-build">website build</link>.</para>
@@ -139,32 +141,37 @@ ports-base</programlisting>
<sect2 id="the-website-cvsup">
<title>Advanced Method: Maintaining a Local
- <application>CVS</application> <literal>doc/www</literal> Repository</title>
+ <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 role="package">net/cvsup-without-gui</filename> port or
+ <para>This method will give you more advanced options, but will
+ require you to install the <filename
+ role="package">net/cvsup-without-gui</filename> port or
package.</para>
<note>
- <para>The <filename role="package">net/cvsup-without-gui</filename>
- port has a build dependency on
- <filename role="package">lang/ezm3</filename>, a Modula&nbsp;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>
+ <para>The <filename
+ role="package">net/cvsup-without-gui</filename> port has a
+ build dependency on <filename
+ role="package">lang/ezm3</filename>, a Modula&nbsp;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;&nbsp;Handbook.</para>
-
- <para>The supfile shown below will fetch the cvs collections required
- for the website build, and create a local
+ <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;&nbsp;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>#
@@ -194,31 +201,32 @@ 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>
+ <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>
+ <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>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&nbsp;MB of free space to
- host the repository files. An additional 200&nbsp;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>
+ <para>Currently, you will need more than 400&nbsp;MB of free
+ space to host the repository files. An additional 200&nbsp;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>
@@ -226,23 +234,25 @@ cvsroot-doc</programlisting>
<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>
+ <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 directory is
- <filename
+ <para>Having completed either of the two methods, you will be
+ ready to start the website build. 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>
@@ -254,10 +264,10 @@ cvsroot-doc</programlisting>
</step>
<step>
- <para>The website build starts from the
- <filename class="directory">www/en</filename> directory by executing
- the &man.make.1; <maketarget>all</maketarget> target, to create
- the web pages.</para>
+ <para>The website build starts from the <filename
+ class="directory">www/en</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>
&prompt.root; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen>
@@ -270,18 +280,19 @@ cvsroot-doc</programlisting>
<procedure>
<step>
- <para>If you have moved out of the
- <filename class="directory">en</filename> directory, change back to
+ <para>If you have moved out of the <filename
+ class="directory">en</filename> directory, change back to
it.</para>
<screen>&prompt.root; <userinput><command>cd</command> <replaceable>/usr/build/www/en</replaceable></userinput></screen>
</step>
<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>
+ <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
root.</para>
@@ -289,11 +300,12 @@ cvsroot-doc</programlisting>
</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 find and delete all
- files that have not been updated in three days.</para>
+ <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
+ 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>
@@ -314,11 +326,12 @@ cvsroot-doc</programlisting>
<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>
+ <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>
@@ -327,15 +340,15 @@ cvsroot-doc</programlisting>
<listitem>
<para>If set and not empty, the makefiles will build and
- install only the English documents. All translations will be
- ignored. E.g.:</para>
+ install only the English documents. 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 <makevar>ENGLISH_ONLY</makevar>
- to an empty value:</para>
+ <makevar>ENGLISH_ONLY</makevar> and build all pages,
+ including translations, set the variable
+ <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>
</listitem>
@@ -345,10 +358,13 @@ cvsroot-doc</programlisting>
<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 class="directory">www</filename> directory. All documents from
- the <filename class="directory">doc</filename> directory (Handbook,
- FAQ, Tutorials) will be ignored. E.g.:</para>
+ <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.
+ E.g.:</para>
<screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen>
</listitem>
@@ -361,7 +377,8 @@ cvsroot-doc</programlisting>
<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
- other languages except English will be ignored. E.g.:</para>
+ 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>
</listitem>
@@ -371,19 +388,21 @@ cvsroot-doc</programlisting>
<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>
+ <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>,
- <filename>Makefile.inc</filename>, as environment variables on the
- command line, or in your dot files.</para>
+ <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>,
+ <filename>Makefile.inc</filename>, as environment variables on
+ the command line, or in your dot files.</para>
</sect1>
</chapter>