[darcs-users] Separating the user manual and code

Mark Stosberg mark at summersault.com
Sat Oct 25 23:32:22 UTC 2008


Well spoken, David. I have ofter my own responses to your clarified
questions: 

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

I believe we should, for the reasons David's cites-- it creates a
consistency between the code and docs for free. 

> 2. Should we continue using a literate approach for portions of the
> manual?

I do not feel strongly about whether the docs are embedded with the code
or separate. 

Some people in the Perl universe use "literate tests" as David
describes. Or in a slightly different framing, there are ways to check
that your examples work in automated way. I agree these could be
interesting to try, but I don't feel strongly about them. 

> 1. Should we stop using latex for the manual, and if so, which language
> should we switch to?

Here I can give a perspective as someone who for a time was a frequent
contributor the documentation. I did not know Latex well, nor did I find
it very interesting to learn more about it. Further, I often didn't have
a working Latex toolchain on the machine I wanted to update the docs on,
so I would sometimes submit doc patches with Latex syntax errors. 

I do not know reST well either, but I like the way that it has a visual
layout even as plain text, and I am interested to learn more about it.
Also, after a simple "apt-get install python-docutils", I found I had
"rst2html" and "rst2pdf". The toolchain was easier to install for me. 

I find this point is somewhat a matter of taste, and I can make no
projections about what "most peoples" taste might be. I will say that
technical folk are frequently exposed to wiki-like syntax from dealing
with wikis, while outside of math and Haskell circles, I don't see Latex
in use much. Anyway, I'm personally more interested in a wiki-like
syntax than I am in Latex.

    Mark

-- 
http://mark.stosberg.com/





More information about the darcs-users mailing list