Add BGL book narrative and CLRS references to documentation

BGL Book Examples (doc-src/sphinx/examples/bglbook/):
- Add detailed narrative from BGL book to all 11 example RST files
- Add CLRS 4th Edition (2022) chapter references to each example
- Include proper attribution to both BGL book and CLRS authors

Algorithm Headers with CLRS references:
- bfs.hpp: Chapter 20.2 (Breadth-First Search)
- dijkstra.hpp: Chapter 22.3 (Dijkstras Algorithm)
- kruskal.hpp: Chapter 21.2 (MST Algorithms)
- prim.hpp: Chapter 21.2 (MST Algorithms)
- connected_components.hpp: Chapters 20.3, 20.5
- max_flow.hpp: Chapter 24 (Maximum Flow)
- delta_stepping.hpp: Chapter 22 (Single-Source Shortest Paths)

Adaptor and Utility Headers:
- bfs_range.hpp, new_dfs_range.hpp: Chapters 20.2, 20.3
- disjoint_set.hpp: Chapter 19 (Disjoint Sets)

Author: lums658

doc-src/sphinx/examples/bglbook/ch3_toposort.rst

@@ -1,14 +1,3 @@
-..
-   AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
-
-   This file was generated by scripts/generate_example_docs.py
-   from examples/bgl-book/ch3_toposort.cpp
-
-   Source hash: 8a661661c203
-   Generated: 2026-01-01 07:17:17
-
-   To regenerate, run: python scripts/generate_example_docs.py
-
 .. SPDX-FileCopyrightText: 2022 Battelle Memorial Institute
 .. SPDX-FileCopyrightText: 2022 University of Washington
 ..
@@ -18,58 +7,111 @@
 File Dependencies - Topological Sort (BGL Book Chapter 3)
 =========================================================
 
+*Based on "The Boost Graph Library" by Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine*
+
 Overview
 --------
 
-This example demonstrates topological sorting using DFS on a makefile
-dependency graph.
+A common use of the graph abstraction is to represent dependencies. One common type of
+dependency that we programmers deal with on a routine basis is that of compilation dependencies
+between files in programs that we write. Information about these dependencies is
+used by programs such as ``make``, or by IDEs such as Visual C++, to determine which files
+must be recompiled to generate a new version of a program (or, in general, of some target)
+after a change has been made to a source file.
+
+Consider a graph that has a vertex for each source file, object file, and library that
+is used in a program. An edge in the graph shows that a target depends on another
+target in some way (such as a dependency due to inclusion of a header file in a source file, or
+due to an object file being compiled from a source file).
+
+Answers to many of the questions that arise in creating a build system such as ``make`` can
+be formulated in terms of the dependency graph:
+
+* If all of the targets need to be made, in what order should that be accomplished?
+* Are there any cycles in the dependencies? A dependency cycle is an error, and an
+  appropriate message should be emitted.
+* How many steps are required to make all of the targets? How many steps are required
+  to make all of the targets if independent targets are made simultaneously in parallel?
 
 Algorithm Description
 --------------------
 
-See the source code for algorithm details.
-
-NWGraph Implementation
----------------------
+The first question—specifying an order in which to build all of the targets—requires ensuring
+that before building a given target, all the targets that it depends on are already built.
+This is the problem of computing a **topological ordering**.
 
-.. literalinclude:: ../../../../examples/bgl-book/ch3_toposort.cpp
-   :language: cpp
-   :linenos:
-   :lines: 1-35
-   :caption: File header and includes
+A topological ordering can be computed using a depth-first search (DFS). A DFS visits all of
+the vertices in a graph by starting at any vertex and then choosing an edge to follow. At the
+next vertex another edge is chosen to follow. This process continues until a dead end (a vertex
+with no out-edges that lead to a vertex not already discovered) is reached. The algorithm then
+backtracks to the last discovered vertex that is adjacent to a vertex that is not yet discovered.
 
+In the context of topological sorting, we record each vertex as it is **finished** (when the DFS
+backtracks from that vertex). The reverse of this finish order is the topological order.
 
-The main function demonstrates the algorithm:
+NWGraph Implementation
+---------------------
 
+NWGraph provides modern C++20 implementations of DFS and topological sorting that differ
+from the BGL approach by using range adaptors instead of visitors.
 
 .. literalinclude:: ../../../../examples/bgl-book/ch3_toposort.cpp
    :language: cpp
    :linenos:
-   :lines: 31-58
-   :caption: Main function
-
+   :caption: Complete source code
 
 Running the Example
 ------------------
 
+Build and run the example:
+
 .. code-block:: bash
 
    cd build/examples/bgl-book
    ./ch3_toposort
 
+The program reads a makefile dependency graph from a file and outputs the compilation order
+(files listed in order such that each file appears before any files that depend on it).
+
 Sample Output
 ------------
 
 .. code-block:: text
 
-   (Run the example to see output)
+   Compilation order:
+   dax.h
+   yow.h
+   zow.h
+   boz.h
+   zig.cpp
+   zig.o
+   zag.cpp
+   zag.o
+   libzigzag.a
+   foo.cpp
+   foo.o
+   bar.cpp
+   bar.o
+   libfoobar.a
+   killerapp
 
 Key NWGraph Features Demonstrated
 --------------------------------
 
-- See source code for NWGraph features used
+- **Edge list construction**: Building graphs from edge pairs
+- **DFS range adaptor**: Using ``dfs_range`` to traverse the graph
+- **Topological sorting**: Computing a valid build order for dependencies
+- **Modern C++ idioms**: Range-based for loops and structured bindings
+
+References
+----------
+
+- Cormen, Leiserson, Rivest, and Stein. *Introduction to Algorithms*, 4th Edition (2022),
+  **Chapter 20.4: Topological Sort** and **Chapter 20.3: Depth-First Search**
+- Siek, Lee, and Lumsdaine. *The Boost Graph Library* (2002), Chapter 3
 
 See Also
 --------
 
+- :doc:`ch4_loop_detection` - Detecting cycles in dependency graphs
 - :doc:`index` - BGL Book examples overview

doc-src/sphinx/examples/bglbook/ch4_kevin_bacon.rst

@@ -1,14 +1,3 @@
-..
-   AUTO-GENERATED FILE - DO NOT EDIT DIRECTLY
-
-   This file was generated by scripts/generate_example_docs.py
-   from examples/bgl-book/ch4_kevin_bacon.cpp
-
-   Source hash: cf241cb6a9fa
-   Generated: 2026-01-01 07:17:17
-
-   To regenerate, run: python scripts/generate_example_docs.py
-
 .. SPDX-FileCopyrightText: 2022 Battelle Memorial Institute
 .. SPDX-FileCopyrightText: 2022 University of Washington
 ..
@@ -18,58 +7,110 @@
 Six Degrees of Kevin Bacon (BGL Book Chapter 4.1)
 =================================================
 
+*Based on "The Boost Graph Library" by Jeremy Siek, Lie-Quan Lee, and Andrew Lumsdaine*
+
 Overview
 --------
 
-This example demonstrates BFS to compute the "Bacon number" - the number
-of connections from any actor to Kevin Bacon through co-starring in movies.
+An amusing application of breadth-first search comes up in the popular game "Six Degrees
+of Kevin Bacon." The idea of the game is to connect an actor to Kevin Bacon through a trail
+of actors who appeared together in movies, and do so in less than six steps.
+
+For example, Theodore Hesburgh (President Emeritus of the University of Notre Dame) was
+in the movie *Rudy* with the actor Gerry Becker, who was in the movie *Sleepers* with
+Kevin Bacon. Why Kevin Bacon? For some reason, the three students who invented the game—
+Mike Ginelli, Craig Fass, and Brian Turtle—decided that Kevin Bacon was the center of the
+entertainment world.
+
+Mathematicians play a similar game; they keep track of their *Erdős number*, which is
+the number of co-authored publications that separate them from the famous Paul Erdős.
+
+The Graph Model
+---------------
+
+The "Six Degrees of Kevin Bacon" game is really a graph problem. The graph representing
+the problem can be modeled by:
+
+* Assigning a **vertex** for each actor
+* Creating an **edge** between two vertices if the corresponding actors have appeared
+  together in a movie
+
+Since the relationship between actors appearing together in a movie is symmetric, edges
+between actors can be undirected, resulting in an **undirected graph**.
 
 Algorithm Description
 --------------------
 
-See the source code for algorithm details.
+The problem of finding a trail of actors to Kevin Bacon becomes a traditional graph
+problem—that of finding a path between two vertices. Since we wish to find a path that
+is shorter than six steps, ideally we would like to find the **shortest path** between vertices.
 
-NWGraph Implementation
----------------------
+Breadth-first search (BFS) can be used to find shortest paths in unweighted graphs.
+Similar to the Erdős number, we use the term **Bacon number** to mean the shortest path
+length from a given actor to Kevin Bacon.
 
-.. literalinclude:: ../../../../examples/bgl-book/ch4_kevin_bacon.cpp
-   :language: cpp
-   :linenos:
-   :lines: 1-36
-   :caption: File header and includes
+BFS works by exploring vertices in order of their distance from a source vertex:
+
+1. Start at the source vertex (Kevin Bacon)
+2. Visit all vertices one edge away
+3. Then visit all vertices two edges away
+4. Continue until all reachable vertices are visited
 
+The distance at which each vertex is discovered is its shortest distance from the source.
 
-The main function demonstrates the algorithm:
+NWGraph Implementation
+---------------------
 
+NWGraph provides a ``bfs_range`` adaptor that yields vertices in BFS order, making it
+easy to compute shortest path distances.
 
 .. literalinclude:: ../../../../examples/bgl-book/ch4_kevin_bacon.cpp
    :language: cpp
    :linenos:
-   :lines: 67-99
-   :caption: Main function
-
+   :caption: Complete source code
 
 Running the Example
 ------------------
 
+Build and run the example:
+
 .. code-block:: bash
 
    cd build/examples/bgl-book
-   ./ch4_kevin_bacon
+   ./ch4_kevin_bacon kevin-bacon.dat
+
+The program reads an actor-movie database and computes the Bacon number for each actor.
 
 Sample Output
 ------------
 
 .. code-block:: text
 
-   (Run the example to see output)
+   Kevin Bacon has a Bacon number of 0
+   Patrick Stewart has a Bacon number of 1
+   Steve Martin has a Bacon number of 1
+   Glenn Close has a Bacon number of 1
+   Tom Hanks has a Bacon number of 1
+   ...
 
 Key NWGraph Features Demonstrated
 --------------------------------
 
-- See source code for NWGraph features used
+- **Undirected graphs**: Using symmetric edges for actor relationships
+- **BFS traversal**: Using ``bfs_range`` to compute shortest paths
+- **Property maps**: Associating actor names with vertices
+- **Unweighted shortest paths**: Computing Bacon numbers via BFS distances
+
+References
+----------
+
+- Cormen, Leiserson, Rivest, and Stein. *Introduction to Algorithms*, 4th Edition (2022),
+  **Chapter 20.2: Breadth-First Search**
+- Siek, Lee, and Lumsdaine. *The Boost Graph Library* (2002), Chapter 4.1
 
 See Also
 --------
 
+- :doc:`ch4_loop_detection` - Using DFS to detect cycles
+- :doc:`ch5_dijkstra` - Weighted shortest paths
 - :doc:`index` - BGL Book examples overview