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

Tom Pusateri <pusateri@bangj.com> Mon, 05 August 2019 21:35 UTC

Return-Path: <pusateri@bangj.com>
X-Original-To: xml2rfc-dev@ietfa.amsl.com
Delivered-To: xml2rfc-dev@ietfa.amsl.com
Received: from localhost (localhost [127.0.0.1]) by ietfa.amsl.com (Postfix) with ESMTP id F17EB1202D9 for <xml2rfc-dev@ietfa.amsl.com>; Mon, 5 Aug 2019 14:35:27 -0700 (PDT)
X-Virus-Scanned: amavisd-new at amsl.com
X-Spam-Flag: NO
X-Spam-Score: -1.998
X-Spam-Level:
X-Spam-Status: No, score=-1.998 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, HTML_MESSAGE=0.001, MIME_QP_LONG_LINE=0.001, SPF_PASS=-0.001, URIBL_BLOCKED=0.001] autolearn=ham autolearn_force=no
Authentication-Results: ietfa.amsl.com (amavisd-new); dkim=pass (2048-bit key) header.d=bangj.com
Received: from mail.ietf.org ([4.31.198.44]) by localhost (ietfa.amsl.com [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id P-qXaGOKZjYc for <xml2rfc-dev@ietfa.amsl.com>; Mon, 5 Aug 2019 14:35:26 -0700 (PDT)
Received: from oj.bangj.com (69-77-154-174.static.skybest.com [69.77.154.174]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by ietfa.amsl.com (Postfix) with ESMTPS id 199BC12008A for <xml2rfc-dev@ietf.org>; Mon, 5 Aug 2019 14:35:26 -0700 (PDT)
Received: from [172.16.25.117] (69-77-155-155.static.skybest.com [69.77.155.155]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by oj.bangj.com (Postfix) with ESMTPSA id 385C031843; Mon, 5 Aug 2019 17:35:24 -0400 (EDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=bangj.com; s=201907; t=1565040924; bh=0TPSVhOuT4yuw0a85OUpscgZoqG/t1qnFm0KLiHBudI=; h=Subject:From:In-Reply-To:Date:Cc:References:To:From; b=gW1VADvcGubEbb4viYAAYPwRNaqpoAP3Hckrh/ZbHWwvEk8NwsTQvFPdYmufKDjMD A+28d4BMI7DeuNqpcBzuhDsUOKntlGSCAL4B0YxVKFI+cOW6i8pgZEv3NfAMmY2Kgg yCOmBHSiQEEeHFlKNG22wWL2g05+ONCzIlfYN+cbRk2srqrGdf0kjtbLoLxCI1TJ6N OLDX+PBuTuD/76XBl0NJ0asUiqIYjbRfNiwuiCpbJrzmq1L8cUbO2YvgAyXwjPE6ej qiYdoFH00LBsGEVptQwY4+jIYeRc/rtdQfGfccQ0o49QnGn1Q1rg+pA0qND7w5MAXE R8XdlihTDQ4Fg==
Content-Type: multipart/alternative; boundary="Apple-Mail-90B5A6D4-0E18-4FE2-BC69-F9E51771D303"
Mime-Version: 1.0 (1.0)
From: Tom Pusateri <pusateri@bangj.com>
X-Mailer: iPad Mail (16G77)
In-Reply-To: <21700B17-8C83-4F58-932B-A713684FFE20@amsl.com>
Date: Mon, 05 Aug 2019 17:35:23 -0400
Cc: xml2rfc-dev@ietf.org, RFC Editor <rfc-editor@rfc-editor.org>
Content-Transfer-Encoding: 7bit
Message-Id: <59A9FCA3-4B86-484A-9D3B-B9CE3D1FECE9@bangj.com>
References: <21700B17-8C83-4F58-932B-A713684FFE20@amsl.com>
To: Sandy Ginoza <sginoza@amsl.com>
Archived-At: <https://mailarchive.ietf.org/arch/msg/xml2rfc-dev/_owDvUi3JTPGCGQ4vd7s14-UOPY>
Subject: Re: [xml2rfc-dev] Please help review v3 file: draft-ietf-roll-efficient-npdao-15
X-BeenThere: xml2rfc-dev@ietf.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: "Discussion about particulars of xml2rfc V3 design, development and code." <xml2rfc-dev.ietf.org>
List-Unsubscribe: <https://www.ietf.org/mailman/options/xml2rfc-dev>, <mailto:xml2rfc-dev-request@ietf.org?subject=unsubscribe>
List-Archive: <https://mailarchive.ietf.org/arch/browse/xml2rfc-dev/>
List-Post: <mailto:xml2rfc-dev@ietf.org>
List-Help: <mailto:xml2rfc-dev-request@ietf.org?subject=help>
List-Subscribe: <https://www.ietf.org/mailman/listinfo/xml2rfc-dev>, <mailto:xml2rfc-dev-request@ietf.org?subject=subscribe>
X-List-Received-Date: Mon, 05 Aug 2019 21:35:28 -0000

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 <sginoza@amsl.com> 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:
> - 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.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
> xml2rfc-dev@ietf.org
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev