Subject: [xml2rfc-dev] feedback on <stream>

From: Julian Reschke <[email-masked]>
Date: Fri, 17 May 2019 16:35:33 +0200

Hi there,

so I stumbled across the element <stream>, used in the test file
elements.xml (in the svn repo).

Source:

> 	 <reference anchor="RFC7997" target="https://www.rfc-editor.org/info/rfc7997" quote-title="true">
> 	    <stream>IAB</stream>
> 	    <front>
> 	       <title>The Use of Non-ASCII Characters in RFCs</title>
> 	       <author fullname="Heather Flanagan" role="editor">
> 		  <organization/>
> 	       </author>
> 	       <date year="2016" month="December"/>
> ... > 	    </front>
> 	    <seriesInfo name="RFC" value="7997"/>
> 	    <seriesInfo name="DOI" value="10.17487/RFC7997"/>
> 	 </reference>

The text output is:

>    [RFC7997]  Flanagan, H., Ed., "The Use of Non-ASCII Characters in
>               RFCs", IAB, RFC 7997, DOI 10.17487/RFC7997, December 2016,
>               <https://www.rfc-editor.org/info/rfc7997>.

Removing it yields:

>    [RFC7997]  Flanagan, H., Ed., "The Use of Non-ASCII Characters in
>               RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016,
>               <https://www.rfc-editor.org/info/rfc7997>.

...so the contents is inserted between title and series information.

Question: is there an actual requirement for this? I checked the style
guide and related information and could not find anything.

*If* this is indeed needed, my preference would be to name/define the
element more general terms; not in a way totally specific to IETF documents.

Best regards, Julian

---

From: Heather Flanagan <[email-masked]>
Date: Wed, 22 May 2019 17:59:56 -0700

Hi Julian,

> On May 17, 2019, at 07:35, Julian Reschke <[email-masked]> wrote:
> 
> Hi there,
> 

Right. This (the addition of stream in the reference) is something I want to start doing, but haven’t been able to because the current tools couldn’t support it.  See section 4.8.6.2 in https://www.ietf.org/archive/id/draft-flanagan-7322bis-03.txt.

> element more general terms; not in a way totally specific to IETF documents.

While I like the idea of generalizing, this is one area that I think truly is unique to our document series. Do you have a proposal for naming/defining it in another way?

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Thu, 23 May 2019 13:48:30 +0200

On 23.05.2019 02:59, Heather Flanagan wrote:
> ...
> Right. This (the addition of stream in the reference) is something I
> want to start doing, but haven’t been able to because the current tools
> couldn’t support it.  See section 4.8.6.2 in
> https://www.ietf.org/archive/id/draft-flanagan-7322bis-03.txt.

Ah, interesting.

So this is something that goes between the title and the series information.

I note that in V3 we already added <refcontent>
(https://greenbytes.de/tech/webdav/rfc7991.html#element.refcontent), and
documented it to go between title and date. Unfortunately, this is under
specified, because it doesn't say whether it is before or behind the
series information. I raised
<https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/78> for that.

Note that the rational for <refcontent> was actual abuse of seriesInfo,
such as in:

> rfc7001.xml:<seriesInfo name="Work in" value="Progress"/>
> rfc7002.xml:        <seriesInfo name="Work in" value="Progress" />
> rfc7005.xml:        <seriesInfo name="Work in" value="Progress" />
> rfc7006.xml:<seriesInfo name="Work in" value="Progress" />
> rfc7015.xml:<seriesInfo name='Work in' value='Progress' />
> rfc7019.xml:<seriesInfo name='Work in' value='Progress' />
> rfc7019.xml:<seriesInfo name='Work in' value='Progress' />
> rfc7019.xml:<seriesInfo name='Work in' value='Progress' />
> rfc7021.xml:        <seriesInfo name="Work in" value="Progress"/>
> rfc7021.xml:        <seriesInfo name="Work in" value="Progress"/>

(from AUTH48 XML...).

(Note that I see much more of these for recent RFCs, which may indicate
that the style guide requires output we can't produce...)

That said, the *intent* was to place this *behind* seriesInfo, and this
is what rfc2629.xslt does. xml2rfc on the other hand places it *before*
series information, so in that implementation <stream> seems to do
exactly what <refcontent> already does.

Generally, this is a similar problem as the one that we've been
discussing with respect to <postal> (for which I'd really like to see
feedback). The content models of <reference> and <front> do not reflect
the actual order in which things get rendered, so it's somewhat hard to
extend it with new elements that are guaranteed to show up in a specific
place.

 From what I see, we'll need some way to insert additional content both
before the series information and after it, and that could be done with

- multiple elements
- a single element with some control of placement

The latter seems to be more logical to me (and also would scale better
if we'd need another type of placement).

So my proposal would be:

- fix <refcontent> definition to say "by default: after series information,

- add attribute to select placement, for instance: <refcontent
after="title">IAB</refcontent>

Now going back to the actual requirement in
<https://tools.ietf.org/html/draft-flanagan-7322bis-03#section-4.8.6.2>:

>    The following format is required for referencing RFCs.  The Stream
>    abbreviation should be used; when no stream is available, as with
>    legacy RFCs, this may be left blank.
>
>    Note the ordering for multiple authors: the format of the name of the
>    last author listed is different than that of all previous authors in
>    the list.
>
>    For one author or editor:
>
>    [RFCXXXX] Last name, First initial., Ed. (if applicable), "RFC
>    Title", Stream, Sub-series number (if applicable), RFC number, RFC
>    DOI, Date of publication, <https://www.rfc-editor.org/info/rfc# >
>    [1].

This looks ok to me if "Stream" is one of IETF, IAB, or IRTF. But what
about the independent stream? What should be displayed in that case?

Best regards, Julian