aboutsummaryrefslogtreecommitdiff
path: root/doc/rcs
diff options
context:
space:
mode:
authorJoey Hess <joey@gnu.kitenet.net>2009-04-04 18:04:20 -0400
committerJoey Hess <joey@gnu.kitenet.net>2009-04-04 18:04:20 -0400
commitca5704936d1d57fdd11ea850608e6fa9d574d9dd (patch)
tree478d2057e7ea4978adca05f0522ac61e254a1532 /doc/rcs
parentc93360a751ec39191b2cd10a6e8edc67b6c09134 (diff)
downloadikiwiki-ca5704936d1d57fdd11ea850608e6fa9d574d9dd.tar
ikiwiki-ca5704936d1d57fdd11ea850608e6fa9d574d9dd.tar.gz
update docs for darcs
Deleted all the old incomplete implementations. Moved explanation of the two-repo system currently implemented for darcs into rcs/details, and removed discussion from there about other methods (including one-repo). Wrote a rcs/darcs page, which I hope is accurate.
Diffstat (limited to 'doc/rcs')
-rw-r--r--doc/rcs/darcs.mdwn15
-rw-r--r--doc/rcs/details.mdwn98
2 files changed, 25 insertions, 88 deletions
diff --git a/doc/rcs/darcs.mdwn b/doc/rcs/darcs.mdwn
new file mode 100644
index 000000000..7f66d0808
--- /dev/null
+++ b/doc/rcs/darcs.mdwn
@@ -0,0 +1,15 @@
+[Darcs](http://darcs.new) is a distributed revison control
+system. Ikiwiki supports storing a wiki in a
+Darcs repository.
+
+An Ikiwiki wrapper is run by the `posthook` to update a wiki whenever commits
+or remote pushes come in. When running as a [[cgi]] with Darcs, ikiwiki
+automatically commits edited pages, and uses the Darcs history to generate the
+[[RecentChanges]] page.
+
+Example for a `_darcs/prefs/defaults` file in `$SRCDIR`:
+
+ apply posthook /path/to/repository/_darcs/ikiwrapper
+ apply run-posthook
+
+See also [[todo/darcs|todo/darcs]]
diff --git a/doc/rcs/details.mdwn b/doc/rcs/details.mdwn
index 089221cab..00559a4dd 100644
--- a/doc/rcs/details.mdwn
+++ b/doc/rcs/details.mdwn
@@ -32,98 +32,20 @@ You browse and web-edit the wiki on W.
W "belongs" to ikiwiki and should not be edited directly.
-## [darcs](http://darcs.net/) (not yet included)
+## [[darcs]]
-Support for using darcs as a backend is being worked on by [Thomas
-Schwinge](mailto:tschwinge@gnu.org), although development is on hold curretly.
-There is a patch in [[todo/darcs]].
+Regarding the repository layout: There are two darcs repositories. One is the `srcdir`, the other we'll call `master`.
-### How will it work internally?
+* HTML is generated from `srcdir`.
+* CGI edits happen in `srcdir`.
+* The backend pulls updates from `master` into `srcdir`, i.e. darcs commits should happen to `master`.
+* `master` calls ikiwiki (through a wrapper) in its apply posthook, i.e. `master/_darcs/prefs/defaults` should look like this:
-``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 to 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.
-
-What repository should [[RecentChanges]] and History work on? R1?
-
-#### 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 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 the 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.)
-
-#### Another possible approach
-
-Here's what I (tuomov) think, would be a “cleaner” approach:
-
- 1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`.
- This context _and_ the present version of the page are stored in as the “version” of the
- page in a hidden control of the HTML.
- Thus the HTML includes all that is needed to generate a patch wrt. to the state of the
- repository at the time the edit was started. This is of course all that darcs needs.
- 2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs.
- This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits
- only concern single files. The reason why the old version of the page is stored in
- the HTML (possibly compressed) is that the diff can be generated.
- 3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation…
- there are many possibilities.
-
-This approach avoids some of the problems of concurrent edits that the previous one may have,
-although there may be conflicts, which may or may not propagate to the displayed web page.
-(Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution
-bundle’.) Also, only one repository is needed, as it is never directly modified
-by Ikiwiki.
-
-This approach might be applicable to other distributed VCSs as well, although they're not as oriented
-towards transmitting changes with standalone patch bundles (often by email) as darcs is.
-
-> The mercurial plugin seems to just use one repo and edit it directly - is
-> there some reason that's okay there but not for darcs? I agree with tuomov
-> that having just the one repo would be preferable; the point of a dvcs is
-> that there's no difference between one repo and another. I've got a
-> darcs.pm based on mercurial.pm, that's almost usable... --bma
-
->> IMHO it comes down to whatever works well for a given RCS. Seems like
->> the darcs approach _could_ be done with most any distributed system, but
->> it might be overkill for some (or all?) While there is the incomplete darcs
->> plugin in [[todo/darcs]], if you submit one that's complete, I will
->> probably accept it into ikiwiki.. --[[Joey]]
-
->>> I'd like to help make a robust darcs (2) backend. I also think ikiwiki should use
->>> exactly one darcs repo. I think we can simplify and say conflicting web
->>> edits are not allowed, like most current wiki engines. I don't see that
->>> saving (so much) context in the html is necessary, then.
->>> bma, I would like to see your code. --[[Simon_Michael]]
->>> PS ah, there it is. Let's continue on the [[todo/darcs]] page.
+ apply posthook ikiwrap
+ apply run-posthook
+* The backend pushes CGI edits from `srcdir` back into `master` (triggering the apply hook).
+* The working copies in `srcdir` and `master` should *not* be touched by the user, only by the CGI or darcs, respectively.
## [[Git]]