[darcs-users] Darcs Manual
me at worldmaker.net
Wed Jul 22 03:20:27 UTC 2009
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...
More information about the darcs-users