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
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
