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

4 files changed, 211 insertions, 190 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!
-
diff --git a/README b/README
index 790d9f6..4349f61 100644
--- a/README
+++ b/README
@@ -1,70 +1,96 @@
 //////////////////////////////////////////////////////////////////////
-	rvs - retroactive versioning system
-	                  versioning system that allows you to check
-	                  in commit 2 before commit 1
+                               rvs 0.6.1
+	retroactive versioning system
+	          a versioning system that allows you to check
+	            in commit 2 before commit 1
 //////////////////////////////////////////////////////////////////////
 
-CONTENTS:
-	1 ) Introduction
-	2 ) Building
-	2.1 ) configuration
+introduction
 
-//////////////////////////////////////////////////////////////////////
-== 1: Introduction
-The name is a little bit of a nod to RCS (revision control system),
-and even less to CVS.  I'm not particularly fond of CVS, but recognize
-it's impact on the scm scene.
-
-rvs is about being able to go back and edit *anything* that has
-already been committed.  Yes, some other SCMs do this, but fuck things
-proper if someone else has a copy of the old version.
-
-Why would you want to do this?  Take for example the Bazaar repository
-rvs is hosted on: It starts at 0.6.0, what if I later want to import
-0.0.0 - 0.5.10?  Or if I'm trying to construct a history of BSD,
-and import all the BSDs I can find, such as 1,3,4, then latter find 2?
-
-== 2: Building
-rvs doesn't exactly use the GNU build system, but acts much like it
-does. To build rvs with default configuration, simply run:
-	$ ./configure
-	$ make
-	# make install
-It's generally considered good practice to build in another directory
-than the source directory.  This is not nescessary in rvs , all the
-created file are put in another directory anyway.  If you would still
-like to do this, it can be done in rvs-0.6.1 and up.
-
-=== 2.1: Configuration
-There are several configuration variables that can be set. The default
-values are kept in the file `Variables'.
-
-Variables is in the format `VAR_NAME<tab>VALUE'.  You can modify these
-configuration variables by editing the `Variables' file directly, or
-by running ./configure such as:
-	$ ./configure --VAR_NAME=VALUE
-
-The different configuration variables are as follows:
-VER	value='0.6.0'
-	rvs's internal varsion number
-SHELL	value='/usr/bin/env bash'
-	the shell that scripts will be run in.
-prefix	value="$HOME"
-	where the files will be installed.  For me the defualt is
-	`/home/luke'.  Many of you will want to change this to '/usr'
-bindir	value='bin'
-	the binaries folder inside the prefix.  If I leave the prefix
-	and bindir the same, for me rvs is installed in
-	`/home/luke/bin'.  If I change prefix to '/usr', then rvs will
-	be installed in `/usr/bin'
-libdir	value='/etc/rvs/'
-	where the rvs libraries will be installed.
-	in rvs almost nothing is actually done int the core binary
-	([$prefix]/[$bindir]/rvs) but option handling.  All the real
-	work is done in modular sub-programs.  I call them libraries,
-	even though they are independend programs that communicate via
-	pipes.
+   The name is a little bit of a nod to RCS (revision control
+   system), and even less to CVS. I'm not particularly fond of CVS,
+   but recognize it's impact on the scm scene.
+
+   rvs is about being able to go back and edit *anything* that has
+   already been committed. Yes, some other SCMs do this, but fuck
+   things proper if someone else has a copy of the old version.
+
+   Why would you want to do this? Take for example the Bazaar
+   repository rvs is hosted on: It starts at 0.6.0, what if I later
+   want to import 0.0.0 - 0.5.10? Or if I'm trying to construct a
+   history of BSD, and import all the BSDs I can find, such as
+   1,3,4, then latter find 2?
+
+system requirements
+
+   Pretty much any *nix system should be able to run rvs. If you
+   need to use a shell other than GNU bash, run ./configure with
+   the --SHELL=YOUR_SHELL option. rvs is not designed for Windows,
+   but should be able to run in bash if you have some *nix pack
+   installed.
+
+   To my knowledge, this is the absolute requirements (all need to
+   be in your PATH):
+     * GNU bash
+     * cat      (included in GNU Core Utils)
+     * cp       (included in GNU Core Utils)
+     * cut      (included in GNU Core Utils)
+     * echo     (included in GNU Core Utils)
+     * mkdir    (included in GNU Core Utils)
+     * rm       (included in GNU Core Utils)
+     * sed      (included in GNU Core Utils)
+     * sha1sum  (included in GNU Core Utils)
+     * tempfile (included in GNU Core Utils)
+     * tr       (included in GNU Core Utils)
+
+building
+
+   rvs doesn't exactly use the GNU build system, but acts much like
+   it does. To build rvs with default configuration, simply run:
+   	$ ./configure
+   	$ make
+   	# make install
+
+   It's generally considered good practice to build in another
+   directory than the source directory. This is not nescessary in
+   rvs , all the created file are put in another directory anyway.
+   If you would still like to do this, it can be done in rvs-0.6.1
+   and up.
+
+  Configuration
+
+   There are several configuration variables that can be set. The
+   default values are kept in the file `Variables'.
+
+   Variables is in the format `VAR_NAME<tab>VALUE'. You can modify
+   these configuration variables by editing the `Variables' file
+   directly, or by running ./configure such as:
+   	$ ./configure --VAR_NAME=VALUE
+
+   The different configuration variables are as follows:
+   VER   	value='0.6.0'
+   	rvs's internal varsion number
+   SHELL 	value='/usr/bin/env bash'
+   	the shell that scripts will be run in.
+   prefix	value="$HOME"
+   	where the files will be installed. For me the defualt is
+   	`/home/luke'. Many of you will want to change this to '/usr'
+   bindir	value='bin'
+   	the binaries folder inside the prefix. If I leave the prefix
+   	and bindir the same, for me rvs is installed in
+   	`/home/luke/bin'. If I change prefix to '/usr', then rvs will
+   	be installed in `/usr/bin'
+   libdir	value='/etc/rvs/'
+   	where the rvs libraries will be installed. In rvs almost
+   	nothing is actually done in the execurable you call when you
+   	type `rvs' ([$prefix]/[$bindir]/rvs) but option handling. All
+   	the real work is done in modular sub-programs. I call them
+   	libraries, even though they are independend programs that
+   	communicate via pipes.  Note that they probably should NOT be
+   	located in your PATH.
 
 ~ Luke Shumaker <LukeShu@sbcglobal.net>
 Happy Hacking!
+([$prefix]/[$bindir]/rvs) but option handling.
+
 
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..a8a1d78
--- /dev/null
+++ b/TODO
@@ -0,0 +1,11 @@
+* implement other unix file types (see the HACKING file)
+* add real option handling (code from another project is
+  provided in source/rvs)
+* write real documentation
+* implment a parent/child tree
+  	* implement branch ids (NOTE: wch should be used to refer
+  	  to the latest commit in a branch)
+* implement tags
+* owner/filepermissions/timestamps
+* usernames/author
+
diff --git a/docs/README.xhtml b/docs/README.xhtml
deleted file mode 100644
index ec8aedf..0000000
--- a/docs/README.xhtml
+++ /dev/null
@@ -1,124 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE html 
-	PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
-<head>
-	<title>rvs 0.6.0</title>
-	<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
-</head>
-
-<body>
-<h1>rvs 0.6.0</h1>
-<p>rvs is a basic versioning system I've been writing. If you don't know what that means, it isn't for you (at least not at this stage in development).</p>
-
-<h2>installation</h2><li><kbd>soruce/rvs-core/commit</kbd></li>
-<p>see <a href="../README"><kbd>README</kbd></a> file</p>
-
-<ul>
-	<li><kbd>source/rvs-corecommit</kbd></li>
-	<li><kbd>source/rvs-corecommit.d</kbd></li>
-	<li><kbd>source/rvs-corecommit.f</kbd></li>
-	<li><kbd>source/rvs-coreget</kbd></li>
-	<li><kbd>source/rvs-coreget.d</kbd></li>
-	<li><kbd>source/rvs-coreget.f</kbd></li>
-	<li><kbd>source/rvs-coreinit</kbd></li>
-	<li><kbd>source/rvs-corelib/rvsdb</kbd></li>
-	<li><kbd>source/rvs-corelib/stdio</kbd></li>
-	<li><kbd>source/rvs</kbd></li>
-</ul>
-
-<h2>system requirements</h2>
-<p>Pretty much any *nix system should be able to run rvs, provided it has bash, and bash is installed at <kbd>/bin/bash</kbd> (e.g.: <a href="http:/www.freebsd.org/">FreeBSD</a> has it at <kbd>source/bash</kbd>, so you should set up a symlink). rvs is not designed for Windows, but should be able to run in bash if you have some *nix pack installed.</p>
-<p>To my knowledge, this is the absolute requirements (all need to be in your PATH):</p>
-<ul>
-	<li><a href="http:/www.gnu.org/software/bash/">GNU bash</a></li>
-	<li>cat      (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>cp       (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>cut      (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>echo     (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>mkdir    (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>rm       (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>sed      (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>sha1sum  (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>tempfile (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-	<li>tr       (included in <a href="http:/www.gnu.org/software/coreutils/">GNU Core Utils</a>)</li>
-</ul>
-
-<h2>usage</h2>
-<dl>
-	<dt>create repository in the current directory</dt>
-		<dd><kbd>rvs init</kbd></dd>
-	<dt>check in the current directory</dt>
-		<dd><kbd>rvs commit</kbd> This will return a commit id. You need this to check the revision back out.</dd>
-	<dt>check out to the current directory</dt>
-		<dd><kbd>rvs get <var>ID</var></kbd> This checks out commit <var>ID</var></dd>
-</dl>
-
-<h2>hacking</h2>
-<p>Again, here is a list of all files when you check out</p>
-<ul>
-	<li><kbd>source/rvs-corecommit</kbd></li>
-	<li><kbd>source/rvs-corecommit.d</kbd></li>
-	<li><kbd>source/rvs-corecommit.f</kbd></li>
-	<li><kbd>source/rvs-coreget</kbd></li>
-	<li><kbd>source/rvs-coreget.d</kbd></li>
-	<li><kbd>source/rvs-coreget.f</kbd></li>
-	<li><kbd>source/rvs-coreinit</kbd></li>
-	<li><kbd>source/rvs-corelib/rvsdb</kbd></li>
-	<li><kbd>source/rvs-corelib/stdio</kbd></li>
-	<li><kbd>source/rvs</kbd></li>
-</ul>
-<p>These are all shell scripts and may be modified directly. I have designed this system to be extremely modular. As you may have figured out, each bit on functionality is in it's own script, and <kbd>source/rvs</kbd> is just a wrapper for them. If you wish to move the directory with the sub-modules after it has been compiled (see variables), all you have to do is update the variablle <code><var>RVSDIR</var></code> towards the beginning of <kbd>source/rvs</kbd>.</p>
-<p><kbd>commit</kbd> 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 <kbd>./</kbd>. 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 <code>rvs commit.<var>type</var></code> where <var>type</var> is the standard unix file-type code:</p>
-
-<table>
-	<tr><td><pre><em>b</em>lock       (buffered) special</pre></td><td>b</td></tr>
-	<tr><td><pre><em>c</em>haracter (unbuffered) special</pre></td><td>c</td></tr>
-	<tr><td><pre><em>d</em>irectory                     </pre></td><td>d</td></tr>
-	<tr><td><pre>named <em>p</em>ipe (FIFO)             </pre></td><td>p</td></tr>
-	<tr><td><pre>regular <em>f</em>ile                  </pre></td><td>f</td></tr>
-	<tr><td><pre>symbolic <em>l</em>ink                 </pre></td><td>l</td></tr>
-	<tr><td><pre><em>s</em>ocket                        </pre></td><td>s</td></tr>
-	<tr><td><pre><em>d</em>oor (Solaris only)           </pre></td><td>D</td></tr>
-</table>
-<p>As you probably noticed, only directories and regular files have been implemented in this release. <kbd>get</kbd> 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 <kbd>source/rvs-corecommit</kbd>. 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:</p>
-<ol>
-	<li>incompatible licences can be used for different modules</li>
-	<li>modules can be added/removed on the fly</li>
-	<li>one can use any lanugage to write new modules, without having to worry about bindings</li>
-</ol>
-<h3>build system</h3>
-<p>The build system rvs uses is rather simple. <kbd>./configure</kbd> does 2 things, create a preprocessor in <kbd>tmp/var.sed</kbd>, and generate a <kbd>Makefile</kbd> with this preprocessor from <a href="../Makefile.orig"><kbd>Makefile.orig</kbd></a>. Then, the <kbd>Makefile</kbd> (among other things), runs each source file through the preprocessor.</p>
-<h4>preprocessor/variables</h4>
-<p>You know the configuration variables described in <a href="../README"><kbd>README</kbd></a>? Part of the build process involves running all source files through a pre-processor (kept in <kbd>tmp/var.sed</kbd>). This preproccessor allows you to reference the configuration variables in any file in <kbd>source/</kbd> or <a href="../Makefile"><kbd>Makefile</kbd></a>. Any instance of <samp>$$VAR_NAME$$</samp> will be repleced by the value of the variable. Note that only defined variables will be replaced.</p>
-<h3>known bugs</h3>
-<ul>
-	<li>borks on files with the newline character. The smart thing to do would be to escape all speacial characters.
-		<br />Files to be changed:<ul>
-			<li><kbd>source/rvs-core/commit</kbd></li>
-			<li><kbd>source/rvs-core/commit.d</kbd></li>
-			<li><kbd>source/rvs-core/get.d</kbd></li>
-		</ul>
-	</li>
-</ul>
-<h3>TODO</h3>
-<ul>
-	<li>implment other unix file types (see above)</li>
-	<li>add real option handling (code from another project is provided in <kbd>source/rvs</kbd>)</li>
-	<li>write real documentation</li>
-	<li>implment a parent/child tree<ul>
-		<li>implement branch ids (NOTE: <q>wch</q> should be used to refer to the latest commit in a branch)</li>
-	</ul></li>
-	<li>implement tags</li>
-	<li>owner/filepermissions/timestamps</li>
-	<li>usernames/author</li>
-</ul>
-
-<p>I have set up bazaar repository at <a href="https:/launchpad.net/rvs">Launchpad</a>. Only until rvs becomes self-hosting.</p>
-<p>If anyone needs any help, let me know.
-<br />~ Luke Shumaker &lt;<a href="mailto:lukeshu@sbcglobal.net">LukeShu@sbcglobal.net</a>&gt;
-<br />Happy Hacking!</p>
-</body>
-</html>
-