1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
|
<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
Redistribution and use in source (SGML DocBook) and 'compiled' forms
(SGML HTML, PDF, PostScript, RTF and so forth) with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code (SGML DocBook) must retain the above
copyright notice, this list of conditions and the following
disclaimer as the first lines of this file unmodified.
2. Redistributions in compiled form (transformed to other DTDs,
converted to PDF, PostScript, RTF and other formats) must reproduce
the above copyright notice, this list of conditions and the
following disclaimer in the documentation and/or other materials
provided with the distribution.
THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
$FreeBSD$
-->
<chapter id="the-website">
<title>The Website</title>
<sect1 id="the-website-prep">
<title>Preparation</title>
<para>Get 200MB free disk space. You will need the disk space for the
SGML tools, a subset of the CVS tree, temporary build space and the
installed web pages. If you already have installed the SGML tools and
the CVS tree, you need only ~100MB free disk space.</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>pkg_delete jade-1.1</userinput></screen>
</note>
<para>Set up a CVS repository. You need the directories www, doc and
ports in the CVS tree (plus the CVSROOT of course). Please read the
<ulink url="&url.books.handbook;/synching.html#CVSUP">CVSup introduction</ulink>
on how to mirror a CVS tree or parts of a CVS tree.</para>
<para>The essential cvsup collections are: <literal>www</literal>,
<literal>doc-all</literal>, <literal>cvs-base</literal>, and
<literal>ports-base</literal>.</para>
<para>These collections require ~105MB free disk space.</para>
<para>A full CVS tree - including <literal>src</literal>,
<literal>doc</literal>, <literal>www</literal>, and
<literal>ports</literal> - is currently 940MB.</para>
</sect1>
<sect1 id="the-website-build">
<title>Build the web pages from scratch</title>
<procedure>
<step>
<para>Go to into a build directory with at least 60MB of free
space.</para>
<screen>&prompt.root; <userinput>mkdir /var/tmp/webbuild</userinput>
&prompt.root; <userinput>cd /var/tmp/webbuild</userinput></screen>
</step>
<step>
<para>Checkout the SGML files from the CVS tree.</para>
<screen>&prompt.root; <userinput>cvs -R co www doc</userinput></screen>
</step>
<step>
<para>Change into the <filename>www</filename> directory, and
run the &man.make.1; <maketarget>links</maketarget> target, to
create the necessary symbolic links.</para>
<screen>&prompt.root; <userinput>cd www</userinput>
&prompt.root; <userinput>make links</userinput></screen>
</step>
<step>
<para>Change into the <filename>en</filename> directory, and run
the &man.make.1; <maketarget>all</maketarget> target, to create
the web pages.</para>
<screen>&prompt.root; <userinput>cd en</userinput>
&prompt.root; <userinput>make all</userinput></screen>
</step>
</procedure>
</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>en</filename>
directory, change back to it.</para>
<screen>&prompt.root; <userinput>cd <replaceable>path</replaceable>/www/en</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.</para>
<screen>&prompt.root; <userinput>make DESTDIR=<replaceable>/usr/local/www</replaceable> install</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 find and delete all
files that have not been updated in three days.</para>
<screen>&prompt.root; <userinput>find <replaceable>/usr/local/www</replaceable> -ctime 3 -print0 | xargs -0 rm</userinput></screen>
</step>
</procedure>
</sect1>
<sect1 id="the-website-env">
<title>Environment variables</title>
<variablelist>
<varlistentry>
<term><envar>CVSROOT</envar></term>
<listitem>
<para>Location of the CVS tree. Essential.</para>
<screen><userinput>&prompt.root; CVSROOT=/home/ncvs; export CVSROOT</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<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 be
ignored. E.g.:</para>
<screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen>
<para>If you want 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>
<screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
</listitem>
</varlistentry>
<varlistentry>
<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 www directory. All documents from
the doc directory (Handbook, FAQ, Tutorials) will be ignored.
E.g.:</para>
<screen>&prompt.root; <userinput>make WEB_ONLY=YES 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>/usr/ports</filename> (or where the variable
<envar>PORTSBASE</envar> points to).</para>
</listitem>
</varlistentry>
</variablelist>
<para><envar>CVSROOT</envar> is an environment variable. You must set it
on the command line or in your dot files (~/.profile).</para>
<para><makevar>WEB_ONLY</makevar>, <makevar>ENGLISH_ONLY</makevar> and
<makevar>NOPORTSCVS</makevar> are makefile variables. You can set the
variables in <filename>/etc/make.conf</filename>,
<filename>Makefile.inc</filename> or as environment variables on the
command line or in your dot files.</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
sgml-parent-document: ("../book.sgml" "part" "chapter")
End:
-->
|
