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

[Julian Reschke <[e-mail]>]

On 14.07.2019 23:33, John C Klensin wrote:
> ...
> 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.
> ...

I agree that there may be cases where following the link is not
possible. I disagree however that because it may be possible to be
offline, we necessarily need to inline all available information.

> 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.

Hm. Are you saying that we need to optimize Internet Drafts for
recipients who do not have a computing device or connectivity?

> ...
> 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

Yes. The intent of RFC 7749 was to describe the vocabulary, not
necessarily what formatting tools do with it.

> 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.

Note that that text is about the "prep tool", not the actual formatting
tool.

The problem with generating error or warning messages is noise. The
reference files for Internet Drafts contain the day information, so
you'd get one error per Internet Draft being referenced. Is that really
helpful?

> 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.

Well, it has been like that for over 15 years, and as far as I can tell,
it just has come up for the very first time. I understand that you see
an important principle being violated, but please consider the history
how we got where we are as well.

> ...
> 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...
> ...

I'm all for documenting things. I actually spent a significant of time
writing RFC 7749. It may not be perfect, but at least it describes the
vocabulary at the time v3 was started (the vocabulary, not what
formatting tools do with it).

Also note that this is not the only piece of information that is "thrown
away". <reference> re-uses <front>, and that can contain lots of
information that is not rendered in the references section either
(workgroup, area, abstract...). Is that a problem as well for you?

 > ...
> 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

That's not my understanding of a "use case". I understand this is a good
principle, but then there are other principles which are good as well,
and which this one conflicts with; namely the re-use of XML element
definitions in different contexts.

There's also the principle not to annoy users with warnings that they
can't do anything about.

> 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).

I believe it would be a negative outcome if we started to have
additional different rules for IDs and RFCs. That would mean that going
from ID to RFC becomes harder.

For the differences that are there, yes, it would be good to have them
written down, and then potentially be reflected in the formatting tool.

> 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.
> ...

Have a look at the content model for <front>, and you'll see that more
data is already discarded. For instance, metadata is not necessarily
used at all when formatting documents.

Does this mean that there should be an error message? No. Because
formatters are not the only tools processing the source files.

Best regards, Julian