Reading Haddock sources on hackage no longer possible with simple browsers?

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Reading Haddock sources on hackage no longer possible with simple browsers?

Mario Lang-2
Hi.

I have been using Lynx to read stuff on hacakge for a long time.

I recently noticed that it is no longer possible to read the source of a
module, because extra type information (which is likely hidden in a
modern browser) is inline with the actual sources.  This makes the go to
source feature effectively useless.  An example (from the ISBN package):

    deriving (Int -> ISBN -> ShowS
    [ISBN] -> ShowS
    ISBN -> String
    (Int -> ISBN -> ShowS)
    -> (ISBN -> String) -> ([ISBN] -> ShowS) -> Show ISBN
    forall a.
    (Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
    showList :: [ISBN] -> ShowS
    $cshowList :: [ISBN] -> ShowS
    show :: ISBN -> String
    $cshow :: ISBN -> String
    showsPrec :: Int -> ISBN -> ShowS
    $cshowsPrec :: Int -> ISBN -> ShowS
    Show, ISBN -> ISBN -> Bool
    (ISBN -> ISBN -> Bool) -> (ISBN -> ISBN -> Bool) -> Eq ISBN
    forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
    /= :: ISBN -> ISBN -> Bool
    $c/= :: ISBN -> ISBN -> Bool
    == :: ISBN -> ISBN -> Bool
    $c== :: ISBN -> ISBN -> Bool
    Eq)
   
I know Haskell has a ton of extensions, but I am pretty sure nobody
writes code like this :-)

This is, frankly, pretty horrible.   Can something be done to fix this?

(I am aware that certain modernisations are unstoppable.  However, this
one looks like a bug.)

--
CYa,
  ⡍⠁⠗⠊⠕
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Johannes Waldmann-2
> I recently noticed that it is no longer possible
> to read the source of a module, because extra type information
> (which is likely hidden in a modern browser)
> is inline with the actual sources.

I confirmed your example, reading with lynx and w3m.

It seems the extra text
is the methods of the type classes (mentioned after "deriving")
and it gets shown on on mouse-over in a graphical browser.

(Re: "nobody writes code like this" - the compiler does?
Some methods here seem auto-generated.)

Looks like a bug in haddock, then? (Or in lynx' handling of CSS?)
The actual HTML source looks legit, at least partially
(see example below)

This seems related:
https://github.com/haskell/haddock/pull/1197

I will open an issue on accessibility.

- J.W.

<span class="hs-keyword">deriving</span><span> </span><span
class="hs-special">(</span><span id="local-6989586621679046279"><span
id="local-6989586621679046281"><span
id="local-6989586621679046283"><span class="annot"><span
class="annottext">Int -&gt; ISBN -&gt; ShowS
[ISBN] -&gt; ShowS
ISBN -&gt; String
(Int -&gt; ISBN -&gt; ShowS)
-&gt; (ISBN -&gt; String) -&gt; ([ISBN] -&gt; ShowS) -&gt; Show ISBN
forall a.
(Int -&gt; a -&gt; ShowS) -&gt; (a -&gt; String) -&gt; ([a] -&gt; ShowS)
-&gt; Show a
showList :: [ISBN] -&gt; ShowS
$cshowList :: [ISBN] -&gt; ShowS
show :: ISBN -&gt; String
$cshow :: ISBN -&gt; String
showsPrec :: Int -&gt; ISBN -&gt; ShowS
$cshowsPrec :: Int -&gt; ISBN -&gt; ShowS
</span><span class="hs-identifier hs-var hs-var hs-var hs-var hs-var
hs-var hs-var hs-var">Show</span>

_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Li-yao Xia-2
In reply to this post by Mario Lang-2
Note that the raw sources are available in another location:

https://hackage.haskell.org/package/isbn-1.1.0.2/src/lib/Data/ISBN/Types.hs

(starting from the Hackage page for the package, under Downloads, click
"browse")

On 11/14/2020 10:32 AM, Mario Lang wrote:

> Hi.
>
> I have been using Lynx to read stuff on hacakge for a long time.
>
> I recently noticed that it is no longer possible to read the source of a
> module, because extra type information (which is likely hidden in a
> modern browser) is inline with the actual sources.  This makes the go to
> source feature effectively useless.  An example (from the ISBN package):
>
>      deriving (Int -> ISBN -> ShowS
>      [ISBN] -> ShowS
>      ISBN -> String
>      (Int -> ISBN -> ShowS)
>      -> (ISBN -> String) -> ([ISBN] -> ShowS) -> Show ISBN
>      forall a.
>      (Int -> a -> ShowS) -> (a -> String) -> ([a] -> ShowS) -> Show a
>      showList :: [ISBN] -> ShowS
>      $cshowList :: [ISBN] -> ShowS
>      show :: ISBN -> String
>      $cshow :: ISBN -> String
>      showsPrec :: Int -> ISBN -> ShowS
>      $cshowsPrec :: Int -> ISBN -> ShowS
>      Show, ISBN -> ISBN -> Bool
>      (ISBN -> ISBN -> Bool) -> (ISBN -> ISBN -> Bool) -> Eq ISBN
>      forall a. (a -> a -> Bool) -> (a -> a -> Bool) -> Eq a
>      /= :: ISBN -> ISBN -> Bool
>      $c/= :: ISBN -> ISBN -> Bool
>      == :: ISBN -> ISBN -> Bool
>      $c== :: ISBN -> ISBN -> Bool
>      Eq)
>      
> I know Haskell has a ton of extensions, but I am pretty sure nobody
> writes code like this :-)
>
> This is, frankly, pretty horrible.   Can something be done to fix this?
>
> (I am aware that certain modernisations are unstoppable.  However, this
> one looks like a bug.)
>
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Alec Theriault
In reply to this post by Johannes Waldmann-2
Hello,

This is indeed by design - it is a relatively new Haddock feature (here’s the original issue) where types of identifiers and identifiers bound are shown on mouse-over.
Here is what this looks like in a graphical browser:


As for the the weird declarations like $cshowList and company, this seems to be a bug - Haddock should not display those identifiers.

Although I’m sympathetic to the accessibility, in this case wouldn’t just directly opening the sources (in a text editor) be simpler? Is there a (simple) way to preserve the experience when browsing using Lynx without also holding back features aimed at a regular browsing experience?

Alec

On Nov 14, 2020, at 1:01 PM, Johannes Waldmann <[hidden email]> wrote:

I recently noticed that it is no longer possible
to read the source of a module, because extra type information
(which is likely hidden in a modern browser)
is inline with the actual sources.

I confirmed your example, reading with lynx and w3m.

It seems the extra text
is the methods of the type classes (mentioned after "deriving")
and it gets shown on on mouse-over in a graphical browser.

(Re: "nobody writes code like this" - the compiler does?
Some methods here seem auto-generated.)

Looks like a bug in haddock, then? (Or in lynx' handling of CSS?)
The actual HTML source looks legit, at least partially
(see example below)

This seems related:
https://github.com/haskell/haddock/pull/1197

I will open an issue on accessibility.

- J.W.

<span class="hs-keyword">deriving</span><span> </span><span
class="hs-special">(</span><span id="local-6989586621679046279"><span
id="local-6989586621679046281"><span
id="local-6989586621679046283"><span class="annot"><span
class="annottext">Int -&gt; ISBN -&gt; ShowS
[ISBN] -&gt; ShowS
ISBN -&gt; String
(Int -&gt; ISBN -&gt; ShowS)
-&gt; (ISBN -&gt; String) -&gt; ([ISBN] -&gt; ShowS) -&gt; Show ISBN
forall a.
(Int -&gt; a -&gt; ShowS) -&gt; (a -&gt; String) -&gt; ([a] -&gt; ShowS)
-&gt; Show a
showList :: [ISBN] -&gt; ShowS
$cshowList :: [ISBN] -&gt; ShowS
show :: ISBN -&gt; String
$cshow :: ISBN -&gt; String
showsPrec :: Int -&gt; ISBN -&gt; ShowS
$cshowsPrec :: Int -&gt; ISBN -&gt; ShowS
</span><span class="hs-identifier hs-var hs-var hs-var hs-var hs-var
hs-var hs-var hs-var">Show</span>

_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.


_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Johannes Waldmann-2

>  ... a (simple) way to preserve the experience when browsing using Lynx

yes, that is the question. What *is* the recommended way
of providing a tooltip-like experience for text browsers?

- J.
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Mario Lang-2
In reply to this post by Alec Theriault
Alec Theriault <[hidden email]> writes:

> Although I’m sympathetic to the accessibility, in this case wouldn’t just
> directly opening the sources (in a text editor) be simpler?

Following a link to a definition is convenient because there is an
anchor.
Of course I can just open the original sources in a text editor.
But then I am no longer reading documentation, I am reading sources!

> Is there a (simple) way to preserve the experience when browsing using
> Lynx without also holding back features aimed at a regular browsing
> experience?

I was expecting this sort of killer argument.  I have to admit I am too
exhausted with this topic to try and give a meaningful answer.  There
used to be a time when compatibility to existing technology was a goal
by itself.  This is going away even in circles which usually have tried
to achieve some sort of technical excellence.  I am sad.  But I can not
do anything against the tides except for sometimes pointing at ships
while they are sinking, hoping to get someone to see reason and rescue
at least some of them.

Practically speaking, the problem is the visibility style attribute.  As
far as I know, none of the text browsers (lynx, w3m, elinks, eww) have
CSS support.  Barring any other HTML construct which would allow to hide
things by default for text browsers, all I can think of a plain
version in addition to a hip version.  That should be easy to
autogenerate, but it has all the problems attached to a alternative
version.

--
CYa,
  ⡍⠁⠗⠊⠕
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Jon Purdy
(Neglected to CC haskell-cafe, sorry Mario for the duplicate.)

The only plain-HTML solutions I’m aware of are the ‘title’ attribute and the HTML5 ‘<details>’ element. The latter may contain a ‘<summary>’ element for the content displayed by default, plus other content that the user can expand or collapse. Unfortunately, as far as I know Lynx doesn’t support either of these; not sure about other text browsers. In Lynx you could maybe get some nice UX for this with the ‘<fn>’ footnote element from HTML 3.0, but that’s deprecated and probably not supported in other browsers.

It doesn’t help with Lynx support, but I guess the right thing to do here for screenreader support in other browsers is to add the ‘tooltip’ role to the tooltip element, toggle its ‘hidden’ attribute with JavaScript to show and hide it, and use ‘aria-describedby’ / ‘aria-expanded’ on the anchor element to handle relating the two and announcing the tooltip correctly when it’s shown.


On Sat, Nov 14, 2020 at 4:20 PM Mario Lang <[hidden email]> wrote:
Alec Theriault <[hidden email]> writes:

> Although I’m sympathetic to the accessibility, in this case wouldn’t just
> directly opening the sources (in a text editor) be simpler?

Following a link to a definition is convenient because there is an
anchor.
Of course I can just open the original sources in a text editor.
But then I am no longer reading documentation, I am reading sources!

> Is there a (simple) way to preserve the experience when browsing using
> Lynx without also holding back features aimed at a regular browsing
> experience?

I was expecting this sort of killer argument.  I have to admit I am too
exhausted with this topic to try and give a meaningful answer.  There
used to be a time when compatibility to existing technology was a goal
by itself.  This is going away even in circles which usually have tried
to achieve some sort of technical excellence.  I am sad.  But I can not
do anything against the tides except for sometimes pointing at ships
while they are sinking, hoping to get someone to see reason and rescue
at least some of them.

Practically speaking, the problem is the visibility style attribute.  As
far as I know, none of the text browsers (lynx, w3m, elinks, eww) have
CSS support.  Barring any other HTML construct which would allow to hide
things by default for text browsers, all I can think of a plain
version in addition to a hip version.  That should be easy to
autogenerate, but it has all the problems attached to a alternative
version.

--
CYa,
  ⡍⠁⠗⠊⠕
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.

_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

M Douglas McIlroy
In reply to this post by Mario Lang-2
> I am pretty sure nobody writes code like this

> I confirmed your example, reading with lynx and w3m.

> wouldn’t just directly opening the sources (in a text editor) be simpler? Is there a (simple) way to preserve the experience when browsing using Lynx without also holding back features aimed at a regular browsing experience?

I second that.  I have always been annoyed by the ransom-note
appearance of colorized  listings. But that's just my taste. I
suspect, though, that lots of people have been frustrated when they
discover they can't  use the code they see because it's festooned with
markup. Golang.org offers similar listings, but also provides a button
for selecting the underlying plain text. I would like hackage a lot
better if it did so, too.

Doug
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Oleg Grenrus
About hiding some parts of the DOM tree with aria-hidden attribute.
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute

I'm :+1: to making accessibility-first designs / markup. We forgot that
completely when accepting new color scheme for haddock. The accessible
and pretty-looking are not in conflict, but not easy.

- Oleg

On 15.11.2020 17.19, M Douglas McIlroy wrote:

>> I am pretty sure nobody writes code like this
>> I confirmed your example, reading with lynx and w3m.
>> wouldn’t just directly opening the sources (in a text editor) be simpler? Is there a (simple) way to preserve the experience when browsing using Lynx without also holding back features aimed at a regular browsing experience?
> I second that.  I have always been annoyed by the ransom-note
> appearance of colorized  listings. But that's just my taste. I
> suspect, though, that lots of people have been frustrated when they
> discover they can't  use the code they see because it's festooned with
> markup. Golang.org offers similar listings, but also provides a button
> for selecting the underlying plain text. I would like hackage a lot
> better if it did so, too.
>
> Doug
> _______________________________________________
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.
Reply | Threaded
Open this post in threaded view
|

Re: Reading Haddock sources on hackage no longer possible with simple browsers?

Sebastiaan Joosten-3
I'm all for accessibility-first, but Oleg's solution won't help. Here's a test page for some features that are frequently discussed in this context:

Opening this in a browser shows the following content:

This content is perceivable by all browsers but should not be copiable by most.

The standard says this content should not be perceivable by screen readers.

This content is rendered via JavaScript and is not perceivable for those without JavaScript

Here's what Lynx users see (line-wraps are due to the width of my terminal):
   This content is perceivable by all browsers but should not be copiable
   by most.

   The standard says this content should not be perceivable by screen
   readers.

   The standard says this content is not perceivable, following the HTML
   hidden tag.

   The standard says this content is not perceivable, using CSS.

There are separate issues that passed this thread:
- on Lynx, some things that are tooltips are displayed inline, they should not be displayed at all
- using select+copy, some things are selected and copied (when I tried this in Chrome, this only happens if I copy while my mouse is over the Show/Eq element)
There is actually a third use-case to consider, namely brower+screenreader combinations. Using apple's screen reader with Safari simply reads the 'should not be perceivable' line to me as well.

Johannes created an issue for this here: https://github.com/haskell/haddock/issues/1250
I'll put my suggestions on how to fix this there.

Best,

Sebastiaan


On Sun, Nov 15, 2020 at 1:49 PM Oleg Grenrus <[hidden email]> wrote:
About hiding some parts of the DOM tree with aria-hidden attribute.
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-hidden_attribute

I'm :+1: to making accessibility-first designs / markup. We forgot that
completely when accepting new color scheme for haddock. The accessible
and pretty-looking are not in conflict, but not easy.

- Oleg

On 15.11.2020 17.19, M Douglas McIlroy wrote:
>> I am pretty sure nobody writes code like this
>> I confirmed your example, reading with lynx and w3m.
>> wouldn’t just directly opening the sources (in a text editor) be simpler? Is there a (simple) way to preserve the experience when browsing using Lynx without also holding back features aimed at a regular browsing experience?
> I second that.  I have always been annoyed by the ransom-note
> appearance of colorized  listings. But that's just my taste. I
> suspect, though, that lots of people have been frustrated when they
> discover they can't  use the code they see because it's festooned with
> markup. Golang.org offers similar listings, but also provides a button
> for selecting the underlying plain text. I would like hackage a lot
> better if it did so, too.
>
> Doug
> _______________________________________________
> Haskell-Cafe mailing list
> To (un)subscribe, modify options or view archives go to:
> http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
> Only members subscribed via the mailman list are allowed to post.
_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.

_______________________________________________
Haskell-Cafe mailing list
To (un)subscribe, modify options or view archives go to:
http://mail.haskell.org/cgi-bin/mailman/listinfo/haskell-cafe
Only members subscribed via the mailman list are allowed to post.