Subject: [rfc-i] Update on the CSS - second round

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Tue, 21 Feb 2017 07:52:12 +0100

Hello all,

Back in December, you all had an opportunity to review the first draft
of the CSS that will be applied to the HTML RFCs that will be produced
by the RFC Editor when the new formats go live. Issues were collected in
github, either by individuals who posted directly, or by me as I
harvested issues out of various email threads. You can see the issues here:

https://github.com/rfc-format/draft-iab-rfc-css-bis/issues

Based on the issues collected (with some decisions from me where we had
contradictory input) the CSS developer has built a second version of the
CSS. You can see the new look here:

https://rfc-format.github.io/draft-iab-rfc-css-bis/

One of the basic changes includes the addition of a very simple
JavaScript was added to allow for a hamburger menu to appear when the
screen is resized such that the ToC disappears. This JavaScript is not
critical to the reading of the text, and so would be allowed.    

For the issues in github, the following actions were (or were not) taken:

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/17

      o

        [DONE - set table p to margin 0]

      o

        Too much v-space in tables

      o

        NOTE: Seems like significant over-selection; would be better to
        select on a class.

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/16

      o

        [DONE - fixed the lists]

      o

        Levels of indentations for lists from headings

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/15

      o

        [WON'T DO - See #10]

      o

        Increase body indent from headings

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/10

      o

        [DONE - indentation removed]

      o

        Don’t have body indent from headings

      o

        NOTE: is in contradiction to #15

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/8

      o

        [DONE]

      o

        Padding on aside too large (particularly vertically)

      o

        FIXED: remove most padding from aside.

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/7

      o

        [NO CHANGE - kept as is, allowing columns for the Index section
        except on small devices]

      o

        Index in columns

      o

        NOTE: glad that this appears to be supported.  I would like to
        keep columns.

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/6

      o [DONE *- *fixed monospace font sizes]

      o

        Heading with a monospace item in it

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/4

      o [DONE for small devices where the menu will hang over the page
        content; wide widths have no divider (to remain uncluttered)]**

      o

        Visual separation between draft and TOC

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/3

      o [NO CHANGE - prefer the margin + border to ensure blockquote
        stands out]

      o

        Frame + border seems too much for blockquote

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/2

      o [NO CHANGE - paragraph spacing easier to see using real examples
        of sample2.html and sample3.html - we should wait for feedback
        on this now that the community can see what the paragraph
        spacing looks like in practice]

      o

        Paragraph spacing too large

  *

    https://github.com/rfc-format/draft-iab-rfc-css-bis/issues/1

      o

        [DONE - headings decreased in size both in desktop and mobile
        versions]

      o

        Headings too large

Please take a moment to look at the slightly updated design, and to post
your feedback either to this list or directly to github. I’m expecting
the third (and final, for now) set of changes to focus on polishing the
details of the look and feel.

Thank you for your time and attention!

-- 
Heather Flanagan

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Ted Lemon <[email-masked]>
Date: Tue, 21 Feb 2017 10:21:01 -0500

One issue that I noticed when playing with sample 3 is that scrolling the table of contents starts scrolling the document when you get to the end.   This is a bit of a usability problem, but I don't know if there's a way to fix it in the CSS.   The reason it's a usability problem is that a single flick on the TOC gets you to the end, and the momentum carries over to the document, resulting in a substantial scroll of the document.   The two should be completely independent; otherwise, the utility of the TOC is limited, because I'm going to tend to shy away from using it for fear of losing my place in the document.

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 22 Feb 2017 10:29:17 +1300

A tiny detail: in the References sections, the citation labels
are right-aligned, which looks strange and makes visual searching
slightly painful. I think they should be left-aligned.

Example:
https://rfc-format.github.io/draft-iab-rfc-css-bis/sample2-v2.html#n-informative

There are also two specific issues with the very first reference there:
1) the infamous double-comma problem; I hoped we would be rid of that
2) the reference label is too long. At least there should be a style guide
warning about this.

Regards
   Brian

---

From: "Andrew G. Malis" <[email-masked]>
Date: Tue, 21 Feb 2017 17:34:24 -0500

Ted,

The behavior may be browser-specific. In Firefox on a Mac, I found that
scrolling the TOC using the scroll bar or arrow keys would be completely
confined to the TOC. If I used two-finger scrolling, an initial scroll
would be confined to the TOC, even if I did a big flick to get to the end,
and I then had to do a completely separate scroll operation to start the
main text scrolling, with the cursor still in the TOC.

Cheers,
Andy

On Tue, Feb 21, 2017 at 10:21 AM, Ted Lemon <[email-masked]> wrote:

> One issue that I noticed when playing with sample 3 is that scrolling the
> table of contents starts scrolling the document when you get to the end.
>  This is a bit of a usability problem, but I don't know if there's a way to
> fix it in the CSS.   The reason it's a usability problem is that a single
> flick on the TOC gets you to the end, and the momentum carries over to the
> document, resulting in a substantial scroll of the document.   The two
> should be completely independent; otherwise, the utility of the TOC is
> limited, because I'm going to tend to shy away from using it for fear of
> losing my place in the document.
>

---

From: "Andrew G. Malis" <[email-masked]>
Date: Tue, 21 Feb 2017 17:38:24 -0500

Heather,

This is very nicely readable on my iPhone. My only comment is that the
indent on the references leaves a lot of white space when holding the
screen in portrait orientation, perhaps just the first line should have the
full indent.

Thanks,
Andy

On Tue, Feb 21, 2017 at 1:52 AM, Heather Flanagan (RFC Series Editor) <
[email-masked]> wrote:

> Hello all,
>
> Back in December, you all had an opportunity to review the first draft of
> the CSS that will be applied to the HTML RFCs that will be produced by the
> RFC Editor when the new formats go live. Issues were collected in github,
> either by individuals who posted directly, or by me as I harvested issues
> out of various email threads. You can see the issues here:
>
> One of the basic changes includes the addition of a very simple JavaScript
> was added to allow for a hamburger menu to appear when the screen is
> resized such that the ToC disappears. This JavaScript is not critical to
> the reading of the text, and so would be allowed.
>
>    -
>    -
>       -
>       -
>       -
>    -
>       -
>       -
>    -
>       -
>       -
>    -
>       -
>       -
>       -
>    -
>       -
>       -
>       -
>    -
>       -
>       -
>       NOTE: glad that this appears to be supported.  I would like to keep
>       columns.
>       -
>
>    - [DONE *- *fixed monospace font sizes]
>
>       -
>
>       -
>    - [DONE for small devices where the menu will hang over the page
>       content; wide widths have no divider (to remain uncluttered)]
>
>       -
>
>       -
>    - [NO CHANGE - prefer the margin + border to ensure blockquote stands
>       out]
>
>       -
>
>       -
>    - [NO CHANGE - paragraph spacing easier to see using real examples of
>       sample2.html and sample3.html - we should wait for feedback on this now
>       that the community can see what the paragraph spacing looks like in
>       practice]
>
>       -
>
>       -
>    -
>       -
> your feedback either to this list or directly to github. I’m expecting the
> third (and final, for now) set of changes to focus on polishing the details
> of the look and feel.
>

---

From: Ted Lemon <[email-masked]>
Date: Tue, 21 Feb 2017 17:54:23 -0500

On Feb 21, 2017, at 5:34 PM, Andrew G. Malis <[email-masked]> wrote:
> The behavior may be browser-specific. In Firefox on a Mac, I found that scrolling the TOC using the scroll bar or arrow keys would be completely confined to the TOC. If I used two-finger scrolling, an initial scroll would be confined to the TOC, even if I did a big flick to get to the end, and I then had to do a completely separate scroll operation to start the main text scrolling, with the cursor still in the TOC.

I'm using Chrome on Sierra, and using the trackpad to scroll.

---

From: Martin Thomson <[email-masked]>
Date: Wed, 22 Feb 2017 12:52:05 +1100

On 22 February 2017 at 02:21, Ted Lemon <[email-masked]> wrote:
> One issue that I noticed when playing with sample 3 is that scrolling the table of contents starts scrolling the document when you get to the end.   This is a bit of a usability problem, but I don't know if there's a way to fix it in the CSS.

I am not enough of an expert here, but I think that's a fundamental
problem with CSS that probably doesn't get fixed easily.  The best I
could suggest is to add a moderately large pad to the bottom of the
TOC/
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Martin Thomson <[email-masked]>
Date: Wed, 22 Feb 2017 13:05:58 +1100

> https://rfc-format.github.io/draft-iab-rfc-css-bis/

Hi Heather,

I checked these out on phone (with a decently large screen), desktop,
and print preview.  These are all massive improvements and you seem to
have found good resolutions to the issues I raised, thanks.

I don't think that the change to use Javascript for the table of
contents on narrow views is an improvement.  It effectively removes
the TOC from the document.  As a regular reader of these things, I
need to see the table of contents.  Having to click or tap ruins that,
especially since the button is on the very edge of what I can easily
hit with my fat digits.

On narrower screens, leaving the TOC inline (where it would otherwise
appear in the text version) is better.  The little hamburger icon
could then be a link to the TOC.  That wouldn't require Javascript
either, though that's not my overriding concern.

The other issues that I saw were all problems with the source.  For
instance, the double-comma Brian observed was in the HTML source and
easily corrected.  The precis document also uses something that
appears to be a badly formatted definition list in the IANA
considerations, but that turns out to be straightforward text with
irregular spacing.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Dave Thaler <[email-masked]>
Date: Wed, 22 Feb 2017 02:53:32 +0000

Besides the double-comma issue, there's issues of spaces before commas in a number of the references (most obvious one being in RFC2811).
But that's also in the HTML source as Martin said.

-----Original Message-----
From: rfc-interest [mailto:[email-masked]] On Behalf Of Martin Thomson
Sent: Tuesday, February 21, 2017 6:06 PM
To: Heather Flanagan (RFC Series Editor) <[email-masked]>
Cc: [email-masked]
Subject: Re: [rfc-i] Update on the CSS - second round

Hi Heather,

I checked these out on phone (with a decently large screen), desktop, and print preview.  These are all massive improvements and you seem to have found good resolutions to the issues I raised, thanks.

I don't think that the change to use Javascript for the table of contents on narrow views is an improvement.  It effectively removes the TOC from the document.  As a regular reader of these things, I need to see the table of contents.  Having to click or tap ruins that, especially since the button is on the very edge of what I can easily hit with my fat digits.

On narrower screens, leaving the TOC inline (where it would otherwise appear in the text version) is better.  The little hamburger icon could then be a link to the TOC.  That wouldn't require Javascript either, though that's not my overriding concern.

The other issues that I saw were all problems with the source.  For instance, the double-comma Brian observed was in the HTML source and easily corrected.  The precis document also uses something that appears to be a badly formatted definition list in the IANA considerations, but that turns out to be straightforward text with irregular spacing.

---

From: "Andrew G. Malis" <[email-masked]>
Date: Wed, 22 Feb 2017 08:19:55 -0500

Martin (and Heather),

I completely disagree regarding the TOC on small screens. I like that
wherever I am in the document, I can open the TOC, refer to it, scroll it
up and down, and then if I close it without clicking on a link, I’m back in
the exact same place in the document.

That said, in Sample 3 v2, I’m also seeing the TOC scrolling bug in Safari
on my iPhone 6s. If I scroll the TOC beyond its limits (either up or down),
the main document starts to scroll.

One other small bug with the hamburger TOC button - as you scroll up on the
main document, the hamburger icon slowly scrolls up as well, and less and
less of it is visible the further down you go in the document. When I reach
the bottom of the document, the button almost completely disappears.

One other TOC bug I noticed on the iPhone - if I’m reading, say, section
2.1, then use the TOC to jump to section 5, if I then use the browser’s
“back” button, I leave the document rather than go back to section 2.1.
However, this works correctly on Firefox on my Mac - the back button takes
me back to section 2.1.

Cheers,
Andy

---

From: Sam Whited <[email-masked]>
Date: Tue, 28 Feb 2017 14:40:13 -0600

On Wed, Feb 22, 2017 at 7:19 AM, Andrew G. Malis <[email-masked]> wrote:
> wherever I am in the document, I can open the TOC, refer to it, scroll it up
> and down, and then if I close it without clicking on a link, I’m back in the
> exact same place in the document.

Hi all,

I don't often comment on IETF related things, and I'm sure this has
been discussed to death, but I wanted to point out that this is
*always* a problem any time JavaScript based menues are used, and
though I agree that it's nice to be able to quickly get to the TOC
from anywhere, I don't think we should add this feature if JavaScript
has to be involved.

How many times have you gone to a site, moused over a menu, gotten a
JavaScript drop down, moved the mouse down onto it only to have the
menu dissapear before you could click anything? Or had it not work on
mobile? Or had it break on <your browser of choice> but not <your
friends browser of choice? With my XMPP Editor hat on: Even with the
tiny snippet of JavaScript we use at the XMPP Standards Foundation to
do syntax highlighting in XEPs is *constantly* broken due to small
edge cases; this can cause readability issues, but it's far less
important than a table of contents in documents used by people all
over the world in different contexts and environments.

I too love the idea of having a table of contents that doesn't require
me to scroll all the way up, and there very well may be a way to do
this in such a way that it will work everywhere, but in general I
suspect that it's going to be more trouble than it's worth for a
feature that isn't all that important in the end. Being able to see
the TOC is critical, being able to get to it quickly is just nice.
Since the usability of the TOC could be broken by this change (and
almots certainly will be for someone, no matter how many iterations we
do on the script), I really think we should ge rid of it (not that I'm
involved or really have any say; just my two cents).

Thanks for doing all this work on the new format; I'm really looking
forward to seeing it in the wild!

Best,
Sam

TL;DR — JavaScript menus always sound like a good idea, but then just
end up annoying half the people who want to read your document.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Martin Thomson <[email-masked]>
Date: Wed, 1 Mar 2017 12:01:12 +1100

> exact same place in the document.

It's very easy to offer a link to the TOC that hovers over the page,
then - as long as your browser offers a functional back button - you
can return to what you were reading by hitting that button.

There's no perfect solution, but the consequence of the current
proposed design is that you don't see the TOC without tapping.  I'm
suggesting exactly the same number of taps for your use case, no
overscroll "bug", and no javascript.

p.s., That back button behaviour could be a product of javascript
overuse.  Hitting back should move between anchors on the same page.
It could be a Safari bug though, for which I'd recommend using a
different browser.  Of course, that might not help much, because it's
all really Safari anyway, but these things are usually outside of the
rendering engine.
_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest