# [darcs-users] Separating the user manual and code

Jason Dagit dagit at codersbase.com
Wed Oct 22 04:59:17 UTC 2008

On Tue, Oct 21, 2008 at 9:27 PM, Trent W. Buck <trentbuck at gmail.com> wrote:

>  Literate Haskell means the user manual source has to be TeX.  A
>  separate tree would allow us to evaluate alternative source formats,
>  such as texinfo, docbook or restructured text (reST).

I don't think this is strictly true unless the alternative format
doesn't allow \begin{code} ... \end{code} or lines beginning with the
greater than symbol.  On the other hand, your idea about using docbook
is interesting to me.  I've never used docbook but I have, on more
than one occasion, admired non-pdf output from authors using docbook.
I have a mental model where latex tends to generate very attractive
pdfs and docbook generates attractive web-friendly formats like html.
I don't think very many people use our pdf copy of the manual
seriously, but I do think a lot of people reference the html version.
This is an argument to have a format that is optimized for good web
presentation, although I do think our current layout in good.

>  It would also make it easier for us to include translations of the
>  user manual (into other human languages).  It's not obvious to me how
>  that can be achieved using literate haskell.

I can imagine this as something that is hard to maintain without a
documentation manager dedicated to keeping the languages updated.

>  Lastly, Emacs isn't very good at handling two very different languages
>  (like Haskell/TeX or XHTML/Javascript) in a single file, and tools

I haven't really noticed this as a problem in .lhs files.

I'm in support of this experiment/change.

I think it's good that we made it this far using literate haskell, but
I also welcome this change.  I think for the arguments presented above
that separation is better than our use of literate haskell.  I also
think literate haskell makes more sense for people that are presenting
the code as snippets, such as in emails or blog posts.  For user
documentation I don't think it's as useful.

Now how to make this transition easiest?  We don't have hunk move
patches and I don't think we should bother renaming the files.
Leaving them as literate haskell seems fine to me.

Thanks,
Jason