idnits 2.17.1 

draft-levkowetz-xml2rfc-v3-implementation-notes-08.txt:

  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 10 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 (February 12, 2019) is 1899 days in the past.  Is this
     intentional?


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

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

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

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

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

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

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

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

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

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

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

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

  -- Looks like a reference, but probably isn't: '12' on line 2240

  -- Looks like a reference, but probably isn't: '13' on line 2242

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

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

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


     Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 15 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                         February 12, 2019
5	Expires: August 16, 2019

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

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 August 16, 2019.

33	Copyright Notice

35	   Copyright (c) 2019 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  . . . . . . . . . . . . . . . . . . . . . . . .   4
51	   2.  Fitness for Purpose . . . . . . . . . . . . . . . . . . . . .   5
52	     2.1.  Degraded Table of Contents  . . . . . . . . . . . . . . .   5
53	     2.2.  RFC Publication Date Policy . . . . . . . . . . . . . . .   6
54	   3.  Schema Issues . . . . . . . . . . . . . . . . . . . . . . . .   6
55	     3.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .   6
56	       3.1.1.  Before Section 2.5: <artset>  . . . . . . . . . . . .   6
57	       3.1.2.  In Section 2.5.5, "name" Attribute  . . . . . . . . .   7
58	       3.1.3.  In Section 2.5.7, <artwork> "type" Attribute  . . . .   7
59	       3.1.4.  In Section 2.6, <aside> . . . . . . . . . . . . . . .   8
60	       3.1.5.  In Section 2.12, <br> . . . . . . . . . . . . . . . .   9
61	       3.1.6.  In Section 2.20, <dl> . . . . . . . . . . . . . . . .   9
62	       3.1.7.  New Section 2.20.4, "indent" Attribute  . . . . . . .  10
63	       3.1.8.  New Section 2.54.2  . . . . . . . . . . . . . . . . .  10
64	       3.1.9.  In Section 2.27, <iref> . . . . . . . . . . . . . . .  11
65	       3.1.10. In Section 2.29, <li> . . . . . . . . . . . . . . . .  11
66	       3.1.11. In Section 2.32, <name> . . . . . . . . . . . . . . .  12
67	       3.1.12. In Section 2.32, <organization> . . . . . . . . . . .  12
68	       3.1.13. In Section 2.37, <postal> . . . . . . . . . . . . . .  12
69	       3.1.14. In Section 2.40.2, "quoteTitle" . . . . . . . . . . .  13
70	       3.1.15. In Section 2.41, <referencegroup> . . . . . . . . . .  13
71	       3.1.16. In Section 2.42, <references> . . . . . . . . . . . .  13
72	       3.1.17. In Section 2.45.1, "category" Attribute . . . . . . .  14
73	       3.1.18. In Section 2.45.3, "docName" Attribute  . . . . . . .  14
74	       3.1.19. In Section 2.45.7, "number" Attribute . . . . . . . .  14
75	       3.1.20. In Section 2.46.2, "numbered" Attribute . . . . . . .  15
76	       3.1.21. In Section 2.47, <seriesInfo> . . . . . . . . . . . .  15
77	       3.1.22. In Section 2.48,  <sourcecode>  . . . . . . . . . . .  17
78	       3.1.23. In Section 2.53.3 and 2.53.4. . . . . . . . . . . . .  17
79	       3.1.24. New Section 2.X, <u>  . . . . . . . . . . . . . . . .  18
80	       3.1.25. In Section 2.63.2, <ul> "empty" attribute . . . . . .  18
81	       3.1.26. In Section 2.66.1, <xref> "format" attribute  . . . .  19
82	       3.1.27. In Section 3.3, <format>  . . . . . . . . . . . . . .  19
83	       3.1.28. In Section 3.4.2, "hangIndent" Attribute  . . . . . .  20
84	       3.1.29. In Appendix C.  Relax NG schema . . . . . . . . . . .  20
85	       3.1.30. Use of the term "counter".  . . . . . . . . . . . . .  20
86	     3.2.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  21
87	       3.2.1.  New Section 5.1.6, Attribute validation . . . . . . .  21
88	       3.2.2.  In Section 5.2.6, Attribute Default Value Insertion .  21
89	       3.2.3.  In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  21
90	     3.3.  Some attributes should have value type xsd:ID . . . . . .  22
91	   4.  Non-Schema Issues . . . . . . . . . . . . . . . . . . . . . .  22
92	     4.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .  22
93	       4.1.1.  In Section 2.5.7, "type" Attribute  . . . . . . . . .  22
94	       4.1.2.  New Section 2.8.1: Index  . . . . . . . . . . . . . .  23
95	       4.1.3.  In Section 2.17, <date> . . . . . . . . . . . . . . .  23
96	       4.1.4.  In Section 2.40.1, "anchor" Attribute . . . . . . . .  24
97	       4.1.5.  In Appendix A.1.1: TLP switch-over date discrepancies  24
98	       4.1.6.  In Appendix B.2.1: TLP switch-over date discrepancies  25
99	     4.2.  RFC 7992  . . . . . . . . . . . . . . . . . . . . . . . .  25
100	       4.2.1.  In Section 5.1,  IDs  . . . . . . . . . . . . . . . .  25
101	       4.2.2.  In Section 6.2, Root Element  . . . . . . . . . . . .  26
102	       4.2.3.  In Section 6.4,  Page Headers and Footers . . . . . .  26
103	       4.2.4.  In Section 6.5, Document Information  . . . . . . . .  26
104	       4.2.5.  In Section 8.1.1, Index Contents  . . . . . . . . . .  27
105	       4.2.6.  Inconsistent use of "s-", "n-" and User-Supplied "id"
106	               Attributes  . . . . . . . . . . . . . . . . . . . . .  27
107	       4.2.7.  In Section 9.2, <address> . . . . . . . . . . . . . .  28
108	       4.2.8.  In Section 9.7.2, Authors of this Document  . . . . .  28
109	       4.2.9.  In Section 9.7.3, Authors of References . . . . . . .  29
110	       4.2.10. In Section 9.16, <cref> . . . . . . . . . . . . . . .  29
111	       4.2.11. In Section 9.24, <eref> . . . . . . . . . . . . . . .  29
112	       4.2.12. In Section 9.25, <figure> . . . . . . . . . . . . . .  29
113	       4.2.13. In Section 9.27, <iref> . . . . . . . . . . . . . . .  29
114	       4.2.14. In Section 9.33, <note> . . . . . . . . . . . . . . .  29
115	       4.2.15. In Section 9.34, <ol> . . . . . . . . . . . . . . . .  30
116	       4.2.16. In Section 9.35, <organization> . . . . . . . . . . .  30
117	       4.2.17. In Section 9.36, <phone>  . . . . . . . . . . . . . .  30
118	       4.2.18. In Section 9.37, <postal> . . . . . . . . . . . . . .  30
119	       4.2.19. In Section 9.40, <reference>  . . . . . . . . . . . .  31
120	       4.2.20. In Section 9.41, <referencegroup> . . . . . . . . . .  32
121	       4.2.21. In Section 9.42, <references> . . . . . . . . . . . .  32
122	       4.2.22. In Section 9.54, <table>  . . . . . . . . . . . . . .  32
123	       4.2.23. In Section 9.56, <td> . . . . . . . . . . . . . . . .  32
124	       4.2.24. In Section 9.58, <th> . . . . . . . . . . . . . . . .  33
125	       4.2.25. In Section 9.60, <title>  . . . . . . . . . . . . . .  33
126	       4.2.26. In Section 9.66, <xref> . . . . . . . . . . . . . . .  33
127	     4.3.  RFC 7994  . . . . . . . . . . . . . . . . . . . . . . . .  33
128	       4.3.1.  Additional Guidance . . . . . . . . . . . . . . . . .  33
129	     4.4.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  34
130	       4.4.1.  In Section 5.2.3, <date> Insertion  . . . . . . . . .  34
131	       4.4.2.  In Section 5.2.4, "prepTime" Insertion  . . . . . . .  35
132	       4.4.3.  In Section 5.2.6, Attribute Default Value Insertion .  35
133	       4.4.4.  In Section 5.2.7, "toc" Attribute . . . . . . . . . .  35
134	       4.4.5.  In Section 5.2.8, "removeInRFC" Warning Paragraph . .  36
135	       4.4.6.  In Section 5.3.1, "month" Attribute . . . . . . . . .  36
136	       4.4.7.  In Section 5.3.2, ASCII Attribute Processing  . . . .  36
137	       4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation . . .  37
138	       4.4.9.  In Section 5.4.2, <boilerplate> Insertion: Only for
139	               RFCs? . . . . . . . . . . . . . . . . . . . . . . . .  37
140	       4.4.10. In Section 5.4.2, <boilerplate> Insertion: Error
141	               Message . . . . . . . . . . . . . . . . . . . . . . .  38
142	       4.4.11. In Section 5.4.2.1, Compare <rfc> submissionType and
143	               <seriesInfo> "stream".  . . . . . . . . . . . . . . .  38

145	       4.4.12. In Section 5.4.2.2, "Status of this Memo" Insertion .  39
146	       4.4.13. In Section 5.4.3, <reference> "target" Insertion  . .  39
147	       4.4.14. In Section 5.4.4, <name> Slugification  . . . . . . .  39
148	       4.4.15. In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  40
149	       4.4.16. In Section 5.4.7, <iref> Numbering  . . . . . . . . .  41
150	       4.4.17. In Section 5.4.8.1, "derivedContent" Insertion (with
151	               Content)  . . . . . . . . . . . . . . . . . . . . . .  42
152	       4.4.18. In Section 5.4.8.2, "derivedContent" Insertion
153	               (without Content) . . . . . . . . . . . . . . . . . .  43
154	       4.4.19. In Section 5.5.1, <artwork> Processing  . . . . . . .  43
155	       4.4.20. In Section 5.5.2, <sourcecode> Processing . . . . . .  43
156	       4.4.21. In Section 5.4.8.2, "derivedContent" Insertion. . . .  44
157	       4.4.22. In Section 5.4.9, <relref> Processing . . . . . . . .  44
158	       4.4.23. New Section 5.4.10, Unused Reference Warnings . . . .  45
159	       4.4.24. New Section 5.4.11, Index Insertion . . . . . . . . .  45
160	       4.4.25. In Section 5.6.3,  <link> Processing  . . . . . . . .  45
161	   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  46
162	   6.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  46
163	     6.1.  Informative References  . . . . . . . . . . . . . . . . .  46
164	     6.2.  URIs  . . . . . . . . . . . . . . . . . . . . . . . . . .  47
165	   Appendix A.  Proposed new sections in RFC 7991 bis  . . . . . . .  48
166	     A.1.  <u> . . . . . . . . . . . . . . . . . . . . . . . . . . .  48
167	   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  50

169	1.  Introduction

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

176	   *  An XML converter from vocabulary version 2 [RFC7749] to version 3
177	      [RFC7991]

179	   *  A Normalisation processor, "PrepTool", [RFC7997]

181	   *  An XML to plain text converter [RFC7994] for the version 3
182	      vocabulary

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

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

190	   During the implementation work, a number of issues with the
191	   specification has been found (this was expected at the outset by all
192	   parties) and a number of observations has been made about limitations
193	   of the specification and vocabulary version 3 schema, and also
194	   limitations in the specification of the work to be done.

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

199	   When this memo says 'the current version of xml2rfc', it refers to
200	   the latest release of the xml2rfc processor available from the PyPi
201	   package repository [1] at the date this document was published, as
202	   given above.

204	2.  Fitness for Purpose

206	   The introduction to [RFC7991] states:

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

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

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

225	2.1.  Degraded Table of Contents

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

236	   Proposal:  Add support for pagination in a future version of the text
237	      formatter.

239	   Implementation:  None in the current version of xml2rfc.

241	2.2.  RFC Publication Date Policy

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

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

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

257	3.  Schema Issues

259	3.1.  RFC 7991

261	3.1.1.  Before Section 2.5: <artset>

263	   The way <artwork> has been specified to handle the presence of both
264	   SVG artwork and text fallback (in Section 2.5 of [RFC7991]) has the
265	   result that any SVG content has to be placed as a data: URL in the
266	   "src" attribute when an ascii-art fallback is present.  This makes
267	   the SVG effectively uneditable once the preptool has been run, even
268	   if the SVG artwork was originally provided as a regular SVG XML file
269	   external to the document XML file.

271	   In order to be able to more easily deal with alternative instances of
272	   artwork, and in the future possibly deal smoothly with a wider number
273	   of alternative artwork formats than is currently provided for, a new
274	   element <artset> could be introduced, presenting a set of alternative
275	   artwork executions.  This would let the renderer pick the most
276	   appropriate <artwork> instance for its format from the alternatives
277	   present within an <artset> element, based on the "type" attribute of
278	   each enclosed <artwork> element.

280	   If more than one <artwork> element is found within an <artset>
281	   element, with the same "type" attribute, the renderer could select
282	   the first one, or possibly choose between the alternative instances
283	   based on the output format and some quality of the alternative
284	   instances that made one more suitable than the other for that
285	   particular format, such as size, aspect ratio, or whatnot.

287	   Implementation:  Xml2rfc as of version 2.19.0 implements this, with a
288	      preference list when rendering to HTML and PDF of ( "svg",
289	      "binary-art", "ascii-art" ), while the text renderer uses the list
290	      ( "ascii-art", ) -- i.e., one entry only.  The Relax-NG compact
291	      schema used for <artset> is this:

293	      artset =
294	        element artset {
295	          attribute xml:base { text }?,
296	          attribute xml:lang { text }?,
297	          attribute anchor { xsd:ID }?,
298	          attribute pn { xsd:ID }?,
299	          artwork*
300	        }

302	      The <artset> element can occur anywhere an <artwork> element can
303	      occur.  The first anchor on an <artwork> element within an
304	      <artset> element will be promoted to the <artset> element if it
305	      has none; apart from that, anchors on <artwork> elements within an
306	      <artset> element will be removed by the preptool.

308	3.1.2.  In Section 2.5.5, "name" Attribute

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

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

316	   Proposal:  Deprecate "name" for use on <artwork> and <sourcecode>,
317	      and instead use "file", which for <sourcecode> will be explicitly
318	      rendered, as established as best current practice for YANG modules
319	      as specified in [RFC8407].

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

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

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

328	3.1.3.  In Section 2.5.7, <artwork> "type" Attribute

330	   The text lists a number of preferred values, but does not indicate
331	   how these are to be used, or what to do with other values.  In
332	   particular, the default value is "" (i.e., empty) -- should this
333	   cause a warning or error, or any other action?  If not, how should
334	   'preferred' be understood?
335	   Additionally, according to Section 5.1 of RFC 7991, any text content
336	   serves as ascii-art fallback in case the rendering format cannot
337	   render the content that the 'src' attribute indicates.  But in that
338	   case, it seems that the "type" attribute should apply exclusively to
339	   the content that the "src" attribute points at.  This should be
340	   clarified in the text.

342	   Further, some thought about the possible use cases for the listed
343	   preferred values of the "type" attribute makes it appear that the
344	   given list contains values from (at least) two different classes of
345	   things:

347	   *  "svg" seems to describe a format

349	   *  "binary-art" also seems to describe a format

351	   *  "ascii-art" also seems to describe a format

353	   *  "call-flow" seems to describe the art content

355	   *  "hex-dump" seems to describe the art content

357	   Proposal:  Require the "type" attribute to have a value if the "src"
358	      attribute is specified, and let it describe the format.  If any
359	      action should be taken on the basis of one of the preferred values
360	      appearing or a different value appearing, add text to indicate so.

362	      For values like "call-flow" and "hex-dump", add a different
363	      attribute to describe the artwork content.  Do not conflate the
364	      artwork description with the artwork format given in the "type"
365	      attribute.

367	   Implementation:  The current implementation uses the "type" attribute
368	      to determine how to process the "src" attribute.  Handling exists
369	      for the values "svg", "binary-art", and "ascii-art".  The idnits
370	      rewrite warns if type has any value other than "svg", "binary-
371	      art", or "ascii-art".

373	      As of version 2.19.0 of xml2rfc, the conflict between the type
374	      that the "src" attribute points at, and any ascii-art fallback has
375	      been removed by introduction of the <artset> element.

377	3.1.4.  In Section 2.6, <aside>

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

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

385	   Implementation:  Implemented in the current version of xml2rfc.

387	3.1.5.  In Section 2.12, <br>

389	   A number of elements permits a mixed content model (see
390	   Section 3.1.10.2): <li>, <blockquote>, <dd>, <td>, and <th>.
391	   However, when using the simpler of the two content schemas, two of
392	   them (<td> and <th>) permit inline line breaks through the use of
393	   <br> elements; the others do not.  This seems terribly arbitrary.

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

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

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

404	3.1.6.  In Section 2.20, <dl>

406	   The current specification says:

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

413	   This does not match established typographic terminology.  In
414	   typographic terminology, "hanging indent" describes the case where
415	   the indentation of the second and subsequent lines of a paragraph is
416	   greater than the indentation of the first line.  Whether the
417	   definition in a definition list starts on the first line or not has
418	   nothing to do with the presence of hanging indent; our definition
419	   lists will *always* have hanging indent.

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

425	   A more descriptive name for the attribute we're talking about would
426	   be 'start-definition-on-first-line', but that's unwieldy.  Maybe
427	   'newline="false"' to start the definition on the first line, or
428	   something like 'definition-start="first"'?
429	   Proposal:  Change this to a different term that is more descriptive
430	      and does not use typographically incorrect terminology.

432	   Resolution:  The "hanging" attribute will be renamed to "newline",
433	      with newline="true" meaning the same as hanging="false".  The
434	      default value will change accordingly.

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

438	3.1.7.  New Section 2.20.4, "indent" Attribute

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

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

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

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

457	3.1.8.  New Section 2.54.2

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

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

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

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

475	3.1.9.  In Section 2.27, <iref>

477	   In HTML5, <span> may not be placed directly inside a table.  RFC 7992
478	   specifies that <iref> should be rendered as a <span>, and also
479	   specifies that <table> is directly rendered as its HTML counterpart.
480	   This results in generating invalid HTML.  Suggest disallowing <iref>
481	   as a direct child of <table> (but still permitting it within <th> and
482	   <td>).

484	3.1.10.  In Section 2.29, <li>

486	3.1.10.1.  Unordered lists with arbitrary symbols

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

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

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

503	   Proposal:  Add an explicit "bullet" attribute to support this use
504	      case.

506	   Resolution:  Rejected.

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

510	3.1.10.2.  Mixed Content Model

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

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

519	   Resolution:  Rejected.

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

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

526	3.1.11.  In Section 2.32, <name>

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

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

535	   Resolution:  Accepted.

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

539	3.1.12.  In Section 2.32, <organization>

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

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

549	   Implementation:  The current version of xml2rfc supports
550	      "asciiAbbrev".

552	3.1.13.  In Section 2.37, <postal>

554	   The enhancement to <postal>, adding a <postalLine> element, is a fair
555	   step on the way to permitting better representation of the wealth of
556	   postal addresses around the globe which don't match the American
557	   postal addresses.

559	   Unfortunately, it manages to throw the baby out with the bathwater by
560	   constraining postalLine to be used only if none of the other elements
561	   are used.  This makes it impossible to apply hCard [HCARD] labels
562	   (based on vCard [RFC6350] properties) to the elements of an address,
563	   as [RFC7992] requires.  Applying the schema from [RFC7991] would make
564	   country information and hCard tags unavailable for any locality with
565	   a postal address scheme that needs to use <postalLine> because it
566	   does not match the American scheme.  This would make statistics such
567	   as the author origin statistics either miss authors with such
568	   addresses, or make the statistics harder to compile than is
569	   necessary, and make for instance the data on this page skewed:
570	   <https://datatracker.ietf.org/stats/document/yearly/continent/>
571	   The current implementation maps <postalLine> to the hCard property
572	   "extended-address", and permits it to be used together with other
573	   elements, in particular <country>, <region>, and <city>.  This is a
574	   change to the schema.

576	   The current implementation also provides a full set of hCard- and
577	   [RFC6350]-compatible address elements, including <extaddr> and
578	   <pobox>.  The hCard locality address component is mapped to the
579	   current <city> element, however; not renamed to '<locality>'.

581	3.1.14.  In Section 2.40.2, "quoteTitle"

583	   The version two xml2rfc processors already support the attribute
584	   "quote-title".  The attribute name change introduces an
585	   incompatibility.  This in particular impacts existing bibxml
586	   reference files, which should work with both version 2 and 3
587	   vocabulary documents.

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

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

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

598	3.1.15.  In Section 2.41, <referencegroup>

600	   If <referencegroup> is to be used to represent for instance an STD
601	   entries that consist of multiple RFCs, the STD itself will have an
602	   URL.  It would be natural to represent that with a "target"
603	   attribute, as for <reference>.

605	   Proposal:  Add a "target" attribute for <referencegroup<, matching
606	      the one for <reference<.

608	   Implementation:  Implemented in xml2rfc v 2.18.0

610	   This issue is tracked as github issue #48 [11]

612	3.1.16.  In Section 2.42, <references>

614	   The v3 schema cannot properly model multiple reference subsections
615	   contained within one numbered section.  The v2 formatter handled this
616	   by silently inserting an enclosing section, but with the introduction
617	   of the preptool, which in theory should produce a master file from
618	   which various formatters would produce equivalent results, this
619	   becomes troublesome, as the automatic insertion of a container
620	   section is specified for the HTML formatter, in section 9.8. of RFC
621	   7992, but not for the text formatter.  It would be much better to
622	   make the prepped xml explicitly show exactly what should be rendered,
623	   and not rely on formatters silently insert elements.

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

629	   Resolution:  Accepted.

631	   This issue is tracked as github issue #49 [12]

633	3.1.17.  In Section 2.45.1, "category" Attribute

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

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

641	   Implementation:  The "category" attribute on <rfc> has been kept in
642	      the current version of xml2rfc, but the additional <seriesInfo> is
643	      also generated during v2v3 conversion.  For purposes of
644	      determining the category to render, the attribute on <rfc> is the
645	      one used.

647	3.1.18.  In Section 2.45.3, "docName" Attribute

649	   Changing the "docName" attribute of <rfc> to a name value in an
650	   additional <seriesInfo> makes it much harder than it needs to be to
651	   look it up.  It also makes the semantics of <seriesInfo> even less
652	   clear.  See also Section 4.4.25.

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

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

659	3.1.19.  In Section 2.45.7, "number" Attribute

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

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

674	   Implementation:  In The current version of xml2rfc, the number
675	      attribute on <rfc> is used to determine whether to produce an RFC
676	      or Internet-Draft.  If <seriesInfo> elements are found, but no
677	      <seriesInfo> with name="RFC" and value set to the number is found,
678	      a warning is given.  If no <seriesInfo> elements are found, the
679	      appropriate elements, including one giving the RFC number, is
680	      inserted.

682	3.1.20.  In Section 2.46.2, "numbered" Attribute

684	   The text indicates that only top-level sections may have
685	   numbered="false", and that a section with numbered="false" may not
686	   have a child section with numbered="true".  But that leaves no value
687	   that is valid for child sections of an unnumbered section: They
688	   cannot have numbered="false", since they are not top-level sections,
689	   and they cannot have numbered="true", since the parent has
690	   numbered="false".

692	   Additionally, the prohibition against child sections having
693	   numbered="false" removes the option of truncating the ToC listing for
694	   some child sections; without providing a good explanation for this
695	   limitation, it seems arbitrary and counter-intuitive to disallow this
696	   feature.

698	   Proposal:  Permit sections which are not top-level sections to have
699	      numbered="false".

701	   Implementation:  In The current version of xml2rfc, child sections
702	      may have numbered="false".

704	3.1.21.  In Section 2.47, <seriesInfo>

706	3.1.21.1.  Too many possible combinations

708	   The possible and forbidden combinations of attributes for this
709	   element has now become so convoluted that it's really hard to
710	   understand how to use it correctly.  This needs a serious
711	   reconsideration.  New usages, with the purpose of replacing various
712	   attributes on the <rfc> element, have been added without any
713	   consistent pattern or table of permitted and forbidden combinations
714	   of values and attributes.

716	3.1.21.2.  The "name" Attribute

718	   The 'name' attribute is mandatory, and only 3 values are permitted:
719	   "RFC", "Interned-Draft", and "DOI", according to RFC 7991.  But it is
720	   also mandatory to set the name to "" for a <seriesInfo> with a status
721	   attribute.  Hmm...

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

726	   This means that all reference files which has things like name="ISO",
727	   name="W3C Recommendation", etc., etc., in the current reference
728	   library have have become illegal.

730	3.1.21.3.  Incompatibility between v2 and v3 schema

732	   The placement of <seriesInfo> elements within <reference> has changed
733	   in the v3 schema, in that it has been pulled into <front>, and the v2
734	   placement has been deprecated.  But this makes 'bibxml' reference
735	   files produced according to the v3 schema incompatible with v2
736	   processors, and would require us to maintain 2 separate quotation
737	   libraries.

739	3.1.21.4.  Inappropriate Introduction of the "stream" Attribute

741	   The v3 specification in [RFC7991] introduces two new attributes with
742	   semantic content, in addition to the ASCII versions of the pre-
743	   existing "name" and "value" attributes: "stream" and "status".

745	   The intention seems to be to deprecate attributes on <rfc>.  However,
746	   these attributes cannot have multiple values for a document, which
747	   makes the move to <seriesInfo>, which can occur multiple times,
748	   dubious.

750	3.1.21.5.  Summary

752	   The number of issues introduced with the move of the <seriesInfo>
753	   element and its re-purposing in order to fill functionality in the
754	   front of a document is wholly disproportionate with any added
755	   functionality.  The specification [RFC7991] does not provide any
756	   rationale for the changes, and there seems to be no major benefits to
757	   the new schema.

759	   Proposal:  Do a rewrite of this that does not add new details to the
760	      already complex <seriesInfo> semantics, compared to the v2
761	      vocabulary, and does not make non-IETF reference files obsolete,
762	      but actually simplifies the model and use.

764	      Limit the <seriesInfo> element to what is actually needed for use
765	      within <reference/>, and do not add new functionality related to
766	      the document <front>.  Deprecate any functionality not related to
767	      usage within <reference/>.

769	      The easiest approach would be to simply revert to the v2 semantics
770	      and placement of <seriesInfo> elements, with documentation of
771	      that.

773	   Implementation:  The current implementation does not strip or
774	      disregard the attributes on <rfc>; apart from that the schema is
775	      not reverted to v2 in the current implementation, but see also
776	      Section 3.1.17, Section 3.1.19 and Section 3.2.2.

778	3.1.22.  In Section 2.48, <sourcecode>

780	   The specification is not clear on emitting <CODE BEGINS> and <CODE
781	   ENDS> automatically when rendering <sourcecode>.  In some cases it
782	   would be helpful, in others not.

784	   Proposal:  Add an attribute 'markers' for <sourcecode>, to control
785	      the emission of <CODE BEGINS> and <CODE ENDS>.  If markers="true"
786	      and the "name" attribute is set, the filename will also be
787	      emitted, as specified in [RFC8407] for YANG modules.

789	   Implementation:  Implemented as proposed in the current version of
790	      xml2rfc.

792	3.1.23.  In Section 2.53.3 and 2.53.4.

794	3.1.23.1.  Unnecessary limitation on where the "keepWithNext" attribute
795	           can be used

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

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

803	   Implementation:  Not in the current version of xml2rfc.

805	3.1.23.2.  Violation of KISS and DRY principles

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

812	   Proposal:  Keep only one of these two attributes, preferably
813	      keepWithNext.

815	   Implementation:  Not in the current version of xml2rfc.

817	3.1.24.  New Section 2.X, <u>

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

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

831	   One solution to this could be to not try to guess, or establish
832	   heuristics, but instead use a v3 schema element with preptool
833	   validation to ensure a straightforward solution to all the issues, as
834	   follows:

836	   Proposal: Limit the arbitrary placement of Unicode characters and
837	   strings in the body of a document, and control the expansion of the
838	   Unicode code-points by requiring that Unicode characters and strings
839	   be placed within a specific element if they are to occur in the body
840	   of a document.  The text in Appendix A.1 is proposed for inclusion in
841	   RFC 7991-bis as a new section.

843	3.1.25.  In Section 2.63.2, <ul> "empty" attribute

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

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

855	   Proposal:  Specify that in text output, <ul empty="true"> should be
856	      rendered without any bullet and indentation.  In order to produce
857	      unordered lists that are indented, the "bullet" attribute
858	      mentioned in Section 3.1.10 with a white-space bullet could be
859	      used.

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

867	3.1.26.  In Section 2.66.1, <xref> "format" attribute

869	3.1.26.1.  The "derivedContent" attribute

871	   For items in an ordered list, the "derivedContent" attribute should
872	   be set to the counter value for the item.  But that counter value is
873	   only known during rendering.  How is this supposed to work?

875	   Proposal:  In order to be able to set the "derivedContent" value, the
876	      preptool actually has to work through the list and derive the
877	      rendered counter.  If we accept this, [KISS] and [DRY] both points
878	      in the direction of not discarding this value, but making a record
879	      of it, in the same manner as we make a record of "derivedContent"
880	      for <xref>.  To do this, add a "derivedCounter" for <li>, and fill
881	      it in with the calculated counter value.

883	   Implementation:  Implemented as proposed.

885	3.1.26.2.  Referencing a <dl> entry

887	   It is specified that <xref> with format="counter" may reference
888	   sections, figures, tables, or ordered lists; but there does not seem
889	   to be any technical reason why this should not also be permitted for
890	   definition lists.

892	   Proposal:  Permit <xref> with format="counter" to also reference
893	      entries in definition list entries.

895	   Implementation:  Implemented as proposed.

897	3.1.27.  In Section 3.3, <format>

899	   The [RFC7991] text seems to be based on a misunderstanding of the
900	   purpose of the <format> element in pointing to alternative
901	   representations of a reference.  There seems to be no reason in
902	   removing this ability.  The current implementation does not remove
903	   alternative <format> entries when converting v2 to v3.  The RFC 7991
904	   text should be adjusted accordingly, and in RFC 7992 it should be
905	   specified how to render links to alternative formats for a reference.

907	3.1.28.  In Section 3.4.2, "hangIndent" Attribute

909	      "Deprecated.  Use <dl> instead."

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

916	   Proposal:  Provide an attribute "indent" on <dl> as suggested in
917	      Section 3.1.7.

919	   Implementation:  Not in the current version of xml2rfc.

921	3.1.29.  In Appendix C.  Relax NG schema

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

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

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

935	   Implementation:  Done in the current version of xml2rfc.

937	3.1.30.  Use of the term "counter".

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

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

950	   Proposal:  Instead of "counter", use "number" as the attribute value,
951	      and explicitly say "Section number, Figure number, Table number or
952	      ordered list labels" in the description.  Use "-n.n" instead of
953	      "-nnn".

955	   Implementation:  Not in the current version of xml2rfc.

957	3.2.  RFC 7998

959	3.2.1.  New Section 5.1.6, Attribute validation

961	   Some attribute validation beyond what the schema enforces is possible
962	   and desirable.  One example of this is to validate that all
963	   attributes which are expected to have integer values actually does
964	   so.  A section on this should be added.  The current implementation
965	   adds integer attribute validation and verification that apart from
966	   the name attributes of <author>, no attribute values have non-ASCII
967	   content.

969	3.2.2.  In Section 5.2.6, Attribute Default Value Insertion

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

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

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

982	3.2.3.  In Section 5.4.6, "pn" Numbering.

984	   The list of elements that are given p- or paragraph tags is severely
985	   limited, and since the presence of a pn= attribute is required in
986	   order to make internal <xref> instances work, this limits the
987	   elements to which it is possible to reference with HTML fragment
988	   identifiers.  Why?
989	   Why is <dt> and <li> present, but not <ol>, <dl>, <ul>?

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

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

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

1002	   In generated HTML, the values set for "pn" and "slugifiedName" will
1003	   be used as link targets, which makes a type of xsd:ID appropriate in
1004	   the input format, as this will guarantee that they all have distinct
1005	   values in the xml source.

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

1009	   Implementation:  Implemented in the current version of xml2rfc.

1011	4.  Non-Schema Issues

1013	4.1.  RFC 7991

1015	4.1.1.  In Section 2.5.7, "type" Attribute

1017	4.1.1.1.  How should a "src" attribute be handled when no "type" is
1018	          given.

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

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

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

1033	   Implementation:  The current version of xml2rfc implements this as
1034	      proposed.

1036	4.1.1.2.  Missing information on how to handle various types

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

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

1050	4.1.2.  New Section 2.8.1: Index

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

1055	   Proposal:  Please provide specification.

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

1061	4.1.3.  In Section 2.17, <date>

1063	4.1.3.1.  Current Date Requirement

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

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

1078	   Proposal:  Remove the section.

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

1084	4.1.3.2.  Date Specification in References

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

1092	   The text regarding prose text for month and year in bibliographic
1093	   references is not workable.  How should month and year be combined?
1094	   Some bibliographic references may have date text which requires year
1095	   first, others year last, and so on.  Mixing the described fuzziness
1096	   into the otherwise strict year, month, date format makes little sense
1097	   when the result of combining the year, month and date attributes
1098	   cannot be predictably and correctly rendered.

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

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

1109	4.1.4.  In Section 2.40.1, "anchor" Attribute

1111	   Section 5.1 of RFC 7992 says in part:

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

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

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

1123	4.1.5.  In Appendix A.1.1: TLP switch-over date discrepancies

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

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

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

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

1142	   Proposal:  Correct the dates given in the document to indicate the
1143	      official dates, and correct the text on placement of TLP to match
1144	      actual usage.

1146	   Implementation:  The current version of xml2rfc uses the official
1147	      dates during the preptool processing, not the dates given in RFC
1148	      7991.

1150	4.1.6.  In Appendix B.2.1: TLP switch-over date discrepancies

1152	   The current specification says:

1154	      -  "pn" for all elements not listed above always has the format
1155	         "p-nnn-mmm", where "nnn" is the section number and "mmm" is the
1156	         relative position in the section.  For example, this would be
1157	         "p-2.1.3-7" for the seventh part number in Section 2.1.3.

1159	   However, this will result in counting up the part numbers for
1160	   invisible parts, when numbered elements are contained within
1161	   enclosing numbered block elements.

1163	   The current implementation instead uses the same "pn" numbering
1164	   scheme as Julian Reschke's vocabulary v3 XSLT processor, with
1165	   hierarchical subsection element numbering.  For instance, the first
1166	   dt element within a dl in Section 2.1 would have a pn number of
1167	   "section-2.1-2.1".

1169	4.2.  RFC 7992

1171	4.2.1.  In Section 5.1, IDs

1173	   The current specification says:

1175	      HTML elements that are generated from XML elements that include an
1176	      "anchor" attribute will use the value of the "anchor" attribute as
1177	      the value of the "id" attribute of the corresponding HTML element.
1178	      The prep tool produces XML with "anchor" attributes in all
1179	      elements that need them.  Some HTML constructs (such as <section>)
1180	      will use multiple instances of these identifiers.

1182	   But I believe HTML5 does not permit more than one "id" attribute per
1183	   element, which begs the question of how <section> will use multiple
1184	   instances of identifiers?

1186	4.2.2.  In Section 6.2, Root Element

1188	   Typo:

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

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

1194	4.2.3.  In Section 6.4, Page Headers and Footers

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

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

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

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

1211	   Implementation:  The current implementation has code to insert
1212	      placeholder HTML, but not code to fill in the cells with actual
1213	      information from the document.  Since this is meaningless if the
1214	      guess is wrong, this code has been disabled for now.

1216	4.2.4.  In Section 6.5, Document Information

1218	   This information seems to be scrambled and incomplete.  It suggests
1219	   the use of 'Status:' for what is otherwise called 'Category:'.  It
1220	   simplifies the presentation of series information to the point that
1221	   no clue is given of how to handle the two bits of information related
1222	   to series name and series number -- the example shows 'Series:'
1223	   'Internet-Draft', which gives no guidance at all.  There is no
1224	   mention of whether to display 'Obsoletes:' and 'Updates:' information
1225	   or not.

1227	   On a more general note, this is the second section where an
1228	   incomplete example is provided instead of specification.  Examples
1229	   are however not replacements for proper specification; they are at
1230	   best a help in making a specification real to the user.  Both this
1231	   section and Section 4.2.3 needs to be expanded to provide a complete
1232	   specification.

1234	   Styling query: The example gives the style of the element that holds
1235	   author initials the class 'initial' while the attribute is
1236	   appropriately named 'initials'.  Is the difference in attribute and
1237	   style names intentional?  In any case, 'initials' would be more
1238	   appropriate.

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

1245	      The implementation also has used the sample HTML document for
1246	      guidance here, in order to be able to progress with something that
1247	      works with the style sheet from the RFC-Format CSS project.

1249	4.2.5.  In Section 8.1.1, Index Contents

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

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

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

1269	   Implementation:  The implementation consistently transfers the
1270	      "slugifiedName" attribute on <name> to an "id" attribute on the
1271	      <h2> or other header element generated from the name.
1272	      Section numbers ("s-" or "section-" values) from "pn" attributes
1273	      are consistently transferred to the <section>, <p> or other HTML
1274	      element generated from the XML element on which they appear.
1275	      User-supplied "anchor" attributes on XML elements are consistently
1276	      transferred to a <div> inside the HTML element generated from the
1277	      XML element with the anchor, encapsulating the content generated
1278	      from the XML element.

1280	4.2.7.  In Section 9.2, <address>

1282	   The example reiterates an abbreviated form of the xml given under
1283	   <author>, as if there was no difference between the rendering of
1284	   <address> and <author>.  Furthermore, the example shows only
1285	   rendering of elements which are _not_ part of <address>; any
1286	   rendering of the elements contained within <address> is omitted.
1287	   This is misleading, in particular since rendering of the individual
1288	   child elements (<postal>, <phone> , <facsimile> , <email>, and <uri>)
1289	   _has_ been specified to have explicit renderings.

1291	   Given that the specification text is reasonable for author name and
1292	   org, but nonsense for the <address> element, the following text has
1293	   been assumed during implementation:

1295	   The <address> element will be rendered as a sequence of <div>
1296	   elements, each corresponding to a child element of <address>, and
1297	   enclosed in the same <address> element as the name, role, and
1298	   organization information.  Element classes will be taken from hCard
1299	   [HCARD], as specified on <http://microformats.org/wiki/hcard>.

1301	4.2.8.  In Section 9.7.2, Authors of this Document

1303	   RFC 7997 gives the text separating the ASCII and non-ASCII address
1304	   information as "Additional contact information:".

1306	   RFC 7997 manages to convey the desired rendering order of ASCII and
1307	   non-ASCII address information without any americentric language, but
1308	   RFC 7992 talks about the non-ASCII version as 'fallback'.  As a non-
1309	   native English speaker raised speaking and writing 2 languages that
1310	   both have alphabets with non-ASCII letters, the author of this memo
1311	   finds the language in RFC 7992 somewhat offensive, and suggests that
1312	   it be removed from the document.

1314	   The current xml2rfc implementation uses the layout and wording given
1315	   in RFC 7997, not RFC 7992.

1317	   Furthermore, the document also says:

1319	      "When the <author> element, or any of its descendant elements, has
1320	      any attribute that starts with "ascii", all of the author
1321	      information is displayed twice. ..."

1323	   This is in conflict with [RFC7997], Section 3.2, which indicates that
1324	   the determining factor for displaying both non-ASCII and ASCII author
1325	   information is whether a script outside the Unicode Latin blocks is
1326	   used for the primary information.  The current implementation checks
1327	   for this, rather than going by the presence of attributes with an
1328	   'ascii' prefix.

1330	4.2.9.  In Section 9.7.3, Authors of References

1332	   Information is completely missing on how to render non-ascii name
1333	   information in references.

1335	4.2.10.  In Section 9.16, <cref>

1337	   The text does not mention how to deal with <cref>s with
1338	   display="false".  Presumably by not displaying them; but if there
1339	   exists internal links to the <cref> anchor, completely omitting the
1340	   rendering could cause breakage.  The current xml2rfc implementation
1341	   handles this by inserting an empty HTML <span> with the appropriate
1342	   id attribute.

1344	4.2.11.  In Section 9.24, <eref>

1346	   No handling is provided for the case where the <eref> element is
1347	   empty, which would result in an empty (and invisible) HTML <a>
1348	   element.  The current implementation in this case instead inserts a
1349	   span containing '<', an <a> with appropriate href and the target URL
1350	   as text, and '>'.

1352	4.2.12.  In Section 9.25, <figure>

1354	   The specified HTML rendering will result in a figure title text which
1355	   links to itself.  With the caption placed below the figure, this
1356	   means that if you click on the title, the figure will scroll up above
1357	   the browser window.  This is not particularly useful.

1359	   The current implementation instead inserts an empty <span> as the
1360	   first element of the figure, and gives it an id attribute with the
1361	   value set to the slugifiedName attribute of the <name> element, in
1362	   order to make the link from the figure caption text useful.

1364	4.2.13.  In Section 9.27, <iref>

1366	   The text refers to the "irefid" attribute.  Interpreted as meaning
1367	   the "pn" attribute, as the schema has no "irefid" attribute.

1369	4.2.14.  In Section 9.33, <note>

1371	   Typo: s/"yes"/"true"/

1373	4.2.15.  In Section 9.34, <ol>

1375	   The <ol> element has no "style" attribute.  The implementation
1376	   assumes "type" instead.

1378	4.2.16.  In Section 9.35, <organization>

1380	   The text here is in conflict with RFC 7997 with respect to rendering
1381	   the Authors' Addresses section.  RFC 7997 describes rendering two
1382	   sets of full information, one ASCII and one non-ASCII, not a single
1383	   <div> where the non-ASCII name is given first, followed by the ASCII
1384	   version as needed.

1386	4.2.17.  In Section 9.36, <phone>

1388	   The text here is in conflict with the use of 'type' in vCard and
1389	   hCard.  Telephone number type annotations identify things like 'Home'
1390	   and 'Work'.  The current implementation does not add the uppercase
1391	   VOICE type annotation.

1393	4.2.18.  In Section 9.37, <postal>

1395	   The current specification says:

1397	      This element renders as an HTML <div> with CSS class "adr", unless
1398	      it contains one or more <postalLine> child elements; in which
1399	      case, it renders as an HTML <pre> element with CSS class "label".

1401	   Handling <postalLine> elements this way violates the hCard [HCARD]
1402	   specification.  They will instead be rendered as hCard elements with
1403	   class "extended-address" within the same <div> with CSS class "adr"
1404	   as other <postal> sub-elements.

1406	   The specification continues to enforce American postal address
1407	   structure on addresses that don't use <postalLine>.  This has been
1408	   changed in the current implementation; instead of using the fixed
1409	   American layout for all countries, the formatting has been adapted to
1410	   use country-specific formatting for all recognised country names and
1411	   codes.

1413	   ( The implementer considered applying a non-US postal address layout
1414	   for all US addresses, to see how swiftly this would raise hue and cry
1415	   and be labelled a bug, but in the interest of not causing unnecessary
1416	   upset resisted the urge. )

1418	4.2.19.  In Section 9.40, <reference>

1420	4.2.19.1.  Misleading example

1422	   Section 9.41 of [RFC7992] shows <referencegroup> being rendered as
1423	   <dt>, <dd>, while the example for this section shows one reference
1424	   being rendered as <dl> <dt> <dd> </dl>.  This is contradictory.
1425	   Which one is right?  The CSS class on <dl>, which is specified as
1426	   class="reference" points in the direction that each individual
1427	   <reference> entry should be rendered as one <dl> with one set of <dt>
1428	   <dd>, while it would seem much more logical to render the list of
1429	   references as one single list holding all the references.

1431	   The current xml2rfc implementation renders <references> as a section
1432	   containing one <dl>, and each individual <reference> or
1433	   <referencegroup> as a <dt> <dd> pair within that list.  To match
1434	   this, the CSS class used is 'references' rather than 'reference'.

1436	4.2.19.2.  Anchor handling disregards <displayreference>

1438	   There is no mention in the description of the HTML rendering of
1439	   <reference> of the effects of <displayreference>, which definitely
1440	   needs to be considered.  Emitting the original anchor value from the
1441	   reference entry (which often comes from the bibxml reference library)
1442	   would make the emitted reference labels wrong when there is a
1443	   <displayreference> entry for the reference.  The most straightforward
1444	   approach would be to add an attribute "derivedAnchor" to <reference>
1445	   and have the preptool set it.

1447	   Proposal:  Add an attribute "derivedAnchor" to <reference>.  Specify
1448	      in [RFC7998] that this is set by the preptool, and update
1449	      [RFC7991] and [RFC7992] accordingly.

1451	   Implementation:  Implemented as proposed.

1453	4.2.19.3.  Handling of author lists in <reference> is underspecified

1455	   The example shows the 'and' between author names within a span
1456	   (unclear why) but does not show how to handle commas separating
1457	   authors.  The style examples on github do not enclose commas or 'and'
1458	   in a span, which seems reasonable.  Going with the style example
1459	   files here.  Section 9.7.3 of RFC 7992 gives an example without 'and'
1460	   enclosed in a span, contradicting Section 9.40 of the same RFC.

1462	   Trying to sort out the rendering of author names in references by
1463	   looking at other sources than RFC 7992 reveals that the CSS samples
1464	   show dual reference entries, one with ascii names and another with
1465	   non-ascii names.  This contradicts RFC 7997, which shows a single
1466	   reference entry where the non-ascii author names are given with the
1467	   ascii equivalent in parentheses.

1469	   The current implementation follows RFC 7997 in this respect, not RFC
1470	   7992.

1472	4.2.20.  In Section 9.41, <referencegroup>

1474	   This element is a sibling to <reference>, and <reference> is
1475	   described as being rendered as a <dl> with one set of <dt>, <dd>
1476	   child elements.

1478	   However, <referencegroup> is specified to be rendered as a <dt>, <dd>
1479	   set, *without* any containing <dl>.  The individual reference entries
1480	   are then specified to be rendered as <div>s inside the <dd>

1482	   1.  This produces invalid HTML, because there is no containing <dl>

1484	   2.  Why isn't this rendered as a <dl> with multiple <dd> entries?
1485	       That would make the styling much more consistent.

1487	4.2.21.  In Section 9.42, <references>

1489	   The specification says that this is to be rendered as a <section>.
1490	   However, if <reference>s and <referencegroup>s are to be rendered as
1491	   <dt>, <dd>, then this element needs to be rendered as <section> <dl>
1492	   ... </dl> </section>

1494	4.2.22.  In Section 9.54, <table>

1496	   RFC 7992 says: "This element is directly rendered as its HTML
1497	   counterpart."

1499	   This ignores the special processing needed to insert a <caption>
1500	   element.  The current implementation handles this appropriately.  The
1501	   specification should be updated.

1503	4.2.23.  In Section 9.56, <td>

1505	   RFC 7992 says: "This element is directly rendered as its HTML
1506	   counterpart."

1508	   However, that is not correct.  An appropriate style class needs to be
1509	   inserted to honour the "align" attribute.  The classes "alignLeft",
1510	   "alignCenter", and "alignRight" of the provided CSS are geared
1511	   towards block alignment; here text alignment is needed.  The current
1512	   implementation uses "text-left", "text-center", and "text-right", and
1513	   provides appropriate CSS entries.  (These attribute names matches the
1514	   equivalent bootstrap names.)

1516	4.2.24.  In Section 9.58, <th>

1518	   RFC 7992 says: "This element is directly rendered as its HTML
1519	   counterpart."

1521	   However, that is not correct.  An appropriate style class needs to be
1522	   inserted to honour the "align" attribute.  The classes "alignLeft",
1523	   "alignCenter", and "alignRight" of the provided CSS are geared
1524	   towards block alignment; here text alignment is needed.  The current
1525	   implementation uses "text-left", "text-center", and "text-right", and
1526	   provides appropriate CSS entries.  (These attribute names matches the
1527	   equivalent bootstrap names.)

1529	4.2.25.  In Section 9.60, <title>

1531	   This section completely lacks specification on how to render title
1532	   elements with non-Latin content and an "ascii" attribute.

1534	4.2.26.  In Section 9.66, <xref>

1536	   The specification says:

1538	      ... If the "format" attribute has the value "default", and the
1539	      "target" attribute points to a <reference> or <referencegroup>
1540	      element, then the generated <a> element is surrounded by square
1541	      brackets in the output.

1543	   However, inspection of actual usage indicates that a better rendering
1544	   would be to surround the generated <a> with square brackets only for
1545	   empty <xref> elements; when there is content, usage indicates that
1546	   authors provide enclosing parentheses or not depending on
1547	   circumstances.  Since in HTML rendering the brackets are not
1548	   necessary to provide a clue that this refers to other content (unlike
1549	   the text case), the square brackets could be omitted when the <xref>
1550	   element contains text.  The current implementation does so.

1552	4.3.  RFC 7994

1554	4.3.1.  Additional Guidance

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

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

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

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

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

1569	   *  Guidance for <eref> rendering.  In the HTML formatter, handling of
1570	      <eref> is straightforward and is specified; it simply translates
1571	      to an external link.  In the legacy text formatter, <eref> was
1572	      handled by inserting an extra <references> subsection called
1573	      "URLs", and adding reference entries for the URLs there, while the
1574	      <eref> citation point got a trailing numeric reference number.
1575	      With the preptool output becoming the authoritative published
1576	      document, this difference won't be reflected in the xml.  The two
1577	      formats would be more aligned if the text formatter renders <eref>
1578	      URLs inline.

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

1584	      Implementation:  Implemented in the current version of xml2rfc.

1586	4.4.  RFC 7998

1588	4.4.1.  In Section 5.2.3, <date> Insertion

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

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

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

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

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

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

1613	4.4.2.  In Section 5.2.4, "prepTime" Insertion

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

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

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

1626	4.4.3.  In Section 5.2.6, Attribute Default Value Insertion

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

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

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

1641	   Implementation:  Not in the current version of xml2rfc.

1643	4.4.4.  In Section 5.2.7, "toc" Attribute

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

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

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

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

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

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

1671	   Proposal:  Maybe place default setting after all potential element
1672	      insertions have taken place.

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

1680	4.4.6.  In Section 5.3.1, "month" Attribute

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

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

1690	   Proposal:  Clarify the text.

1692	4.4.7.  In Section 5.3.2, ASCII Attribute Processing

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

1698	   Proposal:  Change the title 'ASCII Attribute Processing' to refer
1699	      correctly to the "ascii" attribute: '"ascii" Attribute
1700	      Processing'.

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

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

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

1710	   Implementation:  Implemented in the current version of xml2rfc.

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

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

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

1722	   Implementation:  Implemented as proposed.

1724	4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation

1726	   Proposal:  The new section should specify normalisation of
1727	      keepWithNext/keepWithPrevious such as to replace all
1728	      keepWithPrevious with an equivalent keepWithNext on the previous
1729	      element, in case the proposal in Section 3.1.23.2 is not accepted.

1731	   Implementation:  Not in the current version of xml2rfc.

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

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

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

1747	   Proposal:  The boilerplate-element insertion parts of 5.4.2 should be
1748	      done in both RFC and draft mode, with the appropriate boilerplate
1749	      for each case.  For consistency, either add text to describe the
1750	      appropriate boilerplate for drafts, or remove the sections
1751	      specific to RFC boilerplate.

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

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

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

1767	   Proposal:  If existing boilerplate is found, issue a warning and
1768	      replace it.

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

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

1781	4.4.11.  In Section 5.4.2.1, Compare <rfc> submissionType and
1782	         <seriesInfo> "stream".

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

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

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

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

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

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

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

1817	   Implementation:  The current version of xml2rfc looks at
1818	      "submissionType", "category", and "consensus" on the <rfc>
1819	      element.

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

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

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

1829	   In the formatter, the order of <seriesInfo> determines the rendering
1830	   order.  The insertion should probably be done in the desired
1831	   rendering order.

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

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

1841	4.4.14.  In Section 5.4.4, <name> Slugification

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

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

1848	   Implementation:  Implemented as proposed in the current version of
1849	      xml2rfc.

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

1855	   *  remove non-ascii letters

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

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

1863	   Proposal:  Do slugification and uniqueness enforcement as described
1864	      above.

1866	   Implementation:  As described above.

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

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

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

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

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

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

1890	   Implementation:  Implemented as proposed in the current version of
1891	      xml2rfc.

1893	4.4.15.1.  RFC format anchors / fragment identifiers

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

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

1910	   Proposal:  Update the RFC 7998 preptool to use these prefixes,
1911	      instead:

1913	      -  "section-xxx"

1915	      -  "figure-xxx"

1917	      -  "table-xxx"

1919	      -  "appendix-xxx"

1921	      -  "index-xxx"

1923	      -  "para-xxx"

1925	      -  "name-xxx"

1927	   Implementation:  Implemented as above in the current version of
1928	      xml2rfc.

1930	4.4.16.  In Section 5.4.7, <iref> Numbering

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

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

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

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

1950	4.4.17.  In Section 5.4.8.1, "derivedContent" Insertion (with Content)

1952	   This section is problematic.  It says:

1954	      For each <xref> element that has content, fill the
1955	      "derivedContent" with the element content, having first trimmed
1956	      the whitespace from ends of content text.  Issue a warning if the
1957	      "derivedContent" attribute already exists and has a different
1958	      value from what was being filled in.

1960	   On the surface, it seems to replace the effect of using <xref> with
1961	   format="none" under vocabulary version 2, but in practice it blocks
1962	   the combination of generated text (say a section number fetched from
1963	   the referenced section) with author-provided text, since any author-
1964	   provided text will preempt generated text that is based on the
1965	   "format" attribute with the author-provided text.

1967	   Additionally, and in one sense just as bad, it violates the principle
1968	   of least surprise [POLA], since it is a fundamental change from how
1969	   text inside the <xref> element was combined with generated text in
1970	   version 2.

1972	   Implementation:  As of xml2rfc 2.19.0, the expansion of <xref> and
1973	      its variation based on "format" attribute settings has been
1974	      reverted to be more in line with version two, and more regular.
1975	      The attribute setting format="none" is honoured again, and if the
1976	      <xref> element has text content, it is combined with the content
1977	      derived from the format attribute setting, rather than simply
1978	      overriding it, as was the consequence of Section 5.4.8.1 of
1979	      [RFC7998].

1981	      -  Derived content is generated based on the format attribute

1983	      -  If text content is provided, it is shown together with any
1984	         derived content

1986	      -  If the <xref> target is a listed reference, the derived content
1987	         is shown within square brackets

1989	      -  If the <xref> target is not a listed reference , the derived
1990	         content is shown within parentheses if there is text content,
1991	         and without parentheses if not.

1993	      -  If text content is provided, and is identical with the derived
1994	         content, it is ignored.

1996	   This addresses github issue #17 [13].

1998	4.4.18.  In Section 5.4.8.2, "derivedContent" Insertion (without
1999	         Content)

2001	   There's a formatting mistake:

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

2007	4.4.19.  In Section 5.5.1, <artwork> Processing

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

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

2018	   Implementation:  Implemented as proposed in the current version of
2019	      xml2rfc.

2021	4.4.20.  In Section 5.5.2, <sourcecode> Processing

2023	   List item 4 says:

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

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

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

2036	   Implementation:  Implemented as proposed in the current version of
2037	      xml2rfc.

2039	4.4.21.  In Section 5.4.8.2, "derivedContent" Insertion.

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

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

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

2062	   Proposal:  The whole "derivedContent" handling and specification
2063	      needs a thorough rework, with specification of the intended use of
2064	      the attribute by formatters.  Possibly the whole "derivedContent"
2065	      concept should be scrapped, and the rendering left for the
2066	      formatter, depending on the characteristics of the output format.

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

2073	4.4.22.  In Section 5.4.9, <relref> Processing

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

2081	   Proposal:  Deprecate <relref>, and fold the functionality into
2082	      <xref>.

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

2087	4.4.23.  New Section 5.4.10, Unused Reference Warnings

2089	   During vocabulary version 2 processing, warnings are emitted for
2090	   <reference> entries that are not used.  This is not specified for v3,
2091	   but is desired, according to RFC Editor staff.  Implemented in
2092	   xml2rfc v2.18.0.

2094	4.4.24.  New Section 5.4.11, Index Insertion

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

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

2106	   Proposal:  Insert the XML necessary to render the index into the
2107	      prepped XML.

2109	   Implementation:  Implemented as proposed in the current version of
2110	      xml2rfc.

2112	4.4.25.  In Section 5.6.3, <link> Processing

2114	4.4.25.1.  Using docName to generate convertedFrom

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

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

2122	   Proposal:  Require docName to be set to the draft name, and use that
2123	      to create this link.  This also implies that "docName" not be
2124	      deprecated (see Section 3.1.18).

2126	   Implementation:  Implemented as proposed in the current version of
2127	      xml2rfc.

2129	4.4.25.2.  Invalid "rel" values.

2131	   Using the W3C validator to validate the V3 output, there are some
2132	   errors; all of them with the same basic complaint: The values
2133	   prescribed for the <link> "rel" attribute (derivedFrom, describedBy,
2134	   and item) are not permitted values.  The permitted values are given
2135	   here: <https://html.spec.whatwg.org/multipage/links.html#linkTypes>.

2137	5.  Security Considerations

2139	   This document does not introduce any security considerations on its
2140	   own.

2142	6.  References

2144	6.1.  Informative References

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

2149	   [HCARD]    Celik, T., "hCard 1.0", 2015,
2150	              <http://microformats.org/wiki/hcard>.

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

2155	   [POLA]     Wikipedia, "Principle of least astonishment", 2018,
2156	              <https://en.wikipedia.org/wiki/
2157	              Principle_of_least_astonishment>.

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

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

2167	   [RFC6350]  Perreault, S., "vCard Format Specification", RFC 6350,
2168	              DOI 10.17487/RFC6350, August 2011,
2169	              <https://www.rfc-editor.org/info/rfc6350>.

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

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

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

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

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

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

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

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

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

2208	   [RFC8407]  Bierman, A., "Guidelines for Authors and Reviewers of
2209	              Documents Containing YANG Data Models", BCP 216, RFC 8407,
2210	              DOI 10.17487/RFC8407, October 2018,
2211	              <https://www.rfc-editor.org/info/rfc8407>.

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

2216	6.2.  URIs

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

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

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

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

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

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

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

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

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

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

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

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

2242	   [13] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/17

2244	Appendix A.  Proposed new sections in RFC 7991 bis

2246	A.1.  <u>

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

2255	   In order to insert Unicode characters in any other context, xml2rfc
2256	   vocabulary v3 requires that the Unicode string be enclosed within an
2257	   <u> element.  The element will be expanded inline based on the value
2258	   of a "format" attribute.  This provides a generalised means of
2259	   generating the 6 methods of Unicode renderings listed in [RFC7997],
2260	   Section 3.4, and also several others found in for instance the RFC
2261	   Format Tools example rendering of RFC 7700, at <https://rfc-
2262	   format.github.io/draft-iab-rfc-css-bis/sample2-v2.html>.

2264	   The "format" attribute accepts either a simplified format
2265	   specification, or a full format string with placeholders for the
2266	   various possible Unicode expansions.

2268	   The simplified format consists of dash-separated keywords, where each
2269	   keyword represents a possible expansion of the Unicode character or
2270	   string; use for example "<u "lit-num-name">foo</u>" to expand the
2271	   text to its literal value, code point values, and code point names.

2273	   A combination of up to 3 of the following keywords may be used,
2274	   separated by dashes: "num", "lit", "name", "ascii", "char".  The
2275	   keywords are expanded as follows and combined, with the second and
2276	   third enclosed in parentheses (if present):

2278	      "num"
2279	         The numeric value(s) of the element text, in U+1234 notation

2281	      "name"
2282	         The Unicode name(s) of the element text

2284	      "lit"
2285	         The literal element text, enclosed in quotes

2287	      "char"
2288	         The literal element text, without quotes

2290	      "ascii"
2291	         The provided ASCII value

2293	   In order to ensure that no specification mistakes can result for
2294	   rendering methods that cannot render all Unicode code points, "num"
2295	   must always be part of the specified format.

2297	   The default value of the "format" attribute is "lit-name-num".

2299	   Examples:

2301	      format="num-lit":
2302	         Temperature changes in the Temperature Control Protocol are
2303	         indicated by the character U+0394 ("Δ").

2305	      format="num-name":
2306	         Temperature changes in the Temperature Control Protocol are
2307	         indicated by the character U+0394 (GREEK CAPITAL LETTER DELTA).

2309	      format="num-lit-name":
2310	         Temperature changes in the Temperature Control Protocol are
2311	         indicated by the character U+0394 ("Δ").

2313	      format="num-name-lit":
2314	         Temperature changes in the Temperature Control Protocol are
2315	         indicated by the character U+0394 (GREEK CAPITAL LETTER DELTA,
2316	         "Δ").

2318	      format="name-lit-num":
2319	         Temperature changes in the Temperature Control Protocol are
2320	         indicated by the character GREEK CAPITAL LETTER DELTA ("Δ",
2321	         U+0394).

2323	      format="lit-name-num":
2324	         Temperature changes in the Temperature Control Protocol are
2325	         indicated by the character "Δ" (GREEK CAPITAL LETTER DELTA,
2326	         U+0394).

2328	   If the <u> element encloses a Unicode string, rather than a single
2329	   code point, the rendering reflects this.  The element

2331	      <u format="num-lit">ᏚᎢᎵᎬᎢᎬᏒ</u>

2333	   will be expanded to 'U+13DA U+13A2 U+13B5 U+13AC U+13A2 U+13AC U+13D2
2334	   ("ᏚᎢᎵᎬᎢᎬᏒ")'.

2336	   Unicode characters in document text which are not enclosed in <u>
2337	   will be replaced with a question mark (?) and a warning will be
2338	   issued.

2340	   In order to provide for cases where the simplified format above is
2341	   insufficient, without relinquishing the requirement that the number
2342	   of a code point always must be rendered, the "format" attribute can
2343	   also accept a full format string.  This format uses placeholders
2344	   which consist of any of the key words above enclosed in curly braces;
2345	   outside of this, any ascii text is permissible.  For example,

2347	      The <u format="{lit} character ({num})">Δ</u>.

2349	   will be rendered as

2351	      The "Δ" character (U+0394).

2353	Author's Address

2355	   Henrik Levkowetz
2356	   Elf Tools AB
2357	   Ollonstigen 8
2358	   Lidingö  18164
2359	   Sweden

2361	   Email: henrik@levkowetz.com