idnits 2.17.1 

draft-levkowetz-xml2rfc-v3-implementation-notes-04.txt:
-(7): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding
-(589): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding

  Checking boilerplate required by RFC 5378 and the IETF Trust (see
  https://trustee.ietf.org/license-info):
  ----------------------------------------------------------------------------

     No issues found here.

  Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
  ----------------------------------------------------------------------------

  == There are 11 instances of lines with non-ascii characters in the
     document.


  Checking nits according to https://www.ietf.org/id-info/checklist :
  ----------------------------------------------------------------------------

  ** The document seems to lack an IANA Considerations section.  (See Section
     2.2 of https://www.ietf.org/id-info/checklist for how to handle the case
     when there are no actions for IANA.)

  == There are 1 instance of lines with non-RFC6890-compliant IPv4 addresses
     in the document.  If these are example addresses, they should be changed.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the IETF Trust and authors Copyright Line does not
     match the current year

  -- The document date (October 22, 2018) is 2005 days in the past.  Is this
     intentional?


  Checking references for intended status: Informational
  ----------------------------------------------------------------------------

  -- Looks like a reference, but probably isn't: '1' on line 1589

  -- Looks like a reference, but probably isn't: '2' on line 1591

  -- Looks like a reference, but probably isn't: '3' on line 1593

  -- Looks like a reference, but probably isn't: '4' on line 1595

  -- Looks like a reference, but probably isn't: '5' on line 1597

  -- Looks like a reference, but probably isn't: '6' on line 1599

  -- Looks like a reference, but probably isn't: '7' on line 1601

  -- Looks like a reference, but probably isn't: '8' on line 1603

  -- Looks like a reference, but probably isn't: '9' on line 1605

  -- Looks like a reference, but probably isn't: '10' on line 1607

  -- Looks like a reference, but probably isn't: '11' on line 1609

  == Unused Reference: 'RFC7993' is defined on line 1559, but no explicit
     reference was found in the text

  == Unused Reference: 'RFC7996' is defined on line 1571, but no explicit
     reference was found in the text

  -- Obsolete informational reference (is this intentional?): RFC 6087
     (Obsoleted by RFC 8407)

  -- Obsolete informational reference (is this intentional?): RFC 7749
     (Obsoleted by RFC 7991)


     Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 14 comments (--).

     Run idnits with the --verbose option for more detailed information about
     the items above.

--------------------------------------------------------------------------------


2	Network Working Group                                       H. Levkowetz
3	Internet-Draft                                              Elf Tools AB
4	Intended status: Informational                          October 22, 2018
5	Expires: April 25, 2019

7	 Implementation notes for RFC7991,
"The 'xml2rfc' Version 3 Vocabulary"
8	           draft-levkowetz-xml2rfc-v3-implementation-notes-04

10	Abstract

12	   This memo documents issues and observations found while implementing
13	   RFC 7991.  Individual notes are organised into separate sections,
14	   depending on their character.

16	Status of This Memo

18	   This Internet-Draft is submitted in full conformance with the
19	   provisions of BCP 78 and BCP 79.

21	   Internet-Drafts are working documents of the Internet Engineering
22	   Task Force (IETF).  Note that other groups may also distribute
23	   working documents as Internet-Drafts.  The list of current Internet-
24	   Drafts is at https://datatracker.ietf.org/drafts/current/.

26	   Internet-Drafts are draft documents valid for a maximum of six months
27	   and may be updated, replaced, or obsoleted by other documents at any
28	   time.  It is inappropriate to use Internet-Drafts as reference
29	   material or to cite them other than as "work in progress."

31	   This Internet-Draft will expire on April 25, 2019.

33	Copyright Notice

35	   Copyright (c) 2018 IETF Trust and the persons identified as the
36	   document authors.  All rights reserved.

38	   This document is subject to BCP 78 and the IETF Trust's Legal
39	   Provisions Relating to IETF Documents
40	   (https://trustee.ietf.org/license-info) in effect on the date of
41	   publication of this document.  Please review these documents
42	   carefully, as they describe your rights and restrictions with respect
43	   to this document.  Code Components extracted from this document must
44	   include Simplified BSD License text as described in Section 4.e of
45	   the Trust Legal Provisions and are provided without warranty as
46	   described in the Simplified BSD License.

48	Table of Contents

50	   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
51	   2.  Fitness for Purpose . . . . . . . . . . . . . . . . . . . . .   4
52	     2.1.  Degraded Table of Contents  . . . . . . . . . . . . . . .   5
53	     2.2.  RFC Publication Date Policy . . . . . . . . . . . . . . .   5
54	   3.  Schema Issues . . . . . . . . . . . . . . . . . . . . . . . .   5
55	     3.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .   5
56	       3.1.1.  In Section 2.5.5, "name" Attribute  . . . . . . . . .   5
57	       3.1.2.  In Section 2.6, <aside> . . . . . . . . . . . . . . .   6
58	       3.1.3.  In Section 2.12, <br> . . . . . . . . . . . . . . . .   6
59	       3.1.4.  In Section 2.20, <dl> . . . . . . . . . . . . . . . .   6
60	       3.1.5.  New Section 2.20.4, "indent" Attribute  . . . . . . .   7
61	       3.1.6.  New Section 2.54.2  . . . . . . . . . . . . . . . . .   7
62	       3.1.7.  In Section 2.29, <li> . . . . . . . . . . . . . . . .   8
63	       3.1.8.  In Section 2.32, <name> . . . . . . . . . . . . . . .   9
64	       3.1.9.  In Section 2.32, <organization> . . . . . . . . . . .   9
65	       3.1.10. In Section 2.40.2, "quoteTitle" . . . . . . . . . . .   9
66	       3.1.11. In Section 2.42, <references> . . . . . . . . . . . .   9
67	       3.1.12. In Section 2.45.1, "category" Attribute . . . . . . .  10
68	       3.1.13. In Section 2.45.3, "docName" Attribute  . . . . . . .  10
69	       3.1.14. In Section 2.45.7, "number" Attribute . . . . . . . .  10
70	       3.1.15. In Section 2.53.3 and 2.53.4. . . . . . . . . . . . .  11
71	       3.1.16. New Section 2.X, <u>  . . . . . . . . . . . . . . . .  11
72	       3.1.17. In Section 2.63.2, <ul> "empty" attribute . . . . . .  13
73	       3.1.18. In Section 3.4.2, "hangIndent" Attribute  . . . . . .  14
74	       3.1.19. In Appendix C.  Relax NG schema . . . . . . . . . . .  14
75	       3.1.20. Use of the term "counter".  . . . . . . . . . . . . .  14
76	     3.2.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  15
77	       3.2.1.  In Section 5.2.6, Attribute Default Value Insertion .  15
78	       3.2.2.  In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  15
79	     3.3.  Some attributes should have value type xsd:ID . . . . . .  15
80	   4.  Non-Schema Issues . . . . . . . . . . . . . . . . . . . . . .  16
81	     4.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .  16
82	       4.1.1.  In Section 2.5.7, "type" Attribute  . . . . . . . . .  16
83	       4.1.2.  New Section 2.8.1: Index  . . . . . . . . . . . . . .  16
84	       4.1.3.  In Section 2.17, <date> . . . . . . . . . . . . . . .  17
85	       4.1.4.  In Section 2.40.1, "anchor" Attribute . . . . . . . .  18
86	       4.1.5.  In Section 2.47, <seriesInfo> . . . . . . . . . . . .  18
87	       4.1.6.  In Appendix A.1.1: TLP switch-over date discrepancies  19
88	     4.2.  RFC 7992  . . . . . . . . . . . . . . . . . . . . . . . .  19
89	       4.2.1.  In Section 5.1,  IDs  . . . . . . . . . . . . . . . .  19
90	       4.2.2.  In Section 6.2, Root Element  . . . . . . . . . . . .  20
91	       4.2.3.  In Section 6.4,  Page Headers and Footers . . . . . .  20
92	       4.2.4.  In Section 6.5, Document Information  . . . . . . . .  20
93	       4.2.5.  In Section 8.1.1, Index Contents  . . . . . . . . . .  21
94	       4.2.6.  Inconsistent use of "s-", "n-" and User-Supplied "id"
95	               Attributes  . . . . . . . . . . . . . . . . . . . . .  21

97	     4.3.  RFC 7994  . . . . . . . . . . . . . . . . . . . . . . . .  22
98	       4.3.1.  Additional Guidance . . . . . . . . . . . . . . . . .  22
99	     4.4.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  22
100	       4.4.1.  In Section 5.2.3, <date> Insertion  . . . . . . . . .  22
101	       4.4.2.  In Section 5.2.4, "prepTime" Insertion  . . . . . . .  23
102	       4.4.3.  In Section 5.2.6, Attribute Default Value Insertion .  23
103	       4.4.4.  In Section 5.2.7, "toc" Attribute . . . . . . . . . .  24
104	       4.4.5.  In Section 5.2.8, "removeInRFC" Warning Paragraph . .  24
105	       4.4.6.  In Section 5.3.1, "month" Attribute . . . . . . . . .  24
106	       4.4.7.  In Section 5.3.2, ASCII Attribute Processing  . . . .  25
107	       4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation . . .  25
108	       4.4.9.  In Section 5.4.2, <boilerplate> Insertion: Only for
109	               RFCs? . . . . . . . . . . . . . . . . . . . . . . . .  25
110	       4.4.10. In Section 5.4.2, <boilerplate> Insertion: Error
111	               Message . . . . . . . . . . . . . . . . . . . . . . .  26
112	       4.4.11. In Section 5.4.2.1, Compare <rfc> submissionType and
113	               <seriesInfo> "stream".  . . . . . . . . . . . . . . .  26
114	       4.4.12. In Section 5.4.2.2, "Status of this Memo" Insertion .  27
115	       4.4.13. In Section 5.4.3, <reference> "target" Insertion  . .  27
116	       4.4.14. In Section 5.4.4, <name> Slugification  . . . . . . .  28
117	       4.4.15. In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  28
118	       4.4.16. In Section 5.4.7, <iref> Numbering  . . . . . . . . .  30
119	       4.4.17. In Section 5.4.8.2, "derivedContent" Insertion
120	               (without Content) . . . . . . . . . . . . . . . . . .  30
121	       4.4.18. In Section 5.5.1, <artwork> Processing  . . . . . . .  30
122	       4.4.19. In Section 5.5.2, <sourcecode> Processing . . . . . .  30
123	       4.4.20. In Section 5.4.8.2, "derivedContent" Insertion. . . .  31
124	       4.4.21. In Section 5.4.9, <relref> Processing . . . . . . . .  32
125	       4.4.22. New Section 5.4.10, Index Insertion . . . . . . . . .  32
126	       4.4.23. In Section 5.6.3,  <link> Processing  . . . . . . . .  32
127	   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  33
128	   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  33
129	     6.1.  Informative References  . . . . . . . . . . . . . . . . .  33
130	     6.2.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .  34
131	   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  35

133	1.  Introduction

135	   Implementation of tool support for [RFC7991] and related
136	   specifications has been done during 2017 and 2018, split in the
137	   following individual parts, all implemented as individual modes of
138	   the python-based xml2rfc processor [XML2RFC]:

140	   *  An XML converter from vocabulary version 2 [RFC7749] to version 3
141	      [RFC7991]

143	   *  A Normalisation processor, "PrepTool", [RFC7997]
144	   *  An XML to plain text converter [RFC7994] for the version 3
145	      vocabulary

147	   *  An XML to html converter [RFC7992] for the version 3 vocabulary
148	      (work in progress as of 28 Sep. 2018)

150	   *  A HTML to PDF converter [RFC7995] for the version 3 vocabulary
151	      (pending as of 28 Sep. 2018)

153	   During the implementation work, a number of issues with the
154	   specification has been found (this was expected at the outset by all
155	   parties) and a number of observations has been made about limitations
156	   of the specification and vocabulary version 3 schema, and also
157	   limitations in the specification of the work to be done.

159	   The purpose of this memo is to collect those issues and observations
160	   in one place.

162	   When this memo says 'the current version of xml2rfc', it refers to
163	   the latest release of the xml2rfc processor available from the PyPi
164	   package repository [1] at the date this document was published, as
165	   given above.  As of 28 Sep. 2018, this was version 2.10.3.

167	2.  Fitness for Purpose

169	   The introduction to [RFC7991] states:

171	      "This document defines the "xml2rfc" version 3 vocabulary: an XML-
172	      based language used for writing RFCs and Internet-Drafts.  It is
173	      heavily derived from the version 2 vocabulary that is also under
174	      discussion.  This document obsoletes the v2 grammar described in
175	      RFC 7749."

177	   However, an unstated assumption seems to have been that the new tools
178	   and formatters would be used primarily to produce HTML output, in
179	   order to transition to publication of renderings of RFCs in more
180	   modern formats than plain-text ASCII.

182	   This is a reasonable and worthwhile goal, but as a result, the schema
183	   as specified in [RFC7991] has some drawbacks compared with the
184	   version 2 vocabulary when used to produce Internet-Drafts in the text
185	   format common within the IETF (Internet Engineering Task Force) at
186	   this time.

188	2.1.  Degraded Table of Contents

190	   Lack of pagination has little impact on direct online readability,
191	   but when comparing the output of the new text formatter with the old
192	   one, one aspect leaps out: Since there is no pagination, the table of
193	   contents simply lists the section headers to a certain depth, without
194	   any accompanying page numbers.  This makes a surprising difference in
195	   how useful the table of contents is in getting an initial feel for
196	   the document.  The at-a-glance information which lets a reader know
197	   if this is a document of 10 pages or 100 is simply lacking.

199	   Proposal:  Add support for pagination in a future version of the text
200	      formatter.

202	   Implementation:  None in the current version of xml2rfc.

204	2.2.  RFC Publication Date Policy

206	   The specification [RFC7998] says that an error should be generated if
207	   a <date> specification is found with missing elements; but the RFC
208	   Editor publishes documents (except for April 1st RFCs) with only year
209	   and month, no day of month.  The specification disallows this, and in
210	   effect makes it impossible for the RFC Editor to publish documents
211	   according to the current policy regarding publication date format.

213	   Proposal:  Revert to to the old behaviour, where the tool in RFC mode
214	      would issue a date with or without day depending on whether the
215	      <date> element had a day attribute or not.

217	   Implementation:  All elements of <date> are required in the current
218	      version of xml2rfc.

220	3.  Schema Issues

222	3.1.  RFC 7991

224	3.1.1.  In Section 2.5.5, "name" Attribute

226	      "A filename suitable for the contents (such as for extraction to a
227	      local file)."

229	   Given the existing use of "name" on <seriesInfo>, this attribute name
230	   has a semantic dissonance.

232	   Proposal:  Deprecate "name" for use on <artwork> and <sourcecode>,
233	      and instead use "file", which for <sourcecode> will be explicitly
234	      rendered, as established as best current practice for YANG modules
235	      (see for instance RFC 6087 [RFC6087])

237	   Implementation:  The current version of xml2rfc uses "name".

239	   Resolution:  The attribute "name" was used for this purpose already
240	      in v2 of the vocabulary.  Closed with no action.

242	   This issue is tracked as github issue #36 [2]

244	3.1.2.  In Section 2.6, <aside>

246	   The schema permits <list> inside <aside>, but <list> is deprecated,
247	   and <aside> is a new vocabulary v3 element, so they should never be
248	   able to occur together, it seems to me.

250	   Proposal:  Don't permit <list> inside <aside>.

252	   Implementation:  Implemented in the current version of xml2rfc.

254	3.1.3.  In Section 2.12, <br>

256	   A number of elements permits a mixed content model (see
257	   Section 3.1.7.2): <li>, <blockquote>, <dd>, <td>, and <th>.  However,
258	   when using the simpler of the two content schemas, two of them (<td>
259	   and <th>) permit inline line breaks through the use of <br> elements;
260	   the others do not.  This seems terribly arbitrary.

262	   Proposal:  Remove the <br> element completely.  Alternatively, permit
263	      it to be used all places that 'text' and non-block elements may be
264	      used (that is, in inline context).

266	   Resolution:  The <br> element is to be removed from the schema
267	      completely.

269	   This issue is tracked as github issue #37 [3]

271	3.1.4.  In Section 2.20, <dl>

273	   The current specification says:

275	      "The "hanging" attribute defines whether or not the term appears
276	      on the same line as the definition.  hanging="true" indicates that
277	      the term is to the left of the definition, while hanging="false"
278	      indicates that the term will be on a separate line."

280	   This does not match established typographic terminology.  In
281	   typographic terminology, "hanging indent" describes the case where
282	   the indentation of the second and subsequent lines of a paragraph is
283	   greater than the indentation of the first line.  Whether the
284	   definition in a definition list starts on the first line or not has
285	   nothing to do with the presence of hanging indent; our definition
286	   lists will _always_ have hanging indent.

288	   The 'hanging' attribute also describes something different from what
289	   the term has been used to describe in the version 2 vocabulary.  This
290	   will be confusing to users.

292	   A more descriptive name for the attribute we're talking about would
293	   be 'start-definition-on-first-line', but that's unwieldy.  Maybe
294	   'newline="false"' to start the definition on the first line, or
295	   something like 'definition-start="first"'?

297	   Proposal:  Change this to a different term that is more descriptive
298	      and does not use typographically incorrect terminology.

300	   Resolution:  The "hanging" attribute will be renamed to "newline".

302	   This issue is tracked as github issue #38 [4]

304	3.1.5.  New Section 2.20.4, "indent" Attribute

306	   The deprecation of the "hangIndent" attribute on <list> leaves no
307	   opportunity to control the size of the hanging indent.  In some
308	   definition lists, it is desirable to have a wide indentation, in
309	   order to clearly show the terms, in other cases it is more important
310	   to allow for a larger text volume than the width of the terms would
311	   allow.

313	   Proposal:  Add an "indent" attribute on <dl> to control the size of
314	      the hanging indent.

316	   Resolution:  An "indent" attribute will be added on <dl> to control
317	      the size of the hanging indent.  The value will signify the number
318	      of character positions in text/plain rendering, and a count of
319	      0.5em distances in richer renderings.

321	   This issue is tracked as github issue #39 [5]

323	3.1.6.  New Section 2.54.2

325	   The version 3 schema deprecates the previously available 'align'
326	   attribute for the tables, and the V2 to V3 converter will remove this
327	   attributes if used.  This makes a previous feature that was
328	   appreciated by some authors unavailable.  In the text formatter, the
329	   effect is simply to make all tables left-aligned, which may not be
330	   the most readable and polished output, but for the HTML formatter it
331	   also potentially removes the option of letting text flow around
332	   smaller tables in a controlled way.

334	   Proposal:  Make the 'align' attribute for tables available again.

336	   Resolution:  An attribute "align" will be re-introduced for table
337	      alignment, with the possible values "left", "center", and "right".

339	   This issue is tracked as github issue #40 [6]

341	3.1.7.  In Section 2.29, <li>

343	3.1.7.1.  Unordered lists with arbitrary symbols

345	   When <li> is used with <ul empty="true">, the rendering is under-
346	   specified (the specification says 'no label will be shown", but
347	   doesn't say whether list indentation (leading white-space) should be
348	   eliminated or not.

350	   If the intention is to make it possible to render unordered lists
351	   with arbitrary symbols, chosen on a per-list-item basis, the current
352	   attributes of <li> are insufficient to indent and line-wrap list
353	   items properly with <ul empty='true'>.

355	   It is not possible, for instance, to use <ul> lists to generate XML
356	   for a table of content, since if the width of the bullet (the section
357	   number, in this case) is unknown, the proper indentation and line
358	   wrapping cannot be determined.

360	   Proposal:  Add an explicit "bullet" attribute to support this use
361	      case.

363	   Resolution:  Rejected.

365	   This issue is tracked as github issue #45 [7]

367	3.1.7.2.  Mixed Content Model

369	   The mixed content model for <li> —- either text and inline elements
370	   like sub, sup, bcp14, _or_ <t>, <ul>, <figure> etc, is non-intuitive
371	   and may be hard for users to keep straight.

373	   Proposal:  Consider simplifying the schema by requiring that text and
374	      inline elements always are placed within a <t> element.

376	   Resolution:  Rejected.

378	   This would apply also to other elements that today have alternative
379	   content models: <blockquote>, <dd>, <td>, and <th>.

381	   This issue is tracked as github issue #46 [8]

383	3.1.8.  In Section 2.32, <name>

385	   So the <name> element can contain text or <tt>, and <tt> can contain
386	   other markup like <sub> and <sup> etc., but why cannot <name> contain
387	   <sup> etc.  directly?

389	   Proposal:  Change the <name> element schema to permit all inline
390	      elements that <tt> can contain, in addition to <tt>.

392	   Resolution:  Accepted.

394	   This issue is tracked as github issue #47 [9]

396	3.1.9.  In Section 2.32, <organization>

398	   The schema provides for extra attributes: "ascii" and "abbrev".  Why
399	   no "asciiAbbrev" for the case when the name and abbreviation has non-
400	   ascii characters?

402	   Proposal:  Add an attribute "asciiAbbrev" for <organization>, to
403	      provide abbreviated organization names in both ascii and non-ascii
404	      contexts.

406	   Implementation:  The current version of xml2rfc supports
407	      "asciiAbbrev".

409	3.1.10.  In Section 2.40.2, "quoteTitle"

411	   The version two xml2rfc processors already support the attribute
412	   "quote-title".  The attribute name change introduces an
413	   incompatibility.  This in particular impacts existing bibxml
414	   reference files, which should work with both version 2 and 3
415	   vocabulary documents.

417	   Proposal:  Change the attribute name back to the value supported by
418	      the vocabulary version 2 modes of xml2rfc.

420	   Implementation:  The current version of xml2rfc converts "quote-
421	      title" to "quoteTitle" during v2v3 conversion, but this is really
422	      sub-optimal.

424	   This issue is tracked as github issue #48 [10]

426	3.1.11.  In Section 2.42, <references>

428	   The v3 schema cannot properly model multiple reference subsections
429	   contained within one numbered section.  The v2 formatter handled this
430	   by silently inserting an enclosing section, but with the introduction
431	   of the preptool, which in theory should produce a master file from
432	   which various formatters would produce equivalent results, this
433	   becomes troublesome, as the automatic insertion of a container
434	   section is specified for the html formatter, in section 9.8. of RFC
435	   7992, but not for the text formatter.  It would be much better to
436	   make the prepped xml explicitly show exactly what should be rendered,
437	   and not rely on formatters silently insert elements.

439	   Proposal:  Update the schema to make it possible for <references> to
440	      contain <references>, and have the prepped xml explicitly show
441	      both the encapsulating section and the subsections.

443	   Resolution:  Accepted.

445	   This issue is tracked as github issue #49 [11]

447	3.1.12.  In Section 2.45.1, "category" Attribute

449	   Changing the "category" attribute of <rfc> to a name value in an
450	   additional <seriesInfo> makes it much harder than it needs to be to
451	   look it up.  It also makes the semantics of <seriesInfo> less clear.

453	   Proposal:  Remove this, and keep the "category" attribute on <rfc>

455	   Implementation:  The "category" attribute on <rfc> has been kept in
456	      the current version of xml2rfc, but the additional <seriesInfo> is
457	      also generated during v2v3 conversion.  For purposes of
458	      determining the category to render, the attribute on <rfc> is the
459	      one used.

461	3.1.13.  In Section 2.45.3, "docName" Attribute

463	   Changing the "docName" attribute of <rfc> to a name value in an
464	   additional <seriesInfo> makes it much harder than it needs to be to
465	   look it up.  It also makes the semantics of <seriesInfo> even less
466	   clear.  See also Section 4.4.23.

468	   Proposal:  Remove this, and keep the "docName" attribute on <rfc>

470	   Implementation:  The "docName" attribute on <rfc> has been kept in
471	      the current version of xml2rfc.

473	3.1.14.  In Section 2.45.7, "number" Attribute

475	   The RFC number attribute in the <rfc> element is used as a switch to
476	   control whether an RFC or an Internet-Draft is produced.  Moving what
477	   is effectively an important controlling switch for the operation of
478	   the formatters from the main element down into what is arguably an
479	   obscure combination of attribute values on a <seriesInfo> element
480	   several levels down from the main element feels wrong.

482	   Proposal:  Don't deprecate the number attribute on <rfc>, but require
483	      that the preptool checks that the number attribute matches what's
484	      in the <seriesInfo> set.  Explicitly mention that the presence of
485	      the number attribute on <rfc> causes the generation of an RFC
486	      rather than an Internet-Draft by the formatters.

488	   Implementation:  In The current version of xml2rfc, the number
489	      attribute on <rfc> is used to determine whether to produce an RFC
490	      or Internet-Draft.  If <seriesInfo> elements are found, but no
491	      <seriesInfo> with name="RFC" and value set to the number is found,
492	      a warning is given.  If no <seriesInfo> elements are found, the
493	      appropriate elements, including one giving the RFC number, is
494	      inserted.

496	3.1.15.  In Section 2.53.3 and 2.53.4.

498	3.1.15.1.  Unnecessary limitation on where the "keepWithNext" attribute
499	           can be used

501	   Why keepWithNext only on <t>?  It would be very natural to expect to
502	   be able to say keepWithNext for 2 tables, or 2 figures, or 2 lists?

504	   Proposal:  Permit keepWithNext on all elements that can be siblings
505	      to <t>.

507	   Implementation:  Not in the current version of xml2rfc.

509	3.1.15.2.  Violation of KISS and DRY principles

511	   keepWithNext on one element is equivalent with keepWithPrevious on
512	   the following element, provided the following element can have a
513	   keepWithPrevious attribute.  Providing both violates both KISS [KISS]
514	   and DRY (Don't Repeat Yourself) [DRY].

516	   Proposal:  Keep only one of these two attributes, preferably
517	      keepWithNext.

519	   Implementation:  Not in the current version of xml2rfc.

521	3.1.16.  New Section 2.X, <u>

523	   Thinking about being able to issue warnings both during xml2rfc
524	   processing and when running idnits, it seems very hard to distinguish
525	   between intentional and non-intentional inclusion of non-ASCII
526	   characters in document text.

528	   In addition to the problem of correctly detecting non-intentional use
529	   of Unicode characters, there is also the issue (for authors) of
530	   correctly converting given Unicode characters to one of the forms
531	   recommended in [RFC7997], and the issue (for idnits) of verifying
532	   that any Unicode characters or strings are correctly represented as
533	   Unicode code-point values next to the literal character or string.

535	   One solution to this could be to not try to guess, or establish
536	   heuristics, but instead use a v3 schema element with preptool
537	   validation to ensure a straightforward solution to all the issues, as
538	   follows:

540	   Proposal:  Limit the arbitrary placement of Unicode characters and
541	      strings in the body of a document, and control the expansion of
542	      the Unicode code-points by requiring that Unicode characters and
543	      strings be placed within a specific element if they are to occur
544	      in the body of a document.  The following text is proposed for
545	      inclusion in RFC 7991-bis as a new section:

547	   The <u> element contains a Unicode string which will be rendered
548	   according to one of the 6 methods of Unicode renderings listed in
549	   [RFC7997], Section 3.4.

551	   In xml2rfc vocabulary version 3, the elements <author>,
552	   <organisation>, <street>, <city>, <region>, <code>, <country>,
553	   <postalLine>, <email>, and <seriesInfo> may contain non-ascii
554	   characters for the purpose of rendering author names, addresses, and
555	   reference titles correctly.  They also have an additional "ascii"
556	   attribute for the purpose of proper rendering in ascii-only media.

558	   However, in order to insert Unicode characters in any other context,
559	   xml2rfc vocabulary v3 requires that the Unicode string be enclosed
560	   within an <u> element.  The element will be expanded inline based on
561	   the value of an attribute named "expansion" as follows.  Given an
562	   element <u expansion="...">Δ</u> in an example sentence:

564	   expansion="numeric-literal":
565	      Temperature changes in the Temperature Control Protocol are
566	      indicated by the U+2206 character ("Δ").

568	   expansion="numeric-name":
569	      Temperature changes in the Temperature Control Protocol are
570	      indicated by the U+2206 character (INCREMENT).

572	   expansion="numeric-literal-name":
573	      Temperature changes in the Temperature Control Protocol are
574	      indicated by the U+2206 character ("Δ", INCREMENT).

576	   expansion="numeric-name-literal":
577	      Temperature changes in the Temperature Control Protocol are
578	      indicated by the U+2206 character (INCREMENT, "Δ").

580	   expansion="name-literal-numeric":
581	      Temperature changes in the Temperature Control Protocol are
582	      indicated by the "Delta" character "Δ" (U+2206).

584	   expansion="literal-name-numeric":
585	      Temperature changes in the Temperature Control Protocol are
586	      indicated by the character "Δ" (INCREMENT, U+2206).

588	   If the <u> element encloses a Unicode string, the rendering reflects
589	   this.  The element <u expansion="numeric-literal">ᏚᎢᎵᎬᎢᎬᏒ</u> will be
590	   expanded to 'the characters U+13DA U+13A2 U+13B5 U+13AC U+13A2 U+13AC
591	   U+13D2 ("ᏚᎢᎵᎬᎢᎬᏒ")'

593	   Unicode characters which are not enclosed in one of the elements
594	   mentioned above will be replaced with a question mark (?) and a
595	   warning will be issued.

597	3.1.17.  In Section 2.63.2, <ul> "empty" attribute

599	   In v2, this results in a list using space as the bullet, thus each
600	   list entry is indented as with other bullet symbols.  However, this
601	   leaves no way to get list entries with arbitrary text that are not
602	   indented, in order to produce lists such as that used in Table of
603	   Content and Index.

605	   Furthermore, the specification does not indicate if <ul empty="true">
606	   should be rendered with space as a bullet, or without any bullet and
607	   indentation.  A clarification would be good.

609	   Proposal:  Specify that in text output, <ul empty="true"> should be
610	      rendered without any bullet and indentation.  In order to produce
611	      unordered lists that are indented, the "bullet" attribute
612	      mentioned in Section 3.1.7 with a white-space bullet could be
613	      used.

615	   Implementation:  The current version of xml2rfc introduces a new
616	      attribute "bare" with the possible values "false" | "true" to
617	      signal this.  The default is "true" (which differs from the
618	      default v2 implementation).  Using the extra attribute "bare"
619	      works, but is maybe clumsier than necessary.

621	3.1.18.  In Section 3.4.2, "hangIndent" Attribute

623	      "Deprecated.  Use <dl> instead."

625	   This causes capability loss.  The "hangIndent" attribute did not only
626	   signal that hanging indent should be used, but also gave the size of
627	   the indent.  No equivalent control has been provided for the <dl>
628	   element in the version 3 vocabulary.

630	   Proposal:  Provide an attribute "indent" on <dl> as suggested in
631	      Section 3.1.5.

633	   Implementation:  Not in the current version of xml2rfc.

635	3.1.19.  In Appendix C.  Relax NG schema

637	   The "colspan" attribute is given a default value of "0", this should
638	   be "1".  "0" is not otherwise defined in the text, and the only
639	   reasonable interpretation would be to hide the cell (make it occupy
640	   zero columns).

642	   The "rowspan" attribute is given a default value of "0", this should
643	   be "1".  "0" is not otherwise defined in the text, and the only
644	   reasonable interpretation would be to hide the cell (make it occupy
645	   zero rows).

647	   Proposal:  Change the default values of "colspan" and "rowspan" to 1.

649	   Implementation:  Done in the current version of xml2rfc.

651	3.1.20.  Use of the term "counter".

653	   The classical meaning of this term is a a monotonically increasing
654	   sequence of integers, globally unique or unique within a context.  In
655	   this document, it is instead meant to indicate section, table, figure
656	   numbers, which for sections are not plain counters.

658	   To make more interesting, in other contexts in the document, the
659	   notation "-nnn", which also would normally indicate a dash followed
660	   by digits, i.e., a counter, is also re-interpreted to include section
661	   numbers; strings of numbers including embedded period signs.  This is
662	   bad terminology.

664	   Proposal:  Instead of "counter", use "number" as the attribute value,
665	      and explicitly say "Section number, Figure number, Table number or
666	      ordered list labels" in the description.  Use "-n.n" instead of
667	      "-nnn".

669	   Implementation:  Not in the current version of xml2rfc.

671	3.2.  RFC 7998

673	3.2.1.  In Section 5.2.6, Attribute Default Value Insertion

675	   The <seriesInfo> "stream" attribute has a default value of "IETF".
676	   The effect of setting default values after the XInclude processing is
677	   to set stream="IETF" on all reference <seriesInfo> which don't have a
678	   stream set.  This is probably not right.

680	   Proposal:  Remove the default value for the "stream" attribute from
681	      the <seriesInfo> element in the v3 schema.

683	   Implementation:  The current version of xml2rfc removes the default
684	      value for the "stream" attribute from the schema.

686	3.2.2.  In Section 5.4.6, "pn" Numbering.

688	   The list of elements that are given p- or paragraph tags is severely
689	   limited, and since the presence of a pn= attribute is required in
690	   order to make internal <xref> instances work, this limits the
691	   elements to which it is possible to reference with html fragment
692	   identifiers.  Why?
693	   Why is <dt> and <li> present, but not <ol>, <dl>, <ul>?

695	   Proposal:  Permit and provide "pn" numbers of type 'paragraph-nnn'
696	      for all block-level elements that don't have "pn" numbers
697	      otherwise specified.

699	   Implementation:  Not in the current version of xml2rfc, but the
700	      current version adds p- numbering to <list>, <dl>, <dd>, <ol>,
701	      <ul>, which all are allowed to have pn= attributes according to
702	      the schema.

704	3.3.  Some attributes should have value type xsd:ID

706	   In generated HTML, the values set for "pn" and "slugifiedName" will
707	   be used as link targets, which makes a type of xsd:ID appropriate in
708	   the input format.

710	   Additionally, if Table of Contents and Index is generated internally
711	   as XML, and rendered by the various renderers to appropriate formats,
712	   the <xref> entries will have target values (defined as type
713	   xsd:IDREF) referencing "pn" and "slugifiedName" values, which means
714	   that the XML will be invalid if these are not of type xsd:ID.

716	   Proposal:  Change the "pn" and "slugifiedName" to type xsd:ID.

718	   Implementation:  Implemented in the current version of xml2rfc.

720	4.  Non-Schema Issues

722	4.1.  RFC 7991

724	4.1.1.  In Section 2.5.7, "type" Attribute

726	4.1.1.1.  How should a "src" attribute be handled when no "type" is
727	          given.

729	   The v3 schema does not require the 'type' attribute on <artwork> to
730	   have a value, which makes sense when there's no <artwork> 'src'
731	   attribute to include.  But if there is a 'src' attribute, but no
732	   value for 'type', how should the 'src' value be handled?

734	   The easiest and most explicit handling would be to require a 'type'
735	   value if there is a 'src' attribute; a more doubtful alternative
736	   would be to use something like the Linux file magic command to try to
737	   guess at the content type that 'src' points at.

739	   Proposal:  Warn if there is a 'src' and no 'type' value, and ignore
740	      the 'src' in that case.

742	   Implementation:  The current version of xml2rfc implements this as
743	      proposed.

745	4.1.1.2.  Missing information on how to handle various types

747	      "The RFC Series Editor will maintain a complete list of the
748	      preferred values on the RFC Editor web site, and that list is
749	      expected to be updated over time.  Thus, a consumer of v3 XML
750	      should not cause a failure when it encounters an unexpected type
751	      or no type is specified.  The table will also indicate which type
752	      of art can appear in plain-text output (for example, type="svg"
753	      cannot)."

755	   The RFC Series Editor has not yet provided such a table.  It is
756	   definitely desired, in order to be able to deal correctly with plain-
757	   text output.

759	4.1.2.  New Section 2.8.1: Index

761	   There is no guidance on the structure of an index, if one is to be
762	   generated by the preptool.

764	   Proposal:  Please provide specification.

766	   Implementation:  The current version of xml2rfc provides the
767	      generation of index elements in the prepped XML, but makes no
768	      claim on the generated XML being optimal.

770	4.1.3.  In Section 2.17, <date>

772	4.1.3.1.  Current Date Requirement

774	      "When the prep tool is used to create Internet-Drafts, it will
775	      reject a submitted Internet-Draft that has a <date> element in the
776	      boilerplate for itself that is anything other than today."

778	   It is not up to the format definition to set policy for acceptance or
779	   rejection of draft submissions.  The matter is more complex than the
780	   text assumes, see for instance datatracker issue #2422.  In addition
781	   to being inappropriate, this text also quietly changes policy from
782	   +/- 3 days to +/- 0 days, without saying that it updates RFC 4228
783	   [RFC4228], which is the current specification of permissible dates in
784	   draft submissions.  Finally, enforcing this would cause _a lot_ of
785	   grief and problems.

787	   Proposal:  Remove the section.

789	   Implementation:  The current version of xml2rfc does not reject input
790	      based on the value of <date>, but warns if the date is more than 3
791	      days from the current date, in accordance with [RFC4228].

793	4.1.3.2.  Date Specification in References

795	      "Bibliographic references: In dates in <reference> elements, the
796	      date information can have prose text for the month or year.  For
797	      example, vague dates (year="ca. 2000"), date ranges
798	      (year="2012-2013"), non-specific months (month="Second quarter"),
799	      and so on are allowed."

801	   The text regarding prose text for month and year in bibliographic
802	   references is not workable.  How should month and year be combined?
803	   Some bibliographic references may have date text which requires year
804	   first, others year last, and so on.  Mixing the described fuzziness
805	   into the otherwise strict year, month, date format makes little sense
806	   when the result of combining the year, month and date attributes
807	   cannot be predictably and correctly rendered.

809	   Proposal:  Instead of the current specification, permit either that
810	      the <date> element may have text content, or an alternative
811	      attribute to be used for rendering if year, month, or day cannot
812	      be specified exactly.

814	   Implementation:  The current version of xml2rfc has not implemented
815	      this part of the specification, and is waiting for a more workable
816	      solution.

818	4.1.4.  In Section 2.40.1, "anchor" Attribute

820	   Section 5.1 of RFC 7992 says in part:

822	      "The prep tool produces XML with anchor attributes in all elements
823	      that need them."

825	   This is rather vital information regarding the content of the prepped
826	   xml when building a formatter, unfortunately it is not mentioned in
827	   RFC 7991.

829	   Proposal:  Add this information to the successor of RFC 7991, and to
830	      the formatter specifications.

832	4.1.5.  In Section 2.47, <seriesInfo>

834	   The possible and forbidden combinations of attributes for this
835	   element has now become so convoluted that it's really hard to
836	   understand how to use it correctly.  This needs a serious
837	   reconsideration.

839	   The 'name' attribute is mandatory, and only 3 values are permitted:
840	   "RFC", "Interned-Draft", and "DOI".  But it is also mandatory to set
841	   the name to "" for a <seriesInfo> with a status attribute.  Hmm...

843	   So there are 4, not 3 permitted values: "RFC", "Internet-Draft",
844	   "DOI", and "".

846	   This means that all reference files which has things like name="ISO",
847	   name="W3C Recommendation", etc., etc., have become illegal.

849	   Proposal:  Do a rewrite of this that does not add new details to the
850	      already complex <seriesInfo> semantics, and does not make non-IETF
851	      reference files obsolete, but actually simplifies the model and
852	      use.

854	      Limit the <seriesInfo> element to what is actually needed for use
855	      within <reference/>, and do not add new functionality related to
856	      the document <front>.  Deprecate any functionality not related to
857	      usage within <reference/>.

859	   Implementation:  Mostly not done in the current implementation, but
860	      see also Section 3.1.12, Section 3.1.14 and Section 3.2.1

862	4.1.6.  In Appendix A.1.1: TLP switch-over date discrepancies

864	   There are discrepancies between the specified switch-over dates in
865	   the specification, and those given by the Trust statements:

867	   *  TLP3.0: The specification says 2009-11-01 but the TLP statement
868	      says effective date 2009-09-12.

870	   *  TLP4.0: The specification says 2010-04-01 but the TLP statement
871	      says effective date 2009-12-28.  The dates on which TLP 4 started
872	      to be use in published RFCs seems to match the stated effective
873	      date of 2009-12-28, based on a scan of some RFCs around that date.

875	   RFC 7991 also states this about the pre5378 text: this text appears
876	   under "Copyright Notice", unless the document was published before
877	   November 2009, in which case it appears under "Status of This Memo".
878	   This does not agree at all with what actual RFCs contain; they seem
879	   to consistently have this text under Copyright Notice.

881	   Proposal:  Correct the dates given in the document to indicate the
882	      official dates, and correct the text on placement of TLP to match
883	      actual usage.

885	   Implementation:  The current version of xml2rfc uses the official
886	      dates during the preptool processing, not the dates given in RFC
887	      7991.

889	4.2.  RFC 7992

891	4.2.1.  In Section 5.1, IDs

893	   The current specification says:

895	      HTML elements that are generated from XML elements that include an
896	      "anchor" attribute will use the value of the "anchor" attribute as
897	      the value of the "id" attribute of the corresponding HTML element.
898	      The prep tool produces XML with "anchor" attributes in all
899	      elements that need them.  Some HTML constructs (such as <section>)
900	      will use multiple instances of these identifiers.

902	   But I believe html5 does not permit more than one "id" attribute per
903	   element, which begs the question of how <section> will use multiple
904	   instances of identifiers?

906	4.2.2.  In Section 6.2, Root Element

908	   Typo:

910	   OLD: <seriesInfo> element's "name" attributes

912	   NEW: <seriesInfo> elements' "name" attributes

914	4.2.3.  In Section 6.4, Page Headers and Footers

916	   This is incomplete.  It gives an example, but does not specify how it
917	   is to be filled in.

919	   Is the formatter expected to fill out the cells, based on the pattern
920	   given, or is that supposed to happen magically based on WD-
921	   css3-page-20130314 ?

923	   If the cell content is supposed to be provided by the formatter, it
924	   would be good to have a bit more specification than the example; if
925	   not, it would be nice for that to be stated explicitly.

927	   The mention of the '[Page]' placeholder could be taken as an
928	   indication that all cell content shown are placeholders, but are
929	   they, really?

931	   Implementation:  The current implementation has code to insert
932	      placeholder html, but not code to fill in the cells with actual
933	      information from the document.  Since this is meaningless if the
934	      guess is wrong, this code has been disabled for now.

936	4.2.4.  In Section 6.5, Document Information

938	   This information seems to be scrambled and incomplete.  It suggests
939	   the use of 'Status:' for what is otherwise called 'Category:'.  It
940	   simplifies the presentation of series information to the point that
941	   no clue is given of how to handle the two bits of information related
942	   to series name and series number -- the example shows 'Series:'
943	   'Internet-Draft', which gives no guidance at all.  There is no
944	   mention of whether to display 'Obsoletes:' and 'Updates:' information
945	   or not.

947	   On a more general note, this is the second section where an
948	   incomplete example is provided instead of specification.  Examples
949	   are however not replacements for proper specification; they are at
950	   best a help in making a specification real to the user.  Both this
951	   section and Section 4.2.3 needs to be expanded to provide a complete
952	   specification.

954	   Styling query: The example gives the style of the element that holds
955	   author initials the class 'initial' while the attribute is
956	   appropriately named 'initials'.  Is the difference in attribute and
957	   style names intentional?  In any case, 'initials' would be more
958	   appropriate.

960	   Implementation:  Instead of trying to follow what's written, the
961	      current implementation tries to provide the same fields and
962	      information which is provided by the text/plain formatter, in a
963	      sensible way.  This is guesswork.

965	      The implementation also has used the sample html document for
966	      guidance here, in order to be able to progress with something that
967	      works with the style sheet from the RFC-Format CSS project.

969	4.2.5.  In Section 8.1.1, Index Contents

971	   The index has an extra <div> enclosing the contents, starting
972	   directly after <h2>, while sections explicitly does not have a div
973	   here.  This irregularity seems quite unnecessary, but makes the
974	   formatter code more complex than need be.  Could we please align the
975	   two?

977	4.2.6.  Inconsistent use of "s-", "n-" and User-Supplied "id" Attributes

979	   RFC 7991 [RFC7991] specifies an attribute "slugifiedName" on <name>,
980	   but does not specify how it is to be used.  RFC 7998 [RFC7998]
981	   specifies how to create these, but not how they should be used.  In
982	   RFC 7992, slugified names, with an "n-" (or "name-") prefix, are
983	   sometimes used on sections, sometimes not.  "s-" (or "section-") IDs
984	   are sometimes used on <h2> and other header elements, sometimes on
985	   paragraph, divs, asides, blockquotes etc.  Section 9.33 of [RFC7992]
986	   even uses a reference to an "n-" ID that doesn't exist, although it
987	   clearly should, based on the section name.  This is a mess.

989	   Implementation:  The implementation consistently transfers the
990	      "slugifiedName" attribute on <name> to an "id" attribute on the
991	      <h2> or other header element generated from the name.
992	      Section numbers ("s-" or "section-" values) from "pn" attributes
993	      are consistently transferred to the <section>, <p> or other HTML
994	      element generated from the XML element on which they appear.
995	      User-supplied "anchor" attributes on XML elements are consistently
996	      transferred to a <div> inside the HTML element generated from the
997	      XML element with the anchor, encapsulating the content generated
998	      from the XML element.

1000	4.3.  RFC 7994

1002	4.3.1.  Additional Guidance

1004	   *  <aside>: Guidance requested on the rendering.  Now rendered with
1005	      an indentation of 9 relative to surrounding text

1007	   *  <blockquote>: Guidance requested on the rendering.  Now rendered
1008	      with an indentation of 3 spaces, pipe(|), two spaces relative to
1009	      surrounding text.

1011	   *  <sub>: Guidance requested.  Now rendered as _(text)

1013	   *  <sup>: Guidance requested.  Now rendered as ^(text)

1015	   *  <tt>: Guidance requested.  Now rendered as "text"

1017	   *  Guidance for <eref> rendering.  In the html formatter, handling of
1018	      <eref> is straightforward and is specified; it simply translates
1019	      to an external link.  In the legacy text formatter, <eref> was
1020	      handled by inserting an extra <references> subsection called
1021	      "URLs", and adding reference entries for the URLs there, while the
1022	      <eref> citation point got a trailing numeric reference number.
1023	      With the preptool output becoming the authoritative published
1024	      document, this difference won't be reflected in the xml.  The two
1025	      formats would be more aligned if the text formatter renders <eref>
1026	      URLs inline.

1028	      Proposal:  Change the rendering of <eref> in text to render the
1029	         URL inline within parentheses instead of adding the 'URLs'
1030	         reference subsection.

1032	      Implementation:  Implemented in the current version of xml2rfc.

1034	4.4.  RFC 7998

1036	4.4.1.  In Section 5.2.3, <date> Insertion

1038	   Error if any of year, month, day is missing:

1040	   It is an unnecessary and unwanted restriction when not in RFC
1041	   processing mode to given an error for missing date elements.  Missing
1042	   date elements have been permitted because they make it easier for
1043	   draft authors to rev drafts without having to pay attention to the
1044	   date values every time they generate new output.  This requirement
1045	   should apply only to RFC prepping mode, and only in part:

1047	   In RFC processing mode, this implicitly changes the RFC-Editor policy
1048	   regarding publication dates, which earlier have specified only year
1049	   and month (except for April 1st RFCs).  Is this intentional?

1051	   Proposal:  Remove this restriction for draft mode, and modify it to
1052	      require only year and month in RFC mode.

1054	   Implementation:  The current version of xml2rfc warns if not all
1055	      three elements are present in RFC mode.  The tool author considers
1056	      even this inappropriate.

1058	      In Internet-Draft mode, the current implementation handles missing
1059	      elements the same way that the v2 formatters do.

1061	4.4.2.  In Section 5.2.4, "prepTime" Insertion

1063	   This is under-specified, given the detailed requirements on the
1064	   <date> attributes.  Should probably be specified as format according
1065	   to [RFC3339], with year, month, day, hour, minute, and second.

1067	   Proposal:  Specify the format as RFC3339 compliant with resolution at
1068	      least down to a second.

1070	   Implementation:  Implemented as RFC3339 with year, month, and day up
1071	      to version 2.10.3; changed to the proposal above in the next
1072	      release.

1074	4.4.3.  In Section 5.2.6, Attribute Default Value Insertion

1076	   All the default values in 7991 are also expressed in the v3.rnc
1077	   schema.  Remove text indicating otherwise.  And by the way, it was
1078	   very helpful to extract these from the schema programmatically;
1079	   having them specified otherwise would make it much harder to follow a
1080	   changing schema.

1082	   A number of attributes which are deprecated have default values.  The
1083	   current specification will cause those to be inserted, even if they
1084	   have been removed earlier by the v2v3 converter because they are
1085	   deprecated.  This seems inconsistent.

1087	   Proposal:  Omit deprecated attributes from the default-setting.

1089	   Implementation:  Not in the current version of xml2rfc.

1091	4.4.4.  In Section 5.2.7, "toc" Attribute

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

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

1104	   Proposal:  Move 5.2.7 processing to after 5.4.2, or specify that a
1105	      second pass should be done after boilerplate insertion.  If a
1106	      parent to a section with toc="include" has toc="exclude", an error
1107	      should be generated.

1109	   Implementation:  In order to do the actions of 5.2.7 for boilerplate,
1110	      a second pass is made after boilerplate insertion in the current
1111	      version of xml2rfc.  Handling of inconsistent "toc" attribute
1112	      settings is implemented as proposed.

1114	4.4.5.  In Section 5.2.8, "removeInRFC" Warning Paragraph

1116	   This potentially inserts a new <t> element, but after the default
1117	   setting in 5.2.6.

1119	   Proposal:  Maybe place default setting after all potential element
1120	      insertions have taken place.

1122	   Implementation:  The current version of xml2rfc deals with this by
1123	      adding default-setting of attributes individually on each new
1124	      elements as they are inserted.  This works, but is more complex
1125	      and probably less efficient than doing default-setting once, after
1126	      any new elements have been inserted.

1128	4.4.6.  In Section 5.3.1, "month" Attribute

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

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

1138	   Proposal:  Clarify the text.

1140	4.4.7.  In Section 5.3.2, ASCII Attribute Processing

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

1146	   Proposal:  Change the title 'ASCII Attribute Processing' to refer
1147	      correctly to the "ascii" attribute: '"ascii" Attribute
1148	      Processing'.

1150	      "In every <author> element ..."

1152	   After the earlier XInclude processing, this will include all the
1153	   author elements in the included references, which the document author
1154	   should not normally change in any way.  Was this the intention?

1156	   Proposal:  Limit it to /rfc/front/author' elements.

1158	   Implementation:  Implemented in the current version of xml2rfc.

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

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

1167	   Proposal:  Process all "ascii" attributes in the document <front> as
1168	      specified, and ignore those within <references>

1170	   Implementation:  Implemented as proposed.

1172	4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation

1174	   Proposal:  The new section should specify normalisation of
1175	      keepWithNext/keepWithPrevious such as to replace all
1176	      keepWithPrevious with an equivalent keepWithNext on the previous
1177	      element, in case the proposal in Section 3.1.15.2 is not accepted.

1179	   Implementation:  Not in the current version of xml2rfc.

1181	4.4.9.  In Section 5.4.2, <boilerplate> Insertion: Only for RFCs?

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

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

1195	   Proposal:  The boilerplate-element insertion parts of 5.4.2 should be
1196	      done in both RFC and draft mode, with the appropriate boilerplate
1197	      for each case.  For consistency, either add text to describe the
1198	      appropriate boilerplate for drafts, or remove the sections
1199	      specific to RFC boilerplate.

1201	   Implementation:  The current version of xml2rfc inserts boilerplate
1202	      for both drafts and RFCs, as appropriate.

1204	4.4.10.  In Section 5.4.2, <boilerplate> Insertion: Error Message

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

1215	   Proposal:  If existing boilerplate is found, issue a warning and
1216	      replace it.

1218	      For other tools, suggest that if boilerplate is present during
1219	      draft submission, it should be checked for validity.  This is
1220	      already a function of idnits, so does not constitute anything new,
1221	      but is decidedly better than having the submission tool actually
1222	      reach into the submitted document and change it.

1224	   Implementation:  In the current version of xml2rfc this is
1225	      implemented as proposed, with the following warning if existing
1226	      boilerplate is found: "Expected no <boilerplate> element, but
1227	      found one.  Replacing the content with new boilerplate."

1229	4.4.11.  In Section 5.4.2.1, Compare <rfc> submissionType and
1230	         <seriesInfo> "stream".

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

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

1246	   Proposal:  Remove the default value for stream, and make it
1247	      subordinate to submissionType.

1249	   Implementation:  The current version of xml2rfc implements the
1250	      specification as written, and produces errors (which lead to not
1251	      producing an output document) on inconsistencies.  This does not
1252	      feel user-friendly.

1254	4.4.12.  In Section 5.4.2.2, "Status of this Memo" Insertion

1256	   It specifies that one should consider both submissionType and
1257	   <seriesInfo> stream value; but those have just been set equal in
1258	   5.4.2.1.

1260	   Proposal:  Remove <seriesInfo> from consideration here.  In order to
1261	      produce a correct "Status of this Memo" text, "category",
1262	      "consensus", and "submissionType" must be considered, and all
1263	      three are present as attributes on <rfc>.  Keep it that way.

1265	   Implementation:  The current version of xml2rfc looks at
1266	      "submissionType", "category", and "consensus" on the <rfc>
1267	      element.

1269	4.4.13.  In Section 5.4.3, <reference> "target" Insertion

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

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

1277	   In the formatter, the order of <seriesInfo> determines the rendering
1278	   order.  The insertion should probably be done in the desired
1279	   rendering order.

1281	   Proposal:  In addition to providing the appropriate URL patterns,
1282	      specify the order in which the <seriesInfo> elements should occur,
1283	      for instance: 'BCP', 'RFC', 'DOI'.

1285	   Implementation:  The current version of xml2rfc inserts the
1286	      appropriate <seriesInfo> elements, and after insertion sorts them
1287	      in the order 'BCP', 'RFC', 'DOI', followed by others.

1289	4.4.14.  In Section 5.4.4, <name> Slugification

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

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

1296	   Implementation:  Implemented as proposed in the current version of
1297	      xml2rfc.

1299	   Should the slugs be unique?  Assuming yes, but guidance would be
1300	   good.  The current version of xml2rfc enforces unique slugs, with the
1301	   following algorithm:

1303	   *  remove non-ascii letters

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

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

1311	   Proposal:  Do slugification and uniqueness enforcement as described
1312	      above.

1314	   Implementation:  As described above.

1316	4.4.15.  In Section 5.4.6, "pn" Numbering.

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

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

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

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

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

1338	   Implementation:  Implemented as proposed in the current version of
1339	      xml2rfc.

1341	4.4.15.1.  RFC format anchors / fragment identifiers

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

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

1358	   Proposal:  Update the RFC 7998 preptool to use these prefixes,
1359	      instead:

1361	      -  "section-xxx"

1363	      -  "figure-xxx"

1365	      -  "table-xxx"

1367	      -  "appendix-xxx"

1369	      -  "index-xxx"

1371	      -  "para-xxx"

1373	      -  "name-xxx"

1375	   Implementation:  Implemented as above in the current version of
1376	      xml2rfc.

1378	4.4.16.  In Section 5.4.7, <iref> Numbering

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

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

1389	   Proposal:  Require slugification for pn-numbering of items and sub-
1390	      items, but remove the details of how to ensure uniqueness.
1391	      Correct the mention of 'irefid' to say 'pn', if that was intended.

1393	   Implementation:  Slugification is done, and uniqueness is enforced
1394	      with an algorithm that limits slug length and tries to keep slugs
1395	      readable.  If there are more than 99 slugs that would collide if
1396	      no uniqueness processing was done, an error is generated.

1398	4.4.17.  In Section 5.4.8.2, "derivedContent" Insertion (without
1399	         Content)

1401	   There's a formatting mistake:

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

1407	4.4.18.  In Section 5.5.1, <artwork> Processing

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

1414	   Proposal:  If there is fallback content, convert the external URL
1415	      content to a "data:" URL for the src.  This pulls the external
1416	      content in and makes it immutable, but retains the fallback text.

1418	   Implementation:  Implemented as proposed in the current version of
1419	      xml2rfc.

1421	4.4.19.  In Section 5.5.2, <sourcecode> Processing

1423	   List item 4 says:

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

1428	   However, we have no particular reason to assume that the content of
1429	   the "src" URL is XML.  Quite to the contrary, it would be a very
1430	   natural and common use case that the external content is a source
1431	   code file.

1433	   Proposal:  The URI should not be assumed to resolve to xml, but
1434	      instead treated like CDATA.

1436	   Implementation:  Implemented as proposed in the current version of
1437	      xml2rfc.

1439	4.4.20.  In Section 5.4.8.2, "derivedContent" Insertion.

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

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

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

1462	   Proposal:  The whole "derivedContent" handling and specification
1463	      needs a thorough rework, with specification of the intended use of
1464	      the attribute by formatters.  Possibly the whole "derivedContent"
1465	      concept should be scrapped, and the rendering left for the
1466	      formatter, depending on the characteristics of the output format.

1468	   Implementation:  The current version of xml2rfc works around this
1469	      issue by using different formatter code for different cases, which
1470	      is not good from the viewpoint of using the prepped XML as the
1471	      archival format, but at least produces reasonable output.

1473	4.4.21.  In Section 5.4.9, <relref> Processing

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

1481	   Proposal:  Deprecate <relref>, and fold the functionality into
1482	      <xref>.

1484	   Implementation:  The <relref> functionality has been folded into
1485	      <xref>, but relref support not yet removed.

1487	4.4.22.  New Section 5.4.10, Index Insertion

1489	   RFC7998 does not say anything about inserting xml for the index, if
1490	   one is requested, but it seems counter-intuitive not to produce xml
1491	   for the index as part of the preptool processing, given all the other
1492	   prepping that's being done.  What's more, in Section 2.27 of RFC 7991
1493	   there's this text:

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

1499	   Proposal:  Insert the XML necessary to render the index into the
1500	      prepped XML.

1502	   Implementation:  Implemented as proposed in the current version of
1503	      xml2rfc.

1505	4.4.23.  In Section 5.6.3, <link> Processing

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

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

1513	   Proposal:  Require docName to be set to the draft name, and use that
1514	      to create this link.  This also implies that "docName" not be
1515	      deprecated (see Section 3.1.13).

1517	   Implementation:  Implemented as proposed in the current version of
1518	      xml2rfc.

1520	5.  Security Considerations

1522	   This document does not introduce any security considerations on its
1523	   own.

1525	6.  References

1527	6.1.  Informative References

1529	   [DRY]      Wikipedia, "Don't repeat yourself", 2018,
1530	              <https://en.wikipedia.org/wiki/Don%27t_repeat_yourself>.

1532	   [KISS]     Wikipedia, "KISS Principle", 2018,
1533	              <https://en.wikipedia.org/wiki/KISS_principle>.

1535	   [RFC3339]  Klyne, G. and C. Newman, "Date and Time on the Internet:
1536	              Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
1537	              <https://www.rfc-editor.org/info/rfc3339>.

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

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

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

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

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

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

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

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

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

1575	   [RFC7997]  Flanagan, H., Ed., "The Use of Non-ASCII Characters in
1576	              RFCs", RFC 7997, DOI 10.17487/RFC7997, December 2016,
1577	              <https://www.rfc-editor.org/info/rfc7997>.

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

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

1587	6.2.  URIs

1589	   [1] https://pypi.org/pypi/xml2rfc

1591	   [2] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/36

1593	   [3] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/37

1595	   [4] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/38

1597	   [5] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/39

1599	   [6] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/40

1601	   [7] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/45

1603	   [8] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/46

1605	   [9] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/47

1607	   [10] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/48

1609	   [11] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/49

1611	Author's Address

1613	   Henrik Levkowetz
1614	   Elf Tools AB
1615	   Ollonstigen 8
1616	   Sweden

1618	   Email: henrik@levkowetz.com