update documentation

admin/rfc.sh

@@ -358,7 +358,7 @@ create)
           -f "./doc/devel/rfc_dropped/${name}.txt" ]]; then
         echo "$name.txt exists already"
     else
-        source ./doc/devel/template_rfc.sh >"./doc/devel/rfc_pending/${name}.txt"
+        source ./doc/devel/template/new_rfc.sh >"./doc/devel/rfc_pending/${name}.txt"
         edit "./doc/devel/rfc_pending/${name}.txt" 2 abstract
         git add "./doc/devel/rfc_pending/${name}.txt"
         process "./doc/devel/rfc_pending/${name}.txt"

doc/devel/rfc_pending/VersionNumberScheme.txt

@@ -0,0 +1,160 @@
+VersionNumberScheme
+===================
+
+// please don't remove the //word: comments
+
+[grid="all"]
+`------------`-----------------------
+*State*         _Idea_
+*Date*          _Mi 09 Mär 2011 02:00:41 CET_
+*Proposed by*   Ichthyostega <prg@ichthyostega.de>
+-------------------------------------
+
+[abstract]
+********************************************************************************
+Define and use a version numbering scheme for all releases, including the
+development releases. Use the rules of the debian policy as a guideline.
+********************************************************************************
+
+Description
+-----------
+//description: add a detailed description:
+
+It should be clear right from start how version numbers are to be generated.
+This numbering scheme should include a pattern for development builds. The
+Debian policy defines a nice algorithm for ordering extended version numbers,
+which could be used as a guideline. The sequence of version numbers should
+be monotonous increasing according to this ordering.
+
+Version number sequence
+~~~~~~~~~~~~~~~~~~~~~~~
+....
+0.pre.## < 0.01~dev.20YYMMDDhhmm < 0.01 < 0.99 < 1.0~dev.20YYMMDDhhmm < 1.0 < 1.0.1 
+....
+
+Specifications
+~~~~~~~~~~~~~~
+A *tagged build* is made whenever there is a feature change tangible for users.
+This might just be a *dev release*. Contrary to this, a *published release* is
+a build expected to be installed and used by the users. Amongst the published
+releases, we distinguish *major* and *minor* and *bugfix* releases.
+
+- before we reach _alpha_ status, we don't create any real releases, just
+  tagged preview builds from time to time. The criteria for reaching alpha
+  status are defined on the roadmap.
+
+- during _alpha_ and _beta_ status, we don't differentiate our releases;
+  they are just numbered consecutively with 2 digits (to start with). A
+  release is made whenever there is something significant new or otherwise
+  interesting to try out for the users.
+
+- besides the releases, we create *development snapshot releases*, which
+  are just _tagged builds_.
+  
+  * Not every build/check-in gets promoted to such a tagged build;
+    rather there needs to be any reason from the users point of view,
+    e.g. a bugfix we expect to be tried out at least by _someone_.
+  
+  * these _development snapshots_ are an _anticipation_ of the
+    upcoming next release and thus get a numbering _derived_ from this
+    _next_ release (not the previous one).
+  
+  * dev snapshots use a _timestamp_ attached with a '~' (tilde char).
+    It is common practice to order a tilde _below_ the release it is
+    attached to (and debian follows this practice)
+
+- when we decide the application to be stable enough for real use and
+  past the _beta_ phase, we switch over to the usual 3-digit version numbering.
+  
+  * _major_ releases start with 1.0 and feature high impact changes, usually linked
+    to some significant breakage of compatibility or some other disruptive event.
+  
+  * _minor_ releases may include some new features, but can be considered
+    evolutionary. Their numbers are incremented on the second digit, like
+    1.1, 1.2, 1.3, 1.4, ....
+  
+  * _bugfix_ releases are created when we have serious bugfixes to publish,
+    without any real new features.
+
+- similar to the practice established in pre-1.0, we can create series of
+  development snapshots working against and anticipating the next major/minor
+  release. We'll do so for those users interested in following the development
+  more closely. The version numbers for such anticipating snapshots are again
+  created by attaching a timestamp with a '~' (tilde char).
+
+
+Tasks
+~~~~~
+// List what needs to be done to implement this Proposal:
+ * a debian packaging has been created ([green]#✔#)
+ * the first version was tagged [,yellow]#0.pre.01#
+
+
+Discussion
+~~~~~~~~~~
+
+Pros
+^^^^
+// add a fact list/enumeration which make this suitable:
+ * the format of the version numbers classifies the kind of build
+ * the changes in the scheme where chosen to reflect the changed
+   dynamics in pre-alpha, beta and post-1.0
+ * the anticipating snapshots fit better into the usual habits of
+   developers: the moment a release is published, it is outdated
+   and uninteresting.
+ * this practice with the anticipating snapshots was popularised
+   in by Apache Maven and works well in practice
+
+
+Cons
+^^^^
+// fact list of the known/considered bad implications:
+
+ * this visioning scheme might look overengineered at first sight
+
+
+Alternatives
+^^^^^^^^^^^^
+//alternatives: explain alternatives and tell why they are not viable:
+
+_don't worry -- be happy_ is what developers usually do with version numbering.
+Especially _not caring_ for development snapshots might be viable for commercial
+products; but users of open source software frequently follow the development
+rather directly; thus it's a good idea to have a clear numbering for these
+dev snapshots too.
+
+Alternatively we might consider to use Git SHA-Hashes for the dev builds.
+But unfortunately, these are rather long and not very mnemonic. We're better
+off just adding them to the changelog (as recommended by Debian policy anyway)
+
+
+Rationale
+---------
+//rationale: Give a concise summary why it should be done *this* way:
+
+Many projects face a lot of confusion and bad reputation when they ``happen to run into''
+more widely published releases without any forethought. Users tend to be confused quickly
+and can't be expected to understand the details of the development process. Thus we should
+discuss and set up a unambiguous numbering scheme really early -- including the criteria
+when to use what version number.
+
+
+
+//Conclusion
+//----------
+//conclusion: When approbate (this proposal becomes a Final)
+//            write some conclusions about its process:
+
+
+
+
+Comments
+--------
+//comments: append below
+
+
+//endof_comments:
+
+''''
+Back to link:/documentation/devel/rfc.html[Lumiera Design Process overview]
+

doc/devel/template/DIR_INFO

@@ -0,0 +1 @@
+skeletons for formal documents

doc/devel/template/YYYY-MM-DD-developerMeetingSummary.txt

@@ -0,0 +1,69 @@
+2012-12-12 Lumiera Developers Meeting
+=====================================
+:Author: Everyone Else
+:Date: 2012-12-12
+
+Dec 11, 2012 on #lumiera 20:00 - 23:23 UTC +
+
+__Participants__
+
+ * cehteh
+ * ichthyo
+ * ...
+ 
+_Protocol written by XXXXX_
+
+
+
+Recurring Topics
+----------------
+Discussion of open http://www.pipapo.org/pipawiki/Lumiera/DesignProcess[design process] drafts.
+
+
+Prop1
+~~~~~
+link:/documentation/devel/rfc_pending/SomeProposal[descriptive name]
+Summary what issues are discussed
+..Details..
+
+Conclusion:: drop it
+
+
+
+Topic 1
+-------
+Summary what is discussed
+
+_cehteh_ points out that...
+
+_joelholdsworth_ adds....
+
+
+Conclusion
+~~~~~~~~~~
+
+ * do this
+ * do that
+
+
+
+Next meeting
+------------
+
+The next meeting will be at Wednesday XX XX 20:00 UTC
+
+
+''''
+
+
+.-- Discussion of details --
+[caption="☉Transcript☉ "]
+----------------------------
+12:51 cehteh key/value pairs
+12:51 gmerlin not sure about that
+12:51 cehteh i am pretty sure that i want that in lumiera
+
+( shortened and tidied transcript of some interesting detailed discussions )
+----------------------------
+
+

doc/technical/index.txt

@@ -1,10 +1,16 @@
 Technical Documentation
 =======================
 
+// Menu :  prepend child backend
+// Menu :  prepend child proc
+// Menu :  prepend child gui
+// Menu :  prepend child howto
+// Menu :  prepend child overview
+
 
 This documentation section contains technical documentation about Lumiera. To
-get an overview of all the internals and components, you might want to read
+get an *overview* of all the internals and components, you might want to read
-link:innerCore/the_inner_core.html[Lumiera the Inner Core]
+link:overview.html[Lumiera the Inner Core]
 
 == Three Layers
 

doc/technical/infra/index.txt

@@ -6,8 +6,8 @@ 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]
+ * see link:../build/index.html[separate page for the Buildsystem]
- * generating the link::MenuGen.html[navigation menu] for the website
+ * generating the link:MenuGen.html[navigation menu] for the website
 
 
 

doc/technical/innerCore/DIR_INFO

@@ -1,3 +0,0 @@
-Internal Design Overview
-
-Some rather sketchy document about design decisions and rationales

doc/technical/overview.txt

@@ -1,12 +1,13 @@
 Lumiera: The Inner Core
 =======================
 
+
 [abstract]
 ******************************************************************************
-The Lumiera Developers have a vision about a modern core for a NLE. Here are
+The Lumiera Developers have a distinct vision about the core of a modern NLE. 
-some of the design decisions and rationales in a rather sketchy way explained.
+This document outlines some of the basic technical concepts and highlights
-New Developers may find this Document useful to get an idea about how the
+the fundamental design decisions. New Developers may find this Document useful
-different components work together.
+to get an idea about how the different components work together.
 ******************************************************************************
 
 

doc/user/index.txt

@@ -1,8 +1,11 @@
 User Documentation
 ==================
 
+// Menu :  prepend child intro
+// Menu :  attach child 'manual' after 'intro'
+
  * 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:intro/intro.html[Lumiera (as seen) from Outer Space]
- * link:outerSpace/Glossary.html[Glossary of common terms]
+ * link:intro/Glossary.html[Glossary of common terms]
 

doc/user/intro/intro.txt

@@ -1,6 +1,7 @@
 Lumiera (as seen) from Outer Space
 ==================================
-Christian Thäter <ct@pipapo.org>
+:Author: Christian Thäter ct@pipapo.org
+:Date: Summer 2010
 
 
 [abstract]

doc/user/tutorials/building.txt

@@ -77,7 +77,7 @@ mkdir build
 cd build
 ../configure
 make
-make install
+sudo make install
 ------------------------------------------------------------
 
 Installing GDL
@@ -88,8 +88,11 @@ 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,
 which doesn't interfere with an existing (older) installation of GDL.
 
-Ubuntu 9.04 note: intltool-update is not patched, you must add
+Ubuntu 9.04 note::
-/usr/share/intltool-debian/ to get the gdl-package to configure correctly (JSC).
+  intltool-update is not patched, you must add +/usr/share/intltool-debian/+
+  to get the gdl-package to configure correctly (JSC).
+Ubuntu 10.10 note::
+  you need to install the +intltool+ package from the standard ubuntu repository
 
 ------------------------------------------------------------
 git clone git://git.lumiera.org/gdl-package
@@ -135,14 +138,11 @@ or similar. If any if this libs are not listed, investigate why before continuin
 Building Lumiera
 ----------------
 
-Lumiera has two maintained (and equivalent) build systems: *scons* and
+Up to now, Lumiera has had two maintained (and equivalent) build systems: *scons* and
-*autotools*. You can pick the one you feel more comfortable with.
+*autotools*. (Note 3/2011: Right now, the autotools build is broken. It is always a good
-
+idea to check the current build stats from our *builddrone*, which automatically builds
-When trying to build a development version of Lumiera, it might well be that at
+the latest version from master repository. Please have a look at this
-times one of the builds doesn't work temporarily. It is always a good idea to
+http://lumiera.org/builddrone/table.html[current build stats]-page.)
-check the current build stats from our *builddrone*, which automatically builds
-the latest version from master repository. + Please have a look at this
-http://lumiera.org/builddrone/table.html[current build stats]-page.
 
 Next, after having built and installed the prerequisite libraries, go into the
 _workspace directory_ to retrieve the Lumiera source code and build it.
@@ -159,7 +159,7 @@ scons
 -----------------
 +
    
- * alternatively, if you prefer building with *autotools*:
+ * alternatively, if you prefer building with *autotools* _(not working currently 3/11)_:
 +
 -----------------
 git clone git://git.lumiera.org/LUMIERA
@@ -192,3 +192,12 @@ cd bin
 You should see something like (screenshot from 1/2009):
 
 image:/media/img/design.gui/screenshot090124-resources.jpg[]
+
+
+What's next?
+------------
+If you're a coder, maybe you've found something to improve...? +
+Contributing to Lumiera is made easy, thanks to *Git*
+
+-> Tutorial link:contributing.html[Contributing to Lumiera coding]
+

doc/user/tutorials/contributing.txt

@@ -1,20 +1,27 @@
 Contributing to Lumiera
 =======================
 
-Nothing is easier, follow the
+The Lumiera project uses an infrastructure based on *Git*, the distibuted
-http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[the basic
+sourcecode management software. This deliberately places the barrier for
-instructions], notably the following parts:
+contributing very low: No formal ``commit right'' is necessary; you can
+start right away and present your first results in the _mob repository_.
+
+For starters, follow the
+http://www.kernel.org/pub/software/scm/git/docs/gittutorial.html[basic
+instructions] for using Git, notably the following parts:
 
 ------------------------------------------------------------
 $ git config --global user.name "Your Name Comes Here"
 $ git config --global user.email you@yourdomain.example.com
 ------------------------------------------------------------
 
-Then you are ready to go, you can edit and commit the lumiera code locally in
+If you followed the link:building.html[building-lumiera tutorial], you created
-your cloned repository. Please do small commits which fix/improve only one
+already a local clone of the Lumiera repository. So you are ready to go,
-single thing and use meaningful commit messages.
+you can edit build and commit your changes to the lumiera code locally in
+your cloned repository. Please commit frequently, do small commits which
+fix/improve only one single thing and use meaningful commit messages.
 
-Check that you didn't break anything, by running the testsuite (see above)
+Check that you didn't break anything, by running the testsuite.
 
 Finally you can push your changes to the lumiera server to the 'mob' repository:
 
@@ -24,3 +31,5 @@ $ git push git://git.lumiera.org/lumiera/mob master:refs/heads/YOURNAME
 
 This creates a new branch 'YOURNAME' on the mob repository. Then you notify the
 other devs on the mailinglist and they may merge your code into the mainline.
+
+