Network Working Group H. Levkowetz
Internet-Draft Elf Tools AB
Intended status: Informational September 28, 2018
Expires: April 1, 2019
Implementation notes for RFC7991, "The 'xml2rfc' Version 3 Vocabulary"
draft-levkowetz-xml2rfc-v3-implementation-notes-02
Abstract
This memo documents issues and observations found while implementing
RFC 7991. Individual notes are organised into separate sections,
depending on their character.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 1, 2019.
Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Levkowetz Expires April 1, 2019 [Page 1]
Internet-Draft RFC7991 Implementation Notes September 2018
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Fitness for Purpose . . . . . . . . . . . . . . . . . . . . . 4
2.1. Degraded Table of Contents . . . . . . . . . . . . . . . 4
2.2. Justification of Tables and Artwork . . . . . . . . . . . 5
2.3. RFC Publication Date Policy . . . . . . . . . . . . . . . 5
3. Schema Issues . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. RFC 7991 . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1.1. In Section 2.5.5, "name" Attribute . . . . . . . . . 5
3.1.2. In Section 2.12, . . . . . . . . . . . . . . . . 6
3.1.3. In Section 2.20,
"empty" attribute . . . . . . 11
3.1.14. In Section 3.4.2, "hangIndent" Attribute . . . . . . 11
3.1.15. In Appendix C. Relax NG schema . . . . . . . . . . . 11
3.1.16. Use of the term "counter". . . . . . . . . . . . . . 12
3.2. RFC 7998 . . . . . . . . . . . . . . . . . . . . . . . . 12
3.2.1. In Section 5.2.6, Attribute Default Value Insertion . 12
3.2.2. In Section 5.4.6, "pn" Numbering. . . . . . . . . . . 12
4. Non-Schema Issues . . . . . . . . . . . . . . . . . . . . . . 13
4.1. RFC 7991 . . . . . . . . . . . . . . . . . . . . . . . . 13
4.1.1. In Section 2.17, . . . . . . . . . . . . . . . 13
4.1.2. In Section 2.47, . . . . . . . . . . . . 14
4.1.3. In Appendix A.1.1: TLP switch-over date discrepancies 15
4.1.4. Index . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.5. Anchors . . . . . . . . . . . . . . . . . . . . . . . 15
4.1.6. In Section 2.5.7, "type" Attribute . . . . . . . . . 16
4.2. RFC 7992 . . . . . . . . . . . . . . . . . . . . . . . . 16
4.2.1. In Section 8.1.1, Index Contents . . . . . . . . . . 16
4.3. RFC 7994 . . . . . . . . . . . . . . . . . . . . . . . . 17
4.3.1. Additional Guidance . . . . . . . . . . . . . . . . . 17
4.4. RFC 7998 . . . . . . . . . . . . . . . . . . . . . . . . 17
4.4.1. In Section 5.2.3, Insertion . . . . . . . . . 17
4.4.2. In Section 5.2.4, "prepTime" Insertion . . . . . . . 18
4.4.3. In Section 5.2.6, Attribute Default Value Insertion . 18
4.4.4. In Section 5.2.7, "toc" Attribute . . . . . . . . . . 19
4.4.5. In Section 5.2.8, "removeInRFC" Warning Paragraph . . 19
4.4.6. In Section 5.3.1, "month" Attribute . . . . . . . . . 19
4.4.7. In Section 5.3.2, ASCII Attribute Processing . . . . 20
Levkowetz Expires April 1, 2019 [Page 2]
Internet-Draft RFC7991 Implementation Notes September 2018
4.4.8. New Section: "keepWithNext" Normalisation . . . . . . 20
4.4.9. In Section 5.4.2, Insertion: Only for
RFCs? . . . . . . . . . . . . . . . . . . . . . . . . 20
4.4.10. In Section 5.4.2, Insertion: Error
Message . . . . . . . . . . . . . . . . . . . . . . . 21
4.4.11. In Section 5.4.2.1, Compare submissionType and
"stream". . . . . . . . . . . . . . . . 21
4.4.12. In Section 5.4.2.2, "Status of this Memo" Insertion . 22
4.4.13. In Section 5.4.3, "target" Insertion . . 22
4.4.14. In Section 5.4.4, Slugification . . . . . . . 23
4.4.15. In Section 5.4.6, "pn" Numbering. . . . . . . . . . . 23
4.4.16. In Section 5.4.7, Numbering . . . . . . . . . 25
4.4.17. In Section 5.4.8.2, "derivedContent" Insertion
(without Content) . . . . . . . . . . . . . . . . . . 25
4.4.18. In Section 5.5.1, Processing . . . . . . . 25
4.4.19. In Section 5.5.2, Processing . . . . . . 25
4.4.20. In Section 5.4.8.2, "derivedContent" Insertion. . . . 26
4.4.21. In Section 5.4.9, Processing . . . . . . . . 27
4.4.22. In Section 5.6.3, Processing . . . . . . . . 27
4.4.23. New Section for Index . . . . . . . . . . . . . . . . 27
5. Security Considerations . . . . . . . . . . . . . . . . . . . 28
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 28
6.1. Informative References . . . . . . . . . . . . . . . . . 28
6.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 29
1. Introduction
Implementation of tool support for [RFC7991] and related
specifications has been done during 2017 and 2018, split in the
following individual parts, all implemented as individual modes of
the python-based xml2rfc processor [XML2RFC]:
* An XML converter from vocabulary version 2 [RFC7749] to version 3
[RFC7991]
* A Normalisation processor, "PrepTool", [RFC7997]
* An XML to plain text converter [RFC7994] for the version 3
vocabulary
* An XML to html converter [RFC7992] for the version 3 vocabulary
(work in progress as of 28 Sep. 2018)
* A HTML to PDF converter [RFC7995] for the version 3 vocabulary
(pending as of 28 Sep. 2018)
Levkowetz Expires April 1, 2019 [Page 3]
Internet-Draft RFC7991 Implementation Notes September 2018
During the implementation work, a number of issues with the
specification has been found (this was expected at the outset by all
parties) and a number of observations has been made about limitations
of the specification and vocabulary version 3 schema, and also
limitations in the specification of the work to be done.
The purpose of this memo is to collect those issues and observations
in one place.
When this memo says 'the current version of xml2rfc', it refers to
the latest release of the xml2rfc processor available from the PyPi
package repository [1] at the date this document was published, as
given above. As of 28 Sep. 2018, this was version 2.10.3.
2. Fitness for Purpose
The introduction to [RFC7991] states:
"This document defines the "xml2rfc" version 3 vocabulary: an XML-
based language used for writing RFCs and Internet-Drafts. It is
heavily derived from the version 2 vocabulary that is also under
discussion. This document obsoletes the v2 grammar described in
RFC 7749."
However, an unstated assumption seems to have been that the new tools
and formatters would be used primarily to produce HTML output, in
order to transition to publication of renderings of RFCs in more
modern formats than plain-text ASCII.
This is a reasonable and worthwhile goal, but as a result, the schema
as specified in [RFC7991] has some drawbacks compared with the
version 2 vocabulary when used to produce Internet-Drafts in the text
format common within the IETF (Internet Engineering Task Force) at
this time.
2.1. Degraded Table of Contents
Lack of pagination has little impact on direct online readability,
but when comparing the output of the new text formatter with the old
one, one aspect leaps out: Since there is no pagination, the table of
contents simply lists the section headers to a certain depth, without
any accompanying page numbers. This makes a surprising difference in
how useful the table of contents is in getting an initial feel for
the document. The at-a-glance information which lets a reader know
if this is a document of 10 pages or 100 is simply lacking.
Recommendation: Add support for pagination in a future version of
the text formatter.
Levkowetz Expires April 1, 2019 [Page 4]
Internet-Draft RFC7991 Implementation Notes September 2018
Implementation: None in the current version of xml2rfc.
2.2. Justification of Tables and Artwork
The version 3 schema deprecates the previously available 'align'
attribute for artwork and tables, and the PrepTool will remove these
attributes if used. This makes a previous feature that was
appreciated by some authors unavailable. In the text formatter, the
effect is simply to make all tables and artwork left-aligned, which
may not be the most readable and polished output, but for the HTML
formatter it also potentially removes the option of letting text flow
around smaller artwork and tables in a controlled way.
Recommendation: Make the 'align' attribute for artwork and tables
available again.
Implementation: Implemented but inactive in the current version of
xml2rfc. The current text formatter code already has support for
the 'align' attribute for these elements; but since the attribute
is stripped away by the PrepTool, the code is never invoked.
2.3. RFC Publication Date Policy
The specification [RFC7998] says that an error should be generated if
a specification is found with missing elements; but the RFC
Editor publishes documents (except for April 1st RFCs) with only year
and month, no day of month. The specification disallows this, and in
effect makes it impossible for the RFC Editor to publish documents
according to the current policy regarding publication date format.
Recommendation: Revert to to the old behaviour, where the tool in
RFC mode would issue a date with or without day depending on
whether the element had a day attribute or not.
Implementation: All elements of are required in the current
version of xml2rfc.
3. Schema Issues
3.1. RFC 7991
3.1.1. In Section 2.5.5, "name" Attribute
"A filename suitable for the contents (such as for extraction to a
local file)."
Given the existing use of "name" on , this attribute name
has a semantic dissonance.
Levkowetz Expires April 1, 2019 [Page 5]
Internet-Draft RFC7991 Implementation Notes September 2018
Recommendation: Deprecate "name" for use on and
, and instead use "file", which for will
be explicitly rendered, as established as best current practice
for YANG modules (see for instance RFC 6087 [RFC6087])
Implementation: The current version of xml2rfc uses "name".
3.1.2. In Section 2.12,
A number of elements permits a mixed content model (see
Section "Mixed Content Model"):
,
,
,
, and
. However, when using the simpler of the two content schemas,
two of them (
and
) permit inline line breaks through the use
of elements; the others do not. This seems terribly arbitrary.
Recommendation: Remove the element completely. Alternatively,
permit it to be used all places that 'text' and non-block elements
may be used (that is, in inline context).
Implementation: The current version of xml2rfc renders as a
newline in all inline contexts.
3.1.3. In Section 2.20,
The current specification says:
"The "hanging" attribute defines whether or not the term appears
on the same line as the definition. hanging="true" indicates that
the term is to the left of the definition, while hanging="false"
indicates that the term will be on a separate line."
This does not match established typographic terminology. In
typographic terminology, "hanging indent" describes the case where
the indentation of the second and subsequent lines of a paragraph is
greater than the indentation of the first line. Whether the
definition in a definition list starts on the first line or not has
nothing to do with the presence of hanging indent; our definition
lists will _always_ have hanging indent.
The 'hanging' attribute also describes something different from what
the term has been used to describe in the version 2 vocabulary. This
will be confusing to users.
A more descriptive name for the attribute we're talking about would
be 'start-definition-on-first-line', but that's unwieldy. Maybe
'newline="false"' to start the definition on the first line, or
something like 'definition-start="first"'?
Levkowetz Expires April 1, 2019 [Page 6]
Internet-Draft RFC7991 Implementation Notes September 2018
Recommendation: Change this to a different term that is more
descriptive and does not use typographically incorrect
terminology.
Implementation: The current version of xml2rfc still uses "hanging".
3.1.4. New Section 2.20.4, "indent" Attribute
The deprecation of the "hangIndent" attribute on leaves no
opportunity to control the size of the hanging indent. In some
definition lists, it is desirable to have a wide indentation, in
order to clearly show the terms, in other cases it is more important
to allow for a larger text volume than the width of the terms would
allow.
Recommendation: Add an "indent" attribute on
to control the
size of the hanging indent.
Implementation: The current version of xml2rfc does not support the
attribute, but has all the underlying functions needed to apply
such an attribute. Internally, an indentation is calculated based
on length of the
text and the settings of some of the other
attributes.
3.1.5. In Section 2.29,
3.1.5.1. Unordered lists with arbitrary symbols
When
is used with
, the rendering is under-
specified (the specification say 'no label will be shown", but
doesn't say whether list indentation (leading white-space) should be
eliminated or not.
If the intention is to make it possible to render unordered lists
with arbitrary symbols, chosen on a per-list-item basis, the current
attributes of
are insufficient to indent and line-wrap list
items properly with
.
It is not possible, for instance, to use
lists to generate XML
for a table of content, since if the width of the bullet (the section
number, in this case) is unknown, the proper indentation and line
wrapping cannot be determined.
Recommendation: Add an explicit "bullet" attribute to support this
use case.
Levkowetz Expires April 1, 2019 [Page 7]
Internet-Draft RFC7991 Implementation Notes September 2018
Implementation: None in the current version of xml2rfc, but
internally bullets are taken a configurable bullet list, so
accommodating such an attribute would be trivial.
3.1.5.2. Mixed Content Model
The mixed content model for
--- either text and inline elements
like sub, sup, bcp14, _or_ ,