[darcs-users] Separating the user manual and code

[Trent W. Buck]

"Jason Dagit" <dagit at codersbase.com> writes:

> On Tue, Oct 21, 2008 at 9:27 PM, Trent W. Buck <trentbuck at gmail.com> wrote:
>
> I like your points, here are just a few comments I had.
>
>>  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.

Ah, right.  My memory was a bit flaky.  Still, while Bird style (leading
'>'s) literate haskell would work for things like reST, I think my other
arguments stand.

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

Certainly the HTML output from tex4ht is... less than fantastic.  (I
don't use latex2html because it's not DFSG compliant.)  The free tools
for rendering docbook are pretty unpleasant, but they work well enough
for generating XHTML.  I've been unimpressed so far with their PDF
output.

My strong personal preference is for reST, because it has a relatively
pleasant source markup, is relatively featureful for a lightweight
markup language, has a --strict mode, and generates pretty good HTML and
(with the new rst2pdf) PDF output.  I'm still concerned with its
scalability (document class "book" instead of "article"), but there's a
recent spin-off called Sphinx which might address that.

References:

  http://docutils.sf.net/
  http://code.google.com/p/rst2pdf/
  http://sphinx.pocoo.org/

This would also give coloured code snippets, which some people might
conceivably care about.

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

I'm imagining that we'd have a documentation team that ensures the
English version is up to date and coherent, and then individual
translators who irregularly update translations into their native
languages.

>>  Lastly, Emacs isn't very good at handling two very different languages
>>  (like Haskell/TeX or XHTML/Javascript) in a single file, and tools
>>  like literate-haskell-mode or mumamo only partially address this. :-)
>
> I haven't really noticed this as a problem in .lhs files.
>
> I'm in support of this experiment/change.

I'm certainly happy to do mockups and demos before we make any sweeping
changes to the canonical darcs repo.

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

I wasn't worrying about implementation details until I was confident I
wasn't going to get shouted down :-)