While I was hacking the doc the other day I noticed that
cross-references in the manual aren't very satisfactory.

First, they aren't rendered as hyperlinks in the TeX output.  That could
be fixed by using the hyperref package and, for instance, using \href
for URLs.

Also, URLs in the HTML output seem only to work properly with
latex2html; at least they don't get hyperlinked with tex4ht, which is
what I have, and which understands \href.  I think a free package should
be preferred generally to a non-free one like latex2html.

I could probably make the changes if they're wanted.

On Tue, Jan 13, 2009 at 07:57:09AM +0000, Dave Love wrote:
> While I was hacking the doc the other day I noticed that
> cross-references in the manual aren't very satisfactory.
>
> First, they aren't rendered as hyperlinks in the TeX output.  That
> could be fixed by using the hyperref package and, for instance,
> using \href for URLs.

I sent a patch to fix this about a week ago:

| From: Trent W. Buck <trentbuck@gmail.com>
| Date: Sun, 11 Jan 2009 22:09:41 +1100
| Subject: darcs patch: Clickable ToC, cross-references and URLs in PDF manual.
| Message-ID: <4969d375.1f538c0a.28bb.5e6c@mx.google.com>

It was not applied because it breaks PS output.  (Needs fixing.)

> Also, URLs in the HTML output seem only to work properly with
> latex2html; at least they don't get hyperlinked with tex4ht, which
> is what I have, and which understands \href.  I think a free package
> should be preferred generally to a non-free one like latex2html.
>
> I could probably make the changes if they're wanted.

As long as we're using TeX, latex2html is gonna be the default because
it can produce a bunch of separate HTML files (i.e. one per section),
whereas tex4ht (htlatex) can only produce a single HTML file output.

I agree that using non-Free code to build the HTML output is undesirable.

We have long-term plans to drop LaTeX for reST, but so far I've ended
up spending more time working on the manual's content than the reST
transition.

In the meantime, stable releases ship with pre-built HTML
documentation, so users (e.g. Debian packaging) can use this instead
of recompiling the docs.  Unfortunately, that breaks "make
install-pdf", but I don't intend to address that in the near future
(as we are dropping autoconf/make anyway).

The following patch updated the status of issue1313 to be resolved:

* Resolve issue1313: Clickable ToC and xrefs in PDF user manual. 
Ignore-this: 29bde3a5a170f5965d10d6c160b2099e

Trent Buck <bugs@darcs.net> writes:

> It was not applied because it breaks PS output.  (Needs fixing.)

I can have a look if you like.

> As long as we're using TeX, latex2html is gonna be the default because
> it can produce a bunch of separate HTML files (i.e. one per section),
> whereas tex4ht (htlatex) can only produce a single HTML file output.

Oh.  I thought I'd used it for split output, but I must mis-remember.
Why not tex2page, then?  (It comes with mzscheme in Debian and probably
other distros.  I hope the Scheme implementation isn't regarded as too
tasteless.  It doesn't generally render TeXnical stuff as images.)

> We have long-term plans to drop LaTeX for reST, but so far I've ended
> up spending more time working on the manual's content than the reST
> transition.

What's that?  It seems unfortunate to drop the literate programming
system.

> Unfortunately, that breaks "make
> install-pdf", but I don't intend to address that in the near future
> (as we are dropping autoconf/make anyway).

I know autotools can be a bit obscure, but they normally do the job
pretty well.  What problem with them needs addressing?

Sorry for the long delay in replying.

On Sun, Feb 01, 2009 at 06:59:28PM +0000, Dave Love wrote:
>> [latex2html and htlatex]
>
> Why not tex2page, then?

If you'd like to add support for this as well, that's fine with me.  I
personally can't be bothered.  But please make this a separate ticket
in the BTS, rather than continuing discussion about it on this ticket.

>> We have long-term plans to drop LaTeX for reST [...]
> It seems unfortunate to drop the literate programming system.

Currently we have .lhs files, but they aren't actually being used as
literate programming.  Rather, all that happens is that everything
between \begin{code} and \end{code} is parsed by GHC, and everything
between \end{code} and \begin{code} is parsed by TeX.  That's what
some people call "literate programming", but I don't think it's even
close to the scope of literate programming as Knuth envisioned.

Anyway... a TeX to reST transition (which hasn't happened yet), will
preserve the approximation of literate programming that we have right
now.  Just the bits between \end{code} and \begin{code} will be marked
up as reST instead of TeX.

>> Unfortunately, that breaks "make
>> install-pdf", but I don't intend to address that in the near future
>> (as we are dropping autoconf/make anyway).
> 
> I know autotools can be a bit obscure, but they normally do the job
> pretty well.  What problem with them needs addressing?

We are dropping autotools in favour of Cabal; the former will be
deprecated in the 2.3 release and gone in the 2.4 release.  For
rationale, please see the darcs-users list (it's not related to the
documentation building parts).