Subject: [xml2rfc-dev] V3 breakage in formatting internet draft references

From: Julian Reschke <[email-masked]>
Date: Tue, 1 Oct 2019 17:01:39 +0200

V3:

>    [Messaging]
>               Fielding, R., Ed., Nottingham, M., Ed., and J. F. Reschke,
>               Ed., "HTTP/1.1 Messaging", Internet-Draft, draft-ietf-
>               httpbis-messaging-05, July 2019,
>               <https://tools.ietf.org/html/draft-ietf-httpbis-messaging-
>               99>.

V2:

>    [Messaging]
>               Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
>               Ed., "HTTP/1.1 Messaging", draft-ietf-httpbis-messaging-
>               05 (work in progress), July 2019.

Observations:

1) author initials not restricted to one anymore (I'm open to change,
but it should be properly documented)

2) "Internet-Draft" is inserted

3) "(work in progress)" is missing

4) A URI on tools.ietf.org is inserted that I'd prefer not to have here.

Note: see <https://tools.ietf.org/html/rfc7322#section-4.8.6.4> which
suggests:

>       [SYMBOLIC-TAG]  Last name, First initial., Ed. (if applicable)
>                       and First initial. Last name, Ed. (if
>                       applicable), "I-D Title", Work in Progress,
>                       draft-string-NN, Month Year.
>
>      Example:
>
>       [RFC-STYLE] Flanagan, H. and S. Ginoza, "RFC Style Guide",
>                   Work in Progress, draft-flanagan-style-01,
>                   June 2013.

Best regards, Julian

PS: reported as <https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/436>

---

From: Heather Flanagan <[email-masked]>
Date: Tue, 1 Oct 2019 13:03:29 -0700

> On Oct 1, 2019, at 8:01 AM, Julian Reschke <[email-masked]> wrote:
> 
> V3:
> 
>>   [Messaging]

That’s been in the draft style guide for a while.

"<t>The author's name (initial followed by family name) appears on the
first line of the heading.  Some variation, such as additional
initials or capitalization of family name, is acceptable.  Once the
author has selected how their name should appear, they should use
that display consistently in all of their documents.</t>"

> 2) "Internet-Draft" is inserted

Yes.

> 3) "(work in progress)" is missing

Bug.

> 4) A URI on tools.ietf.org is inserted that I'd prefer not to have here.

Why not? I think having a URI makes a lot of sense.

>>                  Work in Progress, draft-flanagan-style-01,

Stay tuned. About to post an updated version.

-Heather

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

---

From: Julian Reschke <[email-masked]>
Date: Tue, 1 Oct 2019 22:52:05 +0200

> that display consistently in all of their documents.</t>"

That's about the front page, not for references.

For the latter, the draft style guide says in
<https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.4>:

>    [SYMBOLIC-TAG]  Last name, First initial., Ed. (if applicable) and
>    First initial.  Last name, Ed. (if applicable), "I-D Title", Internet
>    Draft, draft-string-NN, Month Year.

Note: "first initial".

> .. >> 3) "(work in progress)" is missing
>
> Bug.

Ack.

> Why not? I think having a URI makes a lot of sense.

The style guide doesn't say so. The author didn't provide one. Why is
the tool inserting something automatically? Also, why to tools.ietf.org?
Are you planning to put that into the style guide?

> ...

Best regards, Julian

---

From: Heather Flanagan <[email-masked]>
Date: Tue, 1 Oct 2019 14:19:37 -0700

> On Oct 1, 2019, at 1:52 PM, Julian Reschke <[email-masked]> wrote:
> 

Iirc, we’ve always tried to be consistent between what’s on the front page and what’s in the references. 

> <https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.4 <https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.4>>:
> 
> Note: "first initial”.

“Second initial if provided” is a really ugly example, but I can add it if you think it’s critical.

>>> 4) A URI on tools.ietf.org <http://tools.ietf.org/> is inserted that I'd prefer not to have here.
>> 
> the tool inserting something automatically? Also, why to tools.ietf.org <http://tools.ietf.org/>?

Well, there are always things the authors don’t provide that are automatically added. And since we’ve been talking about making sure that internal links to specific sections are included (which perforce MUST go to tools references) the thought was to be consistent and have the reference point to the same place that the internal section pointers are going to send people. I think it would be confusing to have one set of links go one place, and another set of links to somewhere entirely different.

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Wed, 2 Oct 2019 05:45:32 +0200

> page and what’s in the references.

Well, but we are not consistent right now.

> if you think it’s critical.

That would still be inconsistent with the front page, no?

> ...
>>>> 4) A URI ontools.ietf.org <http://tools.ietf.org/>is inserted that
>>>> I'd prefer not to have here.
>>>
>> the tool inserting something automatically? Also, why totools.ietf.org
>> <http://tools.ietf.org/>?
> Well, there are always things the authors don’t provide that are
> automatically added. And since we’ve been talking about making sure that
> internal links to specific sections are included (which perforce MUST go
> to tools references) the thought was to be consistent and have the
> reference point to the same place that the internal section pointers are
> going to send people. I think it would be confusing to have one set of
> links go one place, and another set of links to somewhere entirely
> different.

Well.

Right now the tools target is only inserted when none is specified, so
this is not in line what you're arguing for.

Also, for RFCs the target uses https://www.rfc-editor.org/info/rfcNNNN,
which also is not the URI used for the section links.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Wed, 2 Oct 2019 12:10:46 +0200

> “Second initial if provided” is a really ugly example, but I can add it if you think it’s critical.

How does that work?

I have a second initial that I’m not using.  If I started doing that, there would be a hodgepodge of citations, and people would start copying that initial over to citations that don’t have it and delete it from citations that do.

Heck, I’m happy when people don’t use Dave Borman’s last name for citing my documents (*), so I don’t know why we have to facilitate even more inconsistency between citation authors.

(There may be a purpose on earth for an explicit override that a citation author can invoke using some arduous ceremony if absolutely needed.  The normal case it should be not.)

Grüße, Carsten

(*) e.g., in RFC 3374, 3409, 4376, 4628, 4896 (three times).  
Sheesh, I never grepped for that before, I didn’t even know the extent of the problem…

---

From: "Martin Thomson" <[email-masked]>
Date: Fri, 11 Oct 2019 16:24:46 +1100

> which also is not the URI used for the section links.

I'm with Julian here.  There is no right answer, so don't provide one.  For me, today, if I was forced to pick, I'd probably pick the tools.ietf.org URL, but I don't think that that holds true once we start publishing decent HTML copies so that I can use real HTML over a txt2html conversion.  And others will of course have different preferences.

In this context, the bare name is sufficient for identification.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 15 Oct 2019 06:06:01 +0200

> which also is not the URI used for the section links.

FWIW, tracked at
<https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/436>. Would be
awesome to make some progress here.

Best regards, Julian