Updating and Editing Website Content

Getting Content

The website content lives in the Boost Subversion repository. To get the website content, retrieve the website module from the Boost Subversion repository. For in progress work:

svn co https://svn.boost.org/svn/boost/website/public_html/beta

And for the live website:

svn co https://svn.boost.org/svn/boost/website/public_html/live

Existing Page

The web content is structured to be as simple as possible to make generic editing possible. At minimum only a text editor and HTML Tidy are needed to edit content. The content uses XHTML 1.0 Strict 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:

tidy --tidy-mark no -i -wrap 78 -m -asxhtml --merge-divs no --merge-spans no --doctype strict fname

Running HTML Tidy with a consistent set of options also helps in keeping an accurate change history in the repository. There are examples of the kinds of styles supported either directly or through the use of [class="value"] 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.

NOTE: The options for tidy are for the latest version. In particular the --merge-* 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 tidy if possible. You can obtain up to date Windows binaries, and sources from the HTML Tidy Library Project.

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:

Site URL Subversion
Beta http://beta.boost.org/ https://svn.boost.org/svn/boost/website/public_html/beta/
This is the experimetal version of the website. Changes should be made here first and then merged to the live website.
Live http://www.boost.org/ https://svn.boost.org/svn/boost/website/public_html/live/
The website the general public will see.

New Page

To make adding new pages easier there is a template to get one started. There are also _template_.html 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:

Introduction
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: /users
Community
For users who are interested in participating, or are already participitating, this section describes how the Boost community of users and developers functions. Directory: /community
Development
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: /development
Support
Content to help users in getting problems resolved can go here. This would include both public support as informally provided by the Boost developers and the over all Boost community and commercial support when available. Directory: /support
Documentation
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: /doc

To provide the section user interface look and feel there are some changes that need to be done to the template:

  • Each section has a different CSS style reference included in the head section. This reference needs to change to one of:

    • Introduction: /style/section-boost.css
    • Community: /style/section-community.css
    • Development: /style/section-development.css
    • Support: /style/section-support.css
    • Documentation: /style/section-doc.css

  • 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 sidebar section to one of:

    • Introduction: /common/sidebar-boost.html
    • Community: /common/sidebar-community.html
    • Development: /common/sidebar-development.html
    • Support: /common/sidebar-support.html
    • Documentation: /common/sidebar-doc.html

    In the sidebar 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 (/common/sidebar-common.html). It's the second #include that should be changed to reflect the current section.

  • Since this is a new page, you will also need to insert your own corresponding copyright in the footer.

  • To insert the new content you need to insert it into the section-body section. Replace the {stuff} placeholder with the content you want. In addition you might also want to change the title, in the head, and in the section-title section.

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...

Menus, Sidebars, and Index

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 one. 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 website/common directory:

  • Introduction: /common/menu-boost.html
  • Community: /common/menu-community.html
  • Development: /common/menu-development.html
  • Support: /common/menu-support.html
  • Documentation: /common/menu-doc.html

Feeds

There are various section of the web site that correspond to RSS feeds: news, downloads, and the version history. Even though they are displayed in various locations on the site the source feed documents are in the /feed directory. The content is not directly editable, but instead is generated from source Quickbook documents. For example to add a news item one would:

  1. Create a new file in the /feed/news directory, say /feed/news/gui_review_ends.qbk.
  2. In a shell, go to the /feed directory, and run bjam --boost-build=/path/to/tools/build/v2, or bjam --boost=/path/to/boost-root. This will generate the BoostBook XML for the new news item and regenerate the /feed/news.rss file.
  3. Add the new files to the SVN repository, and commit.

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 be precompiled and preconfigured in your user-config.jam. And also requires Python, in the path, to do the BoostBook to RSS translation.

Local Server

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:

  1. Install and get working Apache 2.x. and PHP 4.x or 5.x (install PHP as an Apache module, not as CGI).

  2. Set up a symbolic host lookup in your hosts file by adding "127.0.0.1 boost.localhost".

  3. Add a virtual host in Apache to match the new local host. A likely configuration to work is:

    <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
  </Directory>
</VirtualHost>

  4. Create a local PHP configuration file for Boost specific settings as "/path/to/boost/website/public_html/beta/common/code/boost_config_local.php" that contains something like:

    <?php
define('BOOST_RSS_DIR', '/path/to/boost/website/workplace/rss');
define('ARCHIVE_DIR', '/path/to/boost/website/workplace/archives');
define('RESULTS_DIR', '/path/to/boost/website/workplace/testing');
define('UNZIP', 'unzip');
?>

    For a brief explanation of the settings see the common/code/boost_config.php file.