Ticket #142 (closed enhancement: wontfix)

Opened 4 years ago

Last modified 2 years ago

Special handling of URLs in documentation

Reported by: KrzysztofSkrzetnicki Owned by: SimonHengel
Priority: minor Milestone:
Version: 2.6.0 Keywords:
Cc:

Description

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.

Change History

Changed 4 years ago by KrzysztofSkrzetnicki

  • priority changed from major to minor

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)

Changed 3 years ago by SimonHengel

  • owner set to SimonHengel
  • status changed from new to assigned

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

Changed 3 years ago by 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?

Changed 3 years ago by waern

  • status changed from assigned to closed
  • resolution set to wontfix

Simon,

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

Changed 2 years ago by anonymous

  • milestone 2.7.0 deleted

Milestone 2.7.0 deleted

Note: See TracTickets for help on using tickets.