[nongnu] elpa/treeview d8b8b4a533 02/25: First version of README.md

[ELPA Syncer]

branch: elpa/treeview
commit d8b8b4a53332162b447d9b949de2045bfb5f254c
Author: tilmanrassy <49377318+tilmanrassy@users.noreply.github.com>
Commit: GitHub <noreply@github.com>

    First version of README.md
---
 README.md | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 88 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 97e09ddfc7..e6ecd23a35 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,89 @@
 # emacs-treeview
-Abstract Emacs Lisp framework for tree navigation
+Abstract Emacs Lisp framework for tree navigation. Based on this framework, 
specific libraries for particular
+hierarchical data can be implemented, for example, file systems.
+
+A typical tree could look like the following:
+
+<pre>
+   [+] Node 1
+   [-] Node 2
+    |    [+] Node 21
+    |    [+] Node 22
+    |    [-] Node 23
+    |     |    [+] Node 231
+    |     |      Leaf 231
+    |     |      Leaf 232
+    |     |      Leaf 233
+    |    [+] Node 24
+   [+] Node 3
+   [+] Node 4
+</pre>
+
+Each node has a "label".  Non-leaf nodes also have a "control".  The label is 
the text by which the node is represented.  The control is a clickable piece of 
text  in front of the label which allows the user to fold or unfold the node.  
Nodes without children usually don't have a control.  Nodes can also have an 
icon, but this is optional.  Icons are implemented as symbols in an icon font. 
Control, icon, and label are always displayed in this order. It is assumed that 
each node occupies  [...]
+
+Nodes are represented by lists of the form:
+
+<pre>
+  (NAME PROPS PARENT CHILDREN)
+</pre>
+
+where the elements have the following meaning:
+
+  *  `NAME`     &nbsp;&ndash;&nbsp;  The name of the node.  A string.
+  *  `PROPS`    &nbsp;&ndash;&nbsp;  The properties of the node.  A plist.  
See below for details.
+  *  `PARENT`   &nbsp;&ndash;&nbsp;  The parent of the node.  Another 
node-representing list.
+  *  `CHILDREN` &nbsp;&ndash;&nbsp;  The children of the node.  List of 
node-representing lists.
+
+Node properties are implemented as plists with Lisp symbols as keys.  The 
following
+properties exist:
+
+  *  `:label-overlay`    &nbsp;&ndash;&nbsp; The overlay containing the node 
label
+  *  `:control-overlay`  &nbsp;&ndash;&nbsp; The overlay containing the node 
control
+  *  `:icon-overlay`     &nbsp;&ndash;&nbsp; The overlay containing the node 
icon
+  *  `:start`            &nbsp;&ndash;&nbsp; A marker at the position where 
the node begins
+  *  `:end`              &nbsp;&ndash;&nbsp; A marker at the position where 
the node ends
+  *  `:state`            &nbsp;&ndash;&nbsp; The state of the node.  See below 
for details
+
+Node states: Each node is in exactly one of three states, which are 
represented by the
+following Lisp symbols:
+
+  *  `folded-unread`  &nbsp;&ndash;&nbsp;  The node is folded and has not been 
unfolded before
+  *  `folded-read`    &nbsp;&ndash;&nbsp;  The node is folded, but has been 
unfolded before
+  *  `expanded`       &nbsp;&ndash;&nbsp;  The node is expanded
+
+Initially, a node is in the state 'folded-unread'.  If it gets expanded for 
the first time,
+the state changes to 'expanded'.  If it gets folded again, the state changes 
to 'folded-read'.
+From then, the state toggles between 'expanded' and 'folded-read' each time 
the node is
+expanded or folded.
+
+The framework declares a couple of "abstract" functions in the sense of 
function variables, i.e.,
+variables whose values are function symbols. If the framework is applied for a 
particular purpose,
+specific implementations for these functions must be provided.  Here is a list 
of that function
+variables:
+
+  *  treeview-node-leaf-p-function
+  *  treeview-update-node-children-function
+  *  treeview-get-indent-function
+  *  treeview-get-control-function
+  *  treeview-get-control-margin-left-function
+  *  treeview-get-control-margin-right-function
+  *  treeview-get-icon-function
+  *  treeview-get-icon-margin-left-function
+  *  treeview-get-icon-margin-right-function
+  *  treeview-get-label-function
+  *  treeview-get-label-margin-left-function
+  *  treeview-get-control-keymap-function
+  *  treeview-get-control-face-function
+  *  treeview-get-control-mouse-face-function
+  *  treeview-get-label-keymap-function
+  *  treeview-get-label-face-function
+  *  treeview-get-label-mouse-face-function
+  *  treeview-get-icon-keymap-function
+  *  treeview-get-icon-face-function
+  *  treeview-get-icon-mouse-face-function
+  *  treeview-suggest-point-pos-in-control-function
+
+A description of each variable can be found in the repsetive documentation 
strings.  All
+variables are buffer-local.  Libraries using this framework should create a 
new buffer and
+set the variables to particular functions in that buffer. Then, the root node 
should be
+created and rendered in the buffer by a call to treeview-display-node.