Boost logo

Boost :

Subject: Re: [boost] ATTENTION: Library requirements..
From: Robert Ramey (ramey_at_[hidden])
Date: 2016-01-06 20:05:03


A few observations

a) I think the section "License Requirements" should be changed to just
require the Boost License if it's going to be in boost. It's way to
hard and time consuming for for any one of us to spend time haggling on
licensing issues.

b) Organization. It's not clear whether or not files/directories
besides the one's listed are permitted. For example I have in the
serialization library

/utility
    Jam scripts shared by other directories
/performance
    Benchmark testing programs. Otherwise looks just like test
/CMake
    CMake scripts to build the serialization library
/doc/
    html/
        html documentation
    boostbook/
        xml files to create html docs

May I presume that including these is not a problem? They
don't conflict with any thing you've previously listed.

c) Building Documentation

I would need a better example to figure this out.

BTW one boost library should be selected as the "golden" or canonical
example so that it can be used as an example for others to follow.
Responsability for maintaining this is the "perfect" state would fall to
the person responsable for keeping things running. The idea would be
that someone complains that they can't figure this thing out (normally
me), You can just point to the "golden example" and say do it this way.

d) Design and Programming.

"Aim for ISO Standard C++ ... I think this should be up in the
"portability" section -maybe both places.

"Browse through the Best Practices Handbook for ideas and links to
source code in existing Boost libraries." I don't think that the
opinions expressed in this page reflect a strong consensus among boost
authors so the reference should be stricken.

I don't know if the exceptions-specifications rationale is relevant today.

"use fixed with fonts" I don't think this makes any sense at all. The
font is not an attribute of the source code, but rather it's
representation - which is a whole 'nuther thing. Should be stricken.

"Use spaces rather than tabs" I love tabs - but I've been out-voted in
every place I've ever worked in on this. Oh Well.

I would like to see one of the libraries - a small one - be designated
as the canonical/golden example which demonstrates all these guidlines.

perhaps boost/inspect should be run as part of the regression testing to
help promote adherence to these guidelines.

e) Documentation

Basically this is OK BUT It's missing a huge aspect.

Most Boost libraries use templates. The templates use parameters.
These parameters are not specific types - but are families of types
defined by a set of type requirements (aka concepts). Documentation of
type requirements is key to making a coherent library which is usable by
others. I invested a lot of effort in this subject in the boost library
incubator pages in requirements and simple tools. I would very much
like to see some of the material incorporated in this section. Also I
would like to see the section on writing documentation for boost updated
to include this information. Please consider these requests.

f) javescript.

I thing the admonitions agains java script should be softened. Most of
the concerns existent when the document was originally written don't
apply to day. I would like to see our html documentation support thinks
like syntax coloring, running example code online, and the like. These
things are often supported via injected javascript.

Basically, I'm impressed that this is a fairly conservative document
which doesn't require and major changes for anyone who has been trying
to follow the rules all along.

Hope this helps make your job easier.

Robert Ramey


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk