add README, HACKING, and other documentation

author: Luke Shumaker <LukeShu@sbcglobal.net> 2009-07-13 15:46:14 -0400
committer: Luke Shumaker <lukeshu@sbcglobal.net> 2015-06-26 00:30:11 -0600
commit: 1f75a1dff61a33dea973ebeea64a3bd8bccb715a (patch)
tree: 841f8b9fa2a1e7f0d42413eb7a1afd3911ef7eba /docs/README.xhtml
parent: 3cdfa2a24cd8279ab5d5204d598f319b175940f2 (diff)
1 files changed, 57 insertions, 49 deletions
diff --git a/docs/README.xhtml b/docs/README.xhtml
index 3d6c612..ded2de0 100644
--- a/docs/README.xhtml
+++ b/docs/README.xhtml
@@ -4,48 +4,45 @@
 	"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 $$VER$$</title>
+	<title>rvs 0.6.0</title>
 	<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
 </head>
+
 <body>
-<h1>rvs $$VER$$</h1>
+<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>
-<p>After you have obtained the source code, cd into the directory and run:<code>
-<br />./configure
-<br />make install
-</code></p>
-<p>instead of using options to <kbd>./configure</kbd> like <samp>./configure --prefix=/usr/bin</samp>, all configuration options (that effect the installation, not the build process), are stored in the file <kbd>Variables</kbd>. Many of the source files use variables in the form <samp>$$VARNAME$$</samp>. The <kbd>./configure</kbd> script replaces each instance of this with the value defined in <kbd>Variables</kbd>. <kbd>Variables</kbd> contains a variable name, tab character, then value on each line.</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>/etc/abomination/modules/rvs/commit</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/commit.d</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/commit.f</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get.d</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get.f</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/init</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/lib/rvsdb</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/lib/stdio</kbd></li>
-	<li><kbd>/usr/bin/rvs</kbd></li>
+	<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>/usr/bin/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>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/">bash</a> (needs to be installed at <kbd>/bin/bash</kbd>)</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>
+	<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>
@@ -57,24 +54,22 @@
 	<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>
-<p>The system will bork if you have filenames with spaces or newlines. Why? Because you haven't written a patch to fix it yet.</p>
-<p>Feel free to push to the <a href="https://code.launchpad.net/~lukeshu/+junk/rvs-release">launchpad repository</a>.</p>
 
 <h2>hacking</h2>
-<p>Again, here is a list of all files in <kbd>rvs-0.5.10.tar.gz</kbd>:</p>
+<p>Again, here is a list of all files when you check out</p>
 <ul>
-	<li><kbd>/etc/abomination/modules/rvs/commit</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/commit.d</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/commit.f</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get.d</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/get.f</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/init</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/lib/rvsdb</kbd></li>
-	<li><kbd>/etc/abomination/modules/rvs/lib/stdio</kbd></li>
-	<li><kbd>/usr/bin/rvs</kbd></li>
+	<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>/usr/bin/rvs</kbd> is just a wrapper for them. If you wish to move the directory with the sub-modules, all you have to do is update the variablle <code><var>RVSDIR</var></code> towards the beginning of <kbd>/usr/bin/rvs</kbd>.</p>
+<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>
@@ -84,20 +79,33 @@
 	<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>d</em>ocket                        </pre></td><td>s</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>/etc/abomination/modules/rvs/commit</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>
+<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.</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>soruce/rvs-core/commit</kbd></li>
+			<li><kbd>soruce/rvs-core/commit.d</kbd></li>
+			<li><kbd>soruce/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>/usr/bin/rvs</kbd>)</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>
@@ -107,7 +115,7 @@
 	<li>usernames/author</li>
 </ul>
 
-<p>I have set up bazaar repository at <a href="https://code.launchpad.net/~lukeshu/+junk/rvs-release">Launchpad</a>. Only until rvs becomes self-hosting.</p>
+<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>
author	Luke Shumaker <LukeShu@sbcglobal.net>	2009-07-13 15:46:14 -0400
committer	Luke Shumaker <lukeshu@sbcglobal.net>	2015-06-26 00:30:11 -0600
commit	1f75a1dff61a33dea973ebeea64a3bd8bccb715a (patch)
tree	841f8b9fa2a1e7f0d42413eb7a1afd3911ef7eba /docs/README.xhtml
parent	3cdfa2a24cd8279ab5d5204d598f319b175940f2 (diff)