aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml
blob: a62fdbd2c05a3c9adc9a9a416883f49b306d08c8 (plain) (blame)
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
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- 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 xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website">
  <title>The Website</title>

  <sect1 xml:id="the-website-build">
    <title>Build the Web Pages</title>

    <para>Having obtained the documentation and web site source files,
      the web site can be built.  In this example, the build directory
      is <filename>~/doc</filename>
      and all the required files are already in place.</para>

    <para>The web site is built from the
      <filename>en_US.ISO8859-1/htdocs</filename>
      subdirectory of the document tree directory,
      <filename>~/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>cd ~/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.user; <userinput>make all</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>/usr/ports</filename> is not
	present.  The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports
	Collection</link>.</para>
    </tip>
  </sect1>

  <sect1 xml:id="the-website-install">
    <title>Install the Web Pages</title>

    <para>Run <command>make install</command>, setting
      <varname>DESTDIR</varname> to the target directory for the web
      site files.  The files will be installed in
      <filename>$DESTDIR/data</filename>, which is
      expected to be the web server's document root.</para>

    <para>This installation is run as the <systemitem class="username">root</systemitem>
      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
      <systemitem class="username">jru</systemitem> in their home directory, <filename>/usr/home/jru/doc</filename>.</para>

    <screen>&prompt.root; <userinput>cd /home/jru/doc/en_US.ISO8859-1/htdocs</userinput>
&prompt.root; <userinput>env DESTDIR=/usr/local/www make install</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>find /usr/local/www -ctime 3 -delete</userinput></screen>
  </sect1>

  <sect1 xml:id="the-website-env">
    <title>Environment Variables</title>

    <variablelist>
      <varlistentry>
	<term><varname>ENGLISH_ONLY</varname></term>

	<listitem>
	  <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>make ENGLISH_ONLY=YES all install</userinput></screen>

	  <para>To unset the variable and build all pages, including
	    translations, set <varname>ENGLISH_ONLY</varname> to an
	    empty value:</para>

	  <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><varname>WEB_ONLY</varname></term>

	<listitem>
	  <para>If set and not empty, only the <acronym>HTML</acronym>
	    pages from the <filename>en_US.ISO8859-1/htdocs</filename>
	    directory will be built or installed.  All other
	    directories within
	    <filename>en_US.ISO8859-1</filename>
	    (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><varname>WEB_LANG</varname></term>

	<listitem>
	  <para>If set, build or install only for the languages
	    specified by this variable inside the <filename>~/doc</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>
    </variablelist>

    <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>,
      and <varname>ENGLISH_ONLY</varname> 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 dot files.</para>
  </sect1>
</chapter>