[darcs-users] Separating the user manual and code

David Roundy droundy at darcs.net
Mon Oct 27 18:08:20 UTC 2008

On Sat, Oct 25, 2008 at 03:07:42PM -0400, Max Battcher wrote:
> David Roundy wrote:
> > That said, in most of the darcs source code, I'd be happy to jettison
> > the
> > literate style.  (But then, much of the darcs code isn't included in
> > the
> > manual...)  It makes sense in just a few portions of the code.  One is
> > the
> > commands, which mostly have relatively little source code, most of
> > which is
> > directly relevant to users.  Another is Arguments.lhs, which defines
> > commonly-reused flags.  In both cases, these are files where we make
> > changes to the user interface.  In the case of Arguments.lhs (which, by
> > the
> > way, is a horribly organized file), most of the code itself is user
> > documentation, so it makes sense to me to keep the documentation all
> > together.
> In a Python project I would do this by pulling parts of the Python files
> (the "documentation strings") and embedding them into the final output at
> documentation build-time through a documentation environment (Sphinx)
> extension, which may have no idea of how to "build" the full file but can
> scrape what it needs.  With the goal of having a simpler, faster build path
> for just documentation I think it might be useful if the documentation could
> be built with no GHC at all, or, perhaps more likely, just the bare minimum
> of a GHC environment.
> For instance, if Sphinx were chosen as the build environment I would look
> into how best we might extract interesting bits of text from commands and
> arguments from Python.  I think it would be just as easy to grab portions of
> the .lhs file directly without GHC processing (via RegEx searches or other
> "stupid parser"), and again I think perhaps eliminating GHC from
> documentation builds would be nice for simpler, faster documentation builds
> which I think would indeed encourage more people to build and hack on the
> documentation when they have little/no skills to set up the rest of the
> build environment (even if it does get a lot simpler in the medium term
> thanks to franchise and/or cabal, I think there can still be use in the
> simplest documentation build possible).
> So I agree that there is benefit in the "Don't Repeat Yourself" here: pull
> help documentation into the manual from the code rather than writing it both
> in code-accessible and manual-accessible places.  But I don't think literate
> Haskell requiring a full GHC "unlit" to split the code and documentation
> *just* to build the documentation is necessary to do that.

Literate haskell isn't used to pull the docmentation in from the manual, we
do that in preproc.hs.

> >     rm -rf temp1 #boring
> >     mkdir temp1  #boring
> >     darcs init   #boring
> >     ...
> >     darcs changes --numbered
> >     darcs changes -s -n 3-4 > out
> >     grep change3 out #boring
> >     grep change2 out #boring
> >     not grep change1 out #boring
> >     not grep change4 out #boring
> > 
> > Hopefully you can see the idea.  I'm imagining a preprocessor that cuts
> > out the boring bits from the manual (and I'm far from attached to the
> > syntax) but formats the other bits.  But the test suite would cut out
> > the entire test and execute it, so we'd have verification that the
> > examples in the manual actually continue to work, and at the same time,
> > improvements to the manual could be leveraged into improvments in the
> > test suite.
> 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...

Yes, my thought was to only hide the parts explicitly marked as "boring",
which would likely involve things like setting up and cleaning up.  Of
course, removing this boiler plate would be even better.
David Roundy

More information about the darcs-users mailing list