Re: [xml2rfc] xml2rfc online: references to I-Ds and associated dates

[John C Klensin <[e-mail]>]

--On Sunday, July 14, 2019 07:25 +0200 Julian Reschke
<[e-mail]> wrote:

>...
>> (1) Suppose that there was some external event or announcement
>> that interacted with the subject matter of an I-D (a product
>> being shipped or the announcement of a really nasty
>> vunerability come to mind as possible examples).  It would
>> then be helpful for the reader to be able to tell, quickly,
>> whether there is any chance that the I-D might have addressed
>> those issues. Certainly that date information could be
>> determined by going to the tracker with the version number
>> and looking up the date there, but I don't think our goal
>> should be to see how many hoops (or page clicks) we can get
>> the reader to jump through.  I hope you agree.
> 
> I agree with the goal, but not with the conclusion.
> 
> First of all, with a sane format, you need exactly one click
> to get to
> the referenced Internet Draft, and that will have the date on
> the front
> page. (This is true today for the HTML version on
> tools.ietf.org, and
> will also hopefully be the case for xml2rfc's v3 HTML output).

Ah.  And this may be another example of why our perspectives
differ enough to lead to this disagreement.  Suppose that,
instead of reading the referenced Internet Draft in the HTML
version and when I'm online, I'm reading the text version on
paper, some version after it was downloaded to a disconnected
tablet, or I am not reading it at all but using a screen reader
to "speak" it to me.  Under some circumstances, I might even
extract some of it and read that part on paper.  My reason for
those choices might be personal preference of might fall into
some "disability" category, but I think that someone's making
assumptions that there is no good reason might reasonably be
treated as discriminatory.

With any of those scenarios, if I want to obtain the information
you believe is easily obtained by clicking on a link that
appears in the document, I need to get myself to the computer
(or some handheld I'm willing to use for the purpose), bring up
a browser, bring up either the document (and find the link) or
the datatracker (and enter the name of the relevant I-D), then
then do whatever I need to do to get to the information.   To
avoid saying something rule, please don't assume that everyone
does, or even should, work the way you prefer and to which, I
assume, you have regular and convenient access.

> That said, it is already possible to annotate a reference with
> any prose
> you like. So if you want to say something like "this draft
> addresses the
> security issue raised by xxx on yyy", you can already do that.
> (<https://greenbytes.de/tech/webdav/rfc7749.html#element.annot
> ation>,
> <https://mailarchive.ietf.org/arch/msg/xml2rfc/JGsffnj-JKZRF80
> qvh6dLB_4r0w>).

I've been using annotation elements for years.   Now that I know
that higher-precision date information is being discarded, maybe
I will remember to put the information back in that way.   But
nothing in RFC 2629 or 7749 (particularly Section 2.13 or the
text of 2.13.1 for the latter) for v2 or RFC 7991 (particularly
Section 2.17) for v3 says, along with the "day" parameter "you
can supply this if you like but, except for the date of the
document itself for an I-D, we will probably just throw it away
in the processor".  Nor does the processor generate error
messages about that discarded information.  

If I am aware that the information is being discarded, I have at
least three choices, any of which may be reasonable under
different circumstances.  One is to just accept that.  Another
is to put annotations into the XML.  A third is to open the txt
output file and put the information back in, which might not be
easier but is certainly more attractive given my particular
editorial preferences.  On the other hand, if the information is
provided in the XML but silently discarded.  But there is no
hint to me that it will be discarded unless I carefully inspect
the output.  I suggest that is a disservice to the community.
 
>> (2) As long as the purpose of posting documents as I-Ds
>> includes allowing authors or groups to expose ideas to the
>> community for discussion, editorial decisions about what
>> belongs in those documents should be in the hands of those
>> authors.  Neither the community, nor the authors of a
>> production tool that is recommended by the community for use
>> with I-Ds, should make stylistic decisions that affect what
>> information is presented without a compelling reason.   So
>> the question isn't why I might want to display the day of the
>> month, it is why you (or some other tool author or specifier)
>> should tell me I can't have it displayed.
>> ...
> 
> xml2rfc tries to formalize/automate things that historically
> happened at
> RFC production time. One of these things is consistent style of
> bibliographic references. The goal is to produce the format
> that the RFC Style Guide asks for.
 
> Now that is for RFCs. Using xml2rfc to produce
> *Internet-Drafts* is a
> slightly different use case. My understanding is that people
> use xml2rfc
> for this because it will reduce the amount of formatting
> changes when
> going to RFC. So here the question would be: do we need more
> freedom in
> references styles in Internet Drafts, as opposed to RFCs?
> That's
> definitively an interesting discussion, and maybe the outcome
> is that we
> need to make changes on the RFC Style Guide side.

There may well be some people who use xml2rfc for that purpose.
At least some of the rest of us use it because we have gotten
what has seemed to be a clear message from the IESG, from
assorted WG Chairs (and in WG Chair meetings), and with
reinforcement from the posting tool, that the best way (or at
least one of the best ways) to get the boilerplate right and get
a draft put together for posting.   Our newcomer's tutorials
mention only NROFFEDIT and xml2rfc as preferred ways to produce
I-Ds although they now also talk about markdown as producing
"the XML format accepted by the RFC Editor".  See, e.g.,
https://www.ietf.org/about/participate/tutorials/process/creating-internet-drafts-and-rfcs/.
None of those things suggests other alternatives so I would
suggest that at least some people use xml2rfc to create I-Ds
between that is what they were told to use or it appears to be
one of very few plausible alternatives.

However, in suggesting that this should suggest changes to the
RFC Style Guide, I think you are missing the point I've been
trying to make.  That point is simply that, until and unless the
IESG changes the rules and gets community consensus (or at least
acceptance) for doing so, the xml2rfc processor should not be
discarding information that is supplied in well-documented
elements and their attributes, at least unless the documentation
is clear that the information will be treated as noise.   If the
IESG does make such a change, the documentation should be
adjusted accordingly.  And...

> And yes, I understand that what you say applies to all of the
> text, not
> only reference styles. That's a broad topic, but then, I'd
> prefer to
> discuss concrete use cases, not the whole philosophy.

Ok.  The concrete use case is that information I supply in
markup, using elements and attributes that clearly permit its
use, should not be discarded without warning or discussion.  As
an author, I note that if some information is included in I-Ds
and then discarded by the RFC Editor, that change shows up in
diffs and is subject to AUTH48 review.  At that point, it is
possible to argue about the appropriateness of the change and
sometimes even win if there is a good reason.  But the RFC
Editor gets to supply guidance about what information should be
in an RFC and how it should be organized (in both the general
and in specific cases) -- that is their job.   Tool implementers
should not do that for I-Ds, especially without consultation
with the community (or at least the IESG).

As far as concrete use cases are concerned, that is where I
started, with the discarded "day" information.  If there are
other places where information is being discarded from I-Ds
because of an interpretation of what the RFC Style Guide says,
those should be fixed too.  I hope we don't have to play
whack-a-mole if there are other cases of this.

best,
   john