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

[Sandy Ginoza <[e-mail]>]

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.  


Martin - regarding:

> 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 <[e-mail]> wrote:
> 
> 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:
>> - 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
>> [e-mail]
>> https://www.ietf.org/mailman/listinfo/xml2rfc-dev
>> 
> 
> _______________________________________________
> xml2rfc-dev mailing list
> [e-mail]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev