1.1 --- a/doc/Makefile.am	Mon Sep 04 19:48:09 2006 +0000
     1.2 +++ b/doc/Makefile.am	Mon Sep 04 20:07:37 2006 +0000
     1.3 @@ -7,6 +7,7 @@
     1.4  	doc/icons/geom/ftv2doc.png \
     1.5  	doc/icons/geom/ftv2folderclosed.png \
     1.6  	doc/icons/geom/ftv2folderopen.png \
     1.7 +	doc/algorithms.dox \
     1.8  	doc/coding_style.dox \
     1.9  	doc/developers_interface.dox \
    1.10  	doc/dirs.dox \
    1.11 @@ -18,6 +19,8 @@
    1.12  	doc/license.dox \
    1.13  	doc/mainpage.dox \
    1.14  	doc/maps.dox \
    1.15 +	doc/maps1.dox \
    1.16 +	doc/maps2.dox \
    1.17  	doc/named-param.dox \
    1.18  	doc/namespaces.dox \
    1.19  	doc/quicktour.dox \

     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/algorithms.dox	Mon Sep 04 20:07:37 2006 +0000
     2.3 @@ -0,0 +1,5 @@
     2.4 +/**
     2.5 +\page algorithms Algorithms
     2.6 +
     2.7 +Place-holder page for algorithms.
     2.8 +*/

     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/doc/maps1.dox	Mon Sep 04 20:07:37 2006 +0000
     3.3 @@ -0,0 +1,72 @@
     3.4 +/**
     3.5 +\page maps1 Maps I.
     3.6 +
     3.7 +In the previous section we discussed graph topology. That is the skeleton a complex
     3.8 +graph represented data-set needs. But how to assign the data itself to that skeleton?<br>
     3.9 +Here come the \b maps in.
    3.10 +
    3.11 +\section maps_intro Introduction to maps
    3.12 +Maps play a central role in LEMON. As their name suggests, they map a certain range of <i>keys</i> to certain <i>values</i>.
    3.13 +In LEMON there is many types of maps. Each map has two typedef's to determine the types of keys and values, like this:
    3.14 +\code
    3.15 +  typedef Edge Key;
    3.16 +  typedef double Value;
    3.17 +\endcode
    3.18 +(Except matrix maps, they have two key types.)
    3.19 +
    3.20 +To make easy to use them - especially as template parameters - there are <i>map concepts</i> like by graph classes.
    3.21 +<ul>
    3.22 +<li>\ref ReadMap - values can be red out with the \c operator[].
    3.23 +\code value_typed_variable = map_instance[key_value]; \endcode
    3.24 +</li>
    3.25 +<li>\ref WriteMap - values can be set with the \c set() member function.
    3.26 +\code map_instance.set(key_value, value_typed_expression); \endcode
    3.27 +</li>
    3.28 +<li>\ref ReadWriteMap - it's just a shortcut to indicate that the map is both
    3.29 +readable and writable. It is delivered from them.
    3.30 +</li>
    3.31 +<li>\ref ReferenceMap - a subclass of ReadWriteMap. It has two additional typedefs
    3.32 +<i>Reference</i> and <i>ConstReference</i> and two overloads of \c operator[] to
    3.33 +providing you constant or non-constant reference to the value belonging to a key,
    3.34 +so you have a direct access to the memory address where it is stored.
    3.35 +</li>
    3.36 +<li>And there are the Matrix version of these maps, where the values are assigned to a pair of keys.
    3.37 +The keys can be different types. (\ref ReadMatrixMap, \ref WriteMatrixMap, \ref ReadWriteMatrixMap, \ref ReferenceMatrixMap)
    3.38 +</li>
    3.39 +</ul>
    3.40 +
    3.41 +\section maps_graph Graphs' maps
    3.42 +Every \ref MappableGraphComponent "mappable" graph class has two public templates: NodeMap<VALUE> and EdgeMap<VALUE>
    3.43 +satisfying the \ref GraphMap concept.
    3.44 +If you want to assign data to nodes, just declare a NodeMap with the corresponding
    3.45 +type. As an example, think of a edge-weighted directed graph.
    3.46 +\code ListGraph::EdgeMap<int>  weight(graph); \endcode
    3.47 +You can see that the map needs the graph hows edges will mapped, but nothing more.
    3.48 +
    3.49 +If the graph class is extendable or erasable the map will automatically follow
    3.50 +the changes you make. If a new node is added a default value is mapped to it.
    3.51 +You can define the default value by passing a second argument to the map's constructor.
    3.52 +\code ListGraph::EdgeMap<int>  weight(graph, 13); \endcode
    3.53 +But keep in mind that \c VALUE has to have copy constructor.
    3.54 +
    3.55 +Of course \c VALUE can be a rather complex type.
    3.56 +
    3.57 +For practice let's see the following template function (from \ref maps_summary "maps-summary.cc" in the \ref demo directory)!
    3.58 +\dontinclude maps_summary.cc
    3.59 +\skip template
    3.60 +\until }
    3.61 +The task is simple. We need the summary of some kind of data assigned to a graph's nodes.
    3.62 +(Whit a little trick the summary can be calculated only to a sub-graph without changing
    3.63 +this code. See \ref SubGraph techniques - that's LEMON's true potential.)
    3.64 +
    3.65 +And the usage is simpler than the declaration suggests. The compiler deduces the
    3.66 +template specialization, so the usage is like a simple function call.
    3.67 +\skip std
    3.68 +\until ;
    3.69 +
    3.70 +Most of the time you will probably use graph maps, but keep in mind, that in LEMON maps are more general and can be used widely.
    3.71 +
    3.72 +If you want some 'real-life' examples see the next page, where we discuss \ref algorithms
    3.73 +(coming soon) and will use maps hardly.
    3.74 +Or if you want to know more about maps read these \ref maps2 "advanced map techniques".
    3.75 +*/

     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/doc/maps2.dox	Mon Sep 04 20:07:37 2006 +0000
     4.3 @@ -0,0 +1,72 @@
     4.4 +/**
     4.5 +\page maps2 Maps II.
     4.6 +
     4.7 +Here we discuss some advanced map techniques. Like writing your own maps or how to
     4.8 +extend/modify a maps functionality with adaptors.
     4.9 +
    4.10 +\section custom_maps Writing Custom ReadMap
    4.11 +\subsection custom_read_maps Readable Maps
    4.12 +
    4.13 +Readable maps are very frequently used as the input of an
    4.14 +algorithm.  For this purpose the most straightforward way is the use of the
    4.15 +default maps provided by LEMON's graph structures.
    4.16 +Very often however, it is more
    4.17 +convenient and/or more efficient to write your own readable map.
    4.18 +
    4.19 +You can find some examples below. In these examples \c Graph is the
    4.20 +type of the particular graph structure you use.
    4.21 +
    4.22 +
    4.23 +This simple map assigns \f$\pi\f$ to each edge.
    4.24 +
    4.25 +\code
    4.26 +struct MyMap 
    4.27 +{
    4.28 +  typedef double Value;
    4.29 +  typedef Graph::Edge Key;
    4.30 +  double operator[](Key e) const { return M_PI;}
    4.31 +};
    4.32 +\endcode
    4.33 +
    4.34 +An alternative way to define maps is to use MapBase
    4.35 +
    4.36 +\code
    4.37 +struct MyMap : public MapBase<Graph::Edge,double>
    4.38 +{
    4.39 +  Value operator[](Key e) const { return M_PI;}
    4.40 +};
    4.41 +\endcode
    4.42 +
    4.43 +Here is a bit more complex example.
    4.44 +It provides a length function obtained
    4.45 +from a base length function shifted by a potential difference.
    4.46 +
    4.47 +\code
    4.48 +class ReducedLengthMap  : public MapBase<Graph::Edge,double>
    4.49 +{
    4.50 +  const Graph &g;
    4.51 +  const Graph::EdgeMap<double> &orig_len;
    4.52 +  const Graph::NodeMap<double> &pot;
    4.53 +  
    4.54 +public:
    4.55 +  Value operator[](Key e) const {
    4.56 +    return orig_len[e]-(pot[g.target(e)]-pot[g.source(e)]);
    4.57 +  }
    4.58 +  
    4.59 +  ReducedLengthMap(const Graph &_g,
    4.60 +                   const Graph::EdgeMap &_o,
    4.61 +                   const Graph::NodeMap &_p)
    4.62 +    : g(_g), orig_len(_o), pot(_p) {};
    4.63 +};
    4.64 +\endcode
    4.65 +
    4.66 +Then, you can call e.g. Dijkstra algoritm on this map like this:
    4.67 +\code
    4.68 +  ...
    4.69 +  ReducedLengthMap rm(g,len,pot);
    4.70 +  Dijkstra<Graph,ReducedLengthMap> dij(g,rm);
    4.71 +  dij.run(s);
    4.72 +  ...
    4.73 +\endcode
    4.74 +
    4.75 +*/