[darcs-users] Sphinx or reST (for user manual)?

Trent W. Buck trentbuck at gmail.com
Wed Oct 29 01:40:59 UTC 2008


Mark Stosberg <mark at summersault.com> writes:

>> >>>     darcs get http://repos.worldmaker.net/darcs/sphinx/
> I did notice some of the drawbacks mentioned:
>
>  - an extra "make" command beyond the top-level one

This is easily fixable with some changes to GNUmakefile that I posted
upthread.

>  - no single page output (that I noticed) 

I'm not sure how to address this yet (since obviously the toctree
directive breaks plain rst2html).

>  - no PDF output (currently) 

    $(MAKE) -C doc/manual latex
    $(MAKE) -C doc/manual/_build/latex all-pdf

But this still requires sphinx and latex, which IMO is suboptimal.

> The output was attractive and functional.

One thing I don't like about the default output is that the menu is
physically located at the top of the file, so tty users get a few lines
of navigation junk before the "real" document.  Cf. wikipedia articles
for how I prefer it -- all the navigation is at the end, and then
floated to the top via CSS for GUI users.

I also don't like the way tty users get spammed with ¶'s in headings,
which are hidden via CSS for GUI users.

I assume both of these are trivial to fix, but I've been wrong about
that before -- for example, the trac developers told me that I couldn't
move navigation junk to the bottom of their pages without completely
rewriting their templating code.



More information about the darcs-users mailing list