[darcs-users] Separating the user manual and code

[Trent W. Buck]

On Sat, Oct 25, 2008 at 10:58:30PM -0400, Max Battcher wrote:
> Trent W. Buck wrote
>> 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

I was specifically referring to writing and maintaining the code you
describe below:

> (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.)

Right now Mark Stosberg and I have "dived in" to work on translating
the existing .tex files into reST.  Once that's done, we'll look at
just how the .lhs files turn into both code and reST.  I expect to
start by simplifying preproc.hs -- not making it search for and
recurse over \input{foo.lhs} directives, for example, but rather just
having it turn a single foo.lhs into a single foo.txt, and let the
makefile worry where to apply it.