[darcs-users] documentation suggestion

[David Roundy]

On Mon, Jul 28, 2003 at 07:46:56AM -0700, Zack Brown wrote:
> On Mon, Jul 28, 2003 at 07:38:16AM -0400, David Roundy wrote:
> > On Sat, Jul 26, 2003 at 10:55:22AM -0700, Zack Brown wrote:
> > > 
> > > I'm trying to compile darcs, but I haven't met all of the dependencies on
> > > my system yet, so the compile keeps failing with errors. However, getting
> > > back to a clean tree to make another attemptis also difficult:
> > > 
> > > 10:45:28 [zbrown] ~/site/tmp/darcs/darcs$ make clean    
> > > GNUmakefile:150: .depend: No such file or directory
> > > Rebuild dependencies ...
> > > ArgumentDefaults.lhs: can't locate import `System.Console.GetOpt'
> > > make: *** [.depend] Error 1
> > > 10:45:31 [zbrown] ~/site/tmp/darcs/darcs$ 
> > 
> > Hmmmm.  What version of ghc are you running?
> 
> 5.02.2 - straight from Woody.

That's the problem.  The ghc 5.02 in woody is definitely too old.  5.04.2
is the requirement.  It is missing a rather large number of libraries that
I'd like to use.  :( Here is a sources.list entry for backported haskell
packages to woody:

deb http://www.syntaxpolice.org/haskell-experimental/ stable/

You could go with either the 5.04 or the 6.0 available there.

> Ah. I guess it would be easier for folks to only have to rely on standard
> packages from whatever OS we're using...

Yes, the problem is that debian's packages are *so* old, and haskell is a
pretty rapidly improving language, in terms of library support.  It makes
it hard to use a year and a half old compiler.  I have trouble enough
getting my code to work on both ghc 6.0 and 5.04.3.  :(

I'm hoping that once the hierarchical libraries are stabilized things will
look better in terms of portability of the software across versions...

> > > I'm not sure what I'm doing wrong. Maybe a Quickstart file in the sources
> > > would be good. It could describe the dependencies and the basic commands to
> > > get darcs compiled.
> > 
> > I've added a "Building darcs" section to the manual to give this sort of
> > information.
> 
> Very nice! It looks *really* easy to contribute. I wondered whether 'push'
> would require that I be on a list or something, and just update your tree
> automatically, but no, it just sends you an email containing the patch.

Right.  I could set things up so that gnupg signed patches (by authorized
people) would be automatically applied, but for docs that seems like
overkill, especially given how often I tend to check my email and work on
darcs anyways... also, I'd want to read each patch anyways, to see what's
going in.

I actually have a repository set up that I can push to (it's
http://abridgegame.org/repos/darcs-test), and use it regularly to transfer
patches from home.

> Is it possible to allow other people to push directly into a repository,
> without going through you? So multiple people could all have write
> access without bottlenecking one person? I can see how it would be done
> with procmail, but is there a more direct route?

Yeah, that's what the darcs-patcher does (along with darcs-createrepo, to
set things up).  It doesn't use procmail, but rather sets up a user for
each repository (and thus an email address for each repo).  The
darcs-patcher then checks that the patch is properly signed by an
authorized person, and applys it.  It also runs the test first, so the
patch will bounce (via email) if it has a mistake that is easily caught.

Currently darcs-patcher is rather crude, but I'd like to make it a bit
smarter, so it could do things like send confirmation emails, forward
patches (or just their headers) to a list and forward unauthorized patches
to an appropriate person (currently they just bounce).  But there seems to
always be more to be done than I have time to do...

> One more documentation suggestion: is it possible to have a form of the manual
> that is all on one page? So there would be both the normal page-by-page
> version on the web site, and there would also be a link to an 'all in one
> page' version.

Hmmmm.  Yes, latex2html is certainly capable of doing that.  It's just a
question of setting up the makefile to be able to do it.  A single html
file version is available at:

http://www.abridgegame.org/darcs/manual/bigpage.html

There is a link to this in the paragraph referring to the documentation.
-- 
David Roundy
http://civet.berkeley.edu/droundy/