heavily revise/copy-edit READEME/HACKING/TODO...

1 files changed, 112 insertions, 4 deletions

diff --git a/HACKING b/HACKING
index ea18feb..6fb4597 100644
--- a/HACKING
+++ b/HACKING
@@ -1,8 +1,116 @@
-check docs/README.xhtml for info.  It's a quick edit of the readme for
-the older rvs-0.5.10, but most of it is still valid.
+//////////////////////////////////////////////////////////////////////
+                               rvs 0.6.1
+	retroactive versioning system
+	          a versioning system that allows you to check
+	            in commit 2 before commit 1
+//////////////////////////////////////////////////////////////////////
 
-I'll write a real HACKING file later.
+                              hacking
+
+   There are two main parts to rvs, the wrapper, and the core.  The
+   wrapper is a small executable, located in the PATH, and is the one
+   called when you type `rvs'.  The core is a set of many small
+   executables that do all the real work.
+
+  build system
+
+   The build system rvs uses is rather simple.
+   `./configure' does two things:
+   	* create a preprocessor (`tmp/var.sed')
+   	* run `Makefile.orig' through the preprocessor to generate a
+   	  propper `Makefile'
+   Then, the Makefile runs each file in `source/' through the
+   preprocessor, and writes the resulting files to `out/'.
+
+   preprocessor
+
+    The preprocessor contains all configuration variables.  When it
+    processes a file every instance of `$$VAR_NAME$$' is replaced by
+    that variable's value. Note that this replacement only happens for
+    defined variables.
+
+  configuration Variables
+
+   Again the configuration variables and their default values are:
+   	VER   	'0.6.1'
+   	SHELL 	'/usr/bin/env bash'
+   	prefix	"$HOME"
+   	bindir	'bin'
+   	libdir	'/etc/rvs/'
+
+   The wrapper is installed at `$$prefix$$/$$bindir$$/rvs'
+   The  core   is installed at `$$libdir$$/'
+   The source for the wrapper is in `source/rvs'
+   The source for the  core   is in `source/rvs-core/'
+
+    $$SHELL$$ is the shell all shell scripts that are part of rvs are
+    run in.  As of rvs 0.6.1 all executables are shell scripts. 
+
+   Most of these can easily be changed _after_ compilation also:
+   	VER  	line 4 of the wrapper
+   	SHELL	line 1 each shell script
+   	prefix	simply move the wrapper
+   	bindir	simply move the wrapper
+   	libdir	move the core, then update the line `RVSDIR=...' in
+   	      	the wrapper
+   
+   I have designed this system to be extremely modular. As you may
+   have figured out, each bit on functionality is in it's own
+   executable, and the file you call when you type `rvs' is just a
+   wrapper for them.
+
+----------------------------------------------------------------------
+----- The rest is copy/pasted, and still needs to be copy-edited.-----
+----------------------------------------------------------------------
+
+   commit actually does take a parameter. It can commit any file or
+   directory. It works as it does because if no file is given, it
+   defaults to ./. If it is given a directory (as it is by
+   default), it loops through each file in the directory and
+   commits them (by calling itself). In order to actually commit a
+   file or directory it calls rvs commit.type where type is the
+   standard unix file-type code:
+
+   block       (buffered) special b 
+   character (unbuffered) special c 
+   directory                      d 
+   named pipe (FIFO)              p 
+   regular file                   f 
+   symbolic link                  l 
+   socket                         s 
+   door (Solaris only)            D 
+
+   As you probably noticed, only directories and regular files have
+   been implemented in this release. get works in much the same
+   way. If you implement any other file types, save the commit and
+   get functions accordingly, and uncomment the line in
+   source/rvs-corecommit. Any commit function takes a filename as
+   an argument and outputs the according commit id to stdout. Any
+   get function takes the commit id as an argument and uses stdout
+   only if verbose, or to report errors. So the modules communicate
+   via pipes, which is generally considered bad-design, and
+   libraries should be used. I deliberatly broke this because this
+   way:
+
+    1. incompatible licences can be used for different modules
+    2. modules can be added/removed on the fly
+    3. one can use any lanugage to write new modules, without
+       having to worry about bindings
+
+  known bugs
+
+	* borks on files with the newline character. The smart thing
+	  to do would be to escape all speacial characters.
+	  Files to be changed:
+	  	* source/rvs-core/commit
+	  	* source/rvs-core/commit.d
+	  	* source/rvs-core/get.d
+
+   I have set up bazaar repository at Launchpad:
+   	https://launchpad.net/rvs
+   Only until rvs becomes self-hosting.
+
+   If anyone needs any help, let me know.
 
 ~ Luke Shumaker <LukeShu@sbcglobal.net>
 Happy Hacking!
-