Re: [boost] ATTENTION: Library requirements..

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