From ffb5b212f8fcd638f218ac5d65d2c464f125e429 Mon Sep 17 00:00:00 2001
From: Ichthyostega <prg@ichthyostega.de>
Date: Sat, 19 Feb 2011 19:19:39 +0100
Subject: [PATCH] Add notes regarding the menugen script

Signed-off-by: Ichthyostega <prg@ichthyostega.de>
---
 doc/technical/infra/MenuGen.txt | 35 +++++++++++++++++++++++++++++++++
 doc/technical/infra/index.txt   | 13 ++++++++++++
 2 files changed, 48 insertions(+)
 create mode 100644 doc/technical/infra/MenuGen.txt
 create mode 100644 doc/technical/infra/index.txt

diff --git a/doc/technical/infra/MenuGen.txt b/doc/technical/infra/MenuGen.txt
new file mode 100644
index 000000000..6737eb860
--- /dev/null
+++ b/doc/technical/infra/MenuGen.txt
@@ -0,0 +1,35 @@
+Website Navigation Generator
+============================
+:Author: Hermann Voßeler
+:Date: 2/2011
+
+
+Notes regarding the +menugen.py+ -- written 2/2011 during our attempt
+to get the new Lumiera website online finally.
+
+Known issues
+------------
+
+* for sake of simplicity, there is _one_ generated container HTML element
+  per menu entry. In case this entry is a submenu, the +<ul>+-element is
+  used, _not_ the preceeding headline +<li>+ -- this is due to the fact
+  that this submenu entry is going to be collapsed eventually, but has
+  the side-effect of highlighting _only_ that submenu block, _not_ the
+  preceeding headline.
+* the acceptable DSL syntax needs to be documented manually; there is
+  no way to generate this information. Doing so would require to add
+  specific information methods into Placement subclasses, and it would
+  result in duplicated information between the regular expressions
+  and the informations returned by such information methods.
+  This was deemed dangerous.
+* the +__repr__+ of the Placement subclasses is not an _representation_
+  but rather a +__str__+ -- but unfortunately the debugger in PyDev
+  invokes +__repr__+
+* the startdir for automatic discovery is an global variable and indeed
+  is used in several un-obvious places and contexts
+* when through the use of redirection, the same file is encountered
+  multiple times during discovery, it is treated repeatedly, each times
+  associated with another node, because, on discovery, the node-ID is
+  generated as +parentPath/fileID+, to avoid mixing up similarily named
+  files in different directories. (The NodeIndex allows to retrieve
+  a node just by its bare ID, without path anyway)
diff --git a/doc/technical/infra/index.txt b/doc/technical/infra/index.txt
new file mode 100644
index 000000000..e993d81e9
--- /dev/null
+++ b/doc/technical/infra/index.txt
@@ -0,0 +1,13 @@
+Infrastructure
+==============
+
+
+Various details, documentation and other pieces of information regarding
+the infrastructure of the Lumiera project. This includes the infrastructure
+used for building and maintaining documentation and website.
+
+ * see link::../build/index.html[separate page for the Buildsystem]
+ * generating the link::MenuGen.html[navigation menu] for the website
+
+
+