web commit by ThomasSchwinge: Initial version.

diff --git a/doc/about_rcs_backends.mdwn b/doc/about_rcs_backends.mdwn
new file mode 100644 (file)
index 0000000..547f973
--- /dev/null
+++ b/doc/about_rcs_backends.mdwn
@@ -0,0 +1,71 @@
+## A few bits about the RCS backends
+
+### Terminology
+
+``web-edit'' means that a page is edited by using the web (CGI) interface
+as opposed to using a editor and the RCS interface.
+
+
+### [[Subversion]]
+
+Subversion was that first RCS to be supported by ikiwiki.
+
+#### How does it work internally?
+
+Master repository M.
+
+RCS commits from the outside are installed into M.
+
+There is a working copy of M (a checkout of M): W.
+
+HTML is generated from W.  rcs_update() will update from M to W.
+
+CGI operates on W.  rcs_commit() will commit from W to M.
+
+You browse and web-edit the wiki on W.
+
+
+### [darcs](http://darcs.net/) (not yet included)
+
+Support for using darcs as a backend is being worked on by [Thomas
+Schwinge](mailto:tschwinge@gnu.org).
+
+#### How will it work internally?
+
+``Master'' repository R1.
+
+RCS commits from the outside are installed into R1.
+
+HTML is generated from R1.  HTML is automatically generated (by using a
+``post-hook'') each time a new change is installed into R1.  It follows
+that rcs_update() is not needed.
+
+There is a working copy of R1: R2.
+
+CGI operates on R2.  rcs_commit() will push from R2 to R1.
+
+You browse the wiki on R1 and web-edit it on R2.  This means for example
+that R2 needs to be updated from R1 if you are going the web-edit a page,
+as the user otherwise might be irritated otherwise...
+
+How do changes get from R1 to R2?  Currently only internally in
+rcs_commit().  Is rcs_prepedit() suitable?
+
+It follows that the HTML rendering and the CGI handling can be completely
+separated parts in ikiwiki.
+
+##### Rationale for doing it differently than in the Subversion case
+
+darcs is a distributed RCS, which means that every checkout of a
+repository is equal to the repository it was checked-out from.  There is
+no forced hierarchy.
+
+R1 is the nevertheless called the master repository.  It's used for
+collecting all the changes and publishing them: on the one hand via the
+rendered HTML and on the other via the standard darcs RCS interface.
+
+R2, the repository where CGI operates on, is just a checkout of R1 and
+doesn't really differ from the other checkouts that people will branch
+off from R1.
+
+(To be continued.)