From fbb60689b7f81ef26553b0b82f0be556cf093812 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Mon, 1 Jun 2009 19:18:00 +0000 Subject: [PATCH 1/8] Extra guidelines for writing documentation for the web. [SVN r53551] --- writingdoc/structure.html | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index 900f2a6..b631785 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -116,6 +116,14 @@ by the standard. Boost libraries should also provided additional documentation, such as introductory, tutorial, example, and rationale material.

+ +

Since the documentation is also intended to act as a web reference, it's a + good idea to add some extra information to individual pages, especially + detailed reference pages. Full C++ identifiers and required headers are + especially useful and often overlooked. Remember that individual pages might + be accessed directly from a search engine or link, so readers won't have seen + information from previous pages. In reference pages, it can be helpful to link + to relevant tutorial information.

Standards Conforming Documentation

From 8b3b668ec4176d319a792627c1e770bb71750246 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Wed, 3 Jun 2009 22:48:11 +0000 Subject: [PATCH 2/8] New introduction and web reference guidelines, by Robert Stewart. [SVN r53611] --- writingdoc/structure.html | 76 ++++++++++++++++++++++++--------------- 1 file changed, 48 insertions(+), 28 deletions(-) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index b631785..af38aa8 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -90,40 +90,36 @@ +
Web Reference Documentation
+
Footnotes

Introduction

-

Boost itself does not require any specific documentation structure. The - C++ Standard, however, has very explicit requirements for the description - of library components (Section 17.3). So for Boost libraries likely to be - proposed for inclusion in the standard, it is highly desirable to structure - documentation in a way that meets the requirements of the the standard. - Doing so eliminates the need to rewrite the documentation for - standardization.

+

Boost does not require any specific documentation structure. + However, there are some important considerations that + influence content and structure. For example, many Boost + libraries wind up being proposed for inclusion in the C++ + Standard, so writing them initially with text suitable for + inclusion in the Standard may be helpful. Also, Boost library + documentation is often accessed via the World Wide Web, + including via search engines, so context is often important + for every page. Finally, Boost libraries should provide + additional documentation, such as introductory, tutorial, + example, and rationale content. With those things in mind, we + suggest the following guidelines for Boost library + documentation.

-

Library developers should remember that for a library to be accepted as - part of the C++ Standard Library, the proposal must include full wording. - The committee will not do that work for you.

- -

Beyond that, the documentation structure required for the standard is an - effective way to communicate the technical specifications for a library. - Although terse, it is already familiar to many Boost users, and is far more - precise than most ad hoc documentation structures.

- -

The following description is for the structure of documentation required - by the standard. Boost libraries should also provided additional - documentation, such as introductory, tutorial, example, and rationale - material.

- -

Since the documentation is also intended to act as a web reference, it's a - good idea to add some extra information to individual pages, especially - detailed reference pages. Full C++ identifiers and required headers are - especially useful and often overlooked. Remember that individual pages might - be accessed directly from a search engine or link, so readers won't have seen - information from previous pages. In reference pages, it can be helpful to link - to relevant tutorial information.

+

The documentation structure required for the standard is an + effective way to describe the technical specifications for a + library. Although terse, that format is familiar to many Boost + users and is far more precise than most ad hoc formats. Below + is a description of the Standard documentation structure. Note + that Standard proposals must include full standardese wording, + which the committee will not do for you, to be accepted. That + level of detail is not expected of Boost library + documentation.

Standards Conforming Documentation

@@ -398,6 +394,30 @@ void resize(size_type n, charT c); give users a lot of insight into why a library is designed the way it is. More importantly, it can help prevent "fixing" something that wasn't really broken as the library matures.

+ +

Web Reference Documentation

+ +

Boost library documentation is often accessed via the World + Web. Using search engines, a page deep in the reference + content could be viewed without any further context. + Therefore, it is helpful to add extra context, such as the + following, to each page:

+ + + +

It is also useful to consider the effectiveness of a + description in search engines. Terse or cryptic descriptions + are less likely to help the curious find a relevant function + or type.

Footnotes

From 79f9bbbb9dbd50c31b3fa314d24e959b64a20285 Mon Sep 17 00:00:00 2001 From: Daniel James Date: Wed, 3 Jun 2009 22:48:22 +0000 Subject: [PATCH 3/8] Use the second paragraph of Robert's introduction as an introduction to the standard guidelines section. Reintroduce the reference to the standard and link to the 'more information' section. [SVN r53612] --- writingdoc/structure.html | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index af38aa8..d4b747a 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -111,19 +111,22 @@ suggest the following guidelines for Boost library documentation.

+

Standards + Conforming Documentation

+

The documentation structure required for the standard is an effective way to describe the technical specifications for a library. Although terse, that format is familiar to many Boost - users and is far more precise than most ad hoc formats. Below - is a description of the Standard documentation structure. Note + users and is far more precise than most ad hoc formats. + This section (apart from the introduction) is taken from the + C++ standard's method of description (Section 17.3). The + following section fleshes this out with + more detail. Note that Standard proposals must include full standardese wording, which the committee will not do for you, to be accepted. That level of detail is not expected of Boost library documentation.

-

Standards - Conforming Documentation

-

Document elements

Each document contains the following elements, as applicable Date: Wed, 3 Jun 2009 22:48:35 +0000 Subject: [PATCH 4/8] Link footnotes back to their location in the document. [SVN r53613] --- writingdoc/structure.html | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index d4b747a..43c569b 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -130,7 +130,7 @@

Document elements

Each document contains the following elements, as applicable(1):

+ "footnote" href="#footnote1" id="footnote1-location">(1):

  • Summary
    • @@ -204,7 +204,7 @@

    In some cases the semantic requirements are presented as C++ code. Such code is intended as a specification of equivalance of a construct to another construct, not necessarily as the way the construct must be - implemented.(2)

    + implemented.(2)

    Detailed specification

    @@ -225,7 +225,7 @@

Descriptions of class member functions follow the order (as - appropriate)(3):

+ appropriate)(3):

  • Constructor(s) and destructor
    • @@ -243,7 +243,7 @@

    Descriptions of function semantics contain the following elements (as - appropriate)(4):

    + appropriate)(4):

    Requires: the preconditions for @@ -425,20 +425,20 @@ void resize(size_type n, charT c);

    Footnotes

    -
    (1) To save +
    (1) To save space, items that do not apply to a clause are omitted. For example, if a clause does not specify any requirements, there will be no "Requirements" subclause.
    -
    (2) Although +
    (2) Although in some cases the code is unambiguously the optimum implementation.
    -
    (3) To save +
    (3) To save space, items that do not apply to a class are omitted. For example, if a class does not specify any comparison functions, there will be no "Comparison functions" subclause.
    -
    (4) To save +
    (4) To save space, items that do not apply to a function are omitted. For example, if a function does not specify any precondition, there will be no "Requires" paragraph.
    From e2f996366a037f5c9bc2765223a554381558b57f Mon Sep 17 00:00:00 2001 From: Daniel James Date: Thu, 4 Jun 2009 16:43:30 +0000 Subject: [PATCH 5/8] Writing docs tweaks from Robert Stewart. [SVN r53637] --- writingdoc/structure.html | 21 +++++++++------------ 1 file changed, 9 insertions(+), 12 deletions(-) diff --git a/writingdoc/structure.html b/writingdoc/structure.html index 43c569b..c38b554 100644 --- a/writingdoc/structure.html +++ b/writingdoc/structure.html @@ -114,18 +114,15 @@

    Standards Conforming Documentation

    -

    The documentation structure required for the standard is an - effective way to describe the technical specifications for a - library. Although terse, that format is familiar to many Boost - users and is far more precise than most ad hoc formats. - This section (apart from the introduction) is taken from the - C++ standard's method of description (Section 17.3). The - following section fleshes this out with - more detail. Note - that Standard proposals must include full standardese wording, - which the committee will not do for you, to be accepted. That - level of detail is not expected of Boost library - documentation.

    +

    The documentation structure required for the C++ Standard is + an effective way to describe the technical specifications for + a library. Although terse, that format is familiar to many + Boost users and is far more precise than most ad hoc formats. + The following description is based upon §17.3 of the + Standard. (Note that while final Standard proposals must + include full standardese wording, which the committee will + not do for you, that level of detail is not expected of Boost + library documentation.)

    Document elements

    From 12de1b2fb28a5f79c7e3d6d71d300d5820997c48 Mon Sep 17 00:00:00 2001 From: Vladimir Prus Date: Sat, 6 Jun 2009 14:18:59 +0000 Subject: [PATCH 6/8] Fix typo. Closes #2714. [SVN r53688] --- getting_started/index.html | 2 +- getting_started/index.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/getting_started/index.html b/getting_started/index.html index d1b1cfe..3033e3f 100644 --- a/getting_started/index.html +++ b/getting_started/index.html @@ -16,7 +16,7 @@

    Use the latest version of this Getting Started guide

    The Boost website version of this Getting Started guide may -have undated information, such as the location of additional installers +have updated information, such as the location of additional installers or improved installation procedures, so you might want use that version if you've got an Internet connection available.

    diff --git a/getting_started/index.rst b/getting_started/index.rst index 025226e..c317614 100644 --- a/getting_started/index.rst +++ b/getting_started/index.rst @@ -15,7 +15,7 @@ __ ../../index.htm .. Admonition:: Use the latest version of this Getting Started guide The `Boost website version of this Getting Started guide`_ may - have undated information, such as the location of additional installers + have updated information, such as the location of additional installers or improved installation procedures, so you might want use that version if you've got an Internet connection available. From 2fb1cf0cdd693e2e052606e4de954e30ddf0ad18 Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Sat, 11 Jul 2009 19:32:08 +0000 Subject: [PATCH 7/8] fixes #3260 [SVN r54899] --- getting_started/index.html | 27 ++++++++++++++------------- getting_started/unix-variants.html | 2 +- getting_started/unix-variants.rst | 2 +- 3 files changed, 16 insertions(+), 15 deletions(-) diff --git a/getting_started/index.html b/getting_started/index.html index 3033e3f..7542516 100644 --- a/getting_started/index.html +++ b/getting_started/index.html @@ -3,31 +3,32 @@ - + Boost Getting Started
    -

    Getting Started

    +

    Getting Started

    +

    Use the latest version of this Getting Started guide

    -

    The Boost website version of this Getting Started guide may +

    The Boost website version of this Getting Started guide may have updated information, such as the location of additional installers or improved installation procedures, so you might want use that version if you've got an Internet connection available.

    -
    -

    Welcome

    +
    +

    Welcome

    Welcome to the Boost libraries! By the time you've completed this tutorial, you'll be at least somewhat comfortable with the contents of a Boost distribution and how to go about using it.

    -
    -

    What's Here

    +
    +

    What's Here

    This document is designed to be an extremely gentle introduction, so we included a fair amount of material that may already be very familiar to you. To keep things simple, we also left out some @@ -35,8 +36,8 @@ information intermediate and advanced users will probably want. At the end of this document, we'll refer you on to resources that can help you pursue these topics further.

    -
    -

    Preliminaries

    +
    +

    Preliminaries

    We use one typographic convention that might not be immediately obvious: italic text in examples is meant as a descriptive placeholder for something else, usually information that you'll @@ -47,16 +48,16 @@ provide. For example:

    Here you're expected to imagine replacing the text “your name” with your actual name.

    -
    -

    Ready?

    +
    +

    Ready?

    Let's go!

    -
    Next: Getting Started on Microsoft Windows
    -
    or: Getting Started on Unix variants (e.g. Linux, MacOS)
    +
    Next: Getting Started on Microsoft Windows
    +
    or: Getting Started on Unix variants (e.g. Linux, MacOS)
    diff --git a/getting_started/unix-variants.html b/getting_started/unix-variants.html index 42086e6..cb1166a 100644 --- a/getting_started/unix-variants.html +++ b/getting_started/unix-variants.html @@ -273,7 +273,7 @@ least use

    $ ./bootstrap.sh --prefix=path/to/installation/prefix

    to install somewhere else. Also, consider using the ---show-libraries and --with-libraries= options to limit the +--show-libraries and --with-library_name options to limit the long wait you'll experience if you build everything. Finally,

     $ ./bjam install
diff --git a/getting_started/unix-variants.rst b/getting_started/unix-variants.rst
index 1444cb9..a0af629 100644
--- a/getting_started/unix-variants.rst
+++ b/getting_started/unix-variants.rst
@@ -108,7 +108,7 @@ least use
   **$** ./bootstrap.sh **--prefix=**\ *path*\ /\ *to*\ /\ *installation*\ /\ *prefix* 
 
 to install somewhere else.  Also, consider using the
-``--show-libraries`` and ``--with-libraries=`` options to limit the
+``--show-libraries`` and ``--with-``\ *library_name* options to limit the
 long wait you'll experience if you build everything.  Finally,
 
 .. parsed-literal::

From 82cce853e75d0e52e888427d569cba877f9b9a37 Mon Sep 17 00:00:00 2001
From: Beman Dawes 
Date: Fri, 28 Aug 2009 18:20:44 +0000
Subject: [PATCH 8/8] Set release number to 1.41.0

[SVN r55842]
---
 getting_started/detail/release-variables.rst |  6 ++---
 getting_started/unix-variants.html           | 18 ++++++-------
 getting_started/windows.html                 | 28 ++++++++++----------
 3 files changed, 26 insertions(+), 26 deletions(-)

diff --git a/getting_started/detail/release-variables.rst b/getting_started/detail/release-variables.rst
index f14f5d4..63c224d 100644
--- a/getting_started/detail/release-variables.rst
+++ b/getting_started/detail/release-variables.rst
@@ -5,8 +5,8 @@
 .. This file contains all the definitions that need to be updated
 .. for each new release of Boost.
 
-.. |boost-version-number| replace:: 1.40.0
-.. |boost_ver| replace:: ``boost_1_40_0``
-.. |boost_ver-bold| replace:: **boost_1_40_0**
+.. |boost-version-number| replace:: 1.41.0
+.. |boost_ver| replace:: ``boost_1_41_0``
+.. |boost_ver-bold| replace:: **boost_1_41_0**
 
 .. _sf-download: http://sourceforge.net/project/showfiles.php?group_id=7586&package_id=8041
diff --git a/getting_started/unix-variants.html b/getting_started/unix-variants.html
index cb1166a..bfc9448 100644
--- a/getting_started/unix-variants.html
+++ b/getting_started/unix-variants.html
@@ -63,12 +63,12 @@
 
    The most reliable way to get a copy of Boost is to download a
 distribution from SourceForge:
    
 
      
-
    1. Download boost_1_40_0.tar.bz2.
      
+
    2. Download boost_1_41_0.tar.bz2.
      
 
      3. 
 
    3. In the directory where you want to put the Boost installation,
 execute
      
 
      -tar --bzip2 -xf /path/to/boost_1_40_0.tar.bz2
+tar --bzip2 -xf /path/to/boost_1_41_0.tar.bz2
 
      
 
      4. 
 
    
@@ -91,7 +91,7 @@ from 2   The Boost Distribution
 
    This is a sketch of the resulting directory structure:
    
 
    -boost_1_40_0/ .................The “boost root directory”
+boost_1_41_0/ .................The “boost root directory”
    index.htm .........A copy of www.boost.org starts here
    boost/ .........................All Boost Header files
     
@@ -136,7 +136,7 @@ anything you can use in these directories.

    It's important to note the following:

      -

    1. The path to the boost root directory (often /usr/local/boost_1_40_0) is +

    2. The path to the boost root directory (often /usr/local/boost_1_41_0) is sometimes referred to as $BOOST_ROOT in documentation and mailing lists .

      3. @@ -231,7 +231,7 @@ int main()

      Now, in the directory where you saved example.cpp, issue the following command:

      -c++ -I path/to/boost_1_40_0 example.cpp -o example
+c++ -I path/to/boost_1_41_0 example.cpp -o example

      To test the result, type:

      @@ -262,7 +262,7 @@ you'll need to acquire library binaries.
      
 
      Issue the following commands in the shell (don't type $; that
 represents the shell's prompt):
      
 
      -$ cd path/to/boost_1_40_0
+$ cd path/to/boost_1_41_0
 $ ./bootstrap.sh --help
 
      
 
      Select your configuration options and invoke ./bootstrap.sh again
@@ -428,7 +428,7 @@ bjam --build-dir=Boost.Build documentation.
      
 
      For example, your session might look like this:
      
 
      -$ cd ~/boost_1_40_0
+$ cd ~/boost_1_41_0
 $ bjam --build-dir=/tmp/build-boost toolset=gcc stage
 
      
 
      That will build static and shared non-debug multi-threaded variants of the libraries. To build all variants, pass the additional option, “--build-type=complete”.
      
@@ -543,14 +543,14 @@ project.
 
        
 
      1. You can specify the full path to each library:
        
 
        -$ c++ -I path/to/boost_1_40_0 example.cpp -o example \
+$ c++ -I path/to/boost_1_41_0 example.cpp -o example \
    ~/boost/stage/lib/libboost_regex-gcc34-mt-d-1_36.a
 
        
 
        2. 
 
      2. You can separately specify a directory to search (with -Ldirectory) and a library name to search for (with -llibrary,2 dropping the filename's leading lib and trailing
 suffix (.a in this case):
        
 
        -$ c++ -I path/to/boost_1_40_0 example.cpp -o example \
+$ c++ -I path/to/boost_1_41_0 example.cpp -o example \
    -L~/boost/stage/lib/ -lboost_regex-gcc34-mt-d-1_36
 
        
 
        As you can see, this method is just as terse as method A for one
diff --git a/getting_started/windows.html b/getting_started/windows.html
index 4bfd2a5..d88787c 100644
--- a/getting_started/windows.html
+++ b/getting_started/windows.html
@@ -73,7 +73,7 @@ least install the Static Multithreaded variants of the boost_1_40_0.7z or boost_1_40_0.zip and unpack it to install a complete Boost
+download boost_1_41_0.7z or boost_1_41_0.zip and unpack it to install a complete Boost
 distribution.1
        
 
 
@@ -83,7 +83,7 @@ distribution.1
 
        2   The Boost Distribution
        
 
        This is a sketch of the resulting directory structure:
        
 
        -boost_1_40_0\ .................The “boost root directory”
+boost_1_41_0\ .................The “boost root directory”
    index.htm .........A copy of www.boost.org starts here
    boost\ .........................All Boost Header files
    lib\ .....................precompiled library binaries
@@ -128,7 +128,7 @@ anything you can use in these directories.

    It's important to note the following:

      -

    1. The path to the boost root directory (often C:\Program Files\boost\boost_1_40_0) is +

    2. The path to the boost root directory (often C:\Program Files\boost\boost_1_41_0) is sometimes referred to as $BOOST_ROOT in documentation and mailing lists .

      3. @@ -253,7 +253,7 @@ cd path\to\some\directory

      followed by Return. For example,

      -cd C:\Program Files\boost\boost_1_40_0
+cd C:\Program Files\boost\boost_1_41_0

      Long commands can be continued across several lines by typing a caret (^) at the end of all but the last line. Some examples @@ -278,7 +278,7 @@ select Properties from the resulting pop-up menu

    3. In Configuration Properties > C/C++ > General > Additional Include Directories, enter the path to the Boost root directory, for example

      -

      C:\Program Files\boost\boost_1_40_0

      +

      C:\Program Files\boost\boost_1_41_0

    4. In Configuration Properties > C/C++ > Precompiled Headers, change @@ -316,7 +316,7 @@ Visual Studio compiler. In that window, set the to a suitable location for creating some temporary files and type the following command followed by the Return key:

      -cl /EHsc /I path\to\boost_1_40_0 path\to\example.cpp
+cl /EHsc /I path\to\boost_1_41_0 path\to\example.cpp

      To test the result, type:

      @@ -347,7 +347,7 @@ you'll need to acquire library binaries.
      
 
      5.1   Install Visual Studio Binaries
      
 
      The installers supplied by BoostPro Computing will download and
 install pre-compiled binaries into the lib\ subdirectory of the
-boost root, typically C:\Program Files\boost\boost_1_40_0\lib\.  If you installed
+boost root, typically C:\Program Files\boost\boost_1_41_0\lib\.  If you installed
 all variants of the Boost.Regex binary, you're done with this
 step.  Otherwise, please run the installer again and install them
 now.
      
@@ -513,8 +513,8 @@ bjam --build-dir=Boost.Build documentation.
      
 
      For example, your session might look like this:4
      
 
      -C:\WINDOWS> cd C:\Program Files\boost\boost_1_40_0
-C:\Program Files\boost\boost_1_40_0> bjam ^
+C:\WINDOWS> cd C:\Program Files\boost\boost_1_41_0
+C:\Program Files\boost\boost_1_41_0> bjam ^
 More? --build-dir="C:\Documents and Settings\dave\build-boost" ^
 More? --build-type=complete msvc stage
 
      
@@ -652,7 +652,7 @@ earlier:
      
 select Properties from the resulting pop-up menu
    5. In Configuration Properties > Linker > Additional Library Directories, enter the path to the Boost binaries, -e.g. C:\Program Files\boost\boost_1_40_0\lib\.
      6. +e.g. C:\Program Files\boost\boost_1_41_0\lib\.
    6. From the Build menu, select Build Solution.

    skip to the next step

    @@ -662,10 +662,10 @@ e.g. C:\Program For example, we can compile and link the above program from the Visual C++ command-line by simply adding the bold text below to the command line we used earlier, assuming your Boost binaries are -in C:\Program Files\boost\boost_1_40_0\lib:

    +in C:\Program Files\boost\boost_1_41_0\lib:

    -cl /EHsc /I path\to\boost_1_40_0 example.cpp   ^
-     /link /LIBPATH: C:\Program Files\boost\boost_1_40_0\lib
+cl /EHsc /I path\to\boost_1_41_0 example.cpp   ^
+     /link /LIBPATH: C:\Program Files\boost\boost_1_41_0\lib
    @@ -819,7 +819,7 @@ mailing list.

    [1]We recommend -downloading boost_1_40_0.7z and using 7-Zip to decompress +downloading boost_1_41_0.7z and using 7-Zip to decompress it. We no longer recommend .zip files for Boost because they are twice as large as the equivalent .7z files. We don't recommend using Windows' built-in decompression as it can be painfully slow for large archives.