search

rfc-format / draft-iab-xml2rfc-v3-bis

-bis document for the RFC format xml2rfc v3 draft
6 stars 10 forks source link

Clarifications needed on the `<seriesInfo>` element #28

Open ronaldtse opened 6 years ago

ronaldtse commented 6 years ago

This issue was originally discussed here: https://github.com/riboseinc/asciidoctor-rfc/issues/49

We'd like to clarify the allowed / intended values for the <seriesInfo> tag:

Allowed Values

<seriesInfo> in v3 does to 2 things:

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

Is this correct?

Intention of the 2 <seriesInfo> elements

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.

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

Is this usage accurate?

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

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]" />

Is this the intention?

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

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]" />

Is this correct?

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

Problematic clause

This clause is particular contentious:

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.

Since it means this is intended:

<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]" />

However, this sentence is clearly incorrect:

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

  2. According to RFC 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?

Could someone clarify this?

reschke commented 4 years ago

Related to #7