Emend encoding of intended status

[metanorma]

Emend encoding of intended status

[opoudjis]

The RFC7991 spec as I read it says that intended-series can also have a value of exp|info|historic for RFC documents:

That element might also
contain an additional element with the status of
"info", "exp", or "historic" and a name of "" to indicate the
status of the RFC.

[opoudjis]

The RFC XML 3 is ambiguous enough about what the seriesInfo@value is when name is blank, that an erratum should be lodged:

If a <front> element contains a <seriesInfo> element with a name of "Internet-Draft", it can also have at most one additional <seriesInfo> element with a "status" attribute whose value is of "standard", "full-standard", "bcp", "fyi", "informational", "experimental", or "historic" to indicate the intended status of this Internet-Draft, if it were to be later published as an RFC. If such an additional <seriesInfo> element has one of those statuses, the name needs to be "".

... and what is the value of that additional seriesInfo element? At the moment I'm repeating the draft name, as with the first seriesInfo element. It can't be the series number within the series, because that series number has not yet been assigned.

If a <front> element contains a <seriesInfo> element with a name of "RFC", it can also have at most one additional <seriesInfo> element with a "status" attribute whose value is of "full-standard", "bcp", or "fyi" to indicate the current status of this RFC. If such an additional <seriesInfo> element has one of those statuses, the "value" attribute for that name needs to be the number within that series. That <front> element might also contain an additional <seriesInfo> element with the status of "info", "exp", or "historic" and a name of "" to indicate the status of the RFC.

What is the value of the additional seriesInfo element meant to be if the status is info or exp? Again, there will have been no series number assigned. At the moment, the value is rendered as "none"—because the value attribute is mandatory.

Not putting up examples for this kind of proposal in the RFC, btw, is a fail.

[opoudjis]

This is what the current rspec has:

describe Asciidoctor::RFC::V3::Converter do
  it "sets seriesInfo attributes for Internet Draft" do
    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3, header_footer: true)).to be_equivalent_to <<~'OUTPUT'
      = Document title
      Author
      :doctype: internet-draft
      :docname: internet-draft-this-is-an-internet-draft-00
      :status: informational
      :intended-series: bcp
      :submission-type: IRTF
    INPUT
       <?xml version="1.0" encoding="UTF-8"?>
       <rfc preptime="1970-01-01T00:00:00Z"
                version="3" submissionType="IRTF">
       <front>
       <title>Document title</title>
       <seriesInfo name="Internet-Draft" status="informational" stream="IRTF" value="internet-draft-this-is-an-internet-draft-00"/>
       <seriesInfo name="" status="bcp" value="internet-draft-this-is-an-internet-draft-00"/>
       <author fullname="Author">
       </author>
       </front><middle>
       </middle>
       </rfc>
    OUTPUT
  end

  it "sets seriesInfo attributes for RFC, with FYI status" do
    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3, header_footer: true)).to be_equivalent_to <<~'OUTPUT'
      = Document title
      Author
      :doctype: rfc
      :docname: rfc-1111
      :status: full-standard
      :intended-series: fyi 1111
      :submission-type: IRTF
    INPUT
       <?xml version="1.0" encoding="UTF-8"?>
       <rfc preptime="1970-01-01T00:00:00Z"
                version="3" submissionType="IRTF">
       <front>
       <title>Document title</title>
       <seriesInfo name="RFC" status="full-standard" stream="IRTF" value="1111"/>
       <seriesInfo name="" status="fyi" value="1111"/>
       <author fullname="Author">
       </author>
       </front><middle>
       </middle>
       </rfc>
    OUTPUT
  end

  it "sets seriesInfo attributes for RFC with historic status" do
    expect(Asciidoctor.convert(<<~'INPUT', backend: :rfc3, header_footer: true)).to be_equivalent_to <<~'OUTPUT'
      = Document title
      Author
      :doctype: rfc
      :docname: rfc-1111
      :status: full-standard
      :intended-series: historic
      :submission-type: IRTF
    INPUT
       <?xml version="1.0" encoding="UTF-8"?>
       <rfc preptime="1970-01-01T00:00:00Z"
                version="3" submissionType="IRTF">
       <front>
       <title>Document title</title>
       <seriesInfo name="RFC" status="full-standard" stream="IRTF" value="1111"/>
       <seriesInfo name="" status="historic" value="none"/>
       <author fullname="Author">
       </author>
       </front><middle>
       </middle>
       </rfc>
    OUTPUT
  end

[ronaldtse]

After some (more) thinking I kind of understand their intention of the usage of <seriesInfo> now.

<seriesInfo> in v3 does to 2 things:

• The name, stream and intended-status of this document
• The status of this document

While 7991 2.47.3 allows three values: Internet-Draft, RFC, and DOI, the last one is bogus. If the seriesInfo@name is set to "DOI", this element cannot belong to <front>, which according to RFC 7991 1.3.4:

Make a child of <front>, and deprecated it as a child of <reference>. This also deprecates some of the attributes from <rfc> and moves them into <seriesInfo>.

So the name value of "DOI" should not even apply to <seriesInfo>.

Usually there is a maximum of 2 <seriesInfo> elements:

RFC 7991 2.2.6: A element may have more than one <seriesInfo> element. A <seriesInfo> element determines the document number (for RFCs) or name (for Internet-Drafts). Another <seriesInfo> element determines the "maturity level" (defined in [RFC2026]), using values of "std" for "Standards Track", "bcp" for "BCP", "info" for "Informational", "exp" for "Experimental", and "historic" for "Historic". The "name" attributes of those multiple <seriesInfo> elements interact as described in Section 2.47.

• The first <seriesInfo> is the name, stream, and intended-status of the current document.
• The second <seriesInfo> is the "maturity level" of the document.

Only the seriesInfo@name and seriesInfo@value attributes are "Mandatory".

doctype: Internet-Draft

If a <front> element contains a <seriesInfo> element with a name of "Internet-Draft", it can also have at most one additional <seriesInfo> element with a "status" attribute whose value is of "standard", "full-standard", "bcp", "fyi", "informational", "experimental", or "historic" to indicate the intended status of this Internet-Draft, if it were to be later published as an RFC. If such an additional <seriesInfo> element has one of those statuses, the name needs to be "".

• Only 2 <seriesInfo> elements allowed.

This seems to be the required output:

<!-- Type of document, name of stream, current status of document (2.47.4), value is the Internet-Draft document name (in form of xxxx-xx) -->
<seriesInfo name="Internet-Draft" stream="xx" status="standard|informational|experimental|bcp|fyi|full-standard" value="[my-id-name]" />

<!-- Type of document, intended status of document if becomes RFC, value is the draft name -->
<seriesInfo name="" status="standard|informational|experimental|bcp|fyi|full-standard|historic" value="[my-id-name]" />

doctype: RFC

If a <front> element contains a <seriesInfo> element with a name of "RFC", it can also have at most one additional <seriesInfo> element with a "status" attribute whose value is of "full-standard", "bcp", or "fyi" to indicate the current status of this RFC. If such an additional <seriesInfo> element has one of those statuses, the "value" attribute for that name needs to be the number within that series. That <front> element might also contain an additional <seriesInfo> element with the status of "info", "exp", or "historic" and a name of "" to indicate the status of the RFC.

• Only 2 <seriesInfo> elements allowed.
• The "status" attribute value conflicts with those listed in 2.47.4. Maybe for v2 compatibility. Sounds like an errata is necessary. But in v2 the seriesInfo@status attribute doesn't exist.
• I don't understand what the last sentence means:

  That element might also contain an additional element with the status of "info", "exp", or "historic" and a name of "" to indicate the status of the RFC.

• Maybe it is for v2 compatibility?

This seems to be the required output:

<!-- Type of document, name of originating stream, current status of document (2.47.4), value is the RFC number -->
<seriesInfo name="RFC" stream="xx" status="standard|informational|experimental|bcp|fyi|full-standard" value="[my-rfc-number]" />

<!-- Type of document, current status of document, value the RFC number -->
<seriesInfo name="" status="full-standard|bcp|fyi" value="[my-rfc-number]" />

Only one of "Internet-Draft" or "RFC" as seriesInfo@name allowed

A element that has a element that has the name "Internet-Draft" cannot also have a element that has the name "RFC".

[opoudjis]

<!-- Type of document, name of stream, current status of document (2.47.4), value the RFC number -->
<seriesInfo name="Internet-Draft" stream="xx" status="standard|informational|experimental|bcp|fyi|full-standard" value="[my-rfc-number]" />

... But if it's an internet draft, do you have any idea what the RFC number is? I'm assuming you don't, so I'm just repeating the draft name.

[ronaldtse]

Oops dumb typo. You’re absolutely right it should be the draft name that ends with -xx. So my-id-name.

[opoudjis]

And my reading of the contentious clause

That element might also contain an additional element with the status of "info", "exp", or "historic" and a name of "" to indicate the status of the RFC.

Still tells me that the following is intended as possible

<seriesInfo name="RFC" stream="xx" status="standard|informational|experimental|bcp|fyi|full-standard" value="[my-rfc-number]" />
<seriesInfo name="" status="info|exp|historic" value="[my-rfc-number]" />

I'm making it the rfc number, rather than "none".

[ronaldtse]

I'm a bit skeptical that this is even allowed since this sentence is clearly problematic (wrong).

1. It says "That element might also contain an additional element", but the first "That element" is clearly the <seriesInfo> element, but it is not allowed to contain any element.

2. According to 7991 "status" is only allowed to have these values standard|informational|experimental|bcp|fyi|full-standard, which excludes info|exp. Moreover, in v2 the "status" attribute is not allowed on <seriesInfo>. Why would this section dictate something that is not compliant with both v3 and v2?

[opoudjis]

... Not clear what I should do here, if anything; this really does seem to be a matter for an erratum.

[ronaldtse]

I've reported this here: rfc-format/draft-iab-xml2rfc-v3-bis#28