[darcs-users] Separating the user manual and code

Max Battcher me at worldmaker.net
Sun Oct 26 02:58:30 UTC 2008


Trent W. Buck wrote
> > This is an interesting idea: more examples/use-cases directly in the
> > documentation that double as regression/smoke tests.  I would even
> argue
> > that good examples might even be interesting to some users and so
> maybe the
> > idea might not be to remove them entirely from the final output, but
> perhaps
> > to "hide" it (at least in HTML output), place them in an "Example"
> box and
> > then through a tiny bit of JavaScript allow it so that an interested
> user
> > could expand the example and maybe even try it...
> 
> I'm against tweaking the upstream build tools (except where we
> absolutely have to), because then someone has to document and maintain
> those tweaks.  It also means that the source document no longer behaves
> "as advertised" -- you can't just put someone familiar with LaTeX in
> front of the file anymore, because \input{} and \begin{code} have
> different semantics.
> 

I'm not sure if this is directly in response to my preceding paragraph
there, but just to make sure that I am clear:  Nothing that I suggested
requires tweaking the build tools.  I mentioned two simple reST directives
which are add-ons written in simple Python that have simple extension hooks
in both docutils and, simplier (to use a friend's word), in Sphinx.  The
idea of making expandable/collapsible example boxes can be done with or
without extensions, even, as it can be done in simple CSS + JavaScript
templates based even on just the most basic reST output (reST has very
common admonition directives and there isn't much reason to use anything
much more than an admonition)...

(The other directive might require a bit of code, but that's only because so
far there isn't a existing Sphinx/reST extension for pulling things from
Haskell source files, and would only be necessary if we went that particular
route.)

--
--Max Battcher--
http://worldmaker.net



More information about the darcs-users mailing list