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

Hi Martin,

> On Jul 31, 2019, at 10:19 PM, Martin Thomson <mt@lowentropy.net> 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
>> xml2rfc-dev@ietf.org
>> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>> 
> 
> _______________________________________________
> xml2rfc-dev mailing list
> xml2rfc-dev@ietf.org
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev