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]