[darcs-users] Theory of Patches

[Trent W. Buck]

Daniel Carrera <daniel.carrera at theingots.org> writes:

>> Short answer: the manual
>
> Do you have write access to the manual? Do you have control over it?

The user manual is written in LaTeX and is stored in the Darcs
repository, along with the code.  Anyone can patch it and "darcs send"
their work to the list.  Eric has the authority to approve/reject
submitted patches.

The TeX master document is src/darcs.tex, and it is mangled by
src/preproc.hs (invoked from GNUmakefile) before being passed to
pdflatex.  I probably know the most about this infrastructure, so feel
free to ask me about it (either here, in IRC, or in private email).

There is a long-term goal to replace the TeX and pdflatex with
restructure text and the Pandoc library, but I haven't made much
progress with that yet.  Most of my Darcs time has been spent improving
what the documentation actually says, rather than how it's built.

If you'd like to work on documentation issues, we could certainly use
help.  On bugs.darcs.net you'll find some of the documentation-related
bugs start with "docs:".

> We could try to merge some of the existing work into one larger body
> and then delete the originals. So there is something closer to a
> one-stop place for information. Btw, I'm thinking about the wiki +
> wikibook mostly, and maybe Camp.

My expectation is that the user manual will be for slow-changing
documentation that covers the main corpus of Darcs itself.  The wiki
will be for volatile documentation, new features, tips and tricks
(e.g. migrating from another VCS), and third-party scripts and such.

I'd eventually like the wiki to essentially be the "front line" of
documentation, and an ongoing migration of the best parts into the user
manual.

> Oh no, it's fine, I like where you are going with this. And maybe I
> can contribute something. For example, have you given any thought to
> using a content management system like Drupal?

Yes, and my thought is "no".  I can see the benefit of a CMS for, say, a
news agency or the PR arm of a large company.  I can't see any benefit
of a CMS for FOSS project with only a dozen regular contributors, of
which only two or three ever touch the user documentation.

In my experience, CMSes are very hard to use (compared to editing source
files in a VCS), and they tend to have poor support for any output
format other than HTML.  When I'm trying to navigate someone else's
content stored on a CMS, there's so much crap around the actual content
that it takes me a dozen clicks to actually find it (the content).

I've also seen several CVE notices for moodle lately, which IIRC is the
basis for drupal (or is it the other way around)?

> A Drupal site will also have a menu, a side-bar, pretty URLs and stuff
> like that to make navigation easier. Navigation is one of the things
> that (IMHO) wikis are not very good at.

Contrariwise, my experience of CMSs, particularly those run by small
FOSS communities, is that they spend so much time pissing about getting
stuff like breadcrumbs working that they forget to produce any actual
content.