fix: take andrzej feedback into account

doc/modules/ROOT/examples/algorithms/traversal/bfs_shortest_path.cpp

@@ -5,37 +5,42 @@
 #include <vector>
 
 int main() {
-    using namespace boost;
-    using Graph  = adjacency_list<vecS, vecS, undirectedS>;
+    using Graph = boost::adjacency_list<boost::vecS, boost::vecS, boost::undirectedS>;
     using Vertex = Graph::vertex_descriptor;
 
+    // Undirected graph given as a list of (source, target) vertex-index pairs
     std::vector<std::pair<int,int>> edges = {
         {0,1},{0,3},{0,18},{1,2},{1,19},{2,3},{2,8},{3,4},{4,5},{4,8},
         {5,6},{5,18},{6,7},{6,12},{7,8},{7,11},{8,9},{9,10},{9,19},{10,11},
         {10,15},{11,12},{11,14},{12,13},{13,14},{13,17},{14,15},{14,17},
         {15,16},{16,17},
     };
 
-    Graph g(edges.begin(), edges.end(), 20);
+    // Build the graph from the edge list
+    constexpr int num_vertices = 20;
+    Graph g(edges.begin(), edges.end(), num_vertices);
     const Vertex source = 9;
     const Vertex target = 13;
 
-    // Custom external storage
-    std::vector<int>    distances(num_vertices(g));
-    std::vector<Vertex> predecessors(num_vertices(g));
+    // External storage for the results, one slot per vertex
+    std::vector<int> distance_storage(boost::num_vertices(g));
+    std::vector<Vertex> predecessor_storage(boost::num_vertices(g));
 
-    // 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);
+    // Three property maps:
+    // vertex -> its index (provided by the graph type)
+    auto vertex_index_map = boost::get(boost::vertex_index, g);
+    // vertex -> BFS distance from the source (wraps distance_storage)
+    auto distance = boost::make_iterator_property_map(distance_storage.begin(), vertex_index_map);
+    // vertex -> its parent in the BFS tree (wraps predecessor_storage)
+    auto predecessor = boost::make_iterator_property_map(predecessor_storage.begin(), vertex_index_map);
 
-    breadth_first_search(g, source,
-        visitor(make_bfs_visitor(std::make_pair(
-            record_distances(dmap, on_tree_edge()),
-            record_predecessors(pmap, on_tree_edge())))));
+    boost::breadth_first_search(g, source,
+        boost::visitor(boost::make_bfs_visitor(std::make_pair(
+            boost::record_distances(distance, boost::on_tree_edge()),
+            boost::record_predecessors(predecessor, boost::on_tree_edge())))));
 
-    // Walk back through the predecessor property map
-    for (auto v = target; v != source; v = get(pmap, v))
+    // Walk back from target to source through the predecessor map
+    for (auto v = target; v != source; v = boost::get(predecessor, v))
         std::cout << v << ' ';
     std::cout << source << '\n';
 }

doc/modules/ROOT/pages/index.adoc

@@ -8,6 +8,13 @@ A C++ library of graph algorithms and data structures, generic enough to work on
 * Generic algorithms that work across any graph representation, with fine control on allocations
 * Extensible algorithms: inject your own logic at key points during traversal using visitor hooks
 
+== Example
+
+The example below brings together the three ideas that run through the library.
+You choose how the graph is stored: this one uses an `adjacency_list`, but `adjacency_matrix` or `compressed_sparse_row_graph` would run the same algorithm.
+The results stay in your own containers, which the algorithm reaches through property maps that separate where data lives from how it is read.
+And you hook into the traversal with a visitor that reacts to events as the breadth-first search expands, recording each vertex's distance and predecessor along the way.
+Following the predecessor map back from the target then gives the shortest path.
 
 [subs=attributes+]
 ++++
@@ -17,8 +24,6 @@ A C++ library of graph algorithms and data structures, generic enough to work on
 </video>
 ++++
 
-== Example
-
 ++++
 <p style="padding-left: 2em;"><a href="https://godbolt.org/z/TnnMzW7da">Try it on Compiler Explorer</a></p>
 ++++
@@ -78,4 +83,30 @@ existing one at specific event points (vertex discovered, edge relaxed, etc.).
 
 | https://cppalliance.org/slack[CppLang Slack]
 | Real-time chat. Request an invite, then join the `#boost` channel.
-|===
+|===
+
+== Authors
+
+The Boost Graph Library was originally created by Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine, who also wrote its reference text, _The Boost Graph Library: User Guide and Reference Manual_.
+Many other contributors have extended the library since.
+
+== How to cite
+
+If you use the Boost Graph Library in academic work, please cite the reference book:
+
+[,text]
+----
+Jeremy G. Siek, Lie-Quan Lee, and Andrew Lumsdaine.
+The Boost Graph Library: User Guide and Reference Manual.
+Addison-Wesley Professional, 2002.
+----
+
+[source,bibtex]
+----
+@book{siek2002boost,
+  title     = {The Boost Graph Library: User Guide and Reference Manual},
+  author    = {Siek, Jeremy G. and Lee, Lie-Quan and Lumsdaine, Andrew},
+  publisher = {Addison-Wesley Professional},
+  year      = {2002}
+}
+----