This is just a quick follow-up; I'll avoid re-hashing my position on the less important points.
Max Battcher <[EMAIL PROTECTED]> 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 :-| _______________________________________________ darcs-users mailing list [email protected] http://lists.osuosl.org/mailman/listinfo/darcs-users
