Subject: [xml2rfc-dev] Please help review v3 file: draft-ietf-roll-efficient-npdao-15

From: Sandy Ginoza <[email-masked]>
Date: Mon, 5 Aug 2019 14:16:47 -0700

Hi again,

Continuing with our request to review XMLv3 files, we’d appreciate your input regarding draft-ietf-roll-efficient-npdao-15.  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.  

NOTE: We are aware there is an issue w/ sectionFormat (e.g., it causes text to disappear in Section 4.3.2 of this document). This issue has been reported.

A couple of other 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 related to draft-ietf-roll-efficient-npdao-15: 

https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.html <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.html>
https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.pdf <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.pdf>
https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.txt <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.txt>
https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.xml <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.xml>

Diff files:
https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-xmldiff.html <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-xmldiff.html>
https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-htmlwdiff.html <https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-htmlwdiff.html>

Thanks,
Sandy

---

From: Tom Pusateri <[email-masked]>
Date: Mon, 5 Aug 2019 17:35:23 -0400

After a quick glance, I can report two issues with the HTML version from my iPad running Safari iOS 12.4 (latest):

1. Scrolling downward in the table of contents causes the TOC to disappear
2. This exchange with Heather back in February pointed out an issue that in the Section links, it would be nice to have those go directly to the referenced document at the correct section. Heather agreed that there could be two links when a section is listed (one from the Section N to the external document and one from the RFC reference to the references section of the existing document.) See exchange attached below:

TJP: It would be nice if links to other RFCs would just go directly to the RFC instead of the reference section. This multi-step process doesn’t seem to serve any purpose.

Heather: I think it’s actually fairly important to keep the citation pointing to the reference section. But I think it would be reasonable (and I admit I don’t remember if this is how it works, which is a little embarrassing) for pointers to specific sections (beyond the citation) could reasonably point to the other RFC. And, if it’s a v3 to v3 pointer, it should point to the section/paragraph within the RFC.

TJP: The engineer in me wants to know why it’s fairly important to keep the citation pointing to the reference section. It seems like an extra level of indirection to me and a poor use of HTML.

Heather: Good question, Tom.  Here’s my logic:

Because it provides the context, often better than authors do in the text, about what exactly the person is going to see, whether it is normative information they must have, and given the link that is in the reference section it will also take you to the info page that includes the information on whether there are errata associated with the document you’re about to see.

TJP: Heather,

Thanks for the explanation. Since that information is mostly available on the header of the document you are referred to, how about a compromise?

In the case where a reference is “Section 3.1 of RFC 2136” could this be broken up into two links? “Section 3.1” is one link that goes directly to RFC 2136 section 3.1 and RFC 2136 is another link that goes to the reference section as you would like?

When a reference is simply “RFC 2136”, then it only goes to the reference section.

Heather: I’m pretty ok with that. Let me take this to the developer and see if it’s easy to fit in now, or if it’s something we’d need to add in later.

Good suggestion!

Heather

> On Aug 5, 2019, at 5:16 PM, Sandy Ginoza <[email-masked]> wrote:
> 
> Hi again,
> 
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.html
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.pdf
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.txt
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3.xml
> 
> Diff files:
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-xmldiff.html
> https://www.rfc-editor.org/v3test/draft-ietf-roll-efficient-npdao-15-RE.v2v3-htmlwdiff.html
> 
> 
> Thanks,
> Sandy 
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev

---

From: "Martin Thomson" <[email-masked]>
Date: Tue, 06 Aug 2019 09:19:02 +1000

Restyled: https://martinthomson.github.io/i-d-template/sample3.html

Another HTML bug: <a href="#figure-5">Figure 5</a> or <a href="#table-4">Table 4</a> would be much easier to style if it had class="selfRef" like all the other such instances. I have a ton of special rules just to correctly style those elements without affecting other links.

On Tue, Aug 6, 2019, at 07:17, Sandy Ginoza wrote:
> Hi again,
> 
> Continuing with our request to review XMLv3 files, we’d appreciate your 
> input regarding draft-ietf-roll-efficient-npdao-15. 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. 
> 
> NOTE: We are aware there is an issue w/ sectionFormat (e.g., it causes 
> text to disappear in Section 4.3.2 of this document). This issue has 
> been reported.
> 
> A couple of other notes:

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 6 Aug 2019 17:30:59 +0200

Hi Martin,

On 2019-08-06 01:19, Martin Thomson wrote:
> Another HTML bug: <a href="#figure-5">Figure 5</a> or <a
> href="#table-4">Table 4</a> would be much easier to style if it had
> class="selfRef" like all the other such instances. I have a ton of
> special rules just to correctly style those elements without
> affecting other links.

Ack.  class="selfRef" will be set on these in the next release.

	Henrik