[darcs-users] Separating the user manual and code

David Roundy droundy at darcs.net
Sat Oct 25 16:21:36 UTC 2008


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?

3. Should we continue to auto-generate portions of the manual from the
darcs source code?


I'll address these in reverse order...

3. Currently we include the darcs flags and command help text in the manual
using the preproc program.  This shows up in the literate docs as strings
like

\options{put}
\haskell{put_help}

This has the advantage that the manual is always up-to-date with regard to
command options.  It complicates the build slightly, but so far as I can
tell, this hasn't caused problems.  It ensures that every flag is
documented at least by the string given in its getopt documentation.  It
also means that when the help message for a command is changed, its manual
entry is changed.  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.

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.

2. In places, lierate 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.

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.  One is the
commands, which mostly have relatively little source code, most of which is
directly relevant to users.  Another is Arguments.lhs, which defines
commonly-reused flags.  In both cases, these are files where we make
changes to the user interface.  In the case of Arguments.lhs (which, by the
way, is a horribly organized file), most of the code itself is user
documentation, so it makes sense to me to keep the documentation all
together.

That said, I'm not dead-set on keeping the current literate framework.  A
tantalizing alternative would be to move to having literate tests rather
than literate code.  In this scenario, we would couple portions of the test
suite with the documentation, so that (for instance) after we point out
(in a hypothetical documentation of the patch matching interface)

 The flag -n allows you to specify a range of patches, as shown by darcs
 changes --numbered.  See for example::

    rm -rf temp1 #boring
    mkdir temp1  #boring
    darcs init   #boring
    ...
    darcs changes --numbered
    darcs changes -s -n 3-4 > out
    grep change3 out #boring
    grep change2 out #boring
    not grep change1 out #boring
    not grep change4 out #boring

Hopefully you can see the idea.  I'm imagining a preprocessor that cuts out
the boring bits from the manual (and I'm far from attached to the syntax)
but formats the other bits.  But the test suite would cut out the entire
test and execute it, so we'd have verification that the examples in the
manual actually continue to work, and at the same time, improvements to the
manual could be leveraged into improvments in the test suite.  Certainly we
wouldn't want the entire test suite to be included in the manual, but it
might not hurt to have a regression document of some sort (vaguely
analogous to lilypond's human-readable regression test, see
http://lilypond.org/doc/v2.10/input/regression/collated-files), which could
document some of the more subtle behaviors of darcs.

My concern is that a truly standalone manual is just too easy to leave
behind as we change the code.  Note also that the same technical writers
who are improving the manual would be most valuable in improving either the
test suite or the documentation that is embedded in the code itself
(i.e. the output of darcs command --help).

1. Which language? LaTeX really isn't particularly hard to learn or write,
but it has the major disadvantage that there aren't really nice converters
to html.  This is stupid, and I don't really understand why this is (well,
except probably for the fact that TeX is Turing complete...), but there it
is.  So I agree, a switch to a different language could be nice, and a
lightweight markup language is definitely appealing.

I have little to no experience with lightweight markup languages, so I will
leave this to others to decide.  I'm curious as to the advantages of
reST/sphinx over say markdown.  A quick look at their respective wikipedia
pages suggests that markdown is more widely-used, and is supported by many
implementations, while I wasn't able to find anywhere a hint as to how one
would compile a reST file--probably this is because they are lacking good
technical writers for their manual--except by using pandoc (which is the
tool that caused me to hear about the markdown format).

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.

David


More information about the darcs-users mailing list