Re: Boost.Graph Documentation Got a Facelift: Ship it Or Not ?

śr., 10 cze 2026 o 22:59 Andrzej Krzemienski <[email protected]>
napisał(a):

>
>
> wt., 9 cze 2026 o 17:43 Arnaud Becheler via Boost <[email protected]>
> napisał(a):
>
>> Dear Boostlings, Graphlings,
>>
>> We have taken a first step in modernizing the Boost.Graph documentation
>> with a preview available here:
>> https://491.graph.prtest3.cppalliance.org/graph/index.html .
>>
>> These first steps aim at solving low-hanging fruits and answering frequent
>> complaints from users collected during the 2022 User Survey (
>> https://www.reddit.com/r/cpp/comments/vyt4t5/boostgraph_user_survey/ )
>> and
>> BGL workshop 2026  ( https://github.com/boostorg/graph/discussions/466 )
>>
>> - documentation hard to explore (no table of content, no search bar)
>> - examples use old C++ and several don't even compile
>> - outdated visual design
>>
>> We have been investing into several dimensions:
>>
>> - migrating the old pure html pages to asciidoc + antora
>> - modern examples for each algorithm are compiled and run in CI, with
>> output integrated in the documentation
>> - higher scanability for algorithm complexity + where defined
>> - a better landing for users not familiar with property maps
>>
>> The PR currently sits unmerged as we are trying to assess its viability.
>>
>> Important:
>>
>> - this is NOT the final vision, this is meant as a first important step.
>> - the current scope is NOT a full rewrite/reorganization of each algorithm
>> page (future work).
>> - the current scope is a modernization of the documentation
>> infrastructure.
>>
>> - we are just worried we may have made and missed important mistakes that
>> should prevent the merge, so Jeremy Murphy (principal BGL maintainer) and
>> I
>> decided to poll around for general review and feeling.
>>
>> Question to the community:
>>
>> 1. Is the new documentation preview (
>> https://491.graph.prtest3.cppalliance.org/graph/index.html ) going in the
>> right direction?
>>
>
> Absolutely yes! Thank you so much for doing this!
> It is already way more user friendly and accessible.
>
>
>
>> 2. Is it better than the old documentation (
>> https://www.boost.org/doc/libs/1\_91\_0/libs/graph/doc/ )?
>>
>
> The front matter is definitely better.
>
>
>> 3. Would you want to see it merged in its current state or did you
>> identify
>> important mistakes we should absolutely fix before merge?
>>
>
> In order to be able to say that it can be merged right now, I would have
> to be sure if nothing important didn't disappear from the old one, and I
> was not able to inspect it that thoroughly.
>
> For instance, I do not see a Reference section. Old docs also do not have
> one either, but I can see
> https://www.boost.org/doc/libs/1_91_0/libs/graph/doc/table_of_contents.html
> where all names, like  predecessor_recorder
> <https://www.boost.org/doc/libs/1_91_0/libs/graph/doc/predecessor_recorder.html>,
> are listed. In the new docs, if I knew where to click, I would get to
> section "Predecessor Recorder
> <https://491.graph.prtest3.cppalliance.org/graph/visitors/predecessor_recorder.html>"
> but it is still different spelling: not the one used in code.
>
>
>> Any general complaints not directly related to this PR scope is welcome
>> and
>> will be integrated in future work :)
>>
>
> You bet.
> In the front page, it is not immediately clear that the cool animation
> actually illustrates what the following code snippet does. In fact, the
> animation moves so quickly that I do not know what is actually being
> illustrated. (It is still cool though.)
>
> The code snippet alone already does a great service to the users, present
> and future ones. I would recommend improving it further.
> Please do not use `using namespace boost` and instead prefix every
> function call with `boost::`. This will make the code a bit longer, but it
> will make it clear which parts come from the library, and which are defined
> in the fairly long snippet. For instance, in:
>
> ```
> auto vidx = get(vertex_index, g);
> ```
>
> It is so difficult to figure out what `vertex_index` is and how it got
> there, and  if this example would even compile.  `using namespace` is such
> a bad habit, and young developers learn it from looking at library examples
> like this one.
>
> The code example will require even more comments. For instance, it is not
> clear what 20 is in:
>
> ```
> Graph g(edges.begin(), edges.end(), 20);
> ```
>
> Next, in:
>
> ```
>     // Wrap storage into property maps
>     auto vidx = get(vertex_index, g);
>     auto dmap = make_iterator_property_map(distances.begin(), vidx);
>     auto pmap = make_iterator_property_map(predecessors.begin(), vidx);
> ```
>
> It is not clear that all three represent property maps. The first one
> looks so different from the other two. Why does the first one not have
> "map" in the variable name?
>
> Rename distances/predecessors to distance_storage/predecessor_storage.
> Then rename dmap/pmap to distance/predecessor.
>

Oh, and the original authors from Indiana University need to be listed in
the front matter.

Regards,
&rzej;
_______________________________________________
Boost mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://lists.boost.org/mailman3/lists/boost.lists.boost.org/
Archived at: https://lists.boost.org/archives/list/[email protected]/message/BKHBVH7Y4P6BV24N6TA33KVASL5RG7C4/