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

From: John C Klensin <[email-masked]>
Date: Thu, 11 Jul 2019 17:51:53 -0400

Hi.

I happened to look today at the reference produced for an I-D by
xml2rfc (at least by the online version at
https://xml2rfc.tools.ietf.org/ )

The XML for the relevant cited I-D says (irrelevant material
elided and the identity of the I-D changed to avoid
distractions):

  <reference <reference anchor="ID.draft-ietf-foo-bar"
	 target="https://datatracker.ietf.org/doc/draft-ietf-foo-bar/">
     ...
    <date month="June" day="12" year="2019" />
    </front>
  </reference>

The output is "June 2019".

Now, independent of what the RFC Editor decides to do with the
reference entry when/if the document gets to them [1], while the
document in which this is embedded is still an I-D, it can be
very important to the reader to know which version of the I-D
was cited and, of course, two or more versions of an I-D in the
same month is not uncommon.  

Authors who are happy with month and year can presumably just
leave the day out of the XML.  But, if an author believes the
day is important enough to include in the source file, why is
that part of the date being suppressed?  Is there any hope of
fixing that, which would revert things to earlier behavior?

best,
   john

[1] It is a completely separate matter from the above and
probably a topic for another list and another time, but the
reality, IMO, is that there are two types of I-D references that
might appear in an RFC.  One is a recent draft that is still, or
might reasonably expected to be, under active development.  For
those, the current "work in progress" form is appropriate.  I'd
still argue for explicit version numbers and dates, by they are
probably of limited utility.  The other is a document that is
being referenced for historical context, has typically been
expired for years, and for which it is clear that no further
development will occur, possibly because the referencing
document superceded it.  If we are going to allow references to
such I-Ds at all (IIR, for many years, we didn't) those
references need to be complete with accurate dates and version
numbers.  In addition, claiming that they are works in progress,
especially when the text of the document in which the citation
is imbedded says that they are obsolete... well, I think the
technical term in the bibliographical world would be "plain
silly".  But, again, that is a different set of issues from the
above and not an xml2rfc problem, at least until policies change.

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 12 Jul 2019 10:09:01 +1200

> same month is not uncommon.

Two versions on the same day is not impossible. For an actual case, I once did this:

<!-- ********** This reference is specifically to version 07 of the draft and is therefore
     ********** hand-crafted instead of using the I-D bibliography. -->

<reference anchor='RPL-07'>
<front>
<title>RPL: IPv6 Routing Protocol for Low power and Lossy Networks</title>
<author initials="T." surname="Winter" fullname="T. Winter"/>
<author initials="P." surname="Thubert" fullname="P. Thubert"/> 
<date month='March' year='2010'/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-roll-rpl-07"/> 
</reference> 

You can see the eventual result, which was not 100% satisfactory,
in https://tools.ietf.org/html/rfc6294

    Brian
  
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
>

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 12 Jul 2019 00:52:53 +0200

Why not reference the specific i-d: 

{{I-D.draft-ietf-roll-rpl-07}}

as opposed to latest in series:

{{I-D.ietf-roll-rpl}}

Sent from mobile

> On 12. Jul 2019, at 00:09, Brian E Carpenter <[email-masked]> wrote:
> 
> draft-ietf-roll-rpl-07

---

From: John C Klensin <[email-masked]>
Date: Thu, 11 Jul 2019 19:13:47 -0400

--On Friday, July 12, 2019 10:09 +1200 Brian E Carpenter
<[email-masked]> wrote:

>> I happened to look today at the reference produced for an I-D
>> by xml2rfc (at least by the online version at
>> 	 target="https://datatracker.ietf.org/doc/draft-ietf-foo-bar
>> 	 /"> ...
>> reference entry when/if the document gets to them [1], while
>> the document in which this is embedded is still an I-D, it
>> can be very important to the reader to know which version of
>> the I-D was cited and, of course, two or more versions of an
>> I-D in the same month is not uncommon.
> 
> <!-- ********** This reference is specifically to version 07
> of the draft and is therefore      ********** hand-crafted
> instead of using the I-D bibliography. -->
> 
> <title>RPL: IPv6 Routing Protocol for Low power and Lossy
> Networks</title> <author initials="T." surname="Winter"
> fullname="T. Winter"/> <author initials="P." surname="Thubert"
> fullname="P. Thubert"/>  <date month='March' year='2010'/>
> </front>
> <seriesInfo name="Internet-Draft"
> value="draft-ietf-roll-rpl-07"/>  </reference> 
> 
> You can see the eventual result, which was not 100%
> satisfactory, in https://tools.ietf.org/html/rfc6294

Well, I just looked at the RFC and someone, probably the RFC
Editor, discarded your seriesInfo material entirely, leaving
just the authors, title, month and year, and the notorious "work
in progress".  If my guess about the relationship between [RPL]
and [RPL-7] is correct, the latter is certainly not a work in
progress either.  And, if those are the two versions in
question, they are in the same month but a year apart.
However, that is all about the RFC and other rules, including
the insertion of "work in progress" apply.

For the I-D case, there is no question that the information can
be forced in.  One can use your strategy, one can use something
a little more like I wrote, with the link in the target
attribute of <reference>, and then use 
  <seriesInfo name="Internet-Draft" version="07"/>
or one can use an annotation element and describe what is going
on.  Probably there are other options too.

But, as a long-term fan of the principle of generic markup, I
wasn't looking for a workaround, I was looking for the
information that appears in the markup to be reflected in the
output unless there is a substantive reason to not do so.  

At least some years ago, if a complete date appeared in markup,
a complete date also appeared in the output.  Either its
disappearance is an unintended side-effect of some other change
or someone decided to take it out.   Either way, I suggest the
result is not what we want and that it would make sense to
restore the prior behavior.

best,
   john

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 12 Jul 2019 01:58:15 +0200

> as opposed to latest in series:

FYI: here are the reference entries I get from these:

   [I-D.draft-ietf-roll-rpl-07]
              Winter, T., Thubert, P., and R. Team, "RPL: IPv6 Routing
              Protocol for Low power and Lossy Networks", draft-ietf-
              roll-rpl-07 (work in progress), March 2010.

   [I-D.ietf-roll-rpl]
              Winter, T., Thubert, P., Brandt, A., Clausen, T., Hui, J.,
              Kelsey, R., Levis, P., Pister, K., Struik, R., and J.
              Vasseur, "RPL: IPv6 Routing Protocol for Low power and
              Lossy Networks", draft-ietf-roll-rpl-19 (work in
              progress), March 2011.

The date is a red herring.  Dates in RFC references are always Month-Year.
As was noted, adding a day doesn’t help with frequently respun I-Ds.
I think that’s why the draft number is in the bibxml.

(Well, “R. Team” for “ROLL Design Team" *is* a bit funny :-)

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 12 Jul 2019 02:10:19 +0200

> I think that’s why the draft number is in the bibxml.

Oh, and since this is the xml2rfc list:
The series info looks like this:

<seriesInfo name=‘Internet-Draft' value='draft-ietf-roll-rpl-19' />
and
<seriesInfo name=‘Internet-Draft' value='draft-ietf-roll-rpl-07' />

xml2rfc detects the seriesInfo name “Internet-Draft” and inserts the “work in progress” boilerplate instead:

xml2rfc/writers/raw_txt.py:
            for seriesInfo in ref.findall('seriesInfo'):
                if seriesInfo.attrib['name'] == "Internet-Draft":
                    refstring.append(', '+seriesInfo.attrib['value'] + ' (work in progress)')
                else:
                    refstring.append(', '+seriesInfo.attrib['name'] + u'\u00A0' +
                                     seriesInfo.attrib[‘value'].replace('/', '/' + u'\u200B'))

Grüße, Carsten

---

From: John C Klensin <[email-masked]>
Date: Thu, 11 Jul 2019 22:48:54 -0400

--On Friday, July 12, 2019 01:58 +0200 Carsten Bormann
<[email-masked]> wrote:

>   [I-D.ietf-roll-rpl]
>               Winter, T., Thubert, P., Brandt, A., Clausen,
> T., Hui, J.,               Kelsey, R., Levis, P., Pister, K.,
> Struik, R., and J.               Vasseur, "RPL: IPv6 Routing
> Protocol for Low power and               Lossy Networks",
> draft-ietf-roll-rpl-19 (work in               progress), March
> 2011.
> 
> The date is a red herring.  Dates in RFC references are always
> Month-Year. As was noted, adding a day doesn't help with
> frequently respun I-Ds. I think that's why the draft number
> is in the bibxml.

Brian may have a different answer for his document, but ...

* Historically, dates in RFC references are not "always"
Month-Year.  For a long time, the custom was to show April 1
RFCs with the day for reasons that are probably obvious.   If
that custom has lapsed (and it apparently has) it is a loss in
information for the RFC Series.

* As I said earlier, my concern is about I-Ds referencing I-Ds.
These are not RFC references.  And, while I'll stipulate that
draft version/sequence numbers are more precise than dates, I
can think of any number of reasons why an exact date may convey
useful information.

* While I use bibxml for RFCs, I find that I can rarely use it
for references to I-Ds because either the exact information I
need isn't reliably there or because I need different naming or
structure for stylistic reasons.  Interestingly, the outcome of
a recent discussion with the RFC Editor about a style issue will
result in my being able to use it for fewer references to RFCs
than has been normal in the past.

   john

---

From: Brian E Carpenter <[email-masked]>
Date: Fri, 12 Jul 2019 15:11:52 +1200

> as opposed to latest in series:

I believe that didn't work at that time. If it works now, that's good news.

    Brian

> 
> Sent from mobile
> 
> On 12. Jul 2019, at 00:09, Brian E Carpenter <[email-masked] <mailto:[email-masked]>> wrote:
> 
>> draft-ietf-roll-rpl-07

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Jul 2019 05:10:03 +0200

> restore the prior behavior.

I don't think anything has changed with regards to this. The day of
month never has been shown in references.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 12 Jul 2019 15:16:24 +0200

Hi John,

> The output is "June 2019".

After looking through various output formats, my conclusion here
is that this is the output from the v2 text formatter, not the
v3 text formatter.  The v3 text formatter renders the date with
day, month, and year if all 3 are given.  So going forward, it
seems that this has already been addressed (assuming we leave the
v2 formatter untouched at this late stage in its life cycle).

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Jul 2019 15:40:00 +0200

> v2 formatter untouched at this late stage in its life cycle).

Hmmm.

That seems to be a rather big change to be introduced without notice.

I think the first thing that needs to happen is the RFC Style Guide
would need to say how to handle the format. Right now it says "year
month", and this is what tools have been generating for ages.

Heather?

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 12 Jul 2019 15:44:20 +0200

On Jul 12, 2019, at 15:40, Julian Reschke <[email-masked]> wrote:
> month”, and this is what tools have been generating for ages.

Well, keeping with the style guide could now be the onus of the author (i.e., author has to delete the day to fulfill the style guide).
I wouldn’t like that too much, as it makes automatically generated references (e.g., from a DOI) harder to use.

Still, I have no idea what the semantics of the style guide are here when the interchange format is XML — the full date might be there, but the formatting tools don’t show it.  What is governed by the style guide?

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Jul 2019 15:59:55 +0200

> Still, I have no idea what the semantics of the style guide are here when the interchange format is XML — the full date might be there, but the formatting tools don’t show it.  What is governed by…

The style guide says that RFCs and Internet Drafts are to be shown
without date:

<https://tools.ietf.org/html/rfc7322#section-4.8.6.3>
<https://tools.ietf.org/html/rfc7322#section-4.8.6.4>

And...:

<https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.2>
<https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.3>
<https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.4>

FWIW, it is silent about April 1st RFCs, but see:

<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/30>
(April 2018)

It is *also* silent about other kinds of references.

In a perfect world, the formatter would not need any knowledge specific
to what is being references. But that currently collides with the
reference database and the style guide.

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Fri, 12 Jul 2019 10:43:54 -0400

Henrik,

This was definitely from the v2 formatter.  If it is fixed in
v3, that seems like a satisfactory answer and I'll work around
it in the interim.

thanks,
   john

--On Friday, July 12, 2019 15:16 +0200 Henrik Levkowetz
<[email-masked]> wrote:

> After looking through various output formats, my conclusion
> here is that this is the output from the v2 text formatter,
> not the v3 text formatter.  The v3 text formatter renders the
> date with day, month, and year if all 3 are given.  So going
> forward, it seems that this has already been addressed
> (assuming we leave the v2 formatter untouched at this late
> stage in its life cycle).
> 
> 
> Best regards,
> 
> 	Henrik
> 
>> 
>> reality, IMO, is that there are two types of I-D references
>> that might appear in an RFC.  One is a recent draft that is
>> still, or might reasonably expected to be, under active
>> development.  For those, the current "work in progress" form
>> is appropriate.  I'd still argue for explicit version numbers
>> and dates, by they are probably of limited utility.  The
>> other is a document that is being referenced for historical
>> context, has typically been expired for years, and for which
>> it is clear that no further development will occur, possibly
>> because the referencing document superceded it.  If we are
>> going to allow references to such I-Ds at all (IIR, for many
>> years, we didn't) those references need to be complete with
>> accurate dates and version numbers.  In addition, claiming
>> that they are works in progress, especially when the text of
>> the document in which the citation is imbedded says that they
>> are obsolete... well, I think the technical term in the
>> bibliographical world would be "plain silly".  But, again,
>> that is a different set of issues from the above and not an
>> xml2rfc problem, at least until policies change.
>>

---

From: Heather Flanagan <[email-masked]>
Date: Fri, 12 Jul 2019 09:51:46 -0700

> month", and this is what tools have been generating for ages.

HI,

April 1st RFCs should be the only ones with the day listed in the date. Everything else should be month/year. I don’t think this should necessarily be up to the author. That makes it something else the author has to consider, OR something the RFC Editor has to follow up on. It also becomes a semantically important implication to a far greater (and therefore more confusing) extent than the April 1st situation.

So, while I think we need the option for a date, it should be hidden for the majority of RFCs. Internet Drafts have the version number, and the Work in Progress label, and changes to that are a different topic we can discuss later.

-Heather

---

From: John C Klensin <[email-masked]>
Date: Fri, 12 Jul 2019 13:10:48 -0400

--On Friday, July 12, 2019 15:40 +0200 Julian Reschke
<[email-masked]> wrote:

>>> I happened to look today at the reference produced for an
>>> I-D by xml2rfc (at least by the online version at
>>> 	 target="https://datatracker.ietf.org/doc/draft-ietf-foo-ba
>>> 	 r/"> ...
>> stage in its life cycle). ...
> 
> Hmmm.
> 

Julian (and others),

Please go back and look at the note that started this thread,
where I explicitly said I was concerned about I-Ds and not final
format RFCs. 

The details of RFC formats have _always_ been different than I-D
requirements, with the most obvious example being different
boilerplate.  We do not obscure information in I-Ds by claiming
all other I-Ds are works in progress.  For I-Ds, whatever the
nits checker may find (or thinks it finds) notwithstanding, we
do not try to enforce references to most recent version in I-Ds
(because the earlier version might be intentional.  In the
document header, I-Ds show full dates, show "(if approved)" on
the update line, show the status as "Intended", and don't show
an ISSN.  And I-Ds show a full (with day number) date and an
expiration date (also a full date) while RFCs (at least April 1
documents aside) show only month and year.

<rant TL:DR-version: Citing the RFC Style Guide is irrelevant or
worse where this issue is concerned>

One of the strong advantages of generic markup over the old
methods of preparing I-Ds in ASCII text editors or in nroff is
that most of those differences can be accomplished by using
different style sheets or otherwise in processing for the two
output styles.

For the text of a reference, the easiest workaround for me (see
the exchange with  Brian) when I think the date is important is
to simply generate the text file for posting and then spend two
minutes with a text editor patching the dates back in.   Unless
the intent of being able to use I-Ds to get a preliminary
concept document out there has been lost and the IETF has
developed a serious attack of form over content, those RFC style
requirements or recommendations don't constrain I-Ds.

In particular, at your behest, I went back and looked at
https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.2.
It (and its predecessors) say exactly what I expected them to
say: they talk about RFCs and not about I-Ds.  The only thing
that most current draft says about I-Ds appears in the last
paragraph of Section 1:

	"All RFCs begin as Internet-Drafts (also referred to as
	I-Ds), and a well-written and properly constructed
	Internet-Draft [ID-GUIDE] provides a strong basis for a
	good RFC."

There is also the statement in Section 4.8.6 about normative
references to I-Ds, but that has nothing to do with this
discussion.  Curiously 4.8.6.4 _requires_ that the full draft
name, including the number, appear when (informative) references
to I-Ds appear in RFCs, but not only is this something else that
is not being enforced for I-Ds by xml2rfc or the submission
tool, but the example at the end of that section doesn't bear
"work in progress" and hence does not conform to the _current_
style guide for RFCs but anticipates a change that it makes.   

That proposed change is, by the way, interesting in another way,
which is that it removes a requirement that is rather clearly
specified in RFC 2026 Section 2.2.  Although I believe that
requirement is badly in need of adjustment to avoid silly states
with historical references rather than references to I-Ds that
are even possibly still under development, there is no "updates
2026" in that I-D and we don't make changes that modify BCPs
(especially, IMO, that BCP) in an Informational RFC, especially
one that will not be processed in the IETF Stream. 

</rant>

So, this request is about one thing and one thing only.  If the
author or editor of an I-D decides that it is important to
communicate some information to the reader because that
information will be --in his or her judgment or the judgment of
a relevant WG-- useful to readers in understanding what is going
on, then, as long as the markup is correct enough to get through
the processor, xml2rfc should not discard that information.  If
the IESG wants to constrain those choices, then the ID-guide
should be opened and modified if there is community consensus
for doing so.   

But this has nothing to do with the RFC Style Guide.   I'd hope
the different style sheets/ processors would smooth out any
details there, but, if the RFC Editor says "you must remove all
day attributes from dates in references before the document is
handed off to the RFC Editor", I'll deal with that issue when
the time comes.   Heather has already said, several times,
things equivalent to "if you want documents to go through the
production process quickly, don't say 'the RFC Editor will fix
that'".   I've got that and figured out long ago (while Jon
Postel was still the RFC Editor) that the more I can get a
document --editorially and structurally-- into RFC Editor form
before it is handed off, the faster things will go and the less
aggravated I and the RFC Editor staff will get during Last Call.
So, great advice, but it doesn't have anything to do with this
request either.

best,
    john

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 12 Jul 2019 19:20:07 +0200

Hi Heather,

Below:

On 2019-07-12 18:51, Heather Flanagan wrote:
> April 1st RFCs should be the only ones with the day listed in the
> date. Everything else should be month/year. I don’t think this should
> necessarily be up to the author. That makes it something else the
> author has to consider, OR something the RFC Editor has to follow up
> on. It also becomes a semantically important implication to a far
> greater (and therefore more confusing) extent than the April 1st
> situation.
> 
> So, while I think we need the option for a date, it should be hidden
> for the majority of RFCs. Internet Drafts have the version number,
> and the Work in Progress label, and changes to that are a different
> topic we can discuss later.

The current v3 tools will use day, month, and year if provided in the
references file, but as the RFC references only provide month and year,
except for April 1st RFCs, they will be rendered with only month and
year as references.  Drafts, as they normally have day, month, and year
in the references file, will be rendered with day, month, and year as
references.  The only adjustment I think might be necessary in the v3
renderers would be if you would like draft references to be rendered
without day when rendering an RFC.

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Jul 2019 19:36:55 +0200

On 12.07.2019 19:10, John C Klensin wrote:
> format RFC.

Well, allow me to concerned about all types, being the author on an
xml2rfc processor :-)

> ... > So, this request is about one thing and one thing only.  If the

You're losing me. Why is the day of month of any relevance when the
draft has a version number?

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Jul 2019 19:44:11 +0200

On 12.07.2019 18:51, Heather Flanagan wrote:
> HI,
>
> April 1st RFCs should be the only ones with the day listed in the date.
> Everything else should be month/year. I don’t think this should
> necessarily be up to the author. That makes it something else the author
> has to consider, OR something the RFC Editor has to follow up on. It
> also becomes a semantically important implication to a far greater (and
> therefore more confusing) extent than the April 1st situation.
>
> So, while I think we need the option for a date, it should be hidden for
> the majority of RFCs. Internet Drafts have the version number, and the
> Work in Progress label, and changes to that are a different topic we can
> discuss later.
> ...

So then who is in charge to decide whether the day of month is inserted?

1) The author? (in that case, the citation libs would need to drop the
date for internet drafts)

2) The processor? (in which case it'll need an extra signal for April
1st RFCs)

This may have been not so important in the past. But in the v3 world
(AFAIU), there will be no manual post-processing step anymore, so
whatever the formatter emits will be what people see...

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Sat, 13 Jul 2019 13:45:10 +0200

> whatever the formatter emits will be what people see...

Proposed extension:
<https://greenbytes.de/tech/webdav/rfc2629xslt.html#ext-rfc2629.date>

Example: <https://greenbytes.de/tech/webdav/rfc2616.html#RFC2324>

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Sat, 13 Jul 2019 18:17:44 -0400

--On Friday, July 12, 2019 19:36 +0200 Julian Reschke
<[email-masked]> wrote:

>> where I explicitly said I was concerned about I-Ds and not
>> final format RFC.
> 
>> ... > So, this request is about one thing and one thing only.
>> If the author or editor of an I-D decides that it is
>> important to communicate some information to the reader
>> because that information will be --in his or her judgment or
>> the judgment of a relevant WG-- useful to readers in
>> understanding what is going on, then, as long as the markup
>> is correct enough to get through the processor, xml2rfc
>> should not discard that information.  If the IESG wants to
>> constrain those choices, then the ID-guide should be opened
>> and modified if there is community consensus for doing so.
>> ...
> 
> You're losing me. Why is the day of month of any relevance
> when the draft has a version number?

I fear we are not communicating.

Let me give you two reasons.  The second one is the important
one; I wonder whether the first one is enough of a distraction
that I should omit it.

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

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

I note that we do have some requirements about content.  For
legal and related reasons, I-Ds are not allowed to be posted
unless they contain one of more of a selection of specific
statements.  If some authors doesn't agree, they just don't get
to post.  The same comment applies to some extremely basic
format/layout requirements that make the collection more
manageable.  For similar management reasons, there is even
supposed to be a rule about file naming but people ignore it
with impunity.   The community has decided that documents MUST
have Security Considerations sections but, even for that, we
allow versions of I-Ds to say "to be supplied" or equivalent up
to the point that the community, via a relevant Stream, is asked
to process them.   All of those requirements exist for
substantive reasons and there is rough consensus in the
community that they are important.   One thing they have in
common is that they specify information that is required to be
present, not information that is required to be omitted.   

We do have a few rules about what must be omitted or that is not
allowed to appear, but they are tied to IPR, e.g., I'm breaking
assorted rules if I use an I-D to disclose someone else's trade
secrets.  However, that is a little different from a day number.
Actually, IMO, it is a lot different.

As a specific case of more general principles, I imagine that
there is informal community consensus that foul, obscene, or
inherently denigrating language does not belong in I-Ds.
However, even then, I don't believe it is in the community's
interest to have the xml2rfc processor silently remove the
words.  If you did so, I'd assume some authors would claim the
processor and its authors were behaving inappropriately,
possibly by censoring their freedom of expression or possibly by
causing them to look like illiterates by destroying their
sentence structure.    If you wanted to make a case that the
processor, upon discovering such a word, should put up an error
messages about a prohibition on obscenity and then stop, I'd
think that would be a better choice, but I don't think it would
be reasonable for the Tools Team to decide to do that without at
least some evidence of community discussion and consensus.

In any event, the exclusion of a digit or two does not fall into
a foul or obscene language category.   The processor is simply
removing information that I, as author, believe is important
enough to include in the XML and removing it because you someone
decided I didn't need it.  I assume from this thread that you
think it is my obligation to convince you otherwise (that I do
need to have it displayed), perhaps even on a case by case
basis.  I hope we have not reached the stage that the IETF works
that way.

best,
   john

---

From: Julian Reschke <[email-masked]>
Date: Sun, 14 Jul 2019 07:25:48 +0200

> I fear we are not communicating.

Are we not?

> one; I wonder whether the first one is enough of a distraction

Examples are good.

> hoops (or page clicks) we can get the reader to jump through.  I

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

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.annotation>,
<https://mailarchive.ietf.org/arch/msg/xml2rfc/JGsffnj-JKZRF80qvh6dLB_4r0w>).

> other tool author or specifier) should tell me I can't have it

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.

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.

Best regards, Julian

---

From: John C Klensin <[email-masked]>
Date: Sun, 14 Jul 2019 17:33:45 -0400

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

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

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.

> <https://mailarchive.ietf.org/arch/msg/xml2rfc/JGsffnj-JKZRF80

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.
>> ...
> 
> bibliographic references. The goal is to produce the format
> that the RFC Style Guide asks for.
 
> 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...

> 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

---

From: Julian Reschke <[email-masked]>
Date: Mon, 15 Jul 2019 09:57:07 +0200

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

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

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

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

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

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

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

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

> 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