From cb1b18406e50a8cd7176c6317c609a9b275ef00f Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Mon, 14 Feb 2011 04:59:27 +0100 Subject: [PATCH 01/15] Fix typo in doc/devel/report.txt --- doc/devel/report.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/devel/report.txt b/doc/devel/report.txt index 903b02768..01412eb10 100644 --- a/doc/devel/report.txt +++ b/doc/devel/report.txt @@ -17,7 +17,7 @@ Statistics and Reports ++++++++++++++++++++++++++++++++++++++ '''' -^Statistics generated automatically by *Ohloh* based on Git master^ +^Statistics generated automatically by *Ohloh* based on Git master.^ Tickets @@ -26,9 +26,9 @@ Tickets * link:http://issues.lumiera.org/report/14[recently changed tickets] * link:http://issues.lumiera.org/report/8[core tickets in work] * link:http://issues.lumiera.org/report/5[stalled tickets] - * link:http://issues.lumiera.org/report/15[non-codin small tasks] + * link:http://issues.lumiera.org/report/15[non-coding small task] -See the link:http://issues.lumiera.org/report[Trac overview for more ticket reports] +See the link:http://issues.lumiera.org/report[Trac overview] for more ticket reports. [icon="warning.png"] WARNING: Website under construction From b82aac26cead222dc1cfa1817eab5bd78f96fa4a Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 20 Feb 2011 20:16:28 +0100 Subject: [PATCH 02/15] Add one or two sentences about the user manual. --- doc/user/manual.txt | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/doc/user/manual.txt b/doc/user/manual.txt index 7bce5ad63..5a1e397e8 100644 --- a/doc/user/manual.txt +++ b/doc/user/manual.txt @@ -1,9 +1,8 @@ Lumiera User Manual =================== -'to be written...' - +The plan is to create the users manual later in a colaborative +fashion, similar to what turned out so effective for Cinelerra. -[icon="warning.png"] -WARNING: Website under construction +This work is postponed until the software is actually working. From 10766fe92a18caab45418df61698ae7c01e9f4a2 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 20 Feb 2011 20:24:30 +0100 Subject: [PATCH 03/15] Replace several "Warning: Website under construction" with appropriate stubs. --- doc/design/application/Config.txt | 2 -- doc/design/application/index.txt | 2 -- doc/design/application/plugin_loader.txt | 4 +--- doc/design/backend/index.txt | 4 +--- doc/design/engine/index.txt | 4 +--- doc/design/gui/GuiDiscussion/index.txt | 2 -- doc/design/gui/index.txt | 5 ----- doc/design/model/index.txt | 4 ---- doc/design/plugins/index.txt | 4 ---- doc/design/workflow/index.txt | 5 ----- doc/devel/report.txt | 4 ---- doc/devel/rfc.txt | 5 ----- doc/index.txt | 3 --- doc/technical/backend/index.txt | 5 ----- doc/technical/build/index.txt | 6 +++--- doc/technical/gui/index.txt | 4 +--- doc/technical/howto/index.txt | 6 ------ doc/technical/index.txt | 6 ------ doc/technical/proc/index.txt | 4 +--- doc/user/index.txt | 7 +------ 20 files changed, 9 insertions(+), 77 deletions(-) diff --git a/doc/design/application/Config.txt b/doc/design/application/Config.txt index cc3bfcec4..9f01793e6 100644 --- a/doc/design/application/Config.txt +++ b/doc/design/application/Config.txt @@ -12,6 +12,4 @@ The Lumiera application uses two quite different sources for configuration -> see also the link:{ldoc}/technical/backend/ConfigLoader.html[Config Loader brainstorming from 2008] (implementation details) -[icon="warning.png"] -WARNING: Website under construction diff --git a/doc/design/application/index.txt b/doc/design/application/index.txt index 154614f8d..71b7cebe4 100644 --- a/doc/design/application/index.txt +++ b/doc/design/application/index.txt @@ -5,6 +5,4 @@ Design Documents: Application Framework * link:plugin_loader.html[Plugin Loader] * link:SubsystemLifecycle.html[Application Subsystems and Lifecycle] -[icon="warning.png"] -WARNING: Website under construction diff --git a/doc/design/application/plugin_loader.txt b/doc/design/application/plugin_loader.txt index 4bb5e10c8..a0e2d9a1a 100644 --- a/doc/design/application/plugin_loader.txt +++ b/doc/design/application/plugin_loader.txt @@ -1,7 +1,5 @@ Lumiera Design: Plugin system ============================= - -[icon="warning.png"] -WARNING: Website under construction +Eventually, this will have design documentation for the Plugin system. diff --git a/doc/design/backend/index.txt b/doc/design/backend/index.txt index a16cb5f18..44c57ca8b 100644 --- a/doc/design/backend/index.txt +++ b/doc/design/backend/index.txt @@ -1,7 +1,5 @@ Design Documents: Backend ========================= - -[icon="warning.png"] -WARNING: Website under construction +Eventually, this will have design documentation for the Backend. diff --git a/doc/design/engine/index.txt b/doc/design/engine/index.txt index 946e239e6..7d9b5ea39 100644 --- a/doc/design/engine/index.txt +++ b/doc/design/engine/index.txt @@ -1,7 +1,5 @@ Design Documents: Renderengine ============================== - -[icon="warning.png"] -WARNING: Website under construction +Eventually, this will have design documentation for the Engine. diff --git a/doc/design/gui/GuiDiscussion/index.txt b/doc/design/gui/GuiDiscussion/index.txt index d5f97da23..03660f813 100644 --- a/doc/design/gui/GuiDiscussion/index.txt +++ b/doc/design/gui/GuiDiscussion/index.txt @@ -13,6 +13,4 @@ GUI concepts and -features and proposals. * link:MenuAndShortcuts.html[Ideas for menus and shortcuts] - link:TimelineDiscussion.html[Conclusions by Joel Holdsworth] -[icon="warning.png"] -WARNING: Website under construction diff --git a/doc/design/gui/index.txt b/doc/design/gui/index.txt index 33090d858..2ecddacf8 100644 --- a/doc/design/gui/index.txt +++ b/doc/design/gui/index.txt @@ -16,8 +16,3 @@ integral, so its rather treated separately of individual GUI features. .*TODO* more contributions please... ;-) We had several additional discussions and contributions on the mailinglist, several people did even concept drawings. Collect these and add them here - - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/design/model/index.txt b/doc/design/model/index.txt index ab8fdbd66..2541c63c5 100644 --- a/doc/design/model/index.txt +++ b/doc/design/model/index.txt @@ -3,7 +3,3 @@ Design Documents: Model * two models: high-level and low-level * RfC: link:{rfc}/../rfc_pending/ProcHighLevelModel.html[high-level model basics] - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/design/plugins/index.txt b/doc/design/plugins/index.txt index 2c843477f..6ad7e6138 100644 --- a/doc/design/plugins/index.txt +++ b/doc/design/plugins/index.txt @@ -2,7 +2,3 @@ Design Documents: Plug-In ========================= * link:PluginBrainstorm.html[early draft for the plugin interface] - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/design/workflow/index.txt b/doc/design/workflow/index.txt index c82698708..48147d31e 100644 --- a/doc/design/workflow/index.txt +++ b/doc/design/workflow/index.txt @@ -9,8 +9,3 @@ integral, so it's rather treated separately of individual GUI features. -> see also link:../gui/index.html[general GUI discussion...] * link:LumieraWorkflowOutline.html[Workflow outline by BJMR] - - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/devel/report.txt b/doc/devel/report.txt index 01412eb10..75bbbeb94 100644 --- a/doc/devel/report.txt +++ b/doc/devel/report.txt @@ -29,7 +29,3 @@ Tickets * link:http://issues.lumiera.org/report/15[non-coding small task] See the link:http://issues.lumiera.org/report[Trac overview] for more ticket reports. - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/devel/rfc.txt b/doc/devel/rfc.txt index 36db7c289..996ca1ab3 100644 --- a/doc/devel/rfc.txt +++ b/doc/devel/rfc.txt @@ -21,8 +21,3 @@ Generally you should refrain from editing someone others proposals (except for t * link:rfc[RfC accepted] * link:rfc_pending[RfC pending] * link:rfc_dropped[RfC dropped] - - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/index.txt b/doc/index.txt index 86eaac0d9..ad0c5d3ee 100644 --- a/doc/index.txt +++ b/doc/index.txt @@ -1,8 +1,5 @@ == Documentation -[icon="warning.png"] -WARNING: Website under construction - This documentation section contains documentation for both users and developers. === User diff --git a/doc/technical/backend/index.txt b/doc/technical/backend/index.txt index a3973d3f1..30cd88df5 100644 --- a/doc/technical/backend/index.txt +++ b/doc/technical/backend/index.txt @@ -2,8 +2,3 @@ Technical Documentation: Backend ================================ * link:ConfigLoader.html[Config Loader brainstorming from 2008] - - -[icon="warning.png"] -WARNING: Website under construction - diff --git a/doc/technical/build/index.txt b/doc/technical/build/index.txt index b9575cbd2..72cc1c1e9 100644 --- a/doc/technical/build/index.txt +++ b/doc/technical/build/index.txt @@ -1,6 +1,8 @@ Lumiera Buildsystem =================== +As work progresses, we will add more information on the build system. + build -- continuous integration -- packaging * SCons @@ -8,8 +10,6 @@ build -- continuous integration -- packaging * Dependencies * link:BuildDroneDraft.html[»Builddrone« concept from 2008] * packaging: Debian RPM -* Lumiera debian depot +* Lumiera Debian depot -[icon="warning.png"] -WARNING: Website under construction diff --git a/doc/technical/gui/index.txt b/doc/technical/gui/index.txt index c88640368..e51ed8ee1 100644 --- a/doc/technical/gui/index.txt +++ b/doc/technical/gui/index.txt @@ -1,7 +1,5 @@ Technical Documentation: GUI ============================ - -[icon="warning.png"] -WARNING: Website under construction +Eventually, this will have technical documentation for the GUI. diff --git a/doc/technical/howto/index.txt b/doc/technical/howto/index.txt index 50e3158f4..e3fbae112 100644 --- a/doc/technical/howto/index.txt +++ b/doc/technical/howto/index.txt @@ -10,9 +10,3 @@ similar usefull pieces of information targeted at Lumiera developers. See also == Notepad - link:DebugGdbPretty.html[Python pretty printers for GDB] - - -[icon="warning.png"] -WARNING: Website under construction - - diff --git a/doc/technical/index.txt b/doc/technical/index.txt index eeaa78017..2f09a208f 100644 --- a/doc/technical/index.txt +++ b/doc/technical/index.txt @@ -28,9 +28,3 @@ You may want to read the link:../design/index.html[Design Documents] first to ge .HOWTO * link:howto/index.html[*Developer HOWTOs*] : Collection of instructions, recipes, hints and similar materials intended for developers - - -[icon="warning.png"] -WARNING: Website under construction - - diff --git a/doc/technical/proc/index.txt b/doc/technical/proc/index.txt index 5c438031f..9c0d1bb98 100644 --- a/doc/technical/proc/index.txt +++ b/doc/technical/proc/index.txt @@ -1,7 +1,5 @@ Technical Documentation: Proc-Layer =================================== - -[icon="warning.png"] -WARNING: Website under construction +Eventually, this will have technical documentation for the Proc-Layer. diff --git a/doc/user/index.txt b/doc/user/index.txt index a98e41367..726244fa5 100644 --- a/doc/user/index.txt +++ b/doc/user/index.txt @@ -1,13 +1,8 @@ User Documentation ================== -'to be written...' - - * link:manual.html[We need to write a user manual....] + * link:manual.html[User Manual] _(planned)_ * The following document might become an introductory overview: + link:outerSpace/lumiera_from_outer_space.html[Lumiera (as seen) from Outer Space] * link:outerSpace/Glossary.html[Glossary of common terms] -[icon="warning.png"] -WARNING: Website under construction - From d21747e512aca413e9b8667384ecc18b94435280 Mon Sep 17 00:00:00 2001 From: Stefan Kangas Date: Sun, 20 Feb 2011 20:40:13 +0100 Subject: [PATCH 04/15] doc: Several minor fixes and structural improvements. --- doc/design/index.txt | 64 ++++++++++++++++++++------------- doc/technical/backend/index.txt | 4 +++ doc/technical/build/index.txt | 10 +++--- doc/technical/index.txt | 11 +++--- 4 files changed, 56 insertions(+), 33 deletions(-) diff --git a/doc/design/index.txt b/doc/design/index.txt index 5ebd09a37..a19f26e78 100644 --- a/doc/design/index.txt +++ b/doc/design/index.txt @@ -1,51 +1,67 @@ -== Lumiera Design Documents +Lumiera Design Documents +======================== -The goal of Lumiera is to provide a professionnal tool for video editing on GNU/Linux systems. -The vision of the development team defines a modern design for the core of a Non-Linear Editing software. -One of the key aspect of Lumiera is the strong separation between the user interface and the processing core. -Lumiera as a software will come along with a GTK GUI but that does not make this exclusive, any other GUI could be written as well as scripts to drive the core. -This is made possible by the above-mentioned quality of Lumiera being considered as two strictly separate parts. -Lumiera as a processing core will be able to do anything possibly conceivable, therefore it may be used to do any task on video (and audio?), even unrelated to video editing. +The goal of Lumiera is to provide a professional tool for video editing on +GNU/Linux systems. The vision of the development team defines a modern design +for the core of a Non-Linear Editing software. One of the key aspect of Lumiera +is the strong separation between the user interface and the processing core. +Lumiera as a software will come along with a GTK GUI but that does not make this +exclusive, any other GUI could be written as well as scripts to drive the core. +This is made possible by the above-mentioned quality of Lumiera being considered +as two strictly separate parts. Lumiera as a processing core will be able to do +anything possibly conceivable, therefore it may be used to do any task on video +(and audio?), even unrelated to video editing. .Workflow **** The word Workflow is used to name the way tasks can be achieved in an application. Any operation in Lumiera must be possible in the most suitable and stringent fashion. The Workflow is closely related to how flexible the GUI is but also the concern of deeper and more technical parts of the application. **** -=== Overview -The internal structure of Lumiera is divided in numerous subsystems. -This overview will try to go through the elements from the highest to the lowest piece of the structure. -They can be categorized into three main categories plus extra components : +Overview +-------- -==== link:gui/index.html[Graphical User Interface] +The internal structure of Lumiera is divided in numerous subsystems. This +overview will try to go through the elements from the highest to the lowest +piece of the structure. They can be categorized into three main categories plus +extra components : -User interfaces are basically handled like plugins, consequently it is possible to interface with Lumiera through scripts. It is also possible to create specialized GUIs. -The interface is the closest component to the user, it is purely visual. There the user manipulates, organizes, loads, configures all sorts of datas, especially MObjects (media objects) and Assets. These elements are contained within a structure called the Session. +link:gui/index.html[Graphical User Interface] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -==== The Processing Layer +User interfaces are basically handled like plugins, consequently it is possible +to interface with Lumiera through scripts. It is also possible to create +specialized GUIs. The interface is the closest component to the user, it is +purely visual. There the user manipulates, organizes, loads, configures all +sorts of datas, especially MObjects (media objects) and Assets. These elements +are contained within a structure called the Session. -The Processing layer (or proc) is where the elements from the Session are assembled to form a network of nodes, to be sent to the Backend. The lowest data structure is called the Low-level model. + +The Processing Layer +~~~~~~~~~~~~~~~~~~~~ + +The Processing layer (or proc) is where the elements from the Session are +assembled to form a network of nodes, to be sent to the backend. The lowest data +structure is called the Low-level model. + * link:model/index.html[Model] + * link:engine/index.html[Engine] -==== link:backend/index.html[The Backend] +link:backend/index.html[The Backend] +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The backend uses the Low-level model. It allows the rendering and makes a heavy use of the Input/Output System to the screen or to external monitors. +The backend uses the Low-level model. It allows the rendering and makes a heavy +use of the Input/Output System to the screen or to external monitors. Extra components ---------------- - link:application/index.html[The Application] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The application controls the initialization and shutdown procedures as well as loading external elements like plugins that are widely used. +The application controls the initialization and shutdown procedures as well as +loading external elements like plugins that are widely used. link:plugins/index.html[Plugins] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -They are key elements in Lumiera since the application relies heavily on this concept of modules. For example, the GUI of Lumiera is a plugin. - - - +Plugins are key elements in Lumiera since the application relies heavily on this +concept of modules. For example, the GUI of Lumiera is a plugin. diff --git a/doc/technical/backend/index.txt b/doc/technical/backend/index.txt index 30cd88df5..58fd1a5e9 100644 --- a/doc/technical/backend/index.txt +++ b/doc/technical/backend/index.txt @@ -1,4 +1,8 @@ Technical Documentation: Backend ================================ +Eventually, this will have technical documentation for the Backend. + +For now, we have: + * link:ConfigLoader.html[Config Loader brainstorming from 2008] diff --git a/doc/technical/build/index.txt b/doc/technical/build/index.txt index 72cc1c1e9..a9b3261da 100644 --- a/doc/technical/build/index.txt +++ b/doc/technical/build/index.txt @@ -1,7 +1,7 @@ -Lumiera Buildsystem -=================== +Lumiera build system +==================== -As work progresses, we will add more information on the build system. +As work progresses, we will add more information on the Lumiera build system. build -- continuous integration -- packaging @@ -9,7 +9,7 @@ build -- continuous integration -- packaging * Autotools * Dependencies * link:BuildDroneDraft.html[»Builddrone« concept from 2008] -* packaging: Debian RPM -* Lumiera Debian depot +* Packaging: Debian RPM +* Lumiera debian depot diff --git a/doc/technical/index.txt b/doc/technical/index.txt index 2f09a208f..845b88346 100644 --- a/doc/technical/index.txt +++ b/doc/technical/index.txt @@ -2,13 +2,16 @@ Technical Documentation ======================= -This documentation section contains technical documentation about Lumiera. -To get an overview of all the internals and components, you might want to read +This documentation section contains technical documentation about Lumiera. To +get an overview of all the internals and components, you might want to read link:innerCore/the_inner_core.html[Lumiera the Inner Core] == Three Layers -The technical documentation is split in three parts, one for each of the three main layers of Lumiera. -You may want to read the link:../design/index.html[Design Documents] first to get an overview of all the components. + +The technical documentation is split in three parts, one for each of the three +main layers of Lumiera. You may want to read the +link:../design/index.html[Design Documents] first to get an overview of all the +components. * link:gui/index.html[*Graphical User Interface*] : Documents related to the GTK based Lumiera GUI From ffb5b212f8fcd638f218ac5d65d2c464f125e429 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Sat, 19 Feb 2011 19:19:39 +0100 Subject: [PATCH 05/15] Add notes regarding the menugen script Signed-off-by: Ichthyostega --- 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 +
    +-element is + used, _not_ the preceeding headline +
  • + -- 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 + + + From e766adc1f2b4ce70943f16780042e2f59070bb5d Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 21 Feb 2011 01:44:32 +0100 Subject: [PATCH 06/15] more notes... Signed-off-by: Ichthyostega --- doc/technical/infra/MenuGen.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/technical/infra/MenuGen.txt b/doc/technical/infra/MenuGen.txt index 6737eb860..f2b3d0b0b 100644 --- a/doc/technical/infra/MenuGen.txt +++ b/doc/technical/infra/MenuGen.txt @@ -33,3 +33,11 @@ Known issues 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) +* no escaping: currently any variable text is written to the generated + HTML without any sanitising or escaping. This might be a security issue +* the method Node.matches() is implemented sloppily: it uses just a mutual + postfix match, while actually it should line up full path components and + check equality on components, starting from the path end. This cheesy + implementation can yield surprising side-effects: e.g. an not-yet attached + node +'end'+ could match a new menu page +'documentation/backend'+ + From 5487c244d68b075c675f381c75a68af5230dfdae Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 21 Feb 2011 02:34:16 +0100 Subject: [PATCH 07/15] small change to try the new menugen-auto-script Signed-off-by: Ichthyostega --- doc/technical/howto/index.txt | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/technical/howto/index.txt b/doc/technical/howto/index.txt index e3fbae112..20450cd49 100644 --- a/doc/technical/howto/index.txt +++ b/doc/technical/howto/index.txt @@ -1,6 +1,8 @@ Developer HOWTOs ================ +//MENU: title Dev HOWTOs + This section contains a loose collection of instructions, recipes, tutorials and similar usefull pieces of information targeted at Lumiera developers. See also From 02eec48c3b242e3ba520ca6f25cc05398f215ef3 Mon Sep 17 00:00:00 2001 From: Ichthyostega Date: Mon, 21 Feb 2011 08:24:58 +0100 Subject: [PATCH 08/15] Documentation of the new menu generating script for the website Signed-off-by: Ichthyostega --- doc/technical/infra/MenuGen.txt | 265 ++++++++++++++++++++++++++++++-- 1 file changed, 249 insertions(+), 16 deletions(-) diff --git a/doc/technical/infra/MenuGen.txt b/doc/technical/infra/MenuGen.txt index f2b3d0b0b..a6f402cd1 100644 --- a/doc/technical/infra/MenuGen.txt +++ b/doc/technical/infra/MenuGen.txt @@ -1,43 +1,276 @@ Website Navigation Generator ============================ -:Author: Hermann Voßeler -:Date: 2/2011 +:author: Hermann Voßeler +:revdate: 2/2011 + + +This page contains documentation and notes regarding the +menugen.py+ -- +written 2/2011 during our attempt to get the new Lumiera website online finally. +The link::http://git.lumiera.org/gitweb?p=website-staging;a=blob;f=menugen.lua;h=aad2129d7f4ed3f3b35b2fc3ac2a63a9f1bfb62d;hb=menugen[initial draft version] was written by _cehteh_ in Lua + + +************************************************************************** +The purpose of the +*menugen*+ script is to maintain the navigation menu +on the Lumiera website semi-automatically. In the usual setup, this script +is triggered from a _Git push_ -- it walks the web subdirectories and +discovers menu entries. The generated HTML page contains both visible +elements and JavaScript snippets to display and highlight the menu +on the client side appropriately +************************************************************************** + +Overview: how it works +---------------------- +The menu generation and display is comprised of several parts working together + +. the +build_website.sh+ is triggered as a Git post-receive hook, whenever new + commits are transfered to the website Git repository. After discovering new + Asciidoc source files and generating the corresponding HTML files, the + menu generator script is invoked +. the +menugen+ python script walks the subdirectories to discover possible + menu contents. It visits Asciidoc source files (`*.txt`) and picks up + + - the location / URL + - the title + - special `//MENU:` directives embedded in Asciidoc comments + +. after building a complete menu tree (actually a DAG), this data structure + is walked to generate output HTML into a `menu.html` file in website root. +. the page template (`page.conf`) for generated Asciidoc pages contains an + +