Skip to main content

Implementation notes for RFC 7991, "The 'xml2rfc' Version 3 Vocabulary"
draft-levkowetz-xml2rfc-v3-implementation-notes-00

The information below is for an old version of the document.
Document Type
This is an older version of an Internet-Draft whose latest revision state is "Expired".
Author Henrik Levkowetz
Last updated 2018-07-16
RFC stream (None)
Formats
Additional resources
Stream Stream state (No stream defined)
Consensus boilerplate Unknown
RFC Editor Note (None)
IESG IESG state I-D Exists
Telechat date (None)
Responsible AD (None)
Send notices to (None)
draft-levkowetz-xml2rfc-v3-implementation-notes-00
Internet-Draft        RFC7991 Implementation Notes             July 2018

   Recommendation:  Omit deprecated attributes from the default-setting.

4.4.4.  In Section 5.2.7, "toc" Attribute

   It's specified that sections with <boilerplate> ancestors should have
   toc="exclude", but this won't then affect <boilerplate> sections
   which are inserted as part of the processing in 5.4.2.  It would make
   more sense to move this processing to after 5.4.2.

   The logic in the second bullet is flawed.  First it says to set
   elements with children with toc="include" to "include", but then it
   says that it is an error if they are set to "exclude".  Either there
   should be a warning, and the toc= attribute should be updated, or
   there should be an error and termination.  Not both.

4.4.5.  In Section 5.2.8, "removeInRFC" Warning Paragraph

   This potentially inserts a new <t> element, but after the default
   setting in 5.2.6.  Maybe place default setting after all potential
   element insertions have taken place.

4.4.6.  In Section 5.3.1, "month" Attribute

      "Normalise the values of "month" attributes in all <date> elements
      in <front> elements in <rfc> elements to numeric values."

   Is that 'in' a direct descendant relationship, or any descendant?
   I.e., does this affect <date> elements in included <reference>
   elements?  Unclear.  (RFC7991 is much clearer on this point, but
   that's not an excuse for being unclear here).

4.4.7.  In Section 5.3.2, ASCII Attribute Processing

   The uppercasing of 'ascii' in the section <name> is incorrect in this
   case; the attribute name is explicitly 'ascii', not 'ASCII'.  The
   section name should be '"ascii" Attribute Processing'.

      "In every <author> element"...

   After the earlier XInclude processing, this will include all the
   author elements in the included references, which the document author
   cannot normally do an anything about.  Is this the intention?

   Recommendation:  Limit it to /rfc/front/author' elements.

   <title> and <postalLine> also has an ascii attribute -- is it a
   mistake that they are not mentioned here?  Assuming so, for the
   preptool implementation.

Levkowetz               Expires January 17, 2019               [Page 14]
Internet-Draft        RFC7991 Implementation Notes             July 2018

   What about the ascii* attributes on author?  Assuming they should be
   processed the same way.

4.4.8.  New Section: "keepWithNext" Normalisation

   This should specify normalisation of keepWithNext/keepWithPrevious
   such as to replace all keepWithNext with an equivalent
   keepWithPrevious on the following <t>

4.4.9.  In Section 5.4.2, <boilerplate> Insertion

      "Create a <boilerplate> element if it does not exist.  If there
      are any children of the <boilerplate> element, produce a warning
      that says "Existing boilerplate being removed.  Other tools,
      specifically the draft submission tool, will treat this condition
      as an error" and remove the existing children."

   Should this be done in both I-D mode and RFC mode?  The trouble is
   that the following subsections only describes the boilerplate
   relevant to an RFC; there's additional boilerplate that is needed for
   drafts.  I don't think it's reasonable to have a draft with only
   parts of the boilerplate contained in a boilerplate section.

   Recommendation:  The boilerplate-element insertion parts of 5.4.2 be
      done in both RFC and draft mode, with the appropriate boilerplate
      for each case.  Add text to describe the appropriate boilerplate
      for drafts, or remove the sections specific to RFC boilerplate.

   This section also specifies an error message to be used verbatim; the
   troublesome thing is that it's not clear what it means.  The message
   is: "Existing boilerplate being removed.  Other tools, specifically
   the draft submission tool, will treat this condition as an error".
   What is it that the draft submission tool is going to treat as an
   error?  The presence of boilerplate?  Why?  The removal of
   boilerplate?  How is that related to draft submission?  This is very
   jumbled.

4.4.10.  In Section 5.4.2.1, Compare <rfc> submissionType and
         <seriesInfo> "stream".

   This comes too late.  It is specified that if either is missing, it
   should be added.  But the default attribute setting earlier has set
   stream="IETF" on all <seriesInfo> elements that didn't have it.  If a
   document is read without submissionType, and stream set correctly to
   something else than "IETF" on one of the <seriesInfo> elements, then
   the default-setting will have created a conflict which cannot be
   resolved purely from the document at this point.

Levkowetz               Expires January 17, 2019               [Page 15]
Internet-Draft        RFC7991 Implementation Notes             July 2018

   It doesn't seem like a good fit to have tag attributes that all have
   to be set to the same value.  This is not DRY, and unnecessarily
   introduces the possibility of conflict, as a result of multiple
   <seriesInfo> elements being permitted (Relevant to the v3 schema, not
   the preptool).

   Recommendation:  Remove the default value for stream, and make it
      subordinate to submissionType.

4.4.11.  In Section 5.4.2.2, "Status of this Memo" Insertion

   It specifies that one should consider both submissionType and
   <seriesInfo> stream value; but those have just been set equal in
   5.4.2.1.  The text should be adjusted to not sound as if these two
   should be both be considered as if they could be different.

4.4.12.  In Section 5.4.3, <reference> "target" Insertion

      "Insert "target" attributes for RFC, DOI, and Internet-Draft
      references that lack them."

   It is indicated that the rfc-editor will provide the URL patterns.
   What are they?

   The order of <seriesInfo> determines the rendering order.  These
   should be sorted in the desired rendering order (currently 'BCP',
   'RFC', 'DOI'.  The current implementation does so.

4.4.13.  In Section 5.4.4, <name> Slugification

   The 'n-' prefix for slugs is unnecessarily opaque.

   Recommendation:  Use slugs with prefix "name-" rather than "n-", to
      be more self-documenting.

   Should the slugs be unique?  Assuming yes, but guidance would be
   good.  The current implementation enforces unique slugs, with the
   following algorithm:

   *  remove non-ascii letters

   *  replace-non-letters with dash, compacting multiple dashes to one

   *  reduce length to 32, but insure uniqueness by increasing length or
      adding numerical suffixes, up to length 40 with suffixes numbered
      2 to 99.

Levkowetz               Expires January 17, 2019               [Page 16]
Internet-Draft        RFC7991 Implementation Notes             July 2018

4.4.14.  In Section 5.4.6, "pn" Numbering.

   What does 'pn' mean?  Cryptic is never good when humans have to deal
   with it.  At least explain as "part number" in text.  Possibly even
   change pn="" to part="".

   <back><section> is not mentioned.  Assuming numbering as section-
   appendix.1.2

   <iref> elements are not mentioned (but covered in 7991).  Should be
   listed in 7998.

   The numbering scheme is inconsistent between notes/boilerplate and
   other sections, in that attempting to split a pn on dashes (which
   external tools might want to do) the boilerplate/note sections
   contain an additional dash.

   Recommendation:  Change that to a dot, for better consistency with
      other sections.  This also makes the <t> part numbers less
      confusing: "section-boilerplate.1-1" instead of "section-
      boilerplate-1-1"

4.4.14.1.  RFC format anchors / fragment identifiers

   The anchor prefixes described unnecessarily break with existing links
   to document sections.  Wikipedia has (2018-02-19) about 84 000 pages
   that link to RFCs; with most pages having multiple links.  A small
   manual sampling indicates that about 1 link in 10 has a #section-
   fragment identifier.  All of these will break if the new tools are
   used to generated content linked from these pages.

   How much larger than Wikipedia is the whole of the internet, in terms
   of links to RFCs?  Hard to tell (though searching for 'rfc' on Google
   indicates 'about 10 000 000 results).  In any case, we are talking
   about breaking a substantial number of links using fragment
   identifiers of the format #section- and #appendix- if the new tools
   are used to replace the old html content that sites currently point
   to.

   Recommendation:  update rfc7998 preptool to use these prefixes,
      instead:

      -  "section-xxx"

      -  "figure-xxx"

      -  "table-xxx"

Levkowetz               Expires January 17, 2019               [Page 17]
Internet-Draft        RFC7991 Implementation Notes             July 2018

      -  "appendix-xxx"

      -  "index-xxx"

      -  "para-xxx"

      -  "name-xxx"

4.4.15.  In Section 5.4.7, <iref> Numbering

   Numbering of <iref> talks about setting the 'pn' attribute.  Mixed
   into this is a mention of 'irefid', which isn't a valid attribute.
   The current implementation assumes that 'pn' is meant.

   The item and sub-item text is not constrained to slug format; in
   order to deliver useful pn values, slugification should be done.  On
   the other hand, the explicit prescription of how to ensure uniqueness
   clashes with the total lack of uniqueness attention under 5.4.4.

   Recommendation:  Remove the details of how to ensure uniqueness.

4.4.16.  In Section 5.4.8.2, "derivedContent" Insertion (without
         Content)

   There's a formatting mistake:

   The last sentence of the last bullet ("Issue a warning...") should
   not be part of the bullet, but a separate final paragraph for the
   Section.

4.4.17.  In Section 5.5.1, <artwork> Processing

   RFC791 specifies that the <artwork> content is a fallback if there is
   external <svn> content, but 7998 says to drop the fallback and insert
   the external <svn>.  This deletes information, and makes the fallback
   unavailable.  This needs a better handling.

   For now, if there is fallback content, the external URL content is
   converted to a data: URL for the src, which pulls it in and makes it
   immutable, but retains the fallback.

4.4.18.  In Section 5.5.2, <sourcecode> Processing

   List item 4 says:

      "fill the content of the <sourcecode> element with the resolved
      XML from the URI in the "src" attribute"

Levkowetz               Expires January 17, 2019               [Page 18]
Internet-Draft        RFC7991 Implementation Notes             July 2018

   However, the URI should not be assumed to resolve to xml, but instead
   treated like CDATA.

4.4.19.  In Section 5.4.8.2, "derivedContent" Insertion.

   It is not clear from the description if the derived content text
   should contain square brackets when an <xref> would be rendered with
   square brackets in current output formats.

   It is not clear if the derived content should include the 'Figure',
   or 'Table' label when pointing to such objects.  When rendering such
   a reference in the current output formats, the generated text would
   include the label, but the current text seems to lean towards not
   making this part of the derived content, which would cause
   incompatibility with the output of v2 formatters.

   The purpose of this is insufficiently explained.  If the intention is
   to use this when generating derived formats, there are problems: If,
   for instance, the derived format with a <reference> target is set to
   'RFC1234', the text inserted in a derived format should have
   surrounding square brackets; but if the target is a section, it
   should not.  If on the other hand the derived format includes the
   square brackets when appropriate, the link in a derived format with
   internal link capability will use the whole of the bracketed string,
   rather than the more appropriate text within the brackets.

   The current implementation works around this by using different
   formatter code for different cases, which is not good from the
   viewpoint of using the prepped XML as the archival format.  The whole
   "derivedContent" handling and specification needs a thorough rework,
   with specification of the intended use of the attribute by
   formatters.

4.4.20.  In Section 5.4.9, <relref> Processing

   Why doesn't <relref> have the same format options as <xref>?  Surely
   they must be just as relevant here.  But more importantly, <relref>
   overlaps <xref> so much that it would be better to just add section,
   relative, and displayFormat to <xref>.  Maybe change displayFormat to
   the earlier proposed 'sectionFormat'.

   Recommendation:  Deprecate <relref>, and fold the functionality into
      <xref>.

Levkowetz               Expires January 17, 2019               [Page 19]
Internet-Draft        RFC7991 Implementation Notes             July 2018

4.4.21.  In Section 5.6.3, <link> Processing

   Bullet 4.: Bad grammar s/RFC the form/RFC, in the form/

   Bullet 4.: Hmm.  The <link rel="convertedFrom" href="draft-....">
   should ideally be created automatically, but there is no clear path
   of how to do that.

   Recommendation:  Require docName to be set to the draft name, and use
      that to create this link.

4.4.22.  New Section for Index

   RFC7998 does not say a word about index, but it seems counter-
   intuitive not to produce one, given all other prepping being done.
   What's more, in Section 2.27 of RFC 7991 there's this text:

      "When the prep tool is creating index content, it collects the
      items in a case-sensitive fashion for both the item and sub-item
      level."

5.  Informative References

   [RFC4228]  Rousskov, A., "Requirements for an IETF Draft Submission
              Toolset", RFC 4228, DOI 10.17487/RFC4228, December 2005,
              <https://www.rfc-editor.org/info/rfc4228>.

   [RFC6087]  Bierman, A., "Guidelines for Authors and Reviewers of YANG
              Data Model Documents", RFC 6087, DOI 10.17487/RFC6087,
              January 2011, <https://www.rfc-editor.org/info/rfc6087>.

   [RFC7749]  Reschke, J., "The "xml2rfc" Version 2 Vocabulary",
              RFC 7749, DOI 10.17487/RFC7749, February 2016,
              <https://www.rfc-editor.org/info/rfc7749>.

   [RFC7991]  Hoffman, P., "The "xml2rfc" Version 3 Vocabulary",
              RFC 7991, DOI 10.17487/RFC7991, December 2016,
              <https://www.rfc-editor.org/info/rfc7991>.

   [RFC7992]  Hildebrand, J., Ed. and P. Hoffman, "HTML Format for
              RFCs", RFC 7992, DOI 10.17487/RFC7992, December 2016,
              <https://www.rfc-editor.org/info/rfc7992>.

   [RFC7993]  Flanagan, H., "Cascading Style Sheets (CSS) Requirements
              for RFCs", RFC 7993, DOI 10.17487/RFC7993, December 2016,
              <https://www.rfc-editor.org/info/rfc7993>.

Levkowetz               Expires January 17, 2019               [Page 20]
Internet-Draft        RFC7991 Implementation Notes             July 2018

   [RFC7994]  Flanagan, H., "Requirements for Plain-Text RFCs",
              RFC 7994, DOI 10.17487/RFC7994, December 2016,
              <https://www.rfc-editor.org/info/rfc7994>.

   [RFC7995]  Hansen, T., Ed., Masinter, L., and M. Hardy, "PDF Format
              for RFCs", RFC 7995, DOI 10.17487/RFC7995, December 2016,
              <https://www.rfc-editor.org/info/rfc7995>.

   [RFC7996]  Brownlee, N., "SVG Drawings for RFCs: SVG 1.2 RFC",
              RFC 7996, DOI 10.17487/RFC7996, December 2016,
              <https://www.rfc-editor.org/info/rfc7996>.

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

   [RFC7998]  Hoffman, P. and J. Hildebrand, ""xml2rfc" Version 3
              Preparation Tool Description", RFC 7998,
              DOI 10.17487/RFC7998, December 2016,
              <https://www.rfc-editor.org/info/rfc7998>.

   [XML2RFC]  Levkowetz, H., "xml2rfc", 2018,
              <https://pypi.org/pypi/xml2rfc>.

Author's Address

   Henrik Levkowetz
   Elf Tools AB
   Ollonstigen 8
   Sweden

   Email: henrik@levkowetz.com

Levkowetz               Expires January 17, 2019               [Page 21]