expand documentation #21

svg_rendering/page/js-gen/README.md

@@ -37,31 +37,41 @@ The rendering library relies on a proprietary text markup format. This can be ge
 
 ### Standoff annotation handling 
 
-`adhoc-tree.js` Build a tree from the standoff annotations from `text-annotaion.js`  
-
 `text-annotation.js` Parse standoff markup
 
+`adhoc-tree.js` Build a tree from the standoff annotations generated by `text-annotaion.js`  
+
 `text-index.js` Standoff annotation index for fast lookup
 
 ### Layout
 
 
-`transcript.js` Abstract transcript layout classes
+`transcript.js` Abstract transcript layout classes. These classes provide an interface and general functionality for
+the layout process. This consists most importantly of a hierarchy of 'ViewComponent' classes. These classes need to be 
+augmented by an implementation for a specific graphical output system or 'terminal' which could be e.g. SVG or HTML+CSS.
+At the moment, the only implementation uses SVG, see `transcript-svg.js`
+
+`transcript-svg.js` Augment the abstract classes in `transcript.js` to do the layout with an SVG 'terminal' 
 
 `transcript-adhoc-tree.js` Initialize layout objects from document tree
 
-`transcript-configuration-faust.js` Configure parameters for transcript layout
+`transcript-configuration-faust.js` Configure parameters for transcript layout. Most importantly, 
+'Faust.TranscriptConfiguration.names' provides a set of handler functions that get called when an element 'name' is 
+traversed and which construct and return a 'ViewComponent' element
 
 `transcript-generation.js` Entry point for transcript generation
 
-`transcript-svg.js` Augment the abstract classes in `transcript.js` to do the layout with an SVG 'terminal' 
 
 ## Overview of the layout process
 
 1. Annotated 'Text' object is initiated from an XML file
 2. 'AdhocTree' element is constructed from 'Text' object for easier traversal, and to provide a tree interface for the
-   older layout code that originally operated on a multi-tree model
+   layout code that originally operated on a multi-tree model
 3. A tree of 'ViewComponent' objects is constructed from the 'AdhocTree' object. At the same time, the SVG frontend to
    the 'ViewComponent' will construct an SVG that resembles (but not one-to-one) the 'ViewComponent' tree
 4. The layout process is run iteratively, walking the 'ViewComponent' tree and adjusting the position and size of the 
-   various ViewComponents (and their SVG representations) until the layout converges
+   various ViewComponents (and their SVG representations) until the layout converges to a stable state. 'ViewComponent's
+   are positioned with the help of their 'FaustTranscript.Align' objects, which specify a relative position to another
+   VC (typically the parent or preceding sibling). For example, a typical line of text is positioned right below its 
+   preceding sibling line. In each iteration of the layout process, all Aligns of all traversed VCs are executed once,
+   and after a number of iterations the layout should not change anymore.