forked from boostorg/website
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathwebsite_updating.html
429 lines (356 loc) · 18.1 KB
/
website_updating.html
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
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Boost C++ Libraries - Updating Website</title>
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
<link rel="icon" href="/favicon.ico" type="image/ico" />
<link rel="stylesheet" type="text/css" href=
"../style-v2/section-development.css" />
<!--[if IE 7]> <style type="text/css"> body { behavior: url(/style-v2/csshover3.htc); } </style> <![endif]-->
</head><!--
Note: Editing website content is documented at:
https://www.boost.org/development/website_updating.html
-->
<body>
<div id="heading">
<!--#include virtual="/common/heading.html" -->
</div>
<div id="body">
<div id="body-inner">
<div id="content">
<div class="section" id="intro">
<div class="section-0">
<div class="section-title">
<h1>Updating and Editing Website Content</h1>
</div>
<div class="section-body">
<ul class="toc">
<li><a href="#GettingContent">Getting Content</a></li>
<li><a href="#ExistingPage">Existing Page</a></li>
<li><a href="#NewPage">New Page</a></li>
<li><a href="#Menus">Menus, Sidebars, and Index</a></li>
<li><a href="#Feeds">Feeds</a></li>
<li><a href="#Local_Server">Local Server</a></li>
</ul>
<h2><a name="GettingContent" id="GettingContent"></a>Getting
Content</h2>
<p>The website content lives in the <a href=
"https://github.com/boostorg/website/">git repository</a>.</p>
<p>In progress work is on the <code>beta</code> branch, the
live website is on the <code>master</code> branch. The website
is updated automatically from the git repo. If you want to
update the website, please create a pull request.</p>
<h2><a name="ExistingPage" id="ExistingPage"></a>Existing
Page</h2>
<p>Large sections of the site are automatically generated, this
includes the release notes, the news pages and any files in the
generated directory. If you wish to edit these, see below.</p>
<p>The web content is structured to be as simple as possible to
make generic editing possible. At minimum only a text editor
and <a class="external" href=
"http://tidy.sourceforge.net/">HTML Tidy</a> are needed to edit
content. The content uses <a class="external" href=
"http://www.w3.org/TR/xhtml1/">XHTML 1.0 Strict</a> for various
reasons, the most important being to increase accessibility and
to enforce the separation of style from content. After getting
the content you want to edit as above, make the changes you
want and run the result through HTML Tidy with these
options:</p>
<pre>
tidy --tidy-mark no -i -wrap 78 -m -asxhtml --merge-divs no --merge-spans no --doctype strict <i>fname</i>
</pre>
<p>Running HTML Tidy with a consistent set of options also
helps in keeping an accurate change history in the repository.
There are <a href="/development/exemplar.html">examples</a> of
the kinds of styles supported either directly or through the
use of [<tt>class="<i>value</i>"</tt>] attributes for the
various XHTML tags. Please pay attention to any errors and
warnings that HTML Tidy mentions and strive to remove all of
them.</p>
<p><strong>NOTE:</strong> The options for <tt>tidy</tt> are for
the latest version. In particular the <tt>--merge-*</tt>
options may not be available in the version that comes as part
of many Unix/Linux distributions, and Windows utilities.
Removing the unavailable options is possible and will work. But
we recommend installing the latest <tt>tidy</tt> if possible.
You can obtain up to date Windows binaries, and sources from
the <a class="external" href=
"http://tidy.sourceforge.net/">HTML Tidy Library
Project</a>.</p>
<p>The pages should be viewable in most browsers. If possible
test you changes in as many as possible. Preferably at least
with IE and one other modern browser if you are on Windows. But
if you are on another platform testing with the "default"
browser is best. Normally viewing the page in outside of the a
web server context will only show you the content and part of
the footer. This is because the site uses Server Side Includes
(SSI) which most browsers will not process. To look at the
complete content you will need to either run your own Apache
server, or commit the changes and view the changes online
at:</p>
<table summary="Website Locations">
<tbody>
<tr>
<th>Site</th>
<th>URL</th>
<th>Branch</th>
</tr>
<tr>
<td>Beta</td>
<td><a href=
"http://beta.boost.org/">http://beta.boost.org/</a></td>
<td><code>beta</code></td>
</tr>
<tr>
<td colspan="3">This is the experimetal version of the
website. Development work should be done here first and
then merged to the live website.</td>
</tr>
<tr>
<td>Live</td>
<td><a href=
"https://www.boost.org/">https://www.boost.org/</a></td>
<td><code>master</code></td>
</tr>
<tr>
<td colspan="3">The website the general public will
see.</td>
</tr>
</tbody>
</table>
<h2><a id="NewPage" name="NewPage"></a>New Page</h2>
<p>To make adding new pages easier there is a <a href=
"/development/template/template.html">template</a> to get one
started. There are also <code>_template_.html</code> files in
the various site sections which already include the correct
sidebar menus. To start, copy the template to the section of
the website you want to add to and name the new file with a
reasonably clear name. The section is up to you but the
intended type of content for each is:</p>
<dl>
<dt><dfn>Introduction</dfn></dt>
<dd>Content to help new users understand what Boost is for
and what it is about. This is the one place where new
visitors are going to visit. Directory: <tt>/users</tt></dd>
<dt><dfn>Community</dfn></dt>
<dd>For users who are interested in participating, or are
already participitating, this section describes how the Boost
community of users and developers functions. Directory:
<tt>/community</tt></dd>
<dt><dfn>Development</dfn></dt>
<dd>Prospective or existing Boost developers make use of this
section to quickly get to the most frequetly used content.
This section is intended to hold the references to resources
or directly include content that changes frequently. Or
content that only pertains to library developers, although it
may be of more widespread interest as users become more
involved in the Boost community. Directory:
<tt>/development</tt></dd>
<dt><dfn>Documentation</dfn></dt>
<dd>This section organizes documents specific to the Boost
libraries. This includes at minimum the library documentation
published with each of the Boost releases. Also included is
access to the community maintained Wiki. Directory:
<tt>/doc</tt></dd>
</dl>
<p>To provide the section user interface look and feel there
are some changes that need to be done to the template:</p>
<ul>
<li>
<p>Each section has a different CSS style reference
included in the <tt>head</tt> section. This reference needs
to change to one of:</p>
<ul>
<li>Introduction:
<tt>/style-v2/section-boost.css</tt></li>
<li>Community:
<tt>/style-v2/section-community.css</tt></li>
<li>Development:
<tt>/style-v2/section-development.css</tt></li>
<li>Support: <tt>/style-v2/section-support.css</tt></li>
<li>Documentation:
<tt>/style-v2/section-doc.css</tt></li>
</ul>
</li>
<li>
<p>Each section displays a different context sensitive
sidebar menu through the use of SSI. The reference to the
sidebar to display needs to change in the <tt>sidebar</tt>
section to one of:</p>
<ul>
<li>Introduction:
<tt>/common/sidebar-boost.html</tt></li>
<li>Community:
<tt>/common/sidebar-community.html</tt></li>
<li>Development:
<tt>/common/sidebar-development.html</tt></li>
<li>Support: <tt>/common/sidebar-support.html</tt></li>
<li>Documentation: <tt>/common/sidebar-doc.html</tt></li>
</ul>
<p>In the <tt>sidebar</tt> section there are two menus
included the first is common to all the pages and contains
the download link and search box. Do not replace that
sidebar (<tt>/common/sidebar-common.html</tt>). It's the
second <tt>#include</tt> that should be changed to reflect
the current section.</p>
</li>
<li>
<p>Since this is a new page, you will also need to insert
your own corresponding copyright in the footer.</p>
</li>
<li>
<p>To insert the new content you need to insert it into the
<tt>section-body</tt> section. Replace the <tt>{stuff}</tt>
placeholder with the content you want. In addition you
might also want to change the title, in the <tt>head</tt>,
and in the <tt>section-title</tt> section.</p>
</li>
</ul>
<p>In addition to the immediate content for the new page one
needs to add an entry to the page so it can be accessed from
the sidebar and index. See below...</p>
<h2><a id="Menus" name="Menus"></a>Menus, Sidebars, and
Index</h2>
<p>The various navigation elements are structured to make
adding new entries easy and to keep all places where wuch
entries show consistent. To do this the site makes use of SSI
to reduce the locations that have those entries to
<em>one</em>. This means that changing it at the single common
place one doesn't have to worry about changing all the pages,
they all reflect the new content immediately. To add items to
the various section menus edit the corresponding menu file in
the <tt>website/common</tt> directory:</p>
<ul>
<li>Introduction: <tt>/common/menu-boost.html</tt></li>
<li>Community: <tt>/common/menu-community.html</tt></li>
<li>Development: <tt>/common/menu-development.html</tt></li>
<li>Documentation: <tt>/generated/menu-doc.html</tt></li>
</ul>
<h2><a id="Feeds" name="Feeds"></a>Generated Pages</h2>
<p>There are various sections of the web site that are
generated by a php script from quickbook source files: the home
page, news, downloads, version history and feeds. The content
is not directly editable, but instead is generated from source
Quickbook documents. For example, to add a news item one
would:</p>
<ol>
<li>Create a new file in the <tt>/feed/news</tt> directory,
say <tt>/feed/news/gui_review_ends.qbk</tt>.</li>
<li>In a shell, run the <tt>/site-tools/update.py</tt>
script. This will generate the page for the new news item,
regenerate the <tt>/feed/news.rss</tt> file to include it,
update pages which link to the new item and update the file
<tt>/site-tools/state/feed-pages.txt</tt> which tracks the
current state of generated files.</li>
<li>Add the new files to the SVN repository, and commit.</li>
</ol>
<p>The same procedure applies to the other feeds, but keep in
mind that some feeds may combine entries from more than one
feed subdirectory. Currently this requires Quickbook and Python
in your path.</p>
<h2><a id="Local_Server" name="Local_Server"></a>Local
Server</h2>
<p>Even though the web site is designed so that one only needs
some basic tools and a web browser to make changes there are
some aspects that are dynamic and hence will not work without
an accompanying web server. To set up local web server for
doing changes to the dynamic content one needs to:</p>
<ol>
<li>
<p>Install and get working <a href=
"http://httpd.apache.org/">Apache 2.x.</a> and <a href=
"http://php.net/">PHP 5.3 or later</a> (install PHP as an
Apache module, not as CGI).</p>
</li>
<li>
<p>Set up a symbolic host lookup in your <tt>hosts</tt>
file by adding "<tt>127.0.0.1 boost.localhost</tt>".</p>
</li>
<li>
<p>Add a virtual host in Apache to match the new local
host. A likely configuration to work is:</p>
<pre>
<VirtualHost 127.0.0.1:80>
ServerName boost.localhost
DocumentRoot "/path/to/boost/website/public_html/beta"
<Directory "/path/to/boost/website/public_html/beta">
Options +MultiViews +Includes +ExecCGI +FollowSymLinks +Includes
AllowOverride All
Order allow,deny
Allow from all
# For apache 2.4:
# Require all granted
</Directory>
</VirtualHost>
</pre>
</li>
<li>
<p>Create a local PHP configuration file for Boost specific
settings as
"<tt>/path/to/boost/website/public_html/beta/common/code/boost_config_local.php</tt>"
that contains something like:</p>
<pre>
<?php
define('BOOST_WEBSITE_SHARED_DIR', '/path/to/boost/website/workplace');
define('ARCHIVE_DIR', '/path/to/boost/website/workplace/archives');
define('RESULTS_DIR', '/path/to/boost/website/workplace/testing');
define('UNZIP', 'unzip');
?>
</pre>
<p>For a brief explanation of the settings see the
<tt><a href=
"https://github.com/boostorg/website/blob/master/common/code/boost_config.php">
common/code/boost_config.php</a></tt> file.</p>
</li>
<li>
<p>In order to view the documentation, or the build
sub-site, you'll need to setup the appropriate directories.
<tt>ARCHIVE_DIR</tt> needs to be the location of unzipped
copies of the appropriate boost distribution to serve the
documentation. <tt>/build</tt> needs to contain the
<a href="https://github.com/boostorg/build/tree/website"><tt>
website</tt> branch of Boost.Build</a>. A soft link to
another directory can be used here (which is how it's done
on the server).</p>
</li>
</ol>
<h3>Ubuntu setup</h3>
<p>To setup the site on Ubuntu, I needed to do:</p>
<pre>
sudo apt-get install apache2 libapache2-mod-php5
sudo a2enmod headers
sudo a2enmod rewrite
sudo a2enmod include
sudo a2dismod deflate
sudo service apache2 restart
</pre>
<p>I had to disable <code>deflate</code> because it interacts
badly with php's <code>virtual</code> function.</p>
</div>
</div>
</div>
</div>
<div id="sidebar">
<!--#include virtual="/common/sidebar-common.html" -->
<!--#include virtual="/common/sidebar-development.html" -->
</div>
<div class="clear"></div>
</div>
</div>
<div id="footer">
<div id="footer-left">
<div id="revised">
<p>Revised $Date$</p>
</div>
<div id="copyright">
<p>Copyright Rene Rivera 2006-2007.</p>
</div><!--#include virtual="/common/footer-license.html" -->
</div>
<div id="footer-right">
<!--#include virtual="/common/footer-banners.html" -->
</div>
<div class="clear"></div>
</div>
</body>
</html>