Subject: [xml2rfc-dev] [v3] Please help review v3 files

From: Sandy Ginoza <[email-masked]>
Date: Fri, 2 Aug 2019 13:05:29 -0700

Hi Martin,

> On Jul 31, 2019, at 10:19 PM, Martin Thomson <[email-masked]> wrote:
> 
> Hi Sandy,
> 
> I've been looking at the stylesheet.  Is https://github.com/rfc-format/draft-iab-rfc-css-bis still the right place to go for that?  It looks like the issues list hasn't had any attention in some while, despite some of the issues having been addressed (I found and closed one).  If that is the right place to go, I'll submit a pull request with what I have.
> 
> You can see the work in progress here: https://martinthomson.github.io/i-d-template/sample.html and https://martinthomson.github.io/i-d-template/sample2.html

Great - thanks for working on this!  I saw that Henrik provided info about where the current CSS lives.  

Because you’re looking at improving the CSS, I’m hoping you will take a look at a few items our team has uncovered: 

a) one of the things we talked about is making the RFC number stand out somehow.  Right now it’s getting lost and because there are no longer page headers/footers, it’s the only place where the RFC number appears.  Henrik had some suggestions about how to do this, but I don’t think any final decisions were made.  

b) as you noted below, longer URLs are getting truncated by the toc in the HTML/PDF (the text file is ok).  No matter how wide I make my screen, I can’t see the full URL and I can’t scroll right. [Note, however: it is possible to scroll right if the window is smaller, so that the TOC doesn’t appear on the right.]  More info below.

There are examples of this in https://martinthomson.github.io/i-d-template/sample.html

There is another example here:
https://www.rfc-editor.org/v3test/draft-ietf-sipcore-rejected-09-LB.v2v3-snapshot.html
https://www.rfc-editor.org/v3test/draft-ietf-sipcore-rejected-09-LB.v2v3-snapshot.xml

c) potentially add a line break after long citation tags in the references section.  

> In addition to the stylesheet, I have found several problems with content.  These would need changes in xml2rfc to fix.

Great - thank you for reviewing and providing comments!  

> To aid in styling, these probably need to include <meta name="viewport" content="initial-scale=1.0"> in the <head>.  Viewing the html on a phone does strange things to certain elements.  For instance, <dt> is oddly shrunken on my phone.

Ok - I will pass this request along to Henrik. 

> In the second document there are several cases of
> <span class="bcp14">MUST</span> NOT
> where the "NOT" needs to be under the span.

Ahhh!  Good point!  The issue is in th XML file — I’ll see about updating the script for tagging the 2119 keywords updated.  

> The first sample has empty commas in author blocks.
> The first sample puts the editor's name *after* affiliation.

Right - we’ve been discussing this with Henrik and Heather.  Currently, I believe the display changes depending on what country the authors lists. 

> Figure 3 in the first sample has a pilcrow after the figure, where other figures don't.  

Ack - I see the issue in the XML file; fixed in my copy. 

> I see that there is a blank line for a pilcrow for all figures without captions.  This might be fixed with styling, but I haven't done that yet as it changes the width of those images.

I’ll ask Henrik about this one. 
I thought I could get rid of the pilcrows using the same fix as fig 3; it didn't work.  

> Section 3.1 of the second sample has some very odd formatting.  It has lots of indentation of varying sizes, and some blank lines that I can't really grok.  Maybe it looks OK in text, but the HTML is hard to look at.

Agree - I think we can make this better by updating the XML a bit differently.  
This is part of a discussion we’ve having with Heather regarding whether we need to use the seemingly right list style vs get the right display.  

> Tables are captioned inconsistently across both documents.

I think this refers to whether or not the tables have titles consistently? 

For the second example, our understanding is that table numbering is required so they could be referred to easily from other sections/documents, but titles are not required.  The original document did not provide titles for each of the tables.  We’ll talk to Heather about this one - seems like we could make a recommendation in the Style Guide. 

In the first example, we missed a title when converting the artwork to tables.  Great catch!  

> The contributors section in both documents looks terrible in HTML.   Probably because there is no defined way to add contributors in a way that renders in a manner consistent with authors in text formats, so the authors choose to use <pre>/<artwork> for that section.  We need to fix that somehow.

Right - that was the only way we could get the info to display similar to Authors’ Addresses.  
We will discuss this.

> Not sure whether this is a styling issue, but refusing to wrap links does odd things like add horizontal scrolling on narrow screens.

We asked Henrik about this one; he believes it’s a styling issue because the formatter should not be breaking the URLs.  Please let us know if you disagree. 

> The script for managing the ToC on a narrow screen is much more complex than it needs to be.  Here is what I did:

I had not looked at the HTML on a small device, so I’m not sure how bad the display was previously.  I looked at your samples on my phone, and the ToC handling looks good.  

Again, thanks for your input!  

Sandy 

> 
> <script>
> const toc = document.getElementById("toc");
> toc.querySelector("h2").addEventListener("click", e => { toc.classList.toggle("active"); });
> toc.querySelector("nav").addEventListener("click", e => { toc.classList.remove("active"); });
> </script>
> 
> with styles to support that:
> #toc nav { display: none; } /*already present*/
> #toc.active nav { display: block; }
> 
> 
> On Thu, Jul 18, 2019, at 16:19, Sandy Ginoza wrote:
>> Hi all,
>> 
>> As you know, the transition to XMLv3 is quickly approaching.  As part 
>> of our preparation, the RPC is  converting some XMLv2 files to XMLv3.  
>> We’re hoping some of you will take the time to review the files and 
>> provide feedback regarding whether the updates are as expected and the 
>> XMLv3 files are considered “good” v3 files.  
>> 
>> A couple of notes:
>> - we focused on format only; we did not make editorial updates. 
>> - the diff files compare the initial v2v3 output with the files we edited.
>> 
>> Please review the following files:
>> 
>> 1) draft-ietf-spring-segment-routing-msdc
>> https://www.ietf.org/id/draft-ietf-spring-segment-routing-msdc-11.txt
>> 
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3.html
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3.pdf
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3.txt
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3.xml
>> 
>> rfc-xmldiff:
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3-xmldiff.html
>> 
>> htmlwdiff:
>> file:///Volumes/rfcpa/inc-work/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3-htmlwdiff.html
>> 
>> 
>> 2) draft-ietf-isis-l2bundles
>> https://www.ietf.org/id/draft-ietf-isis-l2bundles-07.txt
>> 
>> Please pay particular attention to lists and the use of <aside>.  We 
>> experimented with list styles and used <aside> for notes.  Using 
>> <aside> in this way required some changes because <aside> can’t be used 
>> within lists.  
>> 
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.v2v3.html
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.v2v3.pdf
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.v2v3.txt
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.v2v3.xml
>> 
>> rfc-xmldiff:
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.orignal.v2v3-xmldiff.html
>> 
>> htmlwdiff:
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.orignal.v2v3-htmlwdiff.html
>> 
>> 
>> Thanks for your help!
>> Sandy
>> 
>> _______________________________________________
>> xml2rfc-dev mailing list
>> [email-masked]
>> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>> 
> 
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev

---

From: Julian Reschke <[email-masked]>
Date: Sat, 3 Aug 2019 14:51:22 +0200

Am 02.08.2019 um 22:05 schrieb Sandy Ginoza> ...
> ...

That is indeed a problem, not only visually, but also with respect to
how search engines find RFCs. Maybe it should just be added to the
document title ("RFC xxxx: ....").

> ...
> ...

And that's a deviation from RFC 799x that really needs more discussion.

> ... >> I see that there is a blank line for a pilcrow for all figures
without captions.  This might be fixed with styling, but I haven't done
that yet as it changes the width of those images.
> ...

Placing pilcrows after block level objects is tricky; if we can't get it
right, we seriously should consider not to do it at all.

> ... >> The contributors section in both documents looks terrible in HTML.
Probably because there is no defined way to add contributors in a way
that renders in a manner consistent with authors in text formats, so the
authors choose to use <pre>/<artwork> for that section.  We need to fix
that somehow.
> Right - that was the only way we could get the info to display similar to Authors’ Addresses.

Please discuss here:
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/81>

 > ...

Best regards, Julian

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 05 Aug 2019 10:47:46 +1000

On Sat, Aug 3, 2019, at 06:05, Sandy Ginoza wrote:
> a) one of the things we talked about is making the RFC number stand out 
> somehow.  Right now it’s getting lost and because there are no longer 
> page headers/footers, it’s the only place where the RFC number appears. 
>  Henrik had some suggestions about how to do this, but I don’t think 
> any final decisions were made.  

I don't think that this is necessary.
 
> b) as you noted below, longer URLs are getting truncated by the toc in 
> the HTML/PDF (the text file is ok).  No matter how wide I make my 
> screen, I can’t see the full URL and I can’t scroll right. [Note, 
> however: it is possible to scroll right if the window is smaller, so 
> that the TOC doesn’t appear on the right.]  More info below.

I found the offending style rule.  This was clearly an intentional decision by the original designer.  I didn't revert that change, but will do so based on your feedback.  It's not like you need the text of the link to know where it points to in HTML.

> c) potentially add a line break after long citation tags in the 

That's something that I've wanted to know how to do for a long time.  My CSS chops are fairly primitive, so maybe there is a way, but I just don't know how.  The fix here, at least in my opinion, is to use shorter tags.  In kramdown-rfc2629, you construct links using {{?SHORT-TAG=I-D.ietf-some-really-long-draft-name}}.  The same is possible in XML, but it's been too long since I did any of that for me to remember.

> This is part of a discussion we’ve having with Heather regarding 
> whether we need to use the seemingly right list style vs get the right 
> display.  

I think that the problem here adjacent lists and <aside>, which have similar styling, except that <aside> is given extra padding above and below.  It's almost like this could benefit from reducing the variance in spacing and using other styling to denote <aside>, like italics.

Regarding the pilcrow on uncaptioned figures, it might be possible to put the pilcrow beside the figures if they could be narrowed relative to the page.  The current design allows 70 column figures with essentially no additional space, so that would be a very disruptive change to the entire design.

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 6 Aug 2019 23:03:06 +0200

Hi Sandy, Martin,

On 2019-08-02 22:05, Sandy Ginoza wrote:
>> I see that there is a blank line for a pilcrow for all figures
>> without captions.  This might be fixed with styling, but I haven't
>> done that yet as it changes the width of those images.

> I thought I could get rid of the pilcrows using the same fix as fig

These figures are plain artwork.  I've tested adding this CSS after the
a.pilcrow {} stanza:

  .artwork .pilcrow {
    float: right;
  }

and moving the pilcrow up before the <pre>; that gives a pilcrow to the
right of the artwork, without reducing the artwork width.  Would that
work for you?

Regards,

	Henrik

---

From: "Martin Thomson" <[email-masked]>
Date: Wed, 07 Aug 2019 13:13:43 +1000

> right of the artwork, without reducing the artwork width. Would that

What I did instead (and you can see that here: https://martinthomson.github.io/i-d-template/sample2.html#section-appendix.a-26) is make <pre> outside of <figure> use inline-block.  I'd use flexbox, but apparently that isn't available.

There's lots of reasons not to use float, and keeping the pilcrow after the paragraph is better from a content-model perspective.

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 7 Aug 2019 13:51:33 +0200

Hi Martin,

On 2019-08-07 05:13, Martin Thomson wrote:
> What I did instead (and you can see that here:
> https://martinthomson.github.io/i-d-template/sample2.html#section-appendix.a-26)
> is make <pre> outside of <figure> use inline-block. I'd use flexbox,
> but apparently that isn't available.

Right.

However, it seems to me that this will make the bare <artwork> narrower than
figure artwork, which is a concern.

> There's lots of reasons not to use float

What are those?  Modern style frameworks like bootstrap 4 uses float to good
effect, and I seem to remember that when float was introduced it was hailed
as a good thing.

>, and keeping the pilcrow
> after the paragraph is better from a content-model perspective.

You'll have to say more to give me a sense of why it's actually better?

I'll agree that a placement at the end matches user expectancy better, but
that's of course hard if you don't want it floating right, and don't want
the blank line.

	Henrik