[darcs-users] Separating the user manual and code

Trent W. Buck trentbuck at gmail.com
Sun Oct 26 02:12:15 UTC 2008


David Roundy <droundy at darcs.net> writes:

> Hi Trent,
>
> I appreciate your interest in the darcs manual!
>
> I think you're conflating two suggestions and omitting a third in your
> suggestions.
>
> Our choice of language for the manual is independent of the decision of
> whether to continue using literate-style programming for portions of the
> manual, so I'll discuss them separately.  And you've left out of your
> discussion the question as to whether we should continue to auto-generate
> portions of the user manual--which is also independent of either of the two
> questions.
>
> So the questions are:
>
> 1. Should we stop using latex for the manual, and if so, which language
> should we switch to?
>
> 2. Should we continue using a literate approach for portions of the
> manual?
>



>| Should we continue to auto-generate portions of the manual from the
>| darcs source code?
>
> This has the advantage that the manual is always up-to-date with
> regard to command options.  [...] And it means that anyone reviewing
> the manual can immediately see if there is a mismatch between darcs
> COMMAND --help and the rest of the manual text.

Sorry, but those two statements sound contradictory to me.

Fundamentally, anything that's not executed (i.e. docstrings and
literate comments) *can* get out of date.  Unlike API docs, I don't
think that it's useful to see the raw code when maintaining the user
manual.

> I consider this integration invaluable, and would be very sad to see
> it go.  It also doesn't depend on what language we choose to use (it's
> easy enough to modify preproc.hs), or on the choice as to whether to
> keep the code literate.

I'd like to reduce the literate intermixing of code and documentation to
where it's useful -- which AFAICT is primarily src/Darcs/Commands.  I
feel less strongly about de-literating src/Darcs/Commands, but I'd still
like other setups to be evaluated and demonstrated (i.e. a branch repo
that people can play in).

> 2. In places, literate programming has several advantages, not the
> least of which is that it makes it easier to review either the code or
> the manual for correctness.  I suspect that in spite of your best
> intentions, a manual that is totally divorced from source code will
> languish, bitrot and soon become a danger instead of a benefit to
> users, as behavior is modified and the manual is not updated.

I can see you point, but I'm not convinced that this danger is
significantly lessened by mixing the user manual in with the code.

When I'm programming, I'm almost always focused on getting the code
working first; even if I'm the one maintaining user documentation, that
user documentation gets updated in a separate mental pass.  It's still
easy for me to forget that second pass when the user manual is in the
same file, because during the coding pass I have been trained to just
skip over it.

> That said, in most of the darcs source code, I'd be happy to jettison the
> literate style.  (But then, much of the darcs code isn't included in the
> manual...)  It makes sense in just a few portions of the code.

I submitted some patches last night to this effect.
>
> 1. Which language? LaTeX really isn't particularly hard to learn or write,

I've used both LaTeX and reST extensively, and I believe that reST is
easier to learn, easier to catch dumb mistakes (due to --strict) and
offers better separation of semantic markup from presentational
markup -- the latter is done by either stylesheets (e.g. CSS) or by
transforms in Python or XSLT prior to emitting the finished document.

> but it has the major disadvantage that there aren't really nice converters
> to html.

reST also emits pretty good HTML, and via either reportlab or latex,
PDFs that are nearly up to LaTeX's own quality.

In short my argument isn't that LaTeX is bad, but that for the Darcs
user manual reST is more appropriate.

> Pandoc is in fact a tool with intriguing possibilities, since it's also a
> Haskell library that could be used to parse and collate contents (and do
> things such as insert darcs command options into the manual.

That would certainly be useful, but I'm simply not convinced that pandoc
support is currently complete enough for it to be "production ready".



More information about the darcs-users mailing list