- Rewrap long lines
- Translators, please ignore this commit With help from: textproc/igor
This commit is contained in:
Glen Barber
parent
0c8f0a640e
commit
d7d10855dd
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=38528
1 changed files with 147 additions and 128 deletions
|
|
@ -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 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 build space and the
|
||||
installed web pages.</para>
|
||||
<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
|
||||
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 Collection. The following sample supfile can be used to
|
||||
obtain a checkout of the files required for the website build:</para>
|
||||
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
|
||||
|
|
@ -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 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 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>
|
||||
<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
|
||||
<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 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>
|
||||
<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>
|
||||
|
|
@ -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>
|
||||
<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>
|
||||
<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>
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue