sync with current documentation

admin/rfc.sh

@@ -4,64 +4,79 @@ shopt -s extglob
 
 function usage()
 {
-    less <<"EOF"
+    less -F <<"EOF"
-Script to maintain Lumiera RFC's
+Lumiera RFC maintenance script
+==============================
+
+// Note: the source of this documentation is maintained
+//       directly admin/rfc.sh in its usage() function
+//       edit it only there and then regenerate
+//       doc/devel/technical/infra/ with:
+//       ./admin/rfc.sh help >doc/technical/infra/rfcsh.txt
+
+Usage
+-----
 
-usage:
  ./admin/rfc.sh <command> [options]
 
-options:
+Commands (with <mandatory> and [optional] parameters)
- title                  - Quoted string used as RFC title
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- rfc                    - Name of the RFC, smart matched, unique
- rfcs                   - Name of the RFC, smart matched, multiple
- regex                  - Regex matched against the content of a RFC
- chapter                - Heading of a section
 
-commands (with <mandatory> and [optional] parameters):
+ find <rfcs> [regex]::    List all matching RFC's (matching `regex`)
- find <rfcs> [regex]    - List all matching RFC's (matching 'regex')
+ show <rfcs> [regex]::    Read RFC's (matching `regex`)
- show <rfcs> [regex]    - Read RFC's (matching 'regex')
+ create <title>::         Create a new RFC
- create <title>         - Create a new RFC
+ edit <rfc> [chapter]::   Edit RFC at chapter
- edit <rfc> [chapter]   - Edit RFC at chapter
+ asciidoc <rfc>::         pass the rfc.txt to `asciidoc` command
- asciidoc <rfc>         - pass the rfc.txt to 'asciidoc' command
+ comment <rfc>::          Add a new comment to a RFC
- comment <rfc>          - Add a new comment to a RFC
+ draft <rfc>::            Change RFC to Draft state
- draft <rfc>            - Change RFC to Draft state
+ final <rfc>::            Change RFC to Final state
- final <rfc>            - Change RFC to Final state
+ park <rfc>::             Change RFC to Parked state
- park <rfc>             - Change RFC to Parked state
+ drop <rfc>::             Change RFC to Dropped state
- drop <rfc>             - Change RFC to Dropped state
+ supersede <rfc> <new>::  Supersede RFC with a new RFC
- supersede <rfc> <new>  - Supersede RFC with a new RFC
+ discard <rfc>::          Delete an RFC
- discard <rfc>          - Delete an RFC
+ help::                   Show this help
- help                   - Show this help
+ process::                Do automatic maintenance work
- process                - Do automatic maintenance work
+ wrap <rfcs>::            canonical reformatting
- wrap <rfcs>            - canonical reformatting
 
-Smart matching:
+Option types
- RFC names don't need to be given exactly, they use a globbing pattern.
+~~~~~~~~~~~~
- This is:
+
+ title::                Quoted string used as RFC title
+ rfc::                  Name of the RFC, smart matched, unique
+ rfcs::                 Name of the RFC, smart matched, multiple
+ regex::                Regex matched against the content of a RFC
+ chapter::              Heading of a section
+
+
+Smart matching
+--------------
+
+RFC names don't need to be given exactly, they use a globbing pattern.
+This is:
  - case insensitive
  - whitespaces are ignored
-  - '*' stands for any number of parameters
+ - `*` stands for any number of parameters
-  - '?' is any single character
+ - `?` is any single character
-  - when starting with '/' they are matched against the begin of the name
+ - when starting with `/` they are matched against the begin of the name
  - some regex operators work too
- 'find' and 'show' can operate on many matches so the given rfc name doesn't
+`find` and `show` can operate on many matches so the given rfc name doesn't
- need to be unique. The other commands will complain when the RFC name given
+need to be unique. The other commands will complain when the RFC name given
- doesn't resolve to one unique RFC.
+doesn't resolve to one unique RFC.
 
-Notes:
+When `less` presents multiple files one can go forth and back with the `:n`
- When less presents multiple files one can go forth and back with the ':n'
+and `:p` commands.
- and ':p' commands.
 
- The tile for 'create' should be a normal document title. Possibly quoted
+The tile for `create` should be a normal document title. Possibly quoted
- since it may contain spaces and not too long. The filename is this title
+since it may contain spaces and not too long. The filename is this title
- in CamelCase with all spaces and special characters removed.
+in CamelCase with all spaces and special characters removed.
 
- Chapter machching single lines containing this word, special asciidoc
+Chapter machching single lines containing this word, special asciidoc
- comments in the form '//word:.*' and asciidoc block attributes '[word.*]'
+comments in the form `//word:.*` and asciidoc block attributes `[word.*]`
- on a single line. When a chapter pattern is not unique, the last one is
+on a single line. When a chapter pattern is not unique, the last one is
- picked.
+picked.
 
- rfc.sh executes git add/rm/mv commands, but never commits. One should do a
+rfc.sh executes git add/rm/mv commands, but never commits. One should do a
- commit as soon he finished editing.
+commit as soon he finished editing.
 
 EOF
 }

doc/design/architecture/ArchitectureSummary.txt

@@ -0,0 +1,36 @@
+Lumiera Architecture: Executive Summary
+=======================================
+:Author:	Hermann Voßeler
+:Email:	<Ichthyostega@web.de>
+:Date:      Sept 2010
+
+//Menu: label Summary
+
+.Three Layers
+Besides the (obvious) separation in GUI frontend and render engine, editing core and application logic
+are treated separately. Besides enforcing clearly defined interfaces, the ability for script driven
+``headless'' operation and extensibility by plug-ins are deeply rooted in the overall design.
+
+.Strong Separation
+High-level and low-level realm remain cleanly separated, relying on a compiler-like translation mechanism.
+This way, each part can be optimised for its purpose. The GUI exposes a feature-rich session model close
+to the problem domain, while the engine operates on a performance optimised render nodes graph.
+
+.Scheduling Micro Operations
+High performance calculations in the engine are organised as micro tasks to be scheduled,
+allowing for adaptation to current and future hardware, expected to operate increasingly parallelised.
+
+.Intelligent IO
+The engine is backed by an sophisticated frame cache and self adjusting I/O manager for maximising throughput
+and bandwidth use.
+
+.Stream Type System
+Instead of relying on a single media framework, data streams are abstracted and classified, allowing to
+handle most wiring, detection of possible connections and conversion automatically.
+
+.Rules Based Configuration
+Rather than driven by hard wired default behaviour or tedious manual operation, control flow is guided by
+a set of rules shaped configuration, which scales better to large and complicated projects. Queries are
+issued at decision points, allowing to build up a work environment customised and tailored for the needs
+of specific projects.
+

doc/design/architecture/index.txt

@@ -0,0 +1,13 @@
+Design Documents: Lumiera Architecture
+======================================
+
+This section will feature some rather high-level considerations regarding
+the architecture of the application.
+
+.Executive Summary
+See link:ArchitectureSummary.html[here] for a short summary of the core architecture
+ideas of the envisioned Lumiera Application.
+
+
+  
+

doc/design/index.txt

@@ -1,6 +1,15 @@
 Lumiera Design Documents
 ========================
 
+// Menu :  prepend child design/backend
+// Menu :  prepend child engine
+// Menu :  prepend child model
+// Menu :  prepend child design/gui
+// Menu :  prepend child architecture
+
+// Menu :  append child plugins
+// Menu :  append child workflow
+
 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

doc/technical/infra/MenuGen.txt

@@ -204,6 +204,7 @@ supported placement directives
 commandline options
 ^^^^^^^^^^^^^^^^^^^
 The behaviour of the +menugen+ script can be influenced by some options:
+
 predefined:: using the built-in predefined nodes
 scan::    discover nodes 
 debug::   dump data structure after discovery

doc/technical/infra/debianDepot.txt

@@ -0,0 +1,128 @@
+Lumiera Debian Package and Depot maintainance
+=============================================
+:Author: Hermann Voßeler deb@ichthyostega.de
+:Date: 3/2011
+
+//Menu: label Debian Depot
+
+This Debian-Depot is part of the Lumiera build infrastructure.
+It is managed automatically, based on the link:http://mirrorer.alioth.debian.org/[reprepro] tool by Bernhard Link
+
+
+The Lumiera debian package
+--------------------------
+As our whole infrastructure relies heavily on the Git version management tool, it's only natural
+also to organise the (debian) packaging with the help of Git. Fortunatlely, there is a nifty tool
+called link:https://honk.sigxcpu.org/piki/projects/git-buildpackage/[git-buildpackage], written
+by Guido Günther exactly for this purpuse: It treats the _debianisation_ as a branch in the
+Git repository, forking off the mainline at the release point.
+
+For Lumiera, this _debianisation branch_ is called 'deb' and can be found in the
+link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=summary[git:/git.lumiera.org/lumiera/debian] repository.
+
+To (re)build the debian package
+
+. +git clone git:/git.lumiera.org/lumiera/debian+
+. +mkdir pack.deb+
+. +cd debian+
+. +git-buildpackage --git-upstream-branch=+_RELEASE-TAG_
+
+-- here _RELEASE-TAG_ denotes the point in the Git history, which should become
+the reference source and be packaged into the *.orig.tar.gz. Usually, it's just
+sufficient to use 'master' for that purpose.
+
+
+Debian-Depot for installation via Apt
+-------------------------------------
+While it is easy just to build a debian package and then install it locally through
++dpkg -i+, if we want to support automated installation and upgrades using the Apt
+package manager, we need to build up more infrastructure. The primary reason is that
+for any source package, a multitude of binary packages might be built for different
+architectures; moreover, we want to support several different distributions.
+For this purpose,the Apt package manager requires a precisely defined folder structure,
+accessible online via 'http:' or 'ftp:'. For maintaining this folder structure, there
+are three concievable levels of complexy:
+
+minimal layout, manual maintainance::
+  place everything in a single directory accessible online. Use only one pseudo-distribution
+  and call the (single) component \'.\' -- just dump packages into the directory and update
+  the packages list
+
+multiple distributions and components, pool directory::
+  this setup is already a full-blown debian depot, just there are some limitations
+  on the flexibility: there might be only _one_ version of each package per distribution,
+  and all different distributions use a shared pool (and thus require different packages
+  to be labeled stringently)
+
+major distribution or mirror site::
+  similar to the above, this is a complete debian depot, but it is backed by a database
+  and allows for much more flexible configuration and is highly automated.
+
+
+For Lumiera, it seems the middle option is the right choice: while it still keeps the
+infrastructure simple, it allows for multiple _distributions_ (Debian/stable, Ubuntu....)
+and multiple _components_ (experimental, development, release). The mentioned 'reprepro'
+tool provides this degree of functionality: Basically, this is a fixed directory structure
+with some control files; the frontent is a commandline tool with a plethora of options
+and quite some automation- and extension hooks. Internally, it uses an embedded BerkelyDB.
+
+Using 'reprepro', existing source, binary or comined packages can be _added_ (imported)
+into the structure with a single command; the files comprising the package are then
+added automatically to the pool directory and all the indices, directories and GPG
+signatures are created and updated automatically. Previous versions of the same
+package are purged, when not needed by any existing package anymore
+
+everyday usage
+~~~~~~~~~~~~~~
+
+import a package::
+  +reprepro -V -C experimental include lenny lumiera_0.pre.01-1+maverick_i386.changes+
++
+this adds the given binary lumiera package, together with all sources and the original
+tarball to the 'lenny' repository, into the 'experimental' section
+
+dump out an entire repository::
+  +reprepro -V export lenny+
++
+this will __re__generate all of the indices, signatures and metadata of the 'lenny' repository
+
+
+Configuration
+~~~~~~~~~~~~~
+The current configuration and the state of the Debian Depot index files is tracked
+is a separate branch in the 
+link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=shortlog;h=refs/heads/depot[lumiera/debian]
+repository. (Note: this is a somewhat unconventional setup, insofar the 'depot' branch tracks
+a directory tree completely separete from the main lumiera source tree tracked by the deb branch;
+I choose this layout because of the marginal relevance of this depot management; I just didn't
+want to create _yet another not so useful Git repository..._)
+
+ * primary link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=blob;f=conf/distributions;hb=refs/heads/depot[configuration]
+ * Logfile of imports: link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=blob;f=log/lenny.log;hb=refs/heads/depot[for Lenny]
+
+[NOTE]
+.some special details to note in our setup
+=======================================================================================================================
+- each block in the 'distributions' file defines a repository for a ``distribution'' (e.g. Lenny, Lucid, Maverick).
+  Within such a repo, there are sections named 'Components'. 
+- The _override_ files mentioned in the configuration allow to overwrite / replace arbitrary fields in the metadata of
+  all packages added to that distribution.
+- In this setup, we enabled the 'tracking' function: thereby reprepro will keep track of the dependencies between 
+  binary packages, signatures, debianisation patches and original upstream tarballs. Never packages overwirte older
+  ones -- _at any time there is at most one version of a package in the repository._ Parts not referred to anymore
+  are automatically discareded. In our configuration, they are moved into the 'morguedir'
+- Please make sure the *gpg signing key* is in proper order, because it protects against evil spirited manipulations.
+
+=======================================================================================================================
+
+
+current setup 3/2011
+^^^^^^^^^^^^^^^^^^^^
+While later we want to automate most of this packaging business, currently it's done semi-manual.
+Mostly, Ichthyo builds the packages on his local PC (or a VM) and then adds/imports them to the
+'reprepro' -- changes are then propagated to lumiera.org via rsync; as kind of a backup, the
+index files are also pushed to link:http://git.lumiera.org/gitweb?p=lumiera/debian;a=shortlog;h=refs/heads/depot[Git].
+----
+rsync -rclvz --progress --partial --delete /local/filesys/path/to/Lumirep/depot/ ichthyo@www.lumiera.org:/var/local/www_debian
+----
+

doc/technical/infra/index.txt

@@ -8,6 +8,64 @@ 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
+ * how to use the link:rfcsh.html[rfc.sh] script for maintaining RFC's
 
 
 
+Other tools in the ./admin folder
+---------------------------------
+
+There are various other small tools and scripts in the admin folder which are
+not yet fully documented (Read the Source!).
+
+.headercheck
+This is a small tool which checks that all headers are sufficiently standalone
+and include anything they need. In future we might extend this to find out
+bogus includes by predefining (-D) headerguards they include, effectively
+disableing this include for a test.
+
+.render_icon.py
+used by the buildsystem to translate svg icons to bitmaps (png)
+
+.treeinfo.sh
+Generates a report about the projects directory structure by parsing the
+DIR_INFO files (which have to be maintained manually)
+
+A DIR_INFO is just a small text file where the first line shall give a short
+summary about the purpose of this directory followed by arbitary text giving
+more details.
+
+.git_hooks
+A directory containing example git hooks for signing and pushing on commit.
+Only use them when you know what you are doing.
+
+.lumiera_c_skeleton
+A script which instantiates a new pair of .c/.h files.
+
+.vg-run.sh
+convenience wrapper script to run an executable with valgrind
+using "typical options"; output goes to a logfile, which is
+fed to less afterwards.
+
+A valgrind suppression file is generated automatically, in
+case there is an executable "vgsuppression" located in the same
+directory as the target executable.
+
+.gnu-indent
+call the "indent" tool with parameters suitable for our (GNU derrived) coding style
+
+.testrunner
+Script driving make and running a test, possibly under valgrind. Works only
+for autotools build.
+
+.vgsuppression_gen.sh
+Use an existing 'vgsupression' executable to generate a valgrind supression file.
+
+Bitrot
+------
+
+Scripts which are not in use and need some makeover to be removed
+
+ testfilter.sh
+ rsync_docs_to_lumieraorg.sh
+

doc/technical/infra/rfcsh.txt

@@ -0,0 +1,73 @@
+Lumiera RFC maintenance script
+==============================
+
+// Note: the source of this documentation is maintained
+//       directly admin/rfc.sh in its usage() function
+//       edit it only there and then regenerate
+//       doc/devel/technical/infra/ with:
+//       ./admin/rfc.sh help >doc/technical/infra/rfcsh.txt
+
+Usage
+-----
+
+ ./admin/rfc.sh <command> [options]
+
+Commands (with <mandatory> and [optional] parameters)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+ find <rfcs> [regex]::    List all matching RFC's (matching `regex`)
+ show <rfcs> [regex]::    Read RFC's (matching `regex`)
+ create <title>::         Create a new RFC
+ edit <rfc> [chapter]::   Edit RFC at chapter
+ asciidoc <rfc>::         pass the rfc.txt to `asciidoc` command
+ comment <rfc>::          Add a new comment to a RFC
+ draft <rfc>::            Change RFC to Draft state
+ final <rfc>::            Change RFC to Final state
+ park <rfc>::             Change RFC to Parked state
+ drop <rfc>::             Change RFC to Dropped state
+ supersede <rfc> <new>::  Supersede RFC with a new RFC
+ discard <rfc>::          Delete an RFC
+ help::                   Show this help
+ process::                Do automatic maintenance work
+ wrap <rfcs>::            canonical reformatting
+
+Option types
+~~~~~~~~~~~~
+
+ title::                Quoted string used as RFC title
+ rfc::                  Name of the RFC, smart matched, unique
+ rfcs::                 Name of the RFC, smart matched, multiple
+ regex::                Regex matched against the content of a RFC
+ chapter::              Heading of a section
+
+
+Smart matching
+--------------
+
+RFC names don't need to be given exactly, they use a globbing pattern.
+This is:
+ - case insensitive
+ - whitespaces are ignored
+ - `*` stands for any number of parameters
+ - `?` is any single character
+ - when starting with `/` they are matched against the begin of the name
+ - some regex operators work too
+`find` and `show` can operate on many matches so the given rfc name doesn't
+need to be unique. The other commands will complain when the RFC name given
+doesn't resolve to one unique RFC.
+
+When `less` presents multiple files one can go forth and back with the `:n`
+and `:p` commands.
+
+The tile for `create` should be a normal document title. Possibly quoted
+since it may contain spaces and not too long. The filename is this title
+in CamelCase with all spaces and special characters removed.
+
+Chapter machching single lines containing this word, special asciidoc
+comments in the form `//word:.*` and asciidoc block attributes `[word.*]`
+on a single line. When a chapter pattern is not unique, the last one is
+picked.
+
+rfc.sh executes git add/rm/mv commands, but never commits. One should do a
+commit as soon he finished editing.
+

doc/user/intro/intro.txt

@@ -119,7 +119,7 @@ Processing of Video (and audio) data can be generalized as graph processing
 (more precisely ``directed acyclic graphs''). Data flows on the edges of these
 graphs and is processed in the nodes.
 
-image:lumiera_big_graph.svg[Example for a graph]
+image:{imgd}/lumiera_big_graph.png[Example for a graph]
 
 When we look at this model we discover that we only need to build
 xref:builder[->] such graphs, the nodes themselves can be seen as black boxes
@@ -162,7 +162,7 @@ The visible Universe
 
 Now its time to take a look at the prelimary Lumiera GUI:
 
-image:lumiera_screenshot.png[Screenshot of Lumiera]
+image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot]
 
 The GUI is a plugin by itself and only one way to work Lumiera, it will become
 possible to create special-purpose GUIs or control Lumiera in different ways,
@@ -178,6 +178,7 @@ xref:screenconcept[->] to adapt to different workplaces and workflows.
 
 Viewer
 ~~~~~~
+[red]#to be written#
 
 // only one viewer type used for everything
 // how is audio integrated in the viewer
@@ -194,21 +195,20 @@ Viewer
 Transport Controls
 ~~~~~~~~~~~~~~~~~~
 
-// current gui is not final (transport controls attached to the timeline)
+The layout in current gui is rather preliminary -- it is not finally decided
-// It is not finally decided where transport controls will be integrated
+where transport controls will be integrated; possibly as its own gui element
-// possibly as its own gui element
 
-// This are devices either controlled by widgets or by some input device (midi
+This are devices either controlled by widgets or by some input device
-// etc) so their gui may look differently.
+(MIDI, control surface, etc) so their gui may look differently.
-// Either way they connect to a Play Controler xref.. in the core which
+Either way they connect to a Play Controler xref.. in the core which
-// manages playing and cursor positioning.
+manages playing and cursor positioning.
 
-// thus there will be some gui facility to attach Transport controls to Play
+thus there will be some gui facility to attach Transport controls to Play
-// Controllers. Transport controls are ganged when they attach to the same
+Controllers. Transport controls are ganged when they attach to the same
-// Play Controler.
+Play Controler.
 
-// just playing some footage for preview creates a simple internal timeline,
+just playing some footage for preview creates a simple internal timeline,
-// no magic here.
+no magic here.
 
 // TODO: bit unrelated, think about how ganging controls in general should
 // work, also for faders, masks and so on
@@ -220,12 +220,13 @@ Transport Controls
 Timeline View
 ~~~~~~~~~~~~~
 
-// hierarchical tracks, not just a stack
+hierarchical tracks, not just a list
+
+Format Independent Timeline, one can put anything on the timeline.
+the busses constrain what kind of data is pulled out and in turn the
+builder creates a processing graph which does the necessary conversions and
+stuff.
 
-// Format Independent Timeline, one can put anything on the timeline.
-// the busses constrain what kind of data is pulled out and in turn the
-// builder creates a processing graph which does the necessary conversions and
-// stuff.
 // Q: how to handle interaction, for example when some conversion can only be
 //    done in a lossy way and some conversion node may or may not be inserted
 //    (i mean gui wise)?
@@ -241,19 +242,23 @@ Timeline View
 //                  a special case of a selection.
 
 
-// Busses
+Busses
-// ~~~~~~
+~~~~~~
-// How will the gui define busses?
+The GUI provides a separate _bus view_, showing the master busses (subgroups)
+in a manner similar to an audio mixing desk. Any bus is just a means to collect
+and sum up the output of a specific kind of media (video, audio, number of channels),
+produced by various processing elements and other busses. Conceptionally, these global
+busses are considered a part of the timeline
 
 
 Asset View
 ~~~~~~~~~~
 
-// Manages all assets available in one project.
+Manages all assets available in one project.
-//  * source media/footage/soundfiles
+  * source media/footage/soundfiles
-//  * prepared clips, known subprojects
+  * prepared clips, known subprojects
-//  * all available effects and transitions
+  * all available effects and transitions
-//  * internal artefacts like sequences and automation data sets
+  * internal artefacts like sequences and automation data sets
 
 // First this will be simply implemented showing data loaded into the session
 // and all available plugins/effects
@@ -272,18 +277,23 @@ Asset View
 // the contents of a clip bin can be played like a storyboard
 
 
+''''''''
+
 
 Dark Matter
 -----------
 
-// coarse overview about things the user does not see but have some contact
+[red]#to be written#
-// with, details later...
+coarse overview about things the user does not see but have some contact
+with, details later...
 
-Now lets take a look under the hood. Lumiera
+
+Now lets take a look under the hood.
 
 
 Session storage
 ~~~~~~~~~~~~~~~
+[red]#to be written#
 
 // not generateable data
 
@@ -314,15 +324,19 @@ output destination, layering, fade control, audio pan,...
 
 Rendering Engine
 ~~~~~~~~~~~~~~~~
-// rendering
+[red]#to be written#
+rendering...
 
 [[builder]]
+[red]#to be written#
 
-// rules system
+rules system
-
+[red]#to be written#
 
 I/O Subsystem
 ~~~~~~~~~~~~~
+[red]#to be written#
+
 // file handling
 //  vault, work, cache
 //  repositories
@@ -331,12 +345,16 @@ I/O Subsystem
 
 Configuration
 ~~~~~~~~~~~~~
+[red]#to be written#
+
 // configuration system
 // serves defaults, actual data are stored in the session
 
 
 Plugins/Interfaces
 ~~~~~~~~~~~~~~~~~~
+[red]#to be written#
+
 // explain whats it is
 // portability
 // versioning
@@ -345,6 +363,7 @@ Plugins/Interfaces
 
 Rendering Video
 ---------------
+[red]#to be written#
 
 // describe the flow of data to render a frame
 
@@ -354,6 +373,7 @@ Rendering Video
 
 Pulling a Frame
 ~~~~~~~~~~~~~~~
+[red]#to be written#
 
 // special cases,
 // case studies,
@@ -372,45 +392,19 @@ Pulling a Frame
 
 // show some case-studies that someone gets a feel how plugins work
 
-[[pluginstack]]
-
-//Audio
 
 
+[red]#TODO# Consider integrating the following things into the document above
 
-
+* plugins
-// TODO Following things need to be integrated into the document above
+* timeline
-
+* pull
-
+* bus defines rendering format
-* [[plugins]]
+* caching
-* [[timeline]]
+* frameserver
-* [[demultiplexer]]
+* screenconcept / perspectives
-* [[multiplexer]]
+* automation
-* [[encoder]]
+* 3 layered model
-* [[pull]]
-bus defines rendering format
-* [[caching]]
-* [[profiling]]
-* [[rendernode]]
-* [[frameserver]]
-* [[screenconcept]]
-* [[busses]]
-
-// gui/screen concepts
-//  perspectives
-
-// Automation
-
-
-
-
-// 3 layered model
-
-
-such as that we only need to pull exactly what we need,
-posibly down to the pixel, this also allows efficient caching xref:caching[->]
-for intermediate data, to be reused later.
-
 
 
 

doc/user/intro/lumiera_big_graph.svg

@@ -33,20 +33,21 @@
      borderopacity="1.0"
      inkscape:pageopacity="0.0"
      inkscape:pageshadow="2"
-     inkscape:zoom="1.0518407"
+     inkscape:zoom="1.4875274"
-     inkscape:cx="564.81009"
+     inkscape:cx="444.97376"
-     inkscape:cy="277.96054"
+     inkscape:cy="280.84291"
      inkscape:document-units="px"
-     inkscape:current-layer="layer2"
+     inkscape:current-layer="layer4"
      showgrid="true"
-     inkscape:window-width="1274"
+     inkscape:window-width="1668"
-     inkscape:window-height="774"
+     inkscape:window-height="1020"
      inkscape:window-x="0"
      inkscape:window-y="0"
      inkscape:window-maximized="0"
      inkscape:snap-to-guides="false"
      inkscape:snap-grids="true"
-     inkscape:snap-global="true">
+     inkscape:snap-global="true"
+     gridtolerance="5">
     <inkscape:grid
        type="xygrid"
        id="grid2854"
@@ -63,8 +64,36 @@
         <dc:format>image/svg+xml</dc:format>
         <dc:type
            rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title />
+        <dc:title>Lumiera Data Flow Overview</dc:title>
+        <cc:license
+           rdf:resource="http://creativecommons.org/licenses/by-sa/3.0/" />
+        <dc:date>Summer 2010</dc:date>
+        <dc:creator>
+          <cc:Agent>
+            <dc:title>Christian Thäter</dc:title>
+          </cc:Agent>
+        </dc:creator>
+        <dc:publisher>
+          <cc:Agent>
+            <dc:title>Lumiera.org</dc:title>
+          </cc:Agent>
+        </dc:publisher>
       </cc:Work>
+      <cc:License
+         rdf:about="http://creativecommons.org/licenses/by-sa/3.0/">
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#Reproduction" />
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#Distribution" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#Notice" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#Attribution" />
+        <cc:permits
+           rdf:resource="http://creativecommons.org/ns#DerivativeWorks" />
+        <cc:requires
+           rdf:resource="http://creativecommons.org/ns#ShareAlike" />
+      </cc:License>
     </rdf:RDF>
   </metadata>
   <g
@@ -130,10 +159,10 @@
        x="279.23798"
        y="309.81433" />
     <rect
-       style="fill:#ffffff;stroke:#b3b3b3;stroke-width:1;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+       style="fill:#ffffff;stroke:#b3b3b3;stroke-width:1;stroke-miterlimit:4;stroke-dasharray:none;stroke-dashoffset:0;stroke-opacity:1"
        id="rect4737"
        width="110"
-       height="80"
+       height="94.736069"
        x="230"
        y="354.40942" />
     <rect
@@ -158,19 +187,16 @@
      style="display:inline">
     <path
        style="fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 502,426.40942 40,0"
+       d="M 500,424.40942 L 540,424.40942"
        id="path3467" />
-    <path
-       style="fill:none;stroke:#b3b3b3;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 502,456.40942 40,0"
-       id="path3471" />
     <path
        style="fill:none;stroke:#ff0000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
-       d="m 502,486.40942 38.57143,-0.51948"
+       d="M 500,464.40942 L 540,464.40942"
-       id="path3473" />
+       id="path3473"
+       sodipodi:nodetypes="cc" />
     <path
-       style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0"
+       style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-dasharray:2, 2;stroke-dashoffset:1;stroke-opacity:1"
-       d="m 502,441.40942 40,0"
+       d="M 500,444.40942 L 540,444.40942"
        id="path3475" />
     <path
        style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0"
@@ -272,6 +298,11 @@
        d="M 365,74.580418 L 474.92023,194.40942"
        id="path2552"
        sodipodi:nodetypes="cc" />
+    <path
+       id="path3336"
+       d="M 345,336.82264 L 475,289.40942 L 475,194.40942"
+       style="fill:none;stroke:#000000;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:2, 2;stroke-dashoffset:0"
+       sodipodi:nodetypes="ccc" />
   </g>
   <g
      inkscape:label="Elements"
@@ -668,10 +699,10 @@
     <g
        style="display:inline"
        id="g3629-3"
-       transform="translate(15,140)">
+       transform="translate(15,149.9825)">
       <path
          transform="translate(0,527.95272)"
-         d="m 265,284.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,284.40942 A 15,5 0 1 1 235,284.40942 A 15,5 0 1 1 265,284.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="284.40942"
@@ -681,7 +712,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,279.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,279.40942 A 15,5 0 1 1 235,279.40942 A 15,5 0 1 1 265,279.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="279.40942"
@@ -691,7 +722,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,274.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,274.40942 A 15,5 0 1 1 235,274.40942 A 15,5 0 1 1 265,274.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="274.40942"
@@ -701,7 +732,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,269.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,269.40942 A 15,5 0 1 1 235,269.40942 A 15,5 0 1 1 265,269.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="269.40942"
@@ -892,10 +923,10 @@
     <g
        style="display:inline"
        id="g3629-3-2"
-       transform="translate(70,140)">
+       transform="translate(70,149.9825)">
       <path
          transform="translate(0,527.95272)"
-         d="m 265,284.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,284.40942 A 15,5 0 1 1 235,284.40942 A 15,5 0 1 1 265,284.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="284.40942"
@@ -905,7 +936,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,279.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,279.40942 A 15,5 0 1 1 235,279.40942 A 15,5 0 1 1 265,279.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="279.40942"
@@ -915,7 +946,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,274.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,274.40942 A 15,5 0 1 1 235,274.40942 A 15,5 0 1 1 265,274.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="274.40942"
@@ -925,7 +956,7 @@
          sodipodi:type="arc" />
       <path
          transform="translate(0,527.95272)"
-         d="m 265,269.40942 a 15,5 0 1 1 -30,0 15,5 0 1 1 30,0 z"
+         d="M 265,269.40942 A 15,5 0 1 1 235,269.40942 A 15,5 0 1 1 265,269.40942 z"
          sodipodi:ry="5"
          sodipodi:rx="15"
          sodipodi:cy="269.40942"
@@ -1108,12 +1139,12 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="285"
+       x="296.88394"
        y="319.40942"
        id="text3434"><tspan
          sodipodi:role="line"
          id="tspan3436"
-         x="285"
+         x="296.88394"
          y="319.40942">Busses</tspan></text>
     <text
        xml:space="preserve"
@@ -1128,73 +1159,74 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="374"
+       x="383.98251"
        y="364.40942"
        id="text3430-0"><tspan
          sodipodi:role="line"
          id="tspan3432-2"
-         x="374"
+         x="383.98251"
+         y="364.40942">Viewer</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial;text-anchor:start;text-align:start;writing-mode:lr;line-height:90%"
+       x="460"
+       y="174.40942"
+       id="text3434-2"
+       sodipodi:linespacing="90%"><tspan
+         sodipodi:role="line"
+         id="tspan2554">Switch-</tspan><tspan
+         sodipodi:role="line"
+         id="tspan2556">board</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       x="550"
+       y="304.40942"
+       id="text4506"><tspan
+         sodipodi:role="line"
+         id="tspan4508"
+         x="550"
+         y="304.40942">Data on Disk</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
+       x="550"
+       y="364.40942"
+       id="text4510"><tspan
+         sodipodi:role="line"
+         id="tspan4512"
+         x="550"
          y="364.40942">Viewer</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="460"
+       x="545"
-       y="174.40942"
+       y="399.40942"
-       id="text3434-2"><tspan
-         sodipodi:role="line"
-         id="tspan3436-9"
-         x="460"
-         y="174.40942">Busses</tspan></text>
-    <text
-       xml:space="preserve"
-       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="548.41583"
-       y="296.5054"
-       id="text4506"><tspan
-         sodipodi:role="line"
-         id="tspan4508"
-         x="548.41583"
-         y="296.5054">Data on Disk</tspan></text>
-    <text
-       xml:space="preserve"
-       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="550.85516"
-       y="348.0954"
-       id="text4510"><tspan
-         sodipodi:role="line"
-         id="tspan4512"
-         x="550.85516"
-         y="348.0954">Viewer</tspan></text>
-    <text
-       xml:space="preserve"
-       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="545.9765"
-       y="397.85779"
        id="text4514"><tspan
          sodipodi:role="line"
          id="tspan4516"
-         x="545.9765"
+         x="545"
-         y="397.85779">Node/Plugin</tspan></text>
+         y="399.40942">Node/Plugin</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="549.39154"
+       x="545"
-       y="426.15408"
+       y="424.40942"
        id="text4518"><tspan
          sodipodi:role="line"
          id="tspan4520"
-         x="549.39154"
+         x="545"
-         y="426.15408">Build Connection between Nodes</tspan></text>
+         y="424.40942">Build Connection between Nodes</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="549.39154"
+       x="545"
-       y="442.74155"
+       y="444.40942"
        id="text4522"><tspan
          sodipodi:role="line"
          id="tspan4524"
-         x="549.39154"
+         x="545"
-         y="442.74155">Temporary Connection between node</tspan></text>
+         y="444.40942">Temporary Connection between node</tspan></text>
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
@@ -1208,12 +1240,21 @@
     <text
        xml:space="preserve"
        style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial"
-       x="255"
+       x="290"
        y="109.40942"
        id="text4711"><tspan
          sodipodi:role="line"
          id="tspan4713"
-         x="255"
+         x="290"
          y="109.40942">Preprocessing</tspan></text>
+    <text
+       id="text3328"
+       y="464.40942"
+       x="545"
+       style="font-size:10px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;fill:#000000;fill-opacity:1;stroke:none;font-family:Arial;-inkscape-font-specification:Arial;text-anchor:start;text-align:start;writing-mode:lr;line-height:125%"
+       xml:space="preserve"
+       sodipodi:linespacing="125%"><tspan
+         sodipodi:role="line"
+         id="tspan3332">External Connection</tspan></text>
   </g>
 </svg>

doc/user/tutorials/DebianBuilding.txt

@@ -0,0 +1,198 @@
+building from source -- the Debian Way
+======================================
+:Author: Ichthyostega
+:Date: 3/2011
+
+When you're using a Debian-based system (e.g. Ubuntu), instead of compiling
+Lumiera from source in the classical (hard) way, you might prefer building
+from the Debian source package.
+
+Why -- what are the benefits?
+
+ * rely on the Debian/Ubuntu package manager for sorting out the library
+   and build dependencies
+ * install Lumiera as a first-class package, like all the other software
+   you're using regularily. This way, the package manager ``knows'' about
+   the library dependencies and can't mix up things due to a system upgrade.
+
+Under some circumstances, these very benefits might be a drawback, though.
+Sometimes you don't want to install; or you might have a version of Lumiera
+installed, but want to try out a (maybe newer / development) version...
+
+No problem -- basically it's always possible to run Lumiera _without installation._
+It is deliberately made such as to find its components actively, within the standard
+directory structure created by the buildsystem. While, thus, Lumiera can be just
+run directly from such a folder tree, the software still relies on some other
+libraries, which somehow need to be installed on your system.
+
+
+building from source package
+----------------------------
+Generally speaking, operations which _modify_ the installation/configuration of your
+linux system require root permissions. To the contrary, just _building_ a package 
+should _not_ be done as root.
+
+. add a suitable source line to your *Apt configuration* ('/etc/apt/sources.lst')
++
+----
+deb-src http://lumiera.org/debian/ lenny experimental
+----
+. get all the *build dependencies*
++
+----
+sudo apt-get build-dep nobug-dev
+sudo apt-get build-dep libgdl-lum-dev
+sudo apt-get build-dep lumiera
+----
+. *build* using the source package.
++
+----
+apt-get source --compile nobug-dev
+----
+
+  * After building went through without error, it might happen that you're be
+    prompted for signing with your GPG key. But because you're not going to upload
+    the created binary packages anywhere, this step can be considered optional.
+
+  * installing the created package.
++
+Finally, you'll find several new +*.deb+ packages in the directory where you started
+the build. You need to _install_ these packages then using the basic debian package
+manager 'dpkg'
++
+----
+sudo dpkg -i libnobug2_201008.1-1_i386.deb nobug-dev_201008.1-1_i386.deb
+----
++
+of course, the package names, versions and architecture will vary, depending on your
+situation.
+
+  * repeat those steps to work your way up to the +lumiera+ package; build and install
+    Nobug, maybe build and install libgdl-lum and finally build and install Lumiera
+
+. clean up.
++
+You can delete the source tree used for compiling. If you never intend to
+re-install the package, you could also delete the created package and source package
+components after installing it. But especially when trying out development versions
+it might be a good idea to file those packages somewhere, as we're not keeping _every_
+package in the online Lumiera debian depot. While every package could be reproduced
+exactly with a bit of Git knowledge, just keeping the +*.deb+ might be more convenient.
+
+
+Required and recommended Debian packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+What follows is a note about configuration for advanced users. You can safely skip and
+ignore this section if in doubt.
+
+The Debian package manager stores for each package not only the required prerequisites,
+but also some additional _recommended_ packages: Software likely to make using the given
+package more convenient or improve the usage in some way. In addition, it also stores
+a list of _suggested_ additional things to try. Now, since some time, the 'Apt' package
+management tool by default automatically installs also the _recommended_ software, not
+only the bare required prerequisites.
+
+While this is certainly fine for users not into the details of package management, it
+has the downside of installing sometimes _a lot_ of additional software no one asked
+about. Plus, all these installed packages are upgraded from time to time. An impressive
+example of this kind of _bloat_ is the *asciidoc* package, which recommends to install
+dockbook, an complete XML toolchain plus a TeX distribution, giving you an average of
+additional 500MB to download and install.
+
+Of course, this behaviour can be changed. Just add the following line to your Apt configuration
+----
+APT::Install-Recommends "false";
+----
+^_Disclaimer:_ please be sure you understand the consequences...^
+
+
+''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+What follows are some more in-depth explanations and background informations
+
+
+anatomy of a debian source package
+----------------------------------
+
+Debian source packages provide a standardised way of compiling software. These
+packages are not intended to be _installed_ on your system; rather you just download
+them and use them to build the software.
+
+Each Debian source package is based on an original _upstream_ tarball. In addition to
+this '\*.orig.tar.gz', there is a '\*.diff.gz' which contains all the _modifications_
+done to the original upstream sources in order to compile it with Debian. Especially,
+this so called ``debianisation patch'' adds a 'debian/' subdirectory to the source tree,
+which then holds all the control files used by Debian package management. Finally, the
+third part of each Debian source package is a _manifest_ file ('*.dsc'), which states
+that this is a Debian package and contains the primary control informations, the
+name and version number. Of course, these three files are named with a common name
+prefix, which matches the 'official' package name and version.
+
+Quite frequently, a given source package generates several binary packages, e.g. the
+main program, maybe a library and a documentation bundle. Because of this, often the
+source package is named slightly different then the binary package, which can be a
+problem sometimes. If in doubt, use the link:http://packages.debian.org[Debian package
+search] or the link:http://packages.ubuntu.com[equivalent for Ubuntu] to locate packages,
+versions, even individual files, or to get at the bug tracker for a package.
+
+interesting files in the debian subdirectory
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Most of the files in that subdirectory are relevant only for the people maintaining
+the package. With the exception of the following:
+
+- the 'debian/control' file defines the properties and *metadata* of the package. Here you'll
+  find the definition of the prerequisites, the name of the packager, the explanatory text.
+- the top entry in the 'debian/changelog' defines the *actual package name and version*
+- the actual build process is conducted by invoking several pre defined targets in the
+  'debian/rules' *makefile*. But modern debian packages often make use of the ``common
+  debian build system'' -- basically a set of macros allowing to write these 'rules'
+  in a very short and concise fashion
+
+
+commands for handling source packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+For all package building tasks, you can use an arbitrary directory of your choice.
+It is recommended to build with normal user permissions (not as root).
+
+- 'apt-get source' PACKAGENAME downloads the three parts of the source package. You may
+  use both the name of a binary or the source package in this command. After downloading,
+  the original tarball is extracted and the debianisation patch is applied. That is,
+  the tree is ready for building
+- 'apt-get source \--compile' PACKAGENAME does even more: it starts off the build
+  of a binary package after downloading and preparing the sources...
+- 'dpkg-source -x' SRCPACKAGE.dsc just extracts a source package and applies the diff
+- 'sudo apt-get buld-dep' PACKAGENAME fetches and installs all the prerequisites
+  necessary for building the denoted package. (however, it does _not_ download the
+  source package itself)
+- 'sudo dpkg -i' BIN-PACKAGE.deb finally installs the result of your building efforts.
+  Note, if several packages depend on each other, you need to give them all as list 
+  in a single command invocation.
+
+After having prepared the sources thusly, you need to step into the root of the
+source tree, if you want to build the whole package, or even want to tweak and
+modify parts.
+
+- 'dpkg-checkbuilddeps' checks that all the requirements of the package are satisfied.
+  It just prints out what is missing; this is especially useful if the fully automated
+  install did not work entirely, so you have to fix / reinstall parts manually
+- 'dpkg-buildpackage -rfakeroot' starts the full build. This includes re-generating
+  the source package (and especially the diff). If you only want to build the binary
+  package, you can skip the diff- / source-package generation with '-b'
+
+prerequisites for building
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+For performing any compiling and packaging tasks, you need some additional software,
+which by default isn't installed on a desktop system -- most notably the GNU C compiler.
+On any Debian based system, you get these basic tooling by
+----
+sudo apt-get install build-essential
+----
+
+library development packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+When building software linked against some library, we need additional 'header files'
+provided together with the library. Conventionally, these headers are packaged separately
+from the library and shipped as a package with a name like 'LIBNAME-dev'. You can safely
+__de__install these development packages when done with building.
+
+
+

doc/user/tutorials/building.txt

@@ -2,15 +2,26 @@ Building Lumiera from source
 ============================
 
 Currently, after building the application, you can try out the Lumiera GUI
-and you can run the test suite.
+and you can run the test suite. This tutorial details the basic procedure
+to compile Lumiera on a Linux (or comparable) system. We'll assume that
+the reader has acquired basic _commandline survival skills_ and is able
+to figure out the usage of the Git version management system from the
+documentation (but we'll mention each actually required command
+explicitly)
 
-For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will
+NOTE: just compiling Lumieara on a _Debian-based_ system (e.g. Ubuntu)
-need:
+      is much simpler using the Debian source package. See the separate
+      link:DebianBuilding.html[tutorial page] for this (or the general
+      link:/debian/[instructions for installing on Debian/Ubuntu]).
+      The purpose of this tutorial here is to show you the elementary
+      and generic steps to compile Lumiera from source.
 
- * http://git-scm.com/[git]
+For building Lumiera, besides the GNU C/C++ compiler (Version 4.X), you will need:
- * http://www.gnu.org/software/libtool/[libtool]
+
- * http://www.boost.org/[Boost libraries]
+ * link:http://git-scm.com/[Git VCS]
- * http://gmerlin.sourceforge.net/[GAVL library]
+ * link:http://www.scons.org/[SCons build system]
+ * link:http://www.boost.org/[Boost libraries]
+ * link:http://gmerlin.sourceforge.net/[GAVL library]
  * *NoBug* (see below)
 
 The GUI depends on:
@@ -22,17 +33,17 @@ TIP: Generally speaking, when you want to build software, you need the
 _development_ version of the packages, containing the headers and pre-built
 libraries to link against. Usually, these packages are named `-devel` or `-dev`
 
-For most Debian based systems, e.g. Ubuntu, you can install these dependencies
+For Debian based systems, e.g. Ubuntu, you can install these dependencies with:
-with:
 
-------------------------------------------------------------
+-------------------------------------------------------------------------------------
-sudo apt-get install build-essential autoconf git-core libboost-dev \
+sudo apt-get install build-essential autoconf scons valgrind libtool git-core \
-libboost-program-options-dev libboost-regex-dev libgavl-dev libgdl-1-dev \
+libboost-dev libboost-program-options-dev libboost-regex-dev libboost-filesystem-dev \
-libgtkmm-2.4-dev librsvg2-dev libtool libxv-dev scons valgrind
+libgavl-dev libgdl-1-dev libgtkmm-2.4-dev librsvg2-dev libxv-dev
-------------------------------------------------------------
+-------------------------------------------------------------------------------------
 
 Optionally, you may also want to install the *gtk2-engines* package.
 
+
 Build directory
 ---------------
 
@@ -85,8 +96,9 @@ Installing GDL
 
 The *GNOME Docking library* is generally available through your package manager,
 but we contributed some improvements, which are only available in the very
-recent development versions of GDL. Thus, for now we created a special package,
+recent development versions of GDL. If your distribution provides a GDL >= 2.27,
-which doesn't interfere with an existing (older) installation of GDL.
+you're fine. Otherwise we've created a special package, which doesn't interfere
+with an existing (older) installation of GDL.
 
 Ubuntu 9.04 note::
   intltool-update is not patched, you must add +/usr/share/intltool-debian/+
@@ -121,7 +133,7 @@ variable.
 Either way, check that all libraries are accessible and OK:
 
 ------------------------------------------------------------
-sudo ldconfig -v | grep 'gdl-lum\|nobug'
+sudo ldconfig -v | grep 'nobug'
 ------------------------------------------------------------
 
 and you should get a list of the libraries, part of which should look like this:
@@ -132,7 +144,9 @@ and you should get a list of the libraries, part of which should look like this:
         libgdl-lum.so.0 -> /usr/local/lib/libgdl-lum.so.0.0.0
 ------------------------------------------------------------
 
-or similar. If any if this libs are not listed, investigate why before continuing. 
+or similar. The same holds true for 'libgdl-lum.so.0' if you needed to build it
+explicitly for your system. If any if these libraries are not listed,
+investigate why before continuing. 
 
 
 Building Lumiera
@@ -175,20 +189,14 @@ maybe build and run the test suite by issuing `scons check` or `make check`
 
 This will take some time.
 
-NOTE: you can not _install_ Lumiera currently. Do not try it, it will not work.
+NOTE: you do not need to _install_ Lumiera. It will find its required files
-Just run it from the build directory.
+relative to the generated directory structure, which is freely relocatable
+as a whole. Just invoke the +target/lumiera+ executable. The current
+working directory is not relevant.
 
 After the build has finished successfully, you should be able to start Lumiera.
 Currently, this will bring up the GUI, without any further functionality
 
- * for autotools build: issue `./lumiera` (from within the `build` subdirectory)
- * for scons build:
-+
--------------------
-cd bin
-./lumiera
--------------------
-
 You should see something like:
 
 image:{l}/images/lumiera_gui_small.png[Current Lumiera GUI Screenshot]

doc/user/tutorials/index.txt

@@ -1,7 +1,10 @@
 Tutorials
 =========
 
+//Menu: sort children
+
 This page contains tutorials for beginners interested in Lumiera development.
 
  * link:building.html[Building Lumiera from source]
+ * link:DebianBuilding.html[Building from Debian source package]
  * link:contributing.html[Contributing to Lumiera]