diff --git a/admin/scons/LumieraEnvironment.py b/admin/scons/LumieraEnvironment.py
index d50b4db04..11dc15b5a 100644
--- a/admin/scons/LumieraEnvironment.py
+++ b/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)
diff --git a/admin/scons/Setup.py b/admin/scons/Setup.py
index 84ef3fd71..af2cfae53 100644
--- a/admin/scons/Setup.py
+++ b/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
diff --git a/doc/SConscript b/doc/SConscript
index 537b9b137..e0abc0ebb 100644
--- a/doc/SConscript
+++ b/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')
diff --git a/doc/devel/LumieraHelpLandingPage.NOTICE b/doc/devel/LumieraHelpLandingPage.NOTICE
new file mode 100644
index 000000000..6a4525d7b
--- /dev/null
+++ b/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)
diff --git a/doc/devel/LumieraHelpLandingPage.html b/doc/devel/LumieraHelpLandingPage.html
new file mode 100644
index 000000000..fa19103df
--- /dev/null
+++ b/doc/devel/LumieraHelpLandingPage.html
@@ -0,0 +1,699 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+Lumiera User Manual
+
+
+
+
Lumiera
+
The new emerging NLE for GNU/Linux
+
+
+
+
+
+
+
+
+
Lumiera User Manual
+
+
+
+
+
+
+
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.
+
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.
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.
The ▶play / ⏸pause / ⏹stop buttons will activate some video output demo code,
+which is actually quite old — it was extracted 2009 from the 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
+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 #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.
+
+
+
+
+
+
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. And there are various known problems related to those docks…
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/doc/user/manual.txt b/doc/user/manual.txt
index d5952352a..ef02b532f 100644
--- a/doc/user/manual.txt
+++ b/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...#