[gegl] docs: update gcut page

[Øyvind Kolås <ok src gnome org>]

commit 5e1433a1d8bd1aa54b81b7e6d7b77a7c666ac9fc
Author: Øyvind Kolås <pippin gimp org>
Date:   Mon Aug 14 14:18:21 2017 +0200

    docs: update gcut page

 docs/gcut.txt |  141 ++++++++++++++++++++++++++++-----------------------------
 1 files changed, 70 insertions(+), 71 deletions(-)
---
diff --git a/docs/gcut.txt b/docs/gcut.txt
index 3cd52bf..ba4047f 100644
--- a/docs/gcut.txt
+++ b/docs/gcut.txt
@@ -1,16 +1,19 @@
-# gcut
+gcut
+====
 
-## a GEGL video editing system
+GEGL video editing system
+-------------------------
 
-gcut is a video editing engine for GEGL. It permits re-arranging bits of video
-with clean cuts and crossfades, as well as applying filtering chains to
-individual clips or as global filters on top of the edited video. At the moment
-gcut is primarily a data-model and file format, it can be used to
-programatically generate video that are then rendered. There is also an
+gcut is a video editing engine for link:http://gegl.org/[GEGL]. It permits
+re-arranging bits of video with clean cuts and crossfades, as well as applying
+filtering chains to individual clips or as global filters on top of the edited
+video. At the moment gcut is primarily a data-model and file format, it can be
+used to programatically generate video that are then rendered. There is also an
 experimental user interface that can be used to augment and at some point
 replace understanding gcuts text file syntax.
 
-### Features
+Features
+--------
 
  - single-track editing, with cross fades
  - keeps source audio when editing
@@ -27,22 +30,11 @@ replace understanding gcuts text file syntax.
 now)
  - timestamped auto-save
 
-### Screenshots
+See [gcut.h](https://git.gnome.org/browse/gegl/tree/gcut/gcut.h) for more
+up-to-date current plans/todos/fixme.
 
-The basic view, with the F1 keyboard shortcut help overlaid over the video.
-
-![screenshot](http://pippin.gimp.org/gedl/gedl-help.png)
-
-In this screenshot, showing the purely synthetic used gegl operations default
-project of gcut. Showing visualization of keyframed parameters and permit
-setting them through sliders. Slanted clip transitions indicates cross-fades.
-Note that the current UI is the first attempt at a direct mapping of the file
-format.
-
-![screenshot](http://pippin.gimp.org/gedl/gedl2.png)
-
-
-### Example output
+Example output
+--------------
 
 The GEGL video from Libre Graphics Meeting 2016 in London,
 https://www.youtube.com/watch?v=GJJPgLGrSgc was made from raw footage using
@@ -52,21 +44,31 @@ video with newer render):
 https://www.youtube.com/watch?v=n91QbTMawuc
 
 
-### Development plans
+Graphical User Interface
+------------------------
 
-The UI is written using microraptor gui, which means that things that can be
-done with simple HTML+CSS or drawn using cairo when programming can be made
-interactive in the local coordiantes drawn with for callbacks.
+The UI is written using microraptor gui, using lightweight CSS styling for text
+and cairo for drawing the interface direct from data structures.
 
-Elements acting on top of the single-track timeline, possibly covering all the
-timeline or just some clips. For filtering/replacing/overlaying video/audio.
-This working similar to annotations/comments, that float with clips as
-preceding clips in the timeline change duration / position. This should expand
-the possible feature scope to video picture in picture, global color / mood
-adjustments - audio bleeping, mixing in music - and probably more.
+The current UI is the minimal amount of UI needed for keyboard centered editing
+with some mouse based scrubbing and positioning. The available keyboard actions
+are different for the first and last frames of a clip compared with the
+mid-clip frames, when jumping between clips with up/down arrows, one jumps
+between the first frames of clips. The filter editing UI is not yet fully usful
+for more than visualizing data created in a text-editor on the project file.
+
+The basic view, with the F1 keyboard shortcut help overlaid over the video.
+
+image::http://pippin.gimp.org/gedl/gedl-help.png[gcut with help]
+
+In this screenshot, showing the purely synthetic used gegl operations default
+project of gcut. Showing visualization of keyframed parameters and permit
+setting them through sliders. Slanted clip transitions indicates cross-fades.
+Note that the current UI is the first attempt at a direct mapping of the file
+format.
+
+image::http://pippin.gimp.org/gedl/gedl2.png[more complex ui]
 
-See [gcut.h](https://github.com/hodefoting/gedl/blob/master/gcut.h) for more
-up-to date plans and documentation of at least some of the known issues.
 
 The amount of code, written in C is about equally divided 50/50 between the
 core rendering logic in C and the UI, both about 3000 lines. All the actual
@@ -81,24 +83,17 @@ associated audio - with playback and seeking oriented caching mechanisms. It
 could be possible to add alternatives to these operations using for instance
 gstreamer, and the rest of gcut would remain unchanged.
 
-It is planned to rewrite the UI part from C to lua, even if even this C ui is
-very young, it will however use the same toolkit, cairo and microraptor gui,
-aiming for shorter interaction cycles during development and less fragile code
-and opening up for easier outside contributions, as well as learning from
-mistakes and short comings in the UI prototype proof of concept written in C,
-with mrg and cairo, anything that can be drawn can be made interactive, thus at
-least editing animation curves could be made a lot more visual and interactive.
+It is planned to, eventually, rewrite the UI part from C to lua, even if even
+this C ui is very young, it will however use the same toolkit, cairo and
+microraptor gui, aiming for shorter interaction cycles during development and
+less fragile code and opening up for easier outside contributions, as well as
+learning from mistakes and short comings in the UI prototype proof of concept
+written in C, with mrg and cairo, anything that can be drawn can be made
+interactive, thus at least editing animation curves could be made a lot more
+visual and interactive.
 
-### UI hints
-
-The current UI is the minimal amount of UI needed for keyboard centered editing
-with some mouse based scrubbing and positioning. The available keyboard actions
-are different for the first and last frames of a clip compared with the
-mid-clip frames, when jumping between clips with up/down arrows, one jumps
-between the first frames of clips.
-
-
-### File format
+File format
+-----------
 
 An example gcut edl file is as follows:
 
@@ -148,7 +143,7 @@ One can for instance write:
 
     A.mp4 200 341 -- gaussian-blur std-dev-x=0.1rel std-dev-y=0.1rel gegl:threshold value=0.3
 
-To threshold the clip, this feature can be used for using arbitrary GEGL
+To blur and threshold A.mp4, this feature can be used for using arbitrary GEGL
 pipelines with interpolated parameters as filters on a video clip. The suffix
 rel used in the gaussian blur is dependant on the height of the video - this
 permits the pipeline to be used for proxies as well as for full size video.
@@ -166,24 +161,28 @@ would insert a chain of invert-gamma from 10.5s until 20s. These entries need
 to be placed at the beginning of the file. (later, these filters will inherit
 the position of the insertion cursor of the timeline.)
 
-### caching architecture
+caching architecture
+--------------------
 
-The core of gcuts architecture is the data storage model, the text file that
-the user sees as a project file contains - together with the referenced source
-assets, the complete description of how to generate a video for a sequence.
+The data storage model is central to gcuts architecture the user sees as a
+project file contains the complete description of how to generate a video for a
+sequence from source assets. The rest of objects used during processing can be
+regenerated deterministically under the same hashed file names.
 
 This file is broken down into a set of global assignments of key/values, and
-lines describing clips with path, in/out point and associated GEGL filter
-stacks.
+lines describing clips with path - and filter overlays, with in/out points and
+optional associated GEGL filter stacks.
 
-GEDL keeps cached data in the .gcut subdir in the same directory as the loaded
-GEDL project file, All the projects in a folder share the same .cache
+gcut keeps cached data in the .gcut subdir in the same directory as the loaded
+gcut project file, All the projects in a folder share the same .cache
 directory. The cache data is separated in subdirs for ease of development and
 debugging.
 
 **.gcut/cache/**   contains the rendered frames - stored in files that are a hash
 of a string containing , source clip/frame no and filter chain at given frame.
-Thus making returns to previous settings reuse previous values.
+Thus making returns to previous settings reuse previous values. This folder can
+be removed but all cached frames are lost - gcut should have a feature to
+remove all non-cached frames.
 
 **.gcut/history/**  contains undo snapshots of files being edited (backups from
 frequent auto-save)
@@ -192,19 +191,19 @@ frequent auto-save)
 
 **.gcut/thumb/**  contains thumb tracks for video clips - thumb tracks are images
 to show in the clips in the timeline, the thumb tracks are created using
-iconographer from the proxy videos - from original would be possible, but take
-longer than creating proxy videos.
+iconographer from the proxy videos.
 
 when the UI is running the following threads and processes exist:
 
-    gcut project.edl   mrg ui thread (cairo + gtk/raw fb)
-                       GEGL renderer/evaluation thread
+**gcut project.edl**  mrg ui thread (cairo + gtk/raw fb) GEGL renderer/evaluation thread
+
+**gcut project.edl cache 0 4**  background frame cache renderer processes
+
+**gcut project.edl cache 1 4**  if frameno % 4 == 1 then this one considers
+
+**gcut project.edl cache 2 4**  it its responsibility to render frameno, the
 
-    gcut project.edl cache 0 4  background frame cache renderer processes
-    gcut project.edl cache 1 4  if frameno % 4 == 1 then this one considers
-    gcut project.edl cache 2 4  it its responsibility to render frameno, the
-    gcut project.edl cache 3 4  count of such processes is set to the number of
-                                cores/processors available.
+**gcut project.edl cache 3 4**  count of such processes is set to the number of cores/processors available.
 
 The background renderer processes are stopped when playback is initiated, as
 well as every 60 seconds, when a new set of caches (restarts to handle both