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

[Trent W. Buck]

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
non-HTML targets.

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
source modules.

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
> Darcs.Commands.Add?

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*
problem.

> 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 :-|