# HG changeset patch
# User alpar
# Date 1157400457 0
# Node ID 09af6d2b683b2b5b4b084b91b0f200005a4f82b4
# Parent f47faf6913abc3605f6fdbb4f44c588282d5af2f
Add missing Tutorial dox files
diff -r f47faf6913ab -r 09af6d2b683b doc/Makefile.am
--- a/doc/Makefile.am Mon Sep 04 19:48:09 2006 +0000
+++ b/doc/Makefile.am Mon Sep 04 20:07:37 2006 +0000
@@ -7,6 +7,7 @@
doc/icons/geom/ftv2doc.png \
doc/icons/geom/ftv2folderclosed.png \
doc/icons/geom/ftv2folderopen.png \
+ doc/algorithms.dox \
doc/coding_style.dox \
doc/developers_interface.dox \
doc/dirs.dox \
@@ -18,6 +19,8 @@
doc/license.dox \
doc/mainpage.dox \
doc/maps.dox \
+ doc/maps1.dox \
+ doc/maps2.dox \
doc/named-param.dox \
doc/namespaces.dox \
doc/quicktour.dox \
diff -r f47faf6913ab -r 09af6d2b683b doc/algorithms.dox
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/algorithms.dox Mon Sep 04 20:07:37 2006 +0000
@@ -0,0 +1,5 @@
+/**
+\page algorithms Algorithms
+
+Place-holder page for algorithms.
+*/
diff -r f47faf6913ab -r 09af6d2b683b doc/maps1.dox
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/maps1.dox Mon Sep 04 20:07:37 2006 +0000
@@ -0,0 +1,72 @@
+/**
+\page maps1 Maps I.
+
+In the previous section we discussed graph topology. That is the skeleton a complex
+graph represented data-set needs. But how to assign the data itself to that skeleton?
+Here come the \b maps in.
+
+\section maps_intro Introduction to maps
+Maps play a central role in LEMON. As their name suggests, they map a certain range of keys to certain values.
+In LEMON there is many types of maps. Each map has two typedef's to determine the types of keys and values, like this:
+\code
+ typedef Edge Key;
+ typedef double Value;
+\endcode
+(Except matrix maps, they have two key types.)
+
+To make easy to use them - especially as template parameters - there are map concepts like by graph classes.
+
+- \ref ReadMap - values can be red out with the \c operator[].
+\code value_typed_variable = map_instance[key_value]; \endcode
+
+- \ref WriteMap - values can be set with the \c set() member function.
+\code map_instance.set(key_value, value_typed_expression); \endcode
+
+- \ref ReadWriteMap - it's just a shortcut to indicate that the map is both
+readable and writable. It is delivered from them.
+
+- \ref ReferenceMap - a subclass of ReadWriteMap. It has two additional typedefs
+Reference and ConstReference and two overloads of \c operator[] to
+providing you constant or non-constant reference to the value belonging to a key,
+so you have a direct access to the memory address where it is stored.
+
+- And there are the Matrix version of these maps, where the values are assigned to a pair of keys.
+The keys can be different types. (\ref ReadMatrixMap, \ref WriteMatrixMap, \ref ReadWriteMatrixMap, \ref ReferenceMatrixMap)
+
+
+
+\section maps_graph Graphs' maps
+Every \ref MappableGraphComponent "mappable" graph class has two public templates: NodeMap and EdgeMap
+satisfying the \ref GraphMap concept.
+If you want to assign data to nodes, just declare a NodeMap with the corresponding
+type. As an example, think of a edge-weighted directed graph.
+\code ListGraph::EdgeMap weight(graph); \endcode
+You can see that the map needs the graph hows edges will mapped, but nothing more.
+
+If the graph class is extendable or erasable the map will automatically follow
+the changes you make. If a new node is added a default value is mapped to it.
+You can define the default value by passing a second argument to the map's constructor.
+\code ListGraph::EdgeMap weight(graph, 13); \endcode
+But keep in mind that \c VALUE has to have copy constructor.
+
+Of course \c VALUE can be a rather complex type.
+
+For practice let's see the following template function (from \ref maps_summary "maps-summary.cc" in the \ref demo directory)!
+\dontinclude maps_summary.cc
+\skip template
+\until }
+The task is simple. We need the summary of some kind of data assigned to a graph's nodes.
+(Whit a little trick the summary can be calculated only to a sub-graph without changing
+this code. See \ref SubGraph techniques - that's LEMON's true potential.)
+
+And the usage is simpler than the declaration suggests. The compiler deduces the
+template specialization, so the usage is like a simple function call.
+\skip std
+\until ;
+
+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.
+
+If you want some 'real-life' examples see the next page, where we discuss \ref algorithms
+(coming soon) and will use maps hardly.
+Or if you want to know more about maps read these \ref maps2 "advanced map techniques".
+*/
diff -r f47faf6913ab -r 09af6d2b683b doc/maps2.dox
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/maps2.dox Mon Sep 04 20:07:37 2006 +0000
@@ -0,0 +1,72 @@
+/**
+\page maps2 Maps II.
+
+Here we discuss some advanced map techniques. Like writing your own maps or how to
+extend/modify a maps functionality with adaptors.
+
+\section custom_maps Writing Custom ReadMap
+\subsection custom_read_maps Readable Maps
+
+Readable maps are very frequently used as the input of an
+algorithm. For this purpose the most straightforward way is the use of the
+default maps provided by LEMON's graph structures.
+Very often however, it is more
+convenient and/or more efficient to write your own readable map.
+
+You can find some examples below. In these examples \c Graph is the
+type of the particular graph structure you use.
+
+
+This simple map assigns \f$\pi\f$ to each edge.
+
+\code
+struct MyMap
+{
+ typedef double Value;
+ typedef Graph::Edge Key;
+ double operator[](Key e) const { return M_PI;}
+};
+\endcode
+
+An alternative way to define maps is to use MapBase
+
+\code
+struct MyMap : public MapBase
+{
+ Value operator[](Key e) const { return M_PI;}
+};
+\endcode
+
+Here is a bit more complex example.
+It provides a length function obtained
+from a base length function shifted by a potential difference.
+
+\code
+class ReducedLengthMap : public MapBase
+{
+ const Graph &g;
+ const Graph::EdgeMap &orig_len;
+ const Graph::NodeMap &pot;
+
+public:
+ Value operator[](Key e) const {
+ return orig_len[e]-(pot[g.target(e)]-pot[g.source(e)]);
+ }
+
+ ReducedLengthMap(const Graph &_g,
+ const Graph::EdgeMap &_o,
+ const Graph::NodeMap &_p)
+ : g(_g), orig_len(_o), pot(_p) {};
+};
+\endcode
+
+Then, you can call e.g. Dijkstra algoritm on this map like this:
+\code
+ ...
+ ReducedLengthMap rm(g,len,pot);
+ Dijkstra dij(g,rm);
+ dij.run(s);
+ ...
+\endcode
+
+*/