Haddock: patch to generate single-index page in addition to perl-letter indexes indices.
When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in "Window" in the Chart package -- no luck: * http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index.... * * * *Therefore I propose that even when generating the "A-Z" individual pages that there also be an "All" option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock:* * * * http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html* The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly! *Cheers,* * -Ryan* * * P.S. At the other end of the spectrum, when considering a central index for all of hackage (as in the below ticket) maybe it would be necessary to have more than 26 pages, I.e. Aa-Am | An-Az or whatever. http://hackage.haskell.org/trac/hackage/ticket/516#comment:6
2010/10/24 Ryan Newton <newton@mit.edu>:
When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in "Window" in the Chart package -- no luck: http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index.... Therefore I propose that even when generating the "A-Z" individual pages that there also be an "All" option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/ right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock: http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly!
Patch applied. Thanks! David
For packages with many items in the index, these pages can get a bit huge. How about a permuted index like <http://www.lispworks.com/documentation/HyperSpec/Front/X_Symbol.htm>? E.g., for your use case, you would go to E and then the row with all the "End" entries, which would contain all the names with "End" anywhere in their name. I don't know if page size can be a problem, but at least for mobile or otherwise low-bandwidth devices this can be a nice alternative. On 24 October 2010 04:41, Ryan Newton <newton@mit.edu> wrote:
When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in "Window" in the Chart package -- no luck: http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index.... Therefore I propose that even when generating the "A-Z" individual pages that there also be an "All" option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/ right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock: http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly! Cheers, -Ryan P.S. At the other end of the spectrum, when considering a central index for all of hackage (as in the below ticket) maybe it would be necessary to have more than 26 pages, I.e. Aa-Am | An-Az or whatever. http://hackage.haskell.org/trac/hackage/ticket/516#comment:6
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
-- Push the envelope. Watch it bend.
(Btw, I blame gmail for the mangled title ;-) -- it's been doing some weird stuff recently on Safari for me; but only in the subject line. I think there were backspace characters in an edit that weren't applied.) The permuted indices are interesting. It means really committing to the style/naming conventions, doesn't it? In common lisp, hyphen separated names and I guess camel-case for Haskell. Though you could split on underscores *or* camel case... I think multiple ways of indexing the data never hurts (except by confusing the user a bit). On that common lisp page I especially like how they've indented the words. Frankly I'd like a search box in any interface that displays more than two thingamajigs. That should be a UI commandment. I was expecting the objection of wasted server bandwidth for very large indices. I wasn't so worried about the client (even mobile) case. People can always press escape if a load takes too long. And it only happens if they manually drill down into "All". Perhaps a good idea would be to follow the convention used elsewhere <http://svnbook.red-bean.com/> and have a link with a size warning -- "All Entries (1.6 MB HTML)." That should keep people from clicking on it with their smartphone :-). I can tweak it again to do that if people like. Cheers, -Ryan On Sun, Oct 24, 2010 at 8:15 AM, Thomas Schilling <nominolo@googlemail.com>wrote:
For packages with many items in the index, these pages can get a bit huge. How about a permuted index like <http://www.lispworks.com/documentation/HyperSpec/Front/X_Symbol.htm>?
E.g., for your use case, you would go to E and then the row with all the "End" entries, which would contain all the names with "End" anywhere in their name.
I don't know if page size can be a problem, but at least for mobile or otherwise low-bandwidth devices this can be a nice alternative.
On 24 October 2010 04:41, Ryan Newton <newton@mit.edu> wrote:
When I encounter a split-index (A-Z) page it can be quite frustrating if I don't know the first letter of what I'm searching for. I want to use my browser find! For example, tonight I wanted to look at all the functions that END in "Window" in the Chart package -- no luck:
http://hackage.haskell.org/packages/archive/Chart/0.13.1/doc/html/doc-index....
Therefore I propose that even when generating the "A-Z" individual pages that there also be an "All" option for the single-page version. Attached is a patch against haddock's HEAD (darcs get http://code.haskell.org/haddock/ right?) that implements this behavior. As an example, here is FGL's documentation built with the patched haddock: http://people.csail.mit.edu/newton/fgl_example_doc/doc-index.html The great thing about hackage being centralized is that if people are happy with this fix it can be widely deployed where it counts, and quickly! Cheers, -Ryan P.S. At the other end of the spectrum, when considering a central index for all of hackage (as in the below ticket) maybe it would be necessary to have more than 26 pages, I.e. Aa-Am | An-Az or whatever. http://hackage.haskell.org/trac/hackage/ticket/516#comment:6
_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe
-- Push the envelope. Watch it bend.
participants (3)
-
David Waern -
Ryan Newton -
Thomas Schilling