Special handling of URLs in documentation

[KrzysztofSkrzetnicki]

It is hard to get URLs like http://example.com right in Haddock documentation. As a result a lot of documentation contain malformed addresses. For example see: http://hackage.haskell.org/package/random-shuffle-0.0.2

It reads: "Random shuffle implementation, on immutable lists. Based on `perfect shuffle' implementation by Oleg Kiselyov, available on http:okmij.orgftpHaskell/perfect-shuffle.txt"

Because '/' conflicts with the syntax reserved for other purposes the link is rendered as "http:okmij.orgftpHaskell/perfect-shuffle.txt". It is easy, but cumbersome, to recreate the original link. One can also go to .cabal file, which includes this description in this form:

description:
    Random shuffle implementation, on immutable lists.

    Based on `perfect shuffle' implementation by Oleg Kiselyov,
    available on http://okmij.org/ftp/Haskell/perfect-shuffle.txt

My proposition is to treat urls in special way: instead of normal processing url should yield a normal link.

I belive that only http://, https:// and ftp:// should need such special handling, so all in all this should be fairly easy to implement.

[KrzysztofSkrzetnicki]

I've just found angle bracket syntax in Haddock documentation. I don't know why it has escaped my attention before... my bad.

Anyway, I think the ticket is still relevant: since it's a common error it could be handled in some way. For example: - Haddock could generate a warning when it sees something that looks like link but is not in angle brackets. There shouldn't be many false positives. - It could automatically behave as if the angle brackets were added. - Hackage could reject packages with this kind of errors (but this is Haddock Trac, so lets stick to other options)

[SimonHengel]

This has bothered me for a long time, too. I'd try to add special markup support for plain URLs to the parser.

[SimonHengel]

If we assume that a URL reaches as far as we do not see any whitespace, it's easy (and possible to do in the lexer, see this commit).

But what about:

   for more see http://example.com.

Here the user's intention is probably, not to include the trailing dot into the URL (same for any of ,;?!). This is still possible, but not particularly beautiful (see this commit).

It gets uglier:

    some text (see http://example.com)

GitHub?'s code for GFM includes more such examples.

I haven't followed that route, but I think it could get quite messy.

To sum up, what options do we have?

1. Close as won't fix
2. Make a partial solution, like "a URL reaches as far as we do not see any whitespace"
3. Implement the full-fledged beast, similar to what GitHub? does
4. Anything else?

Personally, I think (2.) is just trading one shortcoming for an other. Both (1.) and (3.) work for me. (3.) is more work and may give us trouble in the future, so I'd tend to go for (1.) and rather do a sensible implementation of #190.

Opinions?

[waern]

Simon,

I'm with you completely on your conclusion of this. So I'm closing the ticket.

[anonymous]

Milestone 2.7.0 deleted