[darcs-users] Separating the user manual and code

Max Battcher me at worldmaker.net
Sat Oct 25 19:07:42 UTC 2008


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.

(The Sphinx-based approach to preproc/commands might be simple source files
like ./docs/Commands/add.rst:

  Add Command
  ===========

  .. autocommand:: Darcs.Commands.Add

  .. shellexample::

     darcs init
     touch a
     darcs add a
     # ...grep for a in darcs whatsnew...

Where autocommand was a simple extension to scrape the command information
from src/Darcs/Commands/Add.lhs and shellexample might be a simple extension
to mark examples as discussed below...)

> That said, I'm not dead-set on keeping the current literate framework.
> A
> tantalizing alternative would be to move to having literate tests
> rather
> than literate code.  In this scenario, we would couple portions of the
> test
> suite with the documentation, so that (for instance) after we point out
> (in a hypothetical documentation of the patch matching interface)
> 
>  The flag -n allows you to specify a range of patches, as shown by
> darcs
>  changes --numbered.  See for example::
> 
>     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...

> I have little to no experience with lightweight markup languages, so I
> will
> leave this to others to decide.  I'm curious as to the advantages of
> reST/sphinx over say markdown.  A quick look at their respective
> wikipedia
> pages suggests that markdown is more widely-used, and is supported by
> many
> implementations, while I wasn't able to find anywhere a hint as to how
> one
> would compile a reST file--probably this is because they are lacking
> good
> technical writers for their manual--except by using pandoc (which is
> the
> tool that caused me to hear about the markdown format).

Markdown is wider used, but reST was designed to be more amenable to
extension and was also designed to be more useful to technical documentation
(markup for option lists, for example).  As far as I know the only full
parser of reST is the "docutils" parser written in Python, but it does
provide a couple of handy scripts (such as rst2html) that run anywhere
Python does, and an extensive Python API for embedding the parser (anywhere
that you can call out to Python code).  Sphinx is a reST build tool and set
of reST extensions that sit on top/wrap docutils to build multiple source
files into a larger documentation site with extensive cross-links and
auto-generated indices.

Anyway, just my two cents on the subject, hopefully some of it is
enlightening...

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




More information about the darcs-users mailing list