[darcs-users] Sphinx or reST (for user manual)?
Trent W. Buck
trentbuck at gmail.com
Wed Oct 29 01:26:48 UTC 2008
This is just a quick follow-up; I'll avoid re-hashing my position on the
less important points.
Max Battcher <me at worldmaker.net> writes:
>> However I'd like to take a different approach. In short, rst2html is
>> adequate for our needs except for one thing: it can't produce
>> docbook-style split-HTML output. Let's simply extend the stock HTML
>> writer class (or possibly write a second HTML writer class) with this
>> feature. This means that
>> 1. other docutils users benefit;
>> 2. the aforementioned toctree issues go away; and
> This is exactly why Sphinx was built in the first place and
> re-building it seems a little extreme.
I agree that it's extreme. However I'm not proposing to reimplement all
of sphinx, *just* the split-HTML output target, none of the extra
"cleverness" that sphinx adds -- extending the source language
(toctree), having a conf.py and _conf, any notion of "modules", crawling
the source tree, requiring an extra wrapper (sphinx-build) for the
I'm not convinced the extra cleverness is useful enough for a user
manual to justify the complexity it adds.
I also *really* like rst2pdf, so I want to hold off on sphinxization
until the WIP sphinx/rst2pdf integration is complete.
> The Python community has debated and discussed this and Sphinx was
> built as a best practice tool from that debate. The number of Python
> projects moving to Sphinx seems to imply that it works for the
> majority of reST-based projects.
What's right for the Python community is not necessarily what's right
for Darcs' user manual.
What I've seen so far of Python's use of sphinx has had a strong
intertwingling of the user documentation with the API documentation, and
I want to avoid this for darcs. Both because Darcs is an application,
and because Haskell dissociates compile- and run-time, I don't think its
useful for end users to have cross-references from concepts to the
Being explicit: the audience of the user manual is end users, *not*
developers (except inasmuch as they're also end users).
> (The toctree was built, among other reasons, to handle complex table
> of contents building via the subclusion of individual document table
> of contents into a larger table of contents, based on each document's
> own knowledge of their table of contents... I certainly believe that
> building a special split-HTML tool would have to come up with answers
> to many of the same problems toctree was designed to solve...)
I don't understand why this complexity-handling is useful for the darcs
user manual. Can you cite some discussion that lead to toctree,
preferably with user cases?
IME the unify-then-split-at-<chapter> approach works well in Docbook,
for textbooks of similar length and structure to our user manual. I
don't understand why that approach is inadequate for our needs.
>> 3. sphinx' api-oriented features don't get in our way.
> I've already written a long email on why I think the "API-oriented"
> stuff is useful even to Darcs' user manual, but Sphinx makes it easy
> to turn off any that aren't needed and to extend any that don't quite
> fit Darcs' mental model.
I'm sorry, but I don't grok yet. I think I'd understand better if I saw
these features in action for the darcs user manual -- is this something
you (Max) could prepare in your sphinx branch?
>> - sphinx-build ALWAYS emits SGR (ANSI) escape sequences. Since I
>> often use dumb terminals and pure (non-tty) buffers, means I have to
>> go out of my way to make sphinx-build's output readable.
> I've don't think I've seen anyone bring this up as an issue on the
> Sphinx mailing list. I'll bring it up and maybe someone will write a
> patch to act more Darcs-like and attempt to discover if the current
> tty supports colors/rich output.
See also http://bugs.debian.org/501629 and http://bugs.debian.org/503053.
>> - I don't like tweaking stylesheets and templates; it takes time both
>> up-front and for ongoing maintenance (so it works with newer
>> versions of sphinx), it tends to introduces accessibility issues,
>> and tends to introduce rendering issues with buggy (i.e. all)
>> browsers you forget to test with.
>> And because Sphinx's default templates mention "modules", we'd have
>> to make and maintain at least minimal changes to make it "right" for
>> a user manual.
> The module index can be turned off in the configuration.
Righto, that becomes a non-issue, then.
> I can see the case that modules make sense in the Darcs world as well
> (even in the user manual), as Haskell calls source files modules just
> as Python does.
I disagree -- for the user manual. And the developer documentation is
currently handled by haddock.
> Is there a problem in noting that darcs command add is from the module
I think is a problem; it's not useful for end users, and it distracts
them from the important information. I do concede that it's not a *big*
> As I've said before this can usefully replace some of Darcs' current
> reliance on literate haskell by reversing the flow of information
> (allowing developers to continue to get the answer to "what does the
> user manual have to say about module x?").
I think I'd need to see this in action to understand why it's useful for
a user manual.
My remaining remarks are tangential to the issue at hand.
> I think the default templates/stylesheets are fine for Darcs. I would
> add the Darcs logo
Running off on a tangent here, I prefer to only use images where
necessary (diagrams and figures). I don't think that logo images --
which are essentially semantically void -- add any value to a document.
> and maybe tweak the color scheme to better match the darcs homepage,
Nor do I approve of trying to mess with the end user's preferred colour
scheme. Indeed, web developers have personally caused me so much grief
that I had to turn of user-side CSS and instead invert the gamma ramp of
my entire X display in order to reliably get white-on-black web pages.
Now, it only breaks when I go to a site that *itself* tries to enforce a
white-on-black colour scheme :-|
More information about the darcs-users