Trent W. Buck wrote:
On Tue, Jul 21, 2009 at 11:20:27PM -0400, Max Battcher wrote:
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.)
I agree that Sphinx produces the best HTML output. I've got no
problem with adopting Sphinx for building an HTML user manual.
*My* immediate goal re restization is:
- comprehensive command/file/environment docstrings
(command_description) in the source code marked up as reST.
- Rendering these as plain text when the user runs "darcs help foo"
without relying on external commands. I don't want users seeing
double colons before verbatim blocks or underscores peppering their
display when they as for "darcs help push".
To me, that basically means pandoc is already a necessary dependency
for "darcs help". It seems straightforward to me to make "darcs help
manpage" use pandoc instead of emitting reST and having cabal pipe it
through an rst2man (which is not yet a stable part of docutils), but
I'm not married to that idea.
I do think that is a reasonable approach to use pandoc for help/man.
My main concerns with Sphinx are that its PDF output requires LaTeX to
build and looks like a fugly TeX document (admittedly subjective) and
that it requires non-standard ToC and include directives that break
OTHER reST parsers (i.e. we'd be "locked in" to only using Sphinx).
There is an addon in testing to do rst2pdf/reportlab PDF builds for
Sphinx now. The test output I've seen so far looks pretty nice and the
addon maintainer's goals are to get the PDF output to look as close the
HTML output as possible (while respecting the way a PDF should look as
well).
I've been meaning to test this addon with some of my own Sphinx builds,
and I'd be interested in testing it with Darcs' documentation as well.
As for the "non-standard" directives, I don't think it would result in
"lock in". ReST was designed for "extension" directives and
theoretically other reST parsers should allow for extension plugins to
support new directives. I'm guessing that directive plugins aren't part
of the subset of reST that pandoc supports, but docutils itself has
"always" supported it. (Sphinx' directives are in fact just docutils
plugins and "theoretically" could be extracted from Sphinx, although
that is probably more work than is useful.)
Worst case, the reST using those directives won't work and will need to
be rewritten and I don't think that will be a horrible problem. Beyond
that, Sphinx provides several methods to export its information
(particularly the ToC information) and could be bent to a semi-automated
conversion _should_ the need arise. (The JSON-serialized build alone is
actually surprisingly useful.)
--
--Max Battcher--
http://worldmaker.net
_______________________________________________
darcs-users mailing list
[email protected]
http://lists.osuosl.org/mailman/listinfo/darcs-users
