Update README and doc/HACKING, also mention bash completion

Signed-off-by: Jan Pokorný <jpokorny@redhat.com>

1 files changed, 39 insertions, 5 deletions

diff --git a/doc/HACKING b/doc/HACKING
index 2fb6142..804a6c2 100644
--- a/doc/HACKING
+++ b/doc/HACKING
@@ -1,3 +1,42 @@
+High-level Concepts
+-------------------
+
+There are a few concepts that tries to unify effective conversion
+recipes in a relatively loosely coupled way and with clear
+relationships:
+
+  . command is a composition of one or more filters (see below)
+    with some level of flexibility (tee-like splits, etc.)
+
+  . filter is an isolated set of steps from object _A_ of a format _X_
+    (see below) and having the respective internal representation _x_
+    to the same or modified object _A'_ of a format _Y_ and having
+    the respective internal representation _y_ (possibly _X_=_Y_
+    and/or _x_=_y_, whereas string representation is frequented)
+
+  . format is something having possibly many more-or-less interchangeable
+    representations (string, parsed XML/ElementTree, ...), whereas
+    the possible format transitions depend on the available filters;
+    note that the format alone does not fully specify/restrict the set
+    of values/properties of objects being held as these are further
+    refined by previously used uni-format filters (context of
+    previous transitions plays the role)
+
+  . protocol denotes a form of internal representation interchange
+    (either internal in the filters' chain or user-requested IO),
+    with these special kinds:
+    - 'native' denotes most natural/economic form of dealing with
+      (the instance of) given data format, e.g., XML -> parsed tree
+    - 'composite' denotes multi-channel interchange format
+      (consisting of atomic ones)
+
+
+Low-level Terms
+---------------
+
+tuplist		tuple or list (also see utils.py)
+
+
 Notable points
 --------------
 
@@ -22,11 +61,6 @@ Notable points
 [1] http://code.google.com/p/lh-vim/
 [2] http://fedorapeople.org/cgit/jpokorny/public_git/vim4projects.git
 
-Terms
------
-
-tuplist		tuple or list (also see utils.py)
-
 
 Common problems run into (just for self-reference)
 --------------------------------------------------