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

From: Sandy Ginoza <[email-masked]>
Date: Wed, 17 Jul 2019 23:19:19 -0700

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

---

From: Julian Reschke <[email-masked]>
Date: Thu, 18 Jul 2019 08:35:03 +0200

On 18.07.2019 08:19, Sandy Ginoza wrote:
 > ...

In
<https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3.html#name-authors-addresses>,
I see lines only containing commas. Somethings wrong with address
rendering...

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Thu, 18 Jul 2019 09:23:32 +0200

The HTML form has an intrusive tablet of contents that is hiding a third of each line, is hard to get rid of, and that reappears on the slightest scrolling.  The page is essentially unusable.  (Viewed on an iPhone)

Sent from mobile

> On 18. Jul 2019, at 08:19, Sandy Ginoza <[email-masked]> wrote:
> 
> Hi all,
> 
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
> 
>

---

From: Tom Pusateri <[email-masked]>
Date: Thu, 18 Jul 2019 12:12:57 -0400

I have commented before that I think it’s a bad idea to have the table of contents scroll separately in the html output. I think the table of contents should just flow down the page. Multiple scroll bars are really hard for accessibility.

Tom

> On Jul 18, 2019, at 3:23 AM, Carsten Bormann <[email-masked]> wrote:
> 
> On 18. Jul 2019, at 08:19, Sandy Ginoza <[email-masked] <mailto:[email-masked]>> wrote:
> 
>> Hi all,
>> 
>> https://www.ietf.org/id/draft-ietf-spring-segment-routing-msdc-11.txt <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.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.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.txt>
>> https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3..xml <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 <https://www.rfc-editor.org/v3test/draft-ietf-spring-segment-routing-msdc-11-MS.v2v3-xmldiff.html>
>> 
>> htmlwdiff:
>> https://www.ietf.org/id/draft-ietf-isis-l2bundles-07.txt <https://www.ietf.org/id/draft-ietf-isis-l2bundles-07.txt>
>> 
>> 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.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.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.txt>
>> https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.v2v3.xml <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 <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 <https://www.rfc-editor.org/v3test/draft-ietf-isis-l2bundles-07-SG.orignal.v2v3-htmlwdiff.html>
>> 
>> 
>> Thanks for your help!
>> Sandy
>> 
>> [email-masked] <mailto:[email-masked]>
>> https://www.ietf.org/mailman/listinfo/xml2rfc-dev <https://www.ietf..org/mailman/listinfo/xml2rfc-dev>
>> 
>>

---

From: "Martin Thomson" <[email-masked]>
Date: Sat, 20 Jul 2019 09:25:42 -0400

I only looked at the first example.

The table of contents overlay is not great for the reasons Carsten cited.  The spacing between items there is strange.

The references are similarly strangely formatted.  I think that is just the choice of really large anchor names [I-D.ietf-blablabla] rather than using shorter symbolic names though.

I don't like the choice of font, but I concede that this is subjective.

The use of small caps for the "(EDITOR)" designation is jarring.

The weight of the paragraph anchors is enough that it is very distracting.

Line lengths are too long.  https://typographyforlawyers.com/line-length.html

There are too many different font styles in use, particularly in the front matter.  The guidance we got from a professional designer is that you need to reduce the number of variations and that each change should only alter one thing (size, italic, bold, font, etc...)

There are also a bunch of things that are likely the result of problems in the source document.

The contributors section seems to be badly formatted in HTML.

The formatting of the insets in Section 4.2.1 is odd.

The indentation in Section 4.3 is odd.

Authors have errant commas.

The ordering of the trailing sections is a little hard to understand.  There are contributors, then references, then authors.

In comparison, https://quicwg.org/base-drafts/draft-ietf-quic-transport.html has none of these problems.  It also (subjectively) looks much nicer.

On Thu, Jul 18, 2019, at 02: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:
> 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.  
>

---

From: "Martin Thomson" <[email-masked]>
Date: Sun, 21 Jul 2019 13:55:07 -0400

Hi Sandy,

Heather tells me that these style sheets are on GitHub and requested that I provide assistance in the form of pull requests.

I'd love to do that, but I can't find them.  Would you mind pointing me (and the list) at the repository?

Cheers,
Martin

On Sat, Jul 20, 2019, at 09:25, Martin Thomson wrote:
> The table of contents overlay is not great for the reasons Carsten 
> cited.  The spacing between items there is strange.
> 
> The references are similarly strangely formatted.  I think that is just 
> the choice of really large anchor names [I-D.ietf-blablabla] rather 
> than using shorter symbolic names though.
> 
> There are too many different font styles in use, particularly in the 
> front matter.  The guidance we got from a professional designer is that 
> you need to reduce the number of variations and that each change should 
> only alter one thing (size, italic, bold, font, etc...)
> 
> The ordering of the trailing sections is a little hard to understand.  
> There are contributors, then references, then authors.
> 
> In comparison, 
> https://quicwg.org/base-drafts/draft-ietf-quic-transport.html has none 
> of these problems.  It also (subjectively) looks much nicer.
>

---

From: Tom Pusateri <[email-masked]>
Date: Sun, 21 Jul 2019 14:00:36 -0400

Martin,
	your version of the QUIC draft is very well done. I support merging your changes into the HTML template.

Tom

> On Jul 20, 2019, at 9:25 AM, Martin Thomson <[email-masked]> wrote:
>

---

From: Heather Flanagan <[email-masked]>
Date: Sun, 21 Jul 2019 14:06:08 -0400

Here you go:

https://github.com/rfc-format/draft-iab-rfc-css-bis/tree/master/docs

And than you in advance for your PRs!

-Heather

Sent from my iPad

> On Jul 21, 2019, at 13:55, Martin Thomson <[email-masked]> wrote:
> 
> Hi Sandy,
>

---

From: Sandy Ginoza <[email-masked]>
Date: Sun, 21 Jul 2019 11:17:54 -0700

Greetings all,

Thank you for reviewing the documents and for your feedback.  We will pass along the comments about the CSS to the RSE and we’ll report the xml2rfc issues.  

In the places where you think there may be issues with the underlying XML, we would appreciate your input on what you think the proper XML should be.  That will help us greatly as we continue to work with the v3 files.  

> The ordering of the trailing sections is a little hard to understand.  There are contributors, then references, then authors.

FYI - we did not edit the doc or move sections to their usual locations.  This exercise focuses on only the v3 format updates to facilitate review of the XML diff.  

Thanks!
Sandy

> On Jul 20, 2019, at 6:25 AM, Martin Thomson <[email-masked]> wrote:
>

---

From: Julian Reschke <[email-masked]>
Date: Sun, 21 Jul 2019 22:51:59 +0200

> The contributors section seems to be badly formatted in HTML.

Agreed, but I believe the core issue here is that there's no way in v3
to actually get the output the authors wanted (well, except for using
<artwork>).

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 22 Jul 2019 12:17:47 +0200

> to actually get the output the authors wanted (well, except for using

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

Best regards, Julian

---

From: "Martin Thomson" <[email-masked]>
Date: Thu, 01 Aug 2019 15:19:11 +1000

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

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

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.

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

The first sample has empty commas in author blocks.

The first sample puts the editor's name *after* affiliation.

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

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.

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.

Tables are captioned inconsistently across both documents.

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.

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

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

<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; }