Build: provide a placeholder page for the (planned) User-Manual

Debian-Docbase allows to register some HTML documentation;
My old package definition added placeholder config, which renders
the documentation configuration invalid (as pointed out by Lintian).
However, I still think it is a good idea to have the anchor point
already defined, and thus I came up with the idea of in fact
providing some usable placeholder content...

As it turns out, we also have a placeholder page at the Lumiera website,
where the User Manual is assumed to be located later — so why not extend
this one and then provide the HTML-rendering for the DEB package?

To allow for this setup
 * I have now extended the placeholder page for the Website
   to include some generic description about Lumiera (from the 'about' page)
 * Furthermore, I added the screenshot (from the »Outer Space« page)
 * and I use this a an opportunity to document the various test / demo
   facilities currently available in the GUI, since these are rather obscure.
   While only intended for the developer, it seems still worthwhile
   to describe the possible effects — it may well be that we retain
   some of that test/demo functionality and in that case, we have
   now already some starting point for a documentation

 * Then, to include that page as stand-alone HTML, I used the 'Print Edit WE'-plugin
   from Firefox, to encode the images as inline-base64 URLs (which are restored
   by a tiny JavaScript embedded into that page)

 * and last but not least, our SCons buildsystem needs the ability
   to install such a documentation file, since it seems most adequate
   to handle this requirement as part of the generic installation (and
   not hidden in some Debian scripting)

admin/scons/LumieraEnvironment.py

@@ -62,7 +62,7 @@ class LumieraEnvironment(Environment):
                 self.mergeConf(self.libInfo[other])
         else:
             self.Append (LIBS = other.get ('LIBS',[]))
-            self.Append (LIBPATH = other.get ('LIBPATH', []))
+            self.Append (LIBPATH = other.get('LIBPATH', []))
             self.Append (CPPPATH = other.get('CPPPATH', []))
             self.Append (LINKFLAGS = other.get('LINKFLAGS', []))
         
@@ -165,9 +165,11 @@ def register_LumieraResourceBuilder(env):
     
     def ConfigData(env, prefix, source, targetDir=None):
         """ install (copy) configuration- and metadata.
-            target dir is either the install location configured (in SConstruct),
-            or an explicitly given absolute or relative path segment, which might refer
-            to the location of the executable through the $ORIGIN token
+            @param targetDir: when None, then use he install location configured (in SConstruct),
+                otherwise an explicitly given absolute or relative path segment,
+                which might refer to the location of the executable through the $ORIGIN token
+            @param prefix: a prefix relative to the current path (location of SConscript),
+                i.e. typically a subdirectory where to find the source config file
         """
         source = path.join(prefix,str(source))
         subdir = getDirname(source, prefix)  # removes source location path prefix
@@ -188,6 +190,26 @@ def register_LumieraResourceBuilder(env):
         env.Install (toInstall, source)
         return env.Install(toBuild, source)
     
+    def DocFile(env, prefix, source, target=None):
+        """ install (copy) files for documentation.
+            Always places the documentation below the standard location 'installDoc' configured in Setup.py
+            @param prefix: relative to current path (SConscript), will be stripped at destination
+            @param target: when given, the target will be named explicitly, or (when only a directory)
+                placed into a specific subdir, otherwise (when None) the source spec will be placed
+                into the corresponding subdir after stripping the prefix
+        """
+        source = path.join(prefix,str(source))
+        subdir = getDirname(source, prefix)  # removes source location path prefix
+        if not target:
+            target = subdir+'/'
+        elif target.endswith('/'):
+            target = target+subdir+'/'
+        toInstall = path.join(env.path.installDoc, target)
+        if toInstall.endswith('/'):
+            return env.Install(toInstall, source)
+        else:
+            return env.InstallAs(toInstall, source) # this renames at target
+    
     
     buildIcon = env.Builder( action = Action(invokeRenderer, "rendering Icon: $SOURCE --> $TARGETS")
                            , single_source = True
@@ -197,6 +219,7 @@ def register_LumieraResourceBuilder(env):
     env.AddMethod(IconResource)
     env.AddMethod(GuiResource)
     env.AddMethod(ConfigData)
+    env.AddMethod(DocFile)
 
 
 

admin/scons/Setup.py

@@ -40,6 +40,7 @@ installPlug  = '#$DESTDIR/lib/lumiera/modules'
 installIcon  = '#$DESTDIR/share/lumiera/icons'
 installUIRes = '#$DESTDIR/share/lumiera/'
 installConf  = '#$DESTDIR/lib/lumiera/config'
+installDoc   = '#$DESTDIR/share/doc/lumiera/'
 
 #-------------------------------------------------------Configuration
 

doc/SConscript

@@ -8,9 +8,10 @@ Import('env')
 
 
 doxydoc = env.Doxygen('devel/Doxyfile')
+env.Clean(doxydoc, doxydoc + ['devel/,doxylog','devel/doxygen-warnings.txt'])
 
-#  env.Install(dir = '$DESTDIR/share/doc/lumiera$VERSION/devel', source=documentation)
-env.Clean (doxydoc, doxydoc + ['devel/,doxylog','devel/doxygen-warnings.txt'])
+# HTML-documentation: this is a *placeholder* (eventually we'll build a user manual via Asciidoc)
+env.DocFile('devel', 'LumieraHelpLandingPage.html', 'manual-html/index.html')
 
 
 Export('doxydoc')

doc/devel/LumieraHelpLandingPage.NOTICE

@@ -0,0 +1,16 @@
+NOTE: this is a placeholder -- the intention is to build a user Manual via Asciidoc
+
+As of 2025, Lumiera is not usable, and thus only a placeholder HTML page is provided
+for the DEB-Package. The content on this page is identical to the "User-Manual" page:
+https://Lumiera.org/documentation/user/manual.html
+
+For the delivery
+- this page has been rendered with Asciidoc
+- the resulting HTML has been processed with the "Print Edit WE" plugin of Firefox,
+  which inlines any resources (CSS, images)
+
+This page will be installed by the Lumiera SCons build into $prefix/share/doc/lumiera
+(see doc/SConsscript)
+
+Hint: for updates, re-render the Asciidoc and then use git/diff to combine the
+      new or changed content with the embedded inline images (base64 data)

doc/user/manual.txt

@@ -1,8 +1,93 @@
 Lumiera User Manual
 ===================
 
-The plan is to create the users manual later in a collaborative
-fashion, which was effective for Cinelerra.
+.There is no »User Manual« -- yet
+The plan is to create the manual and tutorials later in a collaborative way. +
+This work is postponed until the software is actually usable.
 
-This work is postponed until the software is actually working.
+.What is »Lumiera«?
+Lumiera is a Free/Open Source project to build a Non-Linear Video Editing (NLE)
+and compositing application for GNU/Linux.
+Its primary focus is professional editing, quality, usability and flexibility.
+On the one hand, it must meet the rigours of a professional
+film and video production environment; on the other hand, it must
+be flexible enough to satisfy the needs of more modest single-user
+equipment.
 
+These ambitious goals have led us to a complex and flexible internal structure,
+over the course of the last years. Many elements still need to be connected and
+integrated, so that the functionality becomes visible and can be explored by users.
+And we are a small team. Nevertheless, please be assured that work on the project is ongoing.
+
+- Look at the https://git.lumiera.org/[Git repositories] to see current activity
+- Visit the http://Lumiera.org/documentation/user/intro/intro.html[»Lumiera from Outer Space«]
+  page at the https://Lumiera.org[Lumiera.org] website to read more about the Design and Vision.
+
+
+UI Experiments
+--------------
+While most of the work is focused at the inner workings of the Render Engine
+(as of Nov.2025), the User Interface has been upgraded to GTK-3 and outfitted with
+some experimental connection channels, to test interplay with the application core.
+
+After launching the `lumiera` application, a main window will be displayed.
+
+image:{imgg}/lumiera20250823.png["Lumiera GTK UI / Screenshot 2025-08",width=650, link="{imgg}/lumiera20250823.png"]
+
+
+Video Output
+~~~~~~~~~~~~
+The [green]#▶#_play_ / [blue]#⏸#_pause_ / [red]#⏹#_stop_ buttons will activate some video output demo code,
+which is actually quite old -- it was extracted 2009 from the https://en.wikipedia.org/wiki/Kino_(software)[Kino]
+video editing software and used for various experiments since then. In its current shape,
+this dummy playback ensures that Lumiera is properly built and linked to use the
+https://en.wikipedia.org/wiki/X_video_extension[XVideo] standard with the help of the X11 XServer.
+This _archaic_ standard from 1991 presumably was the first widely available and vendor-neutral interface
+for passing raw video frames to the GPU, which then scales and integrates them into the desktop display.
+
+The video frames for this demo _are not generated by the Lumiera Render Engine_ -- and
+thus this code is largely obsolete; maybe it will continue to live somewhere as a fallback
+for systems without proper support of OpenGL?
+
+The UI-Bus
+~~~~~~~~~~
+Instead of accessing a shared data model, the Lumiera UI is connected to the core
+through an _asynchronous messaging channel,_ to dispatch command instructions into the
+session and to push responses up into the UI. There is a demo to verify this setup
+by pushing info and error messages into the »Info Box«
+
+- In the ``Help'' menu, there is the entry `Help > Self Tests'
+- The tab https://issues.lumiera.org/ticket/1099[#1099] in this non-modal dialog box
+  allows to push notification messages into the UI-Bus...
+   
+  * enter some text into the input widget at the top
+  * send a display message with this text at Info / Warn / or Error level
+  * or push the ``mark'' button to send a `mark` message, selected from the
+    drop-down
+
+Timeline Display
+~~~~~~~~~~~~~~~~
+The second tab in this ``Test and Diagnostics'' dialog box (`Help > Self Tests')
+allows to _Populate the Timeline Display_ with a structure corresponding to session content.
+This structure is sent over the UI-Bus as a ``Diff Message'' -- basically the core can notify
+the UI about changes in structured content elements, which both sides know, without ever sharing
+a common data representation.
+
+This demo engages this mechanism to _populate_ an previously empty Timeline with structured content;
+the actual content is hard-wired for this test, offering two flavours (``Sequence 1'' and ``Sequence 2'').
+
+Sequence 1::
+  A single Track, with two Clips, which can be clicked and dragged; they have a fixed given length,
+  but no further content.
+
+Sequence 2::
+  A complex arrangement of nested tracks, some of which are expanded, and some have overview rulers.
+  Note that it is possible to scroll vertically, while the top-level overview rulers remain always
+  visible and pinned on top. Note furthermore that the _Track-Head display_ in the left pane scrolles
+  alongside, and remains in sync with the main content pane. Tracks can not yet be expanded / collapsed
+
+The Button ``move elements'' is part of an ongoing experiment and currently disabled.
+
+NOTE: the panes can be undocked and re-arranged, but retain their identity, so that
+      they can be addressed via UI-Bus without knowing where they are actually located
+      in the UI. [red]#And there are various known problems related to those docks...#