The read_graphviz function interprets a graph described using the
GraphViz DOT language and builds a BGL graph that captures that
description. Using these functions, you can initialize a graph using
data stored as text.

The DOT language can specify both directed and undirected graphs, and
read_graphviz differentiates between the two. One must pass
read_graphviz an undirected graph when reading an undirected graph;
the same is true for directed graphs. Furthermore, read_graphviz
will throw an exception if it encounters parallel edges and cannot add
them to the graph.

To handle properties expressed in the DOT language, read_graphviz
takes a dynamic_properties object and operates on its collection of
property maps. The reader passes all the properties encountered to
this object, using the GraphViz string keys as the property keys.
Furthermore, read_graphviz stores node identifier names under the
vertex property map named node_id.

Under certain circumstances, read_graphviz will throw one of the
above exceptions. The three concrete exceptions can all be caught
using the general graph_exception moniker when greater precision
is not needed. In addition, all of the above exceptions derive from
the standard std::exception for even more generalized error
handling.

The bad_parallel_edge exception is thrown when an attempt to add a
parallel edge to the supplied MutableGraph fails. The DOT language
supports parallel edges, but some BGL-compatible graph types do not.
One example of such a graph is boost::adjacency_list<setS,vecS>,
which allows at most one edge can between any two vertices.

The directed_graph_error exception occurs when an undirected graph
type is passed to read_graph but the textual representation of the
graph is directed, as indicated by the digraph keyword in the DOT
language.

The undirected_graph_error exception occurs when a directed graph
type is passed to read_graph but the textual representation of the
graph is undirected, as indicated by the graph keyword in the DOT
language.

The bad_graphviz_syntax exception occurs when the graph input is not a
valid GraphViz graph.

To use the GraphViz readers, you will need to build and link against
the "boost_graph" library. The library can be built by following the
Boost Jam Build Instructions for the subdirectory libs/graph/build.

The read_graphviz function does not use any code from the
GraphViz distribution to interpret the DOT Language. Rather, the
implementation was based on documentation found on the GraphViz web
site, as well as experiments run using the dot application. The
resulting interpretation may be subtly different from dot for some
corner cases that are not well specified.

On successful reading of a graph, every vertex and edge will have
an associated value for every respective edge and vertex property
encountered while interpreting the graph. These values will be set
using the dynamic_properties object. Those edges and
vertices that are not explicitly given a value for a property (and that
property has no default) will be
given the default constructed value of the value type. Be sure
that property map value types are default constructible.

read_graphviz treats subgraphs as syntactic sugar. It does not
reflect subgraphs as actual entities in the BGL. Rather, they are
used to shorten some edge definitions as well as to give a subset
of all nodes or edges certain properties. For example, the
DOT graphs digraph{a->subgraph{b->c}->e} and
digraph{a->b->e;a->c->e;b->c} are equivalent.

Subgraph IDs refer to subgraphs defined earlier in the graph
description. Undefined subgraphs behave as empty subgraphs
({}). This is the same behavior as GraphViz.