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. 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). But since I've demonstrably been too busy with "darcs help" and the manpage to give the user manual any love, I'm prepared to let you run with Sphinx and worry about possible fallout in the future. PS: I also have concerns about pandoc's incomplete reST parser, but I stopped caring about that, too :-) _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
