add better output functionality to stdio, use stderr

revise HACKING to say so, and describe the database

1 files changed, 97 insertions, 2 deletions

diff --git a/HACKING b/HACKING
index 062814a..eb7b34f 100644
--- a/HACKING
+++ b/HACKING
@@ -5,6 +5,12 @@
 	            in commit 2 before commit 1
 //////////////////////////////////////////////////////////////////////
 
+   I know this file is long* and boring.  I try to keep it preened and
+   informative, but would rather spend my time actually hacking. If
+   you think you can help this file, have at it! ~ Luke Shumaker
+   
+   * at 200+ lines, it's longer than any rvs source file
+
                               hacking
 
    There are two main parts to rvs, the wrapper, and the core.  The
@@ -13,6 +19,7 @@
    executables that do all the real work.
 
   build system
+   (be sure to read the `configuration' section of `README' first)
 
    The build system rvs uses is rather simple.
    `./configure' does two things:
@@ -78,7 +85,7 @@
 
    As you probably noticed (if you've looked at the blueprints or
    source files), only directories and regular files have been
-   implemented as of rvs 0.6.1.
+   implemented as of rvs 0.6.2.
    
    After `rvs commit' has done this, it creates a meta-file for that
    commit.  The meta file contains author, copyright owner, licence
@@ -92,7 +99,8 @@
    functions in the propper locations.
 
      Any commit function should take a  filename   as an argument and
-     output the according commit id to stdout.
+     output the according commit id to stdout.  stderr should be used
+     for all messages.
 
      Any  get   function should take the commit id as an argument and
      uses stdout only if verbose, or to report errors.
@@ -106,6 +114,93 @@
     3. one can use any language to write new modules, without
        having to worry about bindings
 
+  $$libdir$$/lib/
+
+   I have created two 'libraries' for use by rvs components.  They
+   provide several functions that can be accessed by shell script by 
+   using the code:
+   	source "`rvs -d`/lib/stdio"
+   or
+   	source "`rvs -d`/lib/rvsdb"
+   (`rvs -d' returns $$libdir$$)
+   stdio provides several functions for printing messages:
+   	verbose MESSAGE
+   	   print MESSAGE to stdout only if $verbose is set to '-v'
+   	out MESSAGE
+   	   print MESSAGE to stdout if $verbose isn't set to '-q'
+   	warn MESSAGE
+   	   print "rvs: MESSAGE" to stderr
+   	error MESSAGE
+   	   print "rvs: MESSAGE" and a quick message about `rvs --help'
+   	   (hinting at user error) to stderr, then exit with error
+   	fatal MESSAGE
+   	   For internal error. Print "rvs: MESSAGE" to stderr and exit
+   	   with error
+   	version
+   	   print the version information and exit with success
+   
+   rvsdb provides several functions and variables for dealing with the
+   rvs database:
+   	$repo
+   	   the directory of the database (./.rvs)
+   	getid FILE
+   	   returns what the id of a given file would be if it were in
+   	   the database.  This is used to know where to put files when
+   	   commiting them.  In 0.6.[0-2] this is just the sha1sum of
+   	   the file
+   	NOTE: the "log*" functions aren't very stable or developed
+   	loginit FILE
+   	   initialize an rvs log at FILE.  These logs are used for
+   	   metafiles, directory listings, and (probably) eventually
+   	   checkout logs
+   	lograw LOG
+   	   prepare LOG for reading, and write the output to stdout (to
+   	   pipe into another function).  This is mostly for internal
+   	   use by rvsdb
+   	logread LOG VAR
+   	   read variable VAR from the logfile LOG
+   	logwrite LOG VAR VAL
+   	   set variable VAR to VAL in the logfile LOG
+   	logfind LOG VAL
+   	   return all the names of variables in logfile LOG who have
+   	   the value VAL
+
+  the database (.rvs/*)
+
+   So, what are all these files doing in in the database? The scheme
+   is fairly simple. In the `.rvs' directory there are 2 directories,
+   the `files' directory, and the `tmp' directory. `tmp' is what it
+   sounds like, a place for rvs compnents to keep temporary files.
+   The wrapper sets TMPDIR, so you can create a unique file in there
+   with:
+   	FILENAME=`tempfile`
+   The `files' directory is where all the data is kept.
+   
+   When any file is commited, whether it be a regular file, a
+   directory, a link, or any other type of file, 2 file are created in
+   `.rvs/files', the "raw-file" and the "meta-file". When we speek of
+   file IDs, we mean the filename of the corresponding file in
+   `.rvs/files' in rvs 0.5.8-0.6.2 this is just the sha1sum of the
+   file. The meta-file stores everything not part of the file itself;
+   the filename, file-type, author, copyright owner, file permissions,
+   timestamps, etc, and the ID of the corresponding raw-file. In the
+   case of an regular file, the raw-file contains the file itself. For
+   directories, it contains pointers to each file inside the
+   directory.
+   
+   $$libdir$$/commit calls $$libdir$$/commit.FILETYPE to generate the
+   raw-file, but generates the meta-file itself (in `.rvs/tmp', then
+   calls commit.f to commit the meta-file).  It then returns the ID
+   of the meta-file.  Therefore, the user never deals with the IDs of
+   raw-files, and doesn't need to.  The metafiles contain pointers to
+   the corresponding raw-files.
+   
+   To keep things modular, commit.f is the ONLY thing that should
+   actually put files in `.rvs/files', and get.f the only thing that
+   should get them. Everything else should call them.
+
+  final thoughts
+
    I have set up bazaar repository at Launchpad:
    	https://launchpad.net/rvs
    Only until rvs becomes self-hosting.