Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. — Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

Updating and Editing Website Content

Getting Content

The website content lives in the git repository.

In progress work is on the beta branch, the live website is on the master branch. The website is updated automatically from the git repo. If you want to update the website, please create a pull request.

Existing Page

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.

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 two modern browsers 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 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 Branch
Beta http://beta.boost.org/ beta
This is the experimetal version of the website. Development work should be done here first and then merged to the live website.
Live https://www.boost.org/ master
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
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-v2/section-boost.css
    • Community: /style-v2/section-community.css
    • Development: /style-v2/section-development.css
    • Support: /style-v2/section-support.css
    • Documentation: /style-v2/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
  • Documentation: /generated/menu-doc.html

Generated Pages

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:

  1. Create a new file in the /feed/news directory, say /feed/news/gui_review_ends.qbk.
  2. In a shell, run the /site-tools/update.py script. This will generate the page for the new news item, regenerate the /feed/news.rss file to include it, update pages which link to the new item and update the file /site-tools/state/feed-pages.txt which tracks the current state of generated files.
  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 and Python in your path.

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 5.3 or later (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"
  <Directory "/path/to/boost/website">
    Options +MultiViews +Includes +ExecCGI +FollowSymLinks +Includes
    AllowOverride All
    Order allow,deny
    Allow from all
    # For apache 2.4:
    # Require all granted
  </Directory>
</VirtualHost>

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

    <?php
define('BOOST_WEBSITE_SHARED_DIR', '/path/to/boost/shared');
define('STATIC_DIR', '/path/to/boost/shared/archives/live');
?>

    When setting up an official web server, the file should instead be called config.php, and placed at the path "/home/www/shared/config.php".

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

  5. In order to view the documentation you'll need to set up the appropriate directories. STATIC_DIR needs to be the location of unzipped copies of the appropriate boost distribution to serve the documentation. By default, boost_config.php sets STATIC_DIR to $BOOST_WEBSITE_SHARED_DIR/archives/live. Follow steps similar to this, changing variables as necessary:

    BOOST_WEBSITE_SHARED_DIR=/home/www/shared
mkdir -p $BOOST_WEBSITE_SHARED_DIR/archives/live
cd $BOOST_WEBSITE_SHARED_DIR/archives/live
wget https://archives.boost.io/release/1.74.0/source/boost_1_74_0.tar.gz
tar -xvf boost_1_74_0.tar.gz

Ubuntu setup

To setup the site on Ubuntu, I needed to do:

sudo apt-get install apache2 libapache2-mod-php5
sudo a2enmod headers
sudo a2enmod rewrite
sudo a2enmod include
sudo a2dismod deflate
sudo service apache2 restart

I had to disable deflate because it interacts badly with php's virtual function.