[darcs-users] Darcs Manual

[Max Battcher]

Trent W. Buck wrote:
>> Speaking of which what is the status on the reST conversion, Trent?
> 
> Work is still happening to infrastructure (getting manpage and manual
> generation into the Darcs program to appease cabal, adopting pandoc)
> and migrating content from TeX into the Haskell source, so it
> accessible interactively as well as from an offline manual.
> 
> I'm confident that we'll eventually transition to using reST to markup
> the documentation (instead of the current mishmash of verbatim string
> (in Haskell) and .tex files), but my position is still that improving
> what the documentation *says* takes priority over what it looks like.

I agree that improving what the documentation says is more important 
than what it looks, that is why A) I've backed the reST rewrite: less 
opaque/arcane markup should make documentation editing, and B) I've 
backed Sphinx as a build environment.

I think you've misunderstood some of my aims in suggesting Sphinx. I do 
think that Sphinx is currently the best in class for non-trivial reST 
builds, it has a lot of momentum behind it in the Python community 
alone, and it has a usefully active community/development.

It certainly supports making the documentation look "pretty", but first 
and foremost it is a useful build tool, particularly for (well 
cross-referenced) multiple source document builds (for both single and 
multiple document output).

I know you had some issues with Sphinx the last few times it was 
discussed, but I do think several of them are on the way to being closed 
and I also think that using an existing, tested documentation build tool 
should help more than trying to ad hoc rebuild it in haskell/pandoc. (Or 
maybe even just as a "today" solution until such a haskell-based 
equivalent is built.)

> My initial efforts at simply rewriting .tex files into rest fell down
> because that approach requires the WHOLE conversion be done at once,
> or it breaks builds.  Now I'm intending more incremental changes, such
> as changing the manpage generation code to use pandoc to take in reST
> and spit out roff, rather than the current ad-hoc NIH implementation.

On thinking about it more: it does sound like a good idea to me to put 
conversion work in progress (even if it is a TeX/reST creole) in a 
darcsit environment as an easy way to get eyeballs to work in progress. 
darcsit could serve as a simplified "build environment" to display/edit 
the work in progress without breaking the actual build environment...

--
--Max Battcher--
http://worldmaker.net