idnits 2.17.1 

draft-levkowetz-xml2rfc-v3-implementation-notes-13.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 20 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.

  ** The document seems to lack a both a reference to RFC 2119 and the
     recommended RFC 2119 boilerplate, even if it appears to use RFC 2119
     keywords. 

     RFC 2119 keyword, line 699: '...ch author's name SHOULD be listed with...'
     RFC 2119 keyword, line 2748: '...   MUST always be part of the specifie...'
     RFC 2119 keyword, line 2813: '...ed format, "num" MUST always be part o...'
     RFC 2119 keyword, line 2991: '...   Renderers MUST use the appropriate ...'


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

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

  -- The document date (16 September 2021) is 947 days in the past.  Is this
     intentional?


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

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

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

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


     Summary: 2 errors (**), 0 flaws (~~), 5 warnings (==), 2 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                         16 September 2021
5	Expires: 20 March 2022

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

11	Abstract

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

17	Status of This Memo

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

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

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

32	   This Internet-Draft will expire on 20 March 2022.

34	Copyright Notice

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

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

48	Table of Contents

50	   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   4
51	     1.1.  Current Status  . . . . . . . . . . . . . . . . . . . . .   5
52	   2.  Fitness for Purpose . . . . . . . . . . . . . . . . . . . . .   6
53	     2.1.  Degraded Table of Contents  . . . . . . . . . . . . . . .   7
54	     2.2.  RFC Publication Date Policy . . . . . . . . . . . . . . .   7
55	   3.  Schema Issues . . . . . . . . . . . . . . . . . . . . . . . .   8
56	     3.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .   8
57	       3.1.1.  Before Section 2.5: <artset>  . . . . . . . . . . . .   8
58	       3.1.2.  In Section 2.5.5, "name" Attribute  . . . . . . . . .   9
59	       3.1.3.  In Section 2.5.7, <artwork> "type" Attribute  . . . .   9
60	       3.1.4.  In Section 2.6, <aside> . . . . . . . . . . . . . . .  11
61	       3.1.5.  In Section 2.12, <br> . . . . . . . . . . . . . . . .  11
62	       3.1.6.  In Section 2.20, <dl> . . . . . . . . . . . . . . . .  12
63	       3.1.7.  New Section 2.20.4, "indent" Attribute  . . . . . . .  13
64	       3.1.8.  New Section 2.54.2  . . . . . . . . . . . . . . . . .  13
65	       3.1.9.  In Section 2.27, <iref> . . . . . . . . . . . . . . .  14
66	       3.1.10. In Section 2.29, <li> . . . . . . . . . . . . . . . .  14
67	       3.1.11. In Section 2.32, <name> . . . . . . . . . . . . . . .  15
68	       3.1.12. In Section 2.32, <organization> . . . . . . . . . . .  15
69	       3.1.13. In Section 2.37, <postal> . . . . . . . . . . . . . .  16
70	       3.1.14. In Section 2.40.2, "quoteTitle" . . . . . . . . . . .  17
71	       3.1.15. In Section 2.41, <referencegroup> . . . . . . . . . .  17
72	       3.1.16. In Section 2.42, <references> . . . . . . . . . . . .  18
73	       3.1.17. In Section 2.45.1, "category" Attribute . . . . . . .  18
74	       3.1.18. In Section 2.45.3, "docName" Attribute  . . . . . . .  18
75	       3.1.19. In Section 2.45.7, "number" Attribute . . . . . . . .  19
76	       3.1.20. In Section 2.46.2, "numbered" Attribute . . . . . . .  19
77	       3.1.21. In Section 2.47, <seriesInfo> . . . . . . . . . . . .  20
78	       3.1.22. In Section 2.48, <sourcecode> . . . . . . . . . . . .  21
79	       3.1.23. In Section 2.53.3 and 2.53.4. . . . . . . . . . . . .  22
80	       3.1.24. New Section 2.X, <u>  . . . . . . . . . . . . . . . .  22
81	       3.1.25. In Section 2.63.2, <ul> "empty" attribute . . . . . .  23
82	       3.1.26. In Section 2.66.1, <xref> "format" attribute  . . . .  24
83	       3.1.27. In Section 3.3, <format>  . . . . . . . . . . . . . .  25
84	       3.1.28. In Section 3.4.2, "hangIndent" Attribute  . . . . . .  25
85	       3.1.29. In Appendix C.  Relax NG schema . . . . . . . . . . .  26
86	       3.1.30. Use of the term "counter".  . . . . . . . . . . . . .  26
87	       3.1.31. In Section 2.44, <relref> . . . . . . . . . . . . . .  27
88	       3.1.32. In Section 2.66, <xref> . . . . . . . . . . . . . . .  27
89	       3.1.33. Contributor names . . . . . . . . . . . . . . . . . .  27
90	     3.2.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  28
91	       3.2.1.  New Section 5.1.6, Attribute validation . . . . . . .  28
92	       3.2.2.  In Section 5.2.6, Attribute Default Value
93	               Insertion . . . . . . . . . . . . . . . . . . . . . .  28
94	       3.2.3.  In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  29
95	     3.3.  Some attributes should have value type xsd:ID . . . . . .  29

97	   4.  Non-Schema Issues . . . . . . . . . . . . . . . . . . . . . .  29
98	     4.1.  RFC 7991  . . . . . . . . . . . . . . . . . . . . . . . .  29
99	       4.1.1.  In Section 2.5.7, "type" Attribute  . . . . . . . . .  29
100	       4.1.2.  New Section 2.8.1: Index  . . . . . . . . . . . . . .  30
101	       4.1.3.  In Section 2.17, <date> . . . . . . . . . . . . . . .  30
102	       4.1.4.  In Section 2.40.1, "anchor" Attribute . . . . . . . .  32
103	       4.1.5.  In Section 2.48.4, "type" Attribute . . . . . . . . .  32
104	       4.1.6.  In Appendix A.1.1: TLP switch-over date
105	               discrepancies . . . . . . . . . . . . . . . . . . . .  32
106	       4.1.7.  In Appendix B.2.1: Generation of PN numbers . . . . .  33
107	     4.2.  RFC 7992  . . . . . . . . . . . . . . . . . . . . . . . .  33
108	       4.2.1.  In Section 5.1, IDs . . . . . . . . . . . . . . . . .  33
109	       4.2.2.  In Section 6.2, Root Element  . . . . . . . . . . . .  34
110	       4.2.3.  In Section 6.4, Page Headers and Footers  . . . . . .  34
111	       4.2.4.  In Section 6.5, Document Information  . . . . . . . .  35
112	       4.2.5.  In Section 8.1.1, Index Contents  . . . . . . . . . .  35
113	       4.2.6.  Inconsistent use of "s-", "n-" and User-Supplied "id"
114	               Attributes  . . . . . . . . . . . . . . . . . . . . .  36
115	       4.2.7.  In Section 9.2, <address> . . . . . . . . . . . . . .  36
116	       4.2.8.  In Section 9.7.2, Authors of this Document  . . . . .  37
117	       4.2.9.  In Section 9.7.3, Authors of References . . . . . . .  38
118	       4.2.10. In Section 9.16, <cref> . . . . . . . . . . . . . . .  38
119	       4.2.11. In Section 9.24, <eref> . . . . . . . . . . . . . . .  38
120	       4.2.12. In Section 9.25, <figure> . . . . . . . . . . . . . .  38
121	       4.2.13. In Section 9.27, <iref> . . . . . . . . . . . . . . .  38
122	       4.2.14. In Section 9.33, <note> . . . . . . . . . . . . . . .  39
123	       4.2.15. In Section 9.34, <ol> . . . . . . . . . . . . . . . .  39
124	       4.2.16. In Section 9.35, <organization> . . . . . . . . . . .  39
125	       4.2.17. In Section 9.36, <phone>  . . . . . . . . . . . . . .  39
126	       4.2.18. In Section 9.37, <postal> . . . . . . . . . . . . . .  39
127	       4.2.19. In Section 9.40, <reference>  . . . . . . . . . . . .  40
128	       4.2.20. In Section 9.41, <referencegroup> . . . . . . . . . .  41
129	       4.2.21. In Section 9.42, <references> . . . . . . . . . . . .  41
130	       4.2.22. In Section 9.54, <table>  . . . . . . . . . . . . . .  41
131	       4.2.23. In Section 9.56, <td> . . . . . . . . . . . . . . . .  41
132	       4.2.24. In Section 9.58, <th> . . . . . . . . . . . . . . . .  42
133	       4.2.25. In Section 9.60, <title>  . . . . . . . . . . . . . .  42
134	       4.2.26. In Section 9.66, <xref> . . . . . . . . . . . . . . .  42
135	       4.2.27. In Section 9.18, <dd> . . . . . . . . . . . . . . . .  43
136	     4.3.  RFC 7994  . . . . . . . . . . . . . . . . . . . . . . . .  43
137	       4.3.1.  Additional Guidance . . . . . . . . . . . . . . . . .  43
138	     4.4.  RFC 7998  . . . . . . . . . . . . . . . . . . . . . . . .  43
139	       4.4.1.  In Section 5.2.3, <date> Insertion  . . . . . . . . .  44
140	       4.4.2.  In Section 5.2.4, "prepTime" Insertion  . . . . . . .  44
141	       4.4.3.  In Section 5.2.6, Attribute Default Value
142	               Insertion . . . . . . . . . . . . . . . . . . . . . .  44
143	       4.4.4.  In Section 5.2.7, "toc" Attribute . . . . . . . . . .  45
144	       4.4.5.  In Section 5.2.8, "removeInRFC" Warning Paragraph . .  45
145	       4.4.6.  In Section 5.3.1, "month" Attribute . . . . . . . . .  45
146	       4.4.7.  In Section 5.3.2, ASCII Attribute Processing  . . . .  46
147	       4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation . . .  46
148	       4.4.9.  In Section 5.4.2, <boilerplate> Insertion: Only for
149	               RFCs? . . . . . . . . . . . . . . . . . . . . . . . .  47
150	       4.4.10. In Section 5.4.2, <boilerplate> Insertion: Error
151	               Message . . . . . . . . . . . . . . . . . . . . . . .  47
152	       4.4.11. In Section 5.4.2.1, Compare submissionType and
153	               <seriesInfo> "stream".  . . . . . . . . . . . . . . .  48
154	       4.4.12. In Section 5.4.2.2, "Status of this Memo"
155	               Insertion . . . . . . . . . . . . . . . . . . . . . .  48
156	       4.4.13. In Section 5.4.3, <reference> "target" Insertion  . .  48
157	       4.4.14. In Section 5.4.4, <name> Slugification  . . . . . . .  49
158	       4.4.15. In Section 5.4.6, "pn" Numbering. . . . . . . . . . .  49
159	       4.4.16. In Section 5.4.7, <iref> Numbering  . . . . . . . . .  51
160	       4.4.17. In Section 5.4.8.1, "derivedContent" Insertion (with
161	               Content)  . . . . . . . . . . . . . . . . . . . . . .  51
162	       4.4.18. In Section 5.4.8.2, "derivedContent" Insertion (without
163	               Content)  . . . . . . . . . . . . . . . . . . . . . .  52
164	       4.4.19. In Section 5.5.1, <artwork> Processing  . . . . . . .  52
165	       4.4.20. In Section 5.5.2, <sourcecode> Processing . . . . . .  53
166	       4.4.21. In Section 5.4.8.2, "derivedContent" Insertion. . . .  53
167	       4.4.22. In Section 5.4.9, <relref> Processing . . . . . . . .  54
168	       4.4.23. New Section 5.4.10, Unused Reference Warnings . . . .  54
169	       4.4.24. New Section 5.4.11, Index Insertion . . . . . . . . .  54
170	       4.4.25. In Section 5.6.3, <link> Processing . . . . . . . . .  55
171	   5.  Possible New Work . . . . . . . . . . . . . . . . . . . . . .  55
172	     5.1.  Inline and Display Math . . . . . . . . . . . . . . . . .  55
173	     5.2.  Change Bars . . . . . . . . . . . . . . . . . . . . . . .  56
174	     5.3.  Element Nesting . . . . . . . . . . . . . . . . . . . . .  56
175	     5.4.  Schema Consistency  . . . . . . . . . . . . . . . . . . .  57
176	   6.  Security Considerations . . . . . . . . . . . . . . . . . . .  57
177	   7.  Informative References  . . . . . . . . . . . . . . . . . . .  57
178	   Appendix A.  Proposed new sections in RFC 7991 bis  . . . . . . .  59
179	     A.1.  <u> . . . . . . . . . . . . . . . . . . . . . . . . . . .  59
180	       A.1.1.  Expansion of simplified <u> format specifications . .  59
181	       A.1.2.  Non-simplified <u> format specifications  . . . . . .  61
182	       A.1.3.  Split expansion of <u> elements . . . . . . . . . . .  61
183	     A.2.  <rendering> . . . . . . . . . . . . . . . . . . . . . . .  64
184	   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  65

186	1.  Introduction

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

193	   *  An XML converter from vocabulary version 2 [RFC7749] to version 3
194	      [RFC7991]

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

198	   *  An XML to plain text converter [RFC7994] for the version 3
199	      vocabulary

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

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

207	   During the implementation work, a number of issues with the
208	   specification has been found (this was expected at the outset by all
209	   parties) and a number of observations has been made about limitations
210	   of the specification and vocabulary version 3 schema, and also
211	   limitations in the specification of the work to be done.

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

216	   When this memo says 'the current version of xml2rfc', it refers to
217	   the latest release of the xml2rfc processor available from the PyPi
218	   package repository (https://pypi.org/pypi/xml2rfc) at the date this
219	   document was published, as given above.

221	1.1.  Current Status

223	   For most of the issues listed in this document, a resolution is now
224	   (14 Jul 2020, "draft-levkowetz-xml2rfc-v3-implementation-notes-11")
225	   available.  For most issues where the resolution imply changes
226	   compared with the published specifications, the changes have been
227	   made over time, and are available in the released "xml2rfc".
228	   However, some issues remain:

230	   *  Separation of type and content for <artwork>, Section 3.1.3:
231	      The implementation only recognises type values that are related to
232	      the format of the artwork, for instance "svg" and "ascii-art", but
233	      no attribute has been designated to hold content types, such as
234	      "call-flow".  We can either simply narrow the description of the
235	      "type" attribute of <artwork>, and eliminate the support for
236	      content labelling, or add a new attribute.

238	   *  Introduction of a "bullet" attribute for <ul> Section 3.1.10.1.
239	      This would let us get rid of the awkward "bare" attribute that was
240	      introduced to make unindented lists possible, something that was
241	      needed by the RPC; and would be a much more general solution.

243	   *  Simplification of mixed-content elements, Section 3.1.10.2.
244	      Confusion about when you have to use a sequence of <t> elements
245	      within for instance <li> elements, and when you can use bare text,
246	      keeps coming up as a point of confusion from users on the mailing
247	      lists.  Being able to omit the wrapping of text in <t> in some
248	      cases is a small convenience that doesn't make up for the
249	      confusion caused by the mixed content model.

251	   *  Deprecation of the new "quoteTitle", keep original "quote-title",
252	      Section 3.1.14.

254	   *  Official deprecation of the new <seriesInfo> attributes,
255	      Section 3.1.21.  Implementing this, and reverting to v2 behaviour
256	      would permit better error messages and would simplified
257	      documentation and usage no end.  Currently <seriesInfo> instances
258	      in references are moved fr

260	   *  Permitting "keepWithNext" on all elements that can be siblings to
261	      <t>, in order to make it useful also for other child elements of
262	      <section>, Section 3.1.23.1.  Not being able to set "keepWithNext"
263	      on other child elements of <section> than <t> repeatedly comes up
264	      as an issue preventing better page break handlinng when generating
265	      PDFs.  (There are also issues with the WeasyPrint engine in this
266	      area, but not having general "keepWithNext" support makes the
267	      issue harder than need be).

269	   *  Permitting an "asciiAbbrev" attribute for <title>,
270	      Section 3.1.12.1, to match the "ascii" attribute for the non-
271	      abbreviated title.

273	2.  Fitness for Purpose

275	   The introduction to [RFC7991] states:

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

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

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

294	2.1.  Degraded Table of Contents

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

305	   Proposal:  Add support for pagination in a future version of the text
306	      formatter.

308	   Implementation:  The current implementation provides pagination for
309	      drafts.  The pagination can be turned off with an option switch.
310	      Text/plain output for RFCs is always generated without pagination.

312	   Heather's indication 20 Jul 2019:  OK for IDs but default should not
313	      change for RFCs

315	2.2.  RFC Publication Date Policy

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

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

328	   Implementation:  The current version of xml2rfc does not enforce the
329	      requirement that all three <date> elements are present in RFC
330	      mode, but leaves up to author and RPC (RFC Production Center)
331	      staff to insert day information as appropriate.

333	   Heather's indication 20 Jul 2019:  Desired behaviour is to be able to
334	      publish with or without exact date.

336	3.  Schema Issues

338	3.1.  RFC 7991

340	3.1.1.  Before Section 2.5: <artset>

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

350	   In order to be able to more easily deal with alternative instances of
351	   artwork, and in the future possibly deal smoothly with a wider number
352	   of alternative artwork formats than is currently provided for, a new
353	   element <artset> could be introduced, presenting a set of alternative
354	   artwork executions.  This would let the renderer pick the most
355	   appropriate <artwork> instance for its format from the alternatives
356	   present within an <artset> element, based on the "type" attribute of
357	   each enclosed <artwork> element.

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

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

372	         artset =
373	           element artset {
374	             attribute xml:base { text }?,
375	             attribute xml:lang { text }?,
376	             attribute anchor { xsd:ID }?,
377	             attribute pn { xsd:ID }?,
378	             artwork+
379	           }

381	      The <artset> element can occur anywhere an <artwork> element can
382	      occur.  The first anchor on an <artwork> element within an
383	      <artset> element will be promoted to the <artset> element if it
384	      has none; apart from that, anchors on <artwork> elements within an
385	      <artset> element will be removed by the preptool.

387	   Heather's indication 20 Jul 2019:  OK

389	3.1.2.  In Section 2.5.5, "name" Attribute

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

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

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

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

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

407	   Heather's indication 20 Jul 2019:  OK on resolution

409	   This issue is tracked as github issue #36 (https://github.com/rfc-
410	   format/draft-iab-xml2rfc-v3-bis/issues/36)

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

414	   The text lists a number of preferred values, but does not indicate
415	   how these are to be used, or what to do with other values.  In
416	   particular, the default value is "" (i.e., empty) -- should this
417	   cause a warning or error, or any other action?  If not, how should
418	   'preferred' be understood?
419	   Additionally, according to Section 5.1 of RFC 7991, any text content
420	   serves as ascii-art fallback in case the rendering format cannot
421	   render the content that the 'src' attribute indicates.  But in that
422	   case, it seems that the "type" attribute should apply exclusively to
423	   the content that the "src" attribute points at.  This should be
424	   clarified in the text.

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

431	   *  "svg" seems to describe a format

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

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

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

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

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

446	      For values like "call-flow" and "hex-dump", add a different
447	      attribute to describe the artwork content.  Do not conflate the
448	      artwork description with the artwork format given in the "type"
449	      attribute.

451	   Implementation:  The current implementation uses the "type" attribute
452	      to determine how to process the "src" attribute.  Handling exists
453	      for the values "svg", "binary-art", and "ascii-art".  The idnits
454	      rewrite warns if type has any value other than "svg", "binary-
455	      art", or "ascii-art".

457	      As of version 2.19.0 of xml2rfc, the conflict between the type
458	      that the "src" attribute points at, and any ascii-art fallback has
459	      been removed by introduction of the <artset> element.  A solution
460	      is still needed if it's desired to have an attribute that
461	      describes the content type.

463	   Heather's indication 20 Jul 2019:  OK on the implementation
464	      (accepting only format types, not content types, for the "type"
465	      attribute, and using that to determine which <artwork> to select).

467	3.1.4.  In Section 2.6, <aside>

469	3.1.4.1.  Child element <list>

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

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

477	   Implementation:  Implemented in the current version of xml2rfc.

479	   Heather's indication 20 Jul 2019:  OK

481	3.1.4.2.  Child element <table>

483	   The schema permits <table> inside <aside>, but does not permit
484	   <table> inside <blockquote>.  Lacking any indication of why this is,
485	   it seems reasonable to propose that the schema be adjusted to permit
486	   <table> inside either both or neither.

488	   An added consideration is that appropriate rendering of table headers
489	   and footers across page breaks may be in conflict with rendering of
490	   <table> within <aside> and <blockquote>.

492	   Implementation:  The current implementation (xml2rfc version 2.21.x)
493	      permits <table> inside both <aside> and <blockquote>, but does not
494	      guarantee that <aside>s and <blockquote>s broken across pages will
495	      have new table headers and footers added if a table inside is
496	      split over multiple pages.

498	   Heather's indication 20 Jul 2019:  OK

500	3.1.5.  In Section 2.12, <br>

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

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

512	   Resolution:  After repeated list discussion, the <br> element was
513	      accepted in inline context.

515	      The implementation permits this element as a child element of
516	      blockquote, cref, dd, dt, em, li, name, strong, t, td, th, title,
517	      and tt.

519	   This issue is tracked as github issue #37 (https://github.com/rfc-
520	   format/draft-iab-xml2rfc-v3-bis/issues/37)

522	3.1.6.  In Section 2.20, <dl>

524	   The current specification says:

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

531	   This does not match established typographic terminology.  In
532	   typographic terminology, "hanging indent" describes the case where
533	   the indentation of the second and subsequent lines of a paragraph is
534	   greater than the indentation of the first line.  Whether the
535	   definition in a definition list starts on the first line or not has
536	   nothing to do with the presence of hanging indent; our definition
537	   lists will *always* have hanging indent.

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

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

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

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

555	   This issue is tracked as github issue #38 (https://github.com/rfc-
556	   format/draft-iab-xml2rfc-v3-bis/issues/38)

558	3.1.7.  New Section 2.20.4, "indent" Attribute

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

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

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

575	   Heather's indication on 20 Jul 2019:  OK

577	   This issue is tracked as github issue #39 (https://github.com/rfc-
578	   format/draft-iab-xml2rfc-v3-bis/issues/39)

580	3.1.8.  New Section 2.54.2

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

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

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

596	   Heather's indication 20 Jul 2019:  OK

598	   This issue is tracked as github issue #40 (https://github.com/rfc-
599	   format/draft-iab-xml2rfc-v3-bis/issues/40)

601	3.1.9.  In Section 2.27, <iref>

603	   In HTML5, <span> may not be placed directly inside a table.  RFC 7992
604	   specifies that <iref> should be rendered as a <span>, and also
605	   specifies that <table> is directly rendered as its HTML counterpart.
606	   This results in generating invalid HTML.

608	   Proposal:  Disallow <iref> as a direct child of <table> (but still
609	      permitting it within <th> and <td>).

611	   Implementation:  The current implementation works around this by
612	      moving the <span> outside the <table>.  This is less than ideal.

614	3.1.10.  In Section 2.29, <li>

616	3.1.10.1.  Unordered lists with arbitrary symbols

618	   When <li> is used with <ul empty="true">, the rendering is under-
619	   specified (the specification says 'no label will be shown", but
620	   doesn't say whether list indentation (leading whitespace) should be
621	   eliminated or not.

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

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

633	   Proposal:  Add an explicit "bullet" attribute to support this use
634	      case.

636	   Resolution:  Rejected.

638	   Heather's indication 20 Jul 2019:  OK, makes sense to implement.
639	      That would eliminate the need for the "bare" attribute mentioned
640	      in Section 3.1.25.

642	   This issue is tracked as github issue #45 (https://github.com/rfc-
643	   format/draft-iab-xml2rfc-v3-bis/issues/45)

645	3.1.10.2.  Mixed Content Model

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

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

654	   Resolution:  Rejected.

656	   Heather's indication 20 Jul 2019:  OK

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

661	   This issue is tracked as github issue #46 (https://github.com/rfc-
662	   format/draft-iab-xml2rfc-v3-bis/issues/46)

664	3.1.11.  In Section 2.32, <name>

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

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

673	   Resolution:  Accepted.

675	   This issue is tracked as github issue #47 (https://github.com/rfc-
676	   format/draft-iab-xml2rfc-v3-bis/issues/47)

678	3.1.12.  In Section 2.32, <organization>

680	3.1.12.1.  Missing "asciiAbbrev" Attribute

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

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

690	   Implementation:  The current version of xml2rfc supports
691	      "asciiAbbrev".

693	   Heather's indication 20 Jul 2019:  OK

695	3.1.12.2.  Attribute "showOnFrontPage"

697	   Guidance from the IAB regarding IAB stream documents
698	   (https://www.rfc-editor.org/materials/iab-format.txt) indicates that
699	   "'Each author's name SHOULD be listed without an organization.".  See
700	   also xml2rfc ticket #311
701	   (https://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/311).

703	   In [RFC7991] there is no way to turn on or off the display of
704	   <organization> on the front page, which would be needed for cases
705	   when it is not wanted IAB documents to show such on the front page.
706	   (Cases where display of <organization> is wanted is trivially
707	   supported by the current code).

709	   In order to make it possible to expressly control this for a
710	   vocabulary version 3 XML document, version 2.21.0 of xml2rfc
711	   introduces an attribute "showOnFrontPage", with default value "true".

713	   This issue is tracked as github issue #36 (https://github.com/rfc-
714	   format/draft-iab-xml2rfc-v3-bis/issues/36)

716	   Heather's indication 20 Jul 2019: OK

718	3.1.13.  In Section 2.37, <postal>

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

725	   Unfortunately, it manages to throw the baby out with the bathwater by
726	   constraining postalLine to be used only if none of the other elements
727	   are used.  This makes it impossible to apply hCard [HCARD] labels
728	   (based on vCard [RFC6350] properties) to the elements of an address,
729	   as [RFC7992] requires.  Applying the schema from [RFC7991] would make
730	   country information and hCard tags unavailable for any locality with
731	   a postal address scheme that needs to use <postalLine> because it
732	   does not match the American scheme.  This would make statistics such
733	   as the author origin statistics either miss authors with such
734	   addresses, or make the statistics harder to compile than is
735	   necessary, and make for instance the data on this page skewed:
736	   https://datatracker.ietf.org/stats/document/yearly/continent/
737	   The current implementation maps <postalLine> to the hCard property
738	   "extended-address", and permits it to be used together with other
739	   elements, in particular <country>, <region>, and <city>.  This is a
740	   change to the schema.

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

747	3.1.14.  In Section 2.40.2, "quoteTitle"

749	   The version two xml2rfc processors already support the attribute
750	   "quote-title".  The attribute name change introduces an
751	   incompatibility.  This in particular impacts existing bibxml
752	   reference files, which should work with both version 2 and 3
753	   vocabulary documents.

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

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

762	   Heather's indication 20 Jul 2019:  OK

764	   This issue is tracked as github issue #48 (https://github.com/rfc-
765	   format/draft-iab-xml2rfc-v3-bis/issues/48)

767	3.1.15.  In Section 2.41, <referencegroup>

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

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

777	   Implementation:  Implemented in xml2rfc v 2.18.0

779	   Heather's indication 20 Jul 2019:  OK

781	3.1.16.  In Section 2.42, <references>

783	   The v3 schema cannot properly model multiple reference subsections
784	   contained within one numbered section.  The v2 formatter handled this
785	   by silently inserting an enclosing section, but with the introduction
786	   of the preptool, which in theory should produce a master file from
787	   which various formatters would produce equivalent results, this
788	   becomes troublesome, as the automatic insertion of a container
789	   section is specified for the HTML formatter, in section 9.8. of RFC
790	   7992, but not for the text formatter.  It would be much better to
791	   make the prepped xml explicitly show exactly what should be rendered,
792	   and not rely on formatters silently insert elements.

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

798	   Resolution:  Accepted.

800	   Heather's indication 20 Jul 2019:  OK

802	   This issue is tracked as github issue #49 (https://github.com/rfc-
803	   format/draft-iab-xml2rfc-v3-bis/issues/49)

805	3.1.17.  In Section 2.45.1, "category" Attribute

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

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

813	   Implementation:  The "category" attribute on <rfc> has been kept in
814	      the current version of xml2rfc, but the additional <seriesInfo> is
815	      also generated during v2v3 conversion.  For purposes of
816	      determining the category to render, the attribute on <rfc> is the
817	      one used.

819	   Heather's indication 20 Jul 2019:  OK

821	3.1.18.  In Section 2.45.3, "docName" Attribute

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

828	   Proposal:  Remove this, and keep the "docName" attribute on <rfc>
829	   Implementation:  The "docName" attribute on <rfc> has been kept in
830	      the current version of xml2rfc.

832	   Heather's indication 20 Jul 2019:  OK

834	3.1.19.  In Section 2.45.7, "number" Attribute

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

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

849	   Implementation:  In The current version of xml2rfc, the number
850	      attribute on <rfc> is used to determine whether to produce an RFC
851	      or Internet-Draft.  If <seriesInfo> elements are found, but no
852	      <seriesInfo> with name="RFC" and value set to the number is found,
853	      a warning is given.  If no <seriesInfo> elements are found, the
854	      appropriate elements, including one giving the RFC number, is
855	      inserted.

857	   Heather's indication 20 Jul 2019:  OK

859	3.1.20.  In Section 2.46.2, "numbered" Attribute

861	   The text indicates that only top-level sections may have
862	   numbered="false", and that a section with numbered="false" may not
863	   have a child section with numbered="true".  But that leaves no value
864	   that is valid for child sections of an unnumbered section: They
865	   cannot have numbered="false", since they are not top-level sections,
866	   and they cannot have numbered="true", since the parent has
867	   numbered="false".

869	   Additionally, the prohibition against child sections having
870	   numbered="false" removes the option of truncating the ToC listing for
871	   some child sections; without providing a good explanation for this
872	   limitation, it seems arbitrary and counter-intuitive to disallow this
873	   feature.

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

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

881	   Heather's indication 20 Jul 2019:  OK

883	3.1.21.  In Section 2.47, <seriesInfo>

885	3.1.21.1.  Too many possible combinations

887	   The possible and forbidden combinations of attributes for this
888	   element has now become so convoluted that it's really hard to
889	   understand how to use it correctly.  This needs a serious
890	   reconsideration.  New usages, with the purpose of replacing various
891	   attributes on the <rfc> element, have been added without any
892	   consistent pattern or table of permitted and forbidden combinations
893	   of values and attributes.

895	3.1.21.2.  The "name" Attribute

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

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

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

909	3.1.21.3.  Incompatibility between v2 and v3 schema

911	   The placement of <seriesInfo> elements within <reference> has changed
912	   in the v3 schema, in that it has been pulled into <front>, and the v2
913	   placement has been deprecated.  But this makes 'bibxml' reference
914	   files produced according to the v3 schema incompatible with v2
915	   processors, and would require us to maintain 2 separate quotation
916	   libraries.

918	3.1.21.4.  Inappropriate Introduction of the "stream" Attribute

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

924	   The intention seems to be to deprecate attributes on <rfc>.  However,
925	   these attributes cannot have multiple values for a document, which
926	   makes the move to <seriesInfo>, which can occur multiple times,
927	   dubious.

929	3.1.21.5.  Summary

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

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

943	      Limit the <seriesInfo> element to what is actually needed for use
944	      within <reference/>, and do not add new functionality related to
945	      the document <front>.  Deprecate any functionality not related to
946	      usage within <reference/>.

948	      The easiest approach would be to simply revert to the v2 semantics
949	      and placement of <seriesInfo> elements, with documentation of
950	      that.

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

957	   Heather's indication 20 Jul 2019:  Starred, rewrite needed in order
958	      to simplify and clean this up.

960	3.1.22.  In Section 2.48, <sourcecode>

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

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

971	   Implementation:  Implemented as proposed in the current version of
972	      xml2rfc.

974	   Heather's indication 20 Jul 2019:  OK

976	3.1.23.  In Section 2.53.3 and 2.53.4.

978	3.1.23.1.  Unnecessary limitation on the use of "keepWithNext"

980	   Why keepWithNext only on <t>?  It would be very natural to expect to
981	   be able to say keepWithNext for 2 tables, or 2 figures, or 2 lists,
982	   or combinations thereof?

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

987	   Implementation:  Not in the current version of xml2rfc.

989	   Heather's indication 25 Jul 2019:  OK to implement.

991	3.1.23.2.  Violation of KISS and DRY principles

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

998	   Proposal:  Keep only one of these two attributes, preferably
999	      keepWithNext.

1001	   Implementation:  Not in the current version of xml2rfc.

1003	   Heather's indication 20 Jul 2019:  Undecided

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

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

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

1019	   One solution to this could be to not try to guess, or establish
1020	   heuristics, but instead use a v3 schema element with preptool
1021	   validation to ensure a straightforward solution to all the issues, as
1022	   follows:

1024	   Proposal: Limit the arbitrary placement of Unicode characters and
1025	   strings in the body of a document, and control the expansion of the
1026	   Unicode code-points by requiring that Unicode characters and strings
1027	   be placed within a specific element if they are to occur in the body
1028	   of a document.  Such an expansion is already mandated by Section 3.4
1029	   of [RFC7997]; but without schema support, it would be very hard for
1030	   tools to enforce this.  The text in Appendix A.1 is proposed for
1031	   inclusion in RFC 7991-bis as a new section.

1033	   Proposal:  Limit the arbitrary placement of Unicode characters and
1034	      strings in the body of a document, and control the expansion of
1035	      the Unicode code-points by requiring that Unicode characters and
1036	      strings be placed within a specific element if they are to occur
1037	      in the body of a document.  Such an expansion is already mandated
1038	      by Section 3.4 of [RFC7997]; but without schema support, it would
1039	      be very hard for tools to enforce this.  The text in Appendix A.1
1040	      is proposed for inclusion in RFC 7991-bis as a new section.

1042	   Implementation:  Implemented as described in Appendix A.1.

1044	   Heather's indication 20 Jul 2019:  Isn't this already required by
1045	      7997??

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

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

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

1059	   Proposal:  Specify that in text output, <ul empty="true"> should be
1060	      rendered without any bullet and indentation.  In order to produce
1061	      unordered lists that are indented, the "bullet" attribute
1062	      mentioned in Section 3.1.10 with a whitespace bullet could be
1063	      used.

1065	   Heather's indication 25 Jul 2019:  OK
1066	   Implementation:  The current version of xml2rfc introduces a new
1067	      attribute "bare" with the possible values "false" | "true" to
1068	      signal this.  The default is "true" (which differs from the
1069	      default v2 implementation).  Using the extra attribute "bare"
1070	      works, but is maybe clumsier than necessary.

1072	   Heather's indication 25 Jul 2019:  Questionable (see Section 3.1.10.1
1073	      for alternative approach.

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

1077	3.1.26.1.  The "derivedContent" attribute

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

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

1091	   Implementation:  Implemented as proposed.

1093	   Heather's indication 25 Jul 2019:  OK

1095	3.1.26.2.  Referencing a <dl> entry

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

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

1105	   Implementation:  Implemented as proposed.

1107	   Heather's indication 25 Jul 2019:  OK

1109	3.1.26.3.  Combined effects of <xref> text, and the "format" and
1110	           "sectionFormat" attributes.

1112	   If the <relref> functionality is folded into <xref> we are left with
1113	   two format attributes, "format" and "sectionFormat".  We then need to
1114	   clearly specify if and how they interact.  The following approach is
1115	   suggested:

1117	   The "format" attribute should have effect only on the content of the
1118	   internal link to the cited <reference> entry.  If the "sectionFormat"
1119	   attribute has a value of "bare", which does not cause any internal
1120	   link to be rendered, the "format" attribute has no effect (or,
1121	   possibly, is disallowed).

1123	   The "sectionFormat" attribute should have effect only on the
1124	   rendering of the external link part.  There is no "derivedSection"
1125	   attribute to match the "derivedFormat" attribute, the "section"
1126	   attribute value is used in combination with the "sectionFormat" value
1127	   when rendering the external link.

1129	   If an <xref> element with a "section" attribute value has text
1130	   content, the text content is only used in the rendering of the
1131	   internal link to the cited <reference>, with one exception: If the
1132	   "sectionFormat" attribute value is "bare", then the <xref> text
1133	   content is used to render a second external link in parentheses,
1134	   after the initial external link that shows the external section
1135	   number.

1137	3.1.27.  In Section 3.3, <format>

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

1147	   Heather's indication on 25 Jul 2019: Detailed proposal needed.

1149	3.1.28.  In Section 3.4.2, "hangIndent" Attribute

1151	      "Deprecated.  Use <dl> instead."

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

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

1161	   Implementation:  Implemented as proposed.

1163	   Heather's indication 25 Jul 2019:  OK

1165	3.1.29.  In Appendix C.  Relax NG schema

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

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

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

1179	   Implementation:  Done in the current version of xml2rfc.

1181	   Heather's indication 25 Jul 2019:  OK

1183	3.1.30.  Use of the term "counter".

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

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

1196	   Proposal:  Instead of "counter", use "number" as the attribute value,
1197	      and explicitly say "Section number, Figure number, Table number or
1198	      ordered list labels" in the description.  Use "-n.n" instead of
1199	      "-nnn".

1201	   Implementation:  Not in the current version of xml2rfc.

1203	   Heather's indication 25 Jul 2019:  Isn't "number" used for something
1204	      else?

1206	3.1.31.  In Section 2.44, <relref>

1208	   (This section is out of order so as to not change the section
1209	   numbering of previous sections while work is onging on a rfc7991bis
1210	   document.)

1212	   The <relref> element has functionality that extends <xref>, and at
1213	   first sight it is hard to distinguish the two.  It would be better to
1214	   remove <relref> and just add section, relative, and displayFormat to
1215	   <xref>.  Maybe change displayFormat to the earlier proposed
1216	   'sectionFormat'.  (This point is also made in Section 4.4.22)

1218	   Proposal:  Deprecate <relref>.

1220	   Implementation:  The current version of xml2rfc converts any
1221	      occurences of <relref> to the equivalent <xref> element.
1222	      Additional warnings about <relref> being deprecated would be in
1223	      order.

1225	3.1.32.  In Section 2.66, <xref>

1227	   (This section is out of order so as to not change the section
1228	   numbering of previous sections while work is onging on a rfc7991bis
1229	   document.)

1231	   The <xref> element permits only plain text content, which limits how
1232	   it can be used with explicit text.  Permitting also <em>, <strong>,
1233	   <sub>, <sup>, and <tt> would make it possible to use the typographic
1234	   expressions permitted in otherwise in running text.  It also makes it
1235	   possible for <toc> entries to reflect these typographic elements.

1237	   Proposal:  Permit <em>, <strong>, <sub>, <sup>, and <tt> to be used
1238	      as children of <xref>

1240	   Implementation:  Implemented in the current version of xml2rfc.

1242	3.1.33.  Contributor names

1244	   (This section is out of order so as to not change the section
1245	   numbering of previous sections while work is onging on a rfc7991bis
1246	   document.)

1248	   One thing that has been repeatedly requested both by the RPC and by
1249	   RFC authors is a way to include contributor information in documents,
1250	   also when the contributor names contain non-ASCII characters.  This
1251	   is applicable also for mention of names and possibly contact details
1252	   of other persons than contributors and authors (even if the
1253	   contributor case is the one that comes up most often).

1255	   Proposal:  Permit a <contact> element to be used to provide name and
1256	      address information for persons that aren't authors.  This will
1257	      allow both non-ASCII and ASCII-equivalence name information to be
1258	      provided and rendered, in much the same way that author
1259	      information is rendered.

1261	   Implementation:  Implemented in the current version of xml2rfc.  The
1262	      <contact> element is allowed in two contexts: As a direct child of
1263	      <section>, where it will be rendered in the same manner that
1264	      author information is rendered in the Authors' Addresses section,
1265	      and as a child of <t>, where it will be rendered inline, in a
1266	      similar manner that author information is rendered in citations.

1268	3.2.  RFC 7998

1270	3.2.1.  New Section 5.1.6, Attribute validation

1272	   Some attribute validation beyond what the schema enforces is possible
1273	   and desirable.  One example of this is to validate that all
1274	   attributes which are expected to have integer values actually does
1275	   so.  A section on this should be added.  The current implementation
1276	   adds integer attribute validation and verification that apart from
1277	   the name attributes of <author>, no attribute values have non-ASCII
1278	   content.

1280	   Heather's indication 25 Jul 2019: Good idea!

1282	3.2.2.  In Section 5.2.6, Attribute Default Value Insertion

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

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

1292	   Implementation:  The current version of xml2rfc removes the default
1293	      value for the "stream" attribute of <seriesInfo> from the schema.
1294	      This is not a problem from a rendering perspecitve, since the
1295	      "stream" attribute does not need to have a value in order for the
1296	      <seriesInfo> to be rendered correctly (most instances of
1297	      <seriesInfo> in the current bibxml library does not have a
1298	      "stream" attribute set).

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

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

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

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

1318	   Heather's indication 25 Jul 2019:  OK

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

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

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

1329	   Implementation:  Implemented in the current version of xml2rfc.

1331	   Heather's indication 25 Jul 2019:  OK

1333	4.  Non-Schema Issues

1335	4.1.  RFC 7991

1337	4.1.1.  In Section 2.5.7, "type" Attribute

1339	4.1.1.1.  How should a "src" attribute be handled when "type" is
1340	          missing.

1342	   The v3 schema does not require the 'type' attribute on <artwork> to
1343	   have a value, which makes sense when there's no <artwork> 'src'
1344	   attribute to include.  But if there is a 'src' attribute, but no
1345	   value for 'type', how should the 'src' value be handled?
1346	   The easiest and most explicit handling would be to require a 'type'
1347	   value if there is a 'src' attribute; a more doubtful alternative
1348	   would be to use something like the Linux file magic command to try to
1349	   guess at the content type that 'src' points at.

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

1354	   Implementation:  The current version of xml2rfc implements this as
1355	      proposed.

1357	   Heather's indication 25 Jul 2019:  OK

1359	4.1.1.2.  Missing information on how to handle various types

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

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

1373	   Heather's indication 25 Jul 2019: TODO

1375	4.1.2.  New Section 2.8.1: Index

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

1380	   Proposal:  Please provide specification.

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

1386	   Heather's indication 25 Jul 2019:  TODO

1388	4.1.3.  In Section 2.17, <date>

1390	4.1.3.1.  Current Date Requirement
1391	      "When the prep tool is used to create Internet-Drafts, it will
1392	      reject a submitted Internet-Draft that has a <date> element in the
1393	      boilerplate for itself that is anything other than today."

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

1404	   Proposal:  Remove the section.

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

1410	   Heather's indication 25 Jul 2019:  OK

1412	4.1.3.2.  Date Specification in References

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

1420	   The text regarding prose text for month and year in bibliographic
1421	   references is not workable.  How should month and year be combined?
1422	   Some bibliographic references may have date text which requires year
1423	   first, others year last, and so on.  Mixing the described fuzziness
1424	   into the otherwise strict year, month, date format makes little sense
1425	   when the result of combining the year, month and date attributes
1426	   cannot be predictably and correctly rendered.

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

1433	   Implementation:  The current version of xml2rfc permits the <date>
1434	      element to have text content, as an alternative to year, month,
1435	      and day attributes.

1437	4.1.4.  In Section 2.40.1, "anchor" Attribute

1439	   Section 5.1 of RFC 7992 says in part:

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

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

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

1451	   Heather's indication 25 Jul 2019:  OK

1453	4.1.5.  In Section 2.48.4, "type" Attribute

1455	   Section 5.1 of RFC 7992 says in part:

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

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

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

1467	   Heather's indication 25 Jul 2019:  OK

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

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

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

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

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

1488	   Proposal:  Correct the dates given in the document to indicate the
1489	      official dates, and correct the text on placement of TLP to match
1490	      actual usage.

1492	   Implementation:  The current version of xml2rfc uses the official
1493	      dates during the preptool processing, not the dates given in RFC
1494	      7991.

1496	   Heather's indication 25 Jul 2019:  OK

1498	4.1.7.  In Appendix B.2.1: Generation of PN numbers

1500	   The current specification says:

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

1507	   However, this will result in counting up the part numbers for
1508	   invisible parts, when numbered elements are contained within
1509	   enclosing numbered block elements.

1511	   The current implementation instead uses the same "pn" numbering
1512	   scheme as Julian Reschke's vocabulary v3 XSLT processor, where both
1513	   the section number part and the relative position within the section
1514	   has hierarchical numbering.  For instance, the second element in
1515	   Section 2.1 would have a pn number of "section-2.1-2", and assuming
1516	   it is a dl element, the first dt element within the dl in Section 2.1
1517	   would have a pn number of "section-2.1-2.1".

1519	4.2.  RFC 7992

1521	4.2.1.  In Section 5.1, IDs

1523	   The current specification says:

1525	      HTML elements that are generated from XML elements that include an
1526	      "anchor" attribute will use the value of the "anchor" attribute as
1527	      the value of the "id" attribute of the corresponding HTML element.
1528	      The prep tool produces XML with "anchor" attributes in all
1529	      elements that need them.  Some HTML constructs (such as <section>)
1530	      will use multiple instances of these identifiers.

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

1536	4.2.2.  In Section 6.2, Root Element

1538	   Typo:

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

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

1544	4.2.3.  In Section 6.4, Page Headers and Footers

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

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

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

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

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

1566	      The current implementation insteads adds CSS that explicitly sets
1567	      the header and footer text to the desired values.

1569	   Heather's indication 25 Jul 2019:  Rewrite needed

1571	4.2.4.  In Section 6.5, Document Information

1573	   This information seems to be scrambled and incomplete.  It suggests
1574	   the use of 'Status:' for what is otherwise called 'Category:'.  It
1575	   simplifies the presentation of series information to the point that
1576	   no clue is given of how to handle the two bits of information related
1577	   to series name and series number -- the example shows 'Series:'
1578	   'Internet-Draft', which gives no guidance at all.  There is no
1579	   mention of whether to display 'Obsoletes:' and 'Updates:' information
1580	   or not.

1582	   On a more general note, this is the second section where an
1583	   incomplete example is provided instead of specification.  Examples
1584	   are however not replacements for proper specification; they are at
1585	   best a help in making a specification real to the user.  Both this
1586	   section and Section 4.2.3 needs to be expanded to provide a complete
1587	   specification.

1589	   Styling query: The example gives the style of the element that holds
1590	   author initials the class 'initial' while the attribute is
1591	   appropriately named 'initials'.  Is the difference in attribute and
1592	   style names intentional?  In any case, 'initials' would be more
1593	   appropriate.

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

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

1604	   Heather's indication 25 Jul 2019:  Rewrite needed

1606	4.2.5.  In Section 8.1.1, Index Contents

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

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

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

1626	   Implementation:  The implementation consistently transfers the
1627	      "slugifiedName" attribute on <name> to an "id" attribute on the
1628	      <h2> or other header element generated from the name.
1629	      Section numbers ("s-" or "section-" values) from "pn" attributes
1630	      are consistently transferred to the <section>, <p> or other HTML
1631	      element generated from the XML element on which they appear.
1632	      User-supplied "anchor" attributes on XML elements are consistently
1633	      transferred to a <div> inside the HTML element generated from the
1634	      XML element with the anchor, encapsulating the content generated
1635	      from the XML element.

1637	4.2.7.  In Section 9.2, <address>

1639	   The example reiterates an abbreviated form of the xml given under
1640	   <author>, as if there was no difference between the rendering of
1641	   <address> and <author>.  Furthermore, the example shows only
1642	   rendering of elements which are _not_ part of <address>; any
1643	   rendering of the elements contained within <address> is omitted.
1644	   This is misleading, in particular since rendering of the individual
1645	   child elements (<postal>, <phone> , <facsimile> , <email>, and <uri>)
1646	   _has_ been specified to have explicit renderings.

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

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

1658	   This is the mapping used by xml2rfc from the address fields to hCard
1659	   properties:

1661	        +====================+=================+==================+
1662	        | i18n address field | xml2rfc element | hCard property   |
1663	        +====================+=================+==================+
1664	        | -                  | <extaddr>       | extended-address |
1665	        +--------------------+-----------------+------------------+
1666	        | street_address     | <street>        | street-address   |
1667	        +--------------------+-----------------+------------------+
1668	        | sorting_code       | <sortingcode>   | postal-code      |
1669	        +--------------------+-----------------+------------------+
1670	        | postal_code        | <code>          | postal-code      |
1671	        +--------------------+-----------------+------------------+
1672	        | city_area          | <cityarea>      | locality         |
1673	        +--------------------+-----------------+------------------+
1674	        | city               | <city>          | locality         |
1675	        +--------------------+-----------------+------------------+
1676	        | country_area       | <region>        | country-area     |
1677	        +--------------------+-----------------+------------------+
1678	        | country_name       | <country>       | country-name     |
1679	        +--------------------+-----------------+------------------+
1680	        | -                  | <pobox>         | post-office-box  |
1681	        +--------------------+-----------------+------------------+

1683	                                  Table 1

1685	4.2.8.  In Section 9.7.2, Authors of this Document

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

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

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

1701	   Furthermore, the document also says:

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

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

1714	4.2.9.  In Section 9.7.3, Authors of References

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

1719	4.2.10.  In Section 9.16, <cref>

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

1728	4.2.11.  In Section 9.24, <eref>

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

1736	4.2.12.  In Section 9.25, <figure>

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

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

1748	4.2.13.  In Section 9.27, <iref>

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

1753	4.2.14.  In Section 9.33, <note>

1755	   Typo: s/"yes"/"true"/

1757	4.2.15.  In Section 9.34, <ol>

1759	   The <ol> element has no "style" attribute.  The implementation
1760	   assumes "type" instead.

1762	4.2.16.  In Section 9.35, <organization>

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

1770	4.2.17.  In Section 9.36, <phone>

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

1777	4.2.18.  In Section 9.37, <postal>

1779	   The current specification says:

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

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

1790	   The specification continues to enforce American postal address
1791	   structure on addresses that don't use <postalLine>.  This has been
1792	   changed in the current implementation; instead of using the fixed
1793	   American layout for all countries, the formatting has been adapted to
1794	   use country-specific formatting for all recognised country names and
1795	   codes.

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

1802	4.2.19.  In Section 9.40, <reference>

1804	4.2.19.1.  Misleading example

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

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

1820	4.2.19.2.  Anchor handling disregards <displayreference>

1822	   There is no mention in the description of the HTML rendering of
1823	   <reference> of the effects of <displayreference>, which definitely
1824	   needs to be considered.  Emitting the original anchor value from the
1825	   reference entry (which often comes from the bibxml reference library)
1826	   would make the emitted reference labels wrong when there is a
1827	   <displayreference> entry for the reference.  The most straightforward
1828	   approach would be to add an attribute "derivedAnchor" to <reference>
1829	   and have the preptool set it.

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

1835	   Implementation:  Implemented as proposed.

1837	4.2.19.3.  Handling of author lists in <reference> is under-specified

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

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

1853	   The current implementation follows RFC 7997 in this respect, not RFC
1854	   7992.

1856	4.2.20.  In Section 9.41, <referencegroup>

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

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

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

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

1871	4.2.21.  In Section 9.42, <references>

1873	   The specification says that this is to be rendered as a <section>.
1874	   However, if <reference>s and <referencegroup>s are to be rendered as
1875	   <dt>, <dd>, then this element needs to be rendered as <section> <dl>
1876	   ... </dl> </section>

1878	4.2.22.  In Section 9.54, <table>

1880	   RFC 7992 says: "This element is directly rendered as its HTML
1881	   counterpart."

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

1887	4.2.23.  In Section 9.56, <td>

1889	   RFC 7992 says: "This element is directly rendered as its HTML
1890	   counterpart."
1891	   However, that is not correct.  An appropriate style class needs to be
1892	   inserted to honour the "align" attribute.  The classes "alignLeft",
1893	   "alignCenter", and "alignRight" of the provided CSS are geared
1894	   towards block alignment; here text alignment is needed.  The current
1895	   implementation uses "text-left", "text-center", and "text-right", and
1896	   provides appropriate CSS entries.  (These attribute names matches the
1897	   equivalent bootstrap names.)

1899	4.2.24.  In Section 9.58, <th>

1901	   RFC 7992 says: "This element is directly rendered as its HTML
1902	   counterpart."

1904	   However, that is not correct.  An appropriate style class needs to be
1905	   inserted to honour the "align" attribute.  The classes "alignLeft",
1906	   "alignCenter", and "alignRight" of the provided CSS are geared
1907	   towards block alignment; here text alignment is needed.  The current
1908	   implementation uses "text-left", "text-center", and "text-right", and
1909	   provides appropriate CSS entries.  (These attribute names matches the
1910	   equivalent bootstrap names.)

1912	4.2.25.  In Section 9.60, <title>

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

1917	4.2.26.  In Section 9.66, <xref>

1919	   The specification says:

1921	      ... If the "format" attribute has the value "default", and the
1922	      "target" attribute points to a <reference> or <referencegroup>
1923	      element, then the generated <a> element is surrounded by square
1924	      brackets in the output.

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

1935	4.2.27.  In Section 9.18, <dd>

1937	   (This section is out of order so as to not change the section
1938	   numbering of previous sections while work is onging on a rfc7991bis
1939	   document.)

1941	   The text does not mention pilcrow insertion.  Having pilcrows on
1942	   other list items, but not on this one turns out to be surprising to
1943	   users.  Applying the same text about pilcrow insertion as for other
1944	   list entries seems indicated: "If there is no contained element that
1945	   has a pilcrow (Section 5.2) attached, a pilcrow is added."

1947	4.3.  RFC 7994

1949	4.3.1.  Additional Guidance

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

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

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

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

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

1964	   *  Guidance for <eref> rendering.  In the HTML formatter, handling of
1965	      <eref> is straightforward and is specified; it simply translates
1966	      to an external link.  In the legacy text formatter, <eref> was
1967	      handled by inserting an extra <references> subsection called
1968	      "URLs", and adding reference entries for the URLs there, while the
1969	      <eref> citation point got a trailing numeric reference number.
1970	      With the preptool output becoming the authoritative published
1971	      document, this difference won't be reflected in the xml.  The two
1972	      formats would be more aligned if the text formatter renders <eref>
1973	      URLs inline.

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

1979	      Implementation:  Implemented in the current version of xml2rfc.

1981	4.4.  RFC 7998
1982	4.4.1.  In Section 5.2.3, <date> Insertion

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

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

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

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

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

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

2007	4.4.2.  In Section 5.2.4, "prepTime" Insertion

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

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

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

2020	4.4.3.  In Section 5.2.6, Attribute Default Value Insertion

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

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

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

2035	   Implementation:  Not in the current version of xml2rfc.

2037	4.4.4.  In Section 5.2.7, "toc" Attribute

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

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

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

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

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

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

2065	   Proposal:  Maybe place default setting after all potential element
2066	      insertions have taken place.

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

2074	4.4.6.  In Section 5.3.1, "month" Attribute
2075	      "Normalise the values of "month" attributes in all <date> elements
2076	      in <front> elements in <rfc> elements to numeric values."

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

2083	   Proposal:  Clarify the text.

2085	4.4.7.  In Section 5.3.2, ASCII Attribute Processing

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

2091	   Proposal:  Change the title 'ASCII Attribute Processing' to refer
2092	      correctly to the "ascii" attribute: '"ascii" Attribute
2093	      Processing'.

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

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

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

2103	   Implementation:  Implemented in the current version of xml2rfc.

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

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

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

2115	   Implementation:  Implemented as proposed.

2117	4.4.8.  New Section 5.3.4: "keepWithNext" Normalisation

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

2124	   Implementation:  Not in the current version of xml2rfc.

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

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

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

2140	   Proposal:  The boilerplate-element insertion parts of 5.4.2 should be
2141	      done in both RFC and draft mode, with the appropriate boilerplate
2142	      for each case.  For consistency, either add text to describe the
2143	      appropriate boilerplate for drafts, or remove the sections
2144	      specific to RFC boilerplate.

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

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

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

2160	   Proposal:  If existing boilerplate is found, issue a warning and
2161	      replace it.

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

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

2174	4.4.11.  In Section 5.4.2.1, Compare submissionType and <seriesInfo>
2175	         "stream".

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

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

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

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

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

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

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

2210	   Implementation:  The current version of xml2rfc looks at
2211	      "submissionType", "category", and "consensus" on the <rfc>
2212	      element.

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

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

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

2222	   In the formatter, the order of <seriesInfo> determines the rendering
2223	   order.  The insertion should probably be done in the desired
2224	   rendering order.

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

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

2234	4.4.14.  In Section 5.4.4, <name> Slugification

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

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

2241	   Implementation:  Implemented as proposed in the current version of
2242	      xml2rfc.

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

2248	   *  remove non-ascii letters

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

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

2256	   Proposal:  Do slugification and uniqueness enforcement as described
2257	      above.

2259	   Implementation:  As described above.

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

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

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

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

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

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

2283	   Implementation:  Implemented as proposed in the current version of
2284	      xml2rfc.

2286	4.4.15.1.  RFC format anchors / fragment identifiers

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

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

2303	   Proposal:  Update the RFC 7998 preptool to use these prefixes,
2304	      instead:

2306	      *  "section-xxx"

2308	      *  "figure-xxx"

2310	      *  "table-xxx"

2312	      *  "appendix-xxx"

2314	      *  "index-xxx"
2315	      *  "para-xxx"

2317	      *  "name-xxx"

2319	   Implementation:  Implemented as above in the current version of
2320	      xml2rfc.

2322	4.4.16.  In Section 5.4.7, <iref> Numbering

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

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

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

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

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

2344	   This section is problematic.  It says:

2346	      For each <xref> element that has content, fill the
2347	      "derivedContent" with the element content, having first trimmed
2348	      the whitespace from ends of content text.  Issue a warning if the
2349	      "derivedContent" attribute already exists and has a different
2350	      value from what was being filled in.

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

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

2364	   Implementation:  As of xml2rfc 2.19.0, the expansion of <xref> and
2365	      its variation based on "format" attribute settings has been
2366	      reverted to be more in line with version two, and more regular.
2367	      The attribute setting format="none" is honoured again, and if the
2368	      <xref> element has text content, it is combined with the content
2369	      derived from the format attribute setting, rather than simply
2370	      overriding it, as was the consequence of Section 5.4.8.1 of
2371	      [RFC7998].

2373	      *  Derived content is generated based on the format attribute

2375	      *  If text content is provided, it is shown together with any
2376	         derived content

2378	      *  If the <xref> target is a listed reference, the derived content
2379	         is shown within square brackets

2381	      *  If the <xref> target is not a listed reference , the derived
2382	         content is shown within parentheses if there is text content,
2383	         and without parentheses if not.

2385	      *  If text content is provided, and is identical with the derived
2386	         content, it is ignored.

2388	   This addresses github issue #17 (https://github.com/rfc-format/draft-
2389	   iab-xml2rfc-v3-bis/issues/17).

2391	4.4.18.  In Section 5.4.8.2, "derivedContent" Insertion (without
2392	         Content)

2394	   There's a formatting mistake:

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

2400	4.4.19.  In Section 5.5.1, <artwork> Processing

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

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

2411	   Implementation:  Implemented as proposed in the current version of
2412	      xml2rfc.

2414	4.4.20.  In Section 5.5.2, <sourcecode> Processing

2416	   List item 4 says:

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

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

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

2429	   Implementation:  Implemented as proposed in the current version of
2430	      xml2rfc.

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

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

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

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

2455	   Proposal:  The whole "derivedContent" handling and specification
2456	      needs a thorough rework, with specification of the intended use of
2457	      the attribute by formatters.  Possibly the whole "derivedContent"
2458	      concept should be scrapped, and the rendering left for the
2459	      formatter, depending on the characteristics of the output format.

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

2466	4.4.22.  In Section 5.4.9, <relref> Processing

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

2474	   Proposal:  Deprecate <relref>, and fold the functionality into
2475	      <xref>.

2477	   Implementation:  The <relref> functionality has been folded into
2478	      <xref>.  As of version 2.20.0, xml2rfc rewrites <relref> to
2479	      <xref>, with "displayFormat" changed to "sectionFormat".

2481	4.4.23.  New Section 5.4.10, Unused Reference Warnings

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

2488	4.4.24.  New Section 5.4.11, Index Insertion

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

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

2500	   Proposal:  Insert the XML necessary to render the index into the
2501	      prepped XML.

2503	   Implementation:  Implemented as proposed in the current version of
2504	      xml2rfc.

2506	4.4.25.  In Section 5.6.3, <link> Processing

2508	4.4.25.1.  Using docName to generate convertedFrom

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

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

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

2520	   Implementation:  Implemented as proposed in the current version of
2521	      xml2rfc.

2523	4.4.25.2.  Invalid "rel" values.

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

2531	5.  Possible New Work

2533	5.1.  Inline and Display Math

2535	   Various people have repeatedly asked for better provisions for using
2536	   math in drafts.  A number of different cases seems to be mentioned,
2537	   listed roughtly in order of complexity:

2539	   1.  Ability to use individual math symbols in running text

2541	   2.  Ability to insert math equations in running text

2543	   3.  Ability to display complex math as figures
2544	   Not surprisingly, these 3 use cases correspond quite well to the 3
2545	   modes the TeX typesetting system uses when considering math.  In text
2546	   mode, individual math symbols may be inserted in running text; in
2547	   inline math mode, equations can be built, but will be displayed
2548	   inline with preceding and following text (but can still display
2549	   content that does not otherwise fit on a single line, such as a
2550	   fraction, to take a very simple example.  In display math mode,
2551	   equations will be displayed on a separate line (or multiple lines).

2553	   One possible approach to integrating the second and third case above
2554	   in IETF documents rendered as HTML and PDF is to add support for
2555	   MathJax [MATH-JAX].

2557	   For the first case, the simplest and most straightforward approach
2558	   would be to extend the permitted range of unicode code-points in
2559	   running body text from permitting ASCII only (unless enclosed in <u>
2560	   elements) to permit ASCII and code-points in the 'Mathematical
2561	   Operators' and 'Supplementary Mathematical Operators' blocks, or
2562	   alternatively code-points in the 'Symbol, Math' ('Sm') category,
2563	   which includes the mentioned blocks, but also includes additional
2564	   symbols, and possibly goes further than needed if the second case
2565	   above is provided for.

2567	5.2.  Change Bars

2569	   Change bars have been used in published RFCs (see for instance
2570	   [RFC6818]), and would seem to be a fairly obvious extension to add.
2571	   When documents were produced with a possible nroff step, adding
2572	   change bars was fairly straightforward, but with the transition to
2573	   publication in XML as the archival format, this capability has now
2574	   been lost, unless we introduce an element that provides it.

2576	5.3.  Element Nesting

2578	   There exists a number of areas where without any obvious reason some
2579	   elements have been excluded from appearing.  For instance, in
2580	   Section 3.1 of RFC-to-be 8646 (draft-ietf-manet-dlep-pause-
2581	   extension), there is a small table as part of one <dd> in a <dl>
2582	   (definition list) that defines the bit fields of a data item.  But
2583	   since <table> is not permitted in a <dd>, the definition list has to
2584	   be broken at this point, a <table> element inserted, and then the
2585	   <dl> continues to define the rest of the data item fields.

2587	   This seems quite unnecssary; there is no obvious reason why tables
2588	   cannot be part of <dd> or <li>.

2590	5.4.  Schema Consistency

2592	   After some changes introduced during implementation, such as
2593	   permitting <blockquote> within <li> after discussion on the xml2rfc-
2594	   dev list (https://mailarchive.ietf.org/arch/browse/xml2rfc-
2595	   dev/?q=subject%3A%22issue%20%2335%22) there is a lack of consistency
2596	   in which elements are permitted where.  Once a decision has been made
2597	   on the additional proposed changes above, (such as permitting <table>
2598	   within <dd> and <li>) a review should be done of the resulting
2599	   schema, and see if a cleanup for consistency is needed.

2601	   Here are for instance lists of elements permitted inside various
2602	   block elements, as of release 2.28.0 of xml2rfc:

2604	   aside:
2605	       (artset| artwork| dl| figure| iref| ol| t| table| ul)*
2606	   blockquote:
2607	       (artset| artwork| dl| figure| ol| sourcecode| t| ul)+
2608	   li: (artset| artwork| blockquote| dl| figure| ol| sourcecode| t| ul)+
2609	   dd: (artset| artwork| dl| figure| ol| sourcecode| t| ul)+
2610	   td: (artset| artwork| dl| figure| ol| sourcecode| t| ul)+
2611	   th: (artset| artwork| dl| figure| ol| sourcecode| t| ul)+

2613	6.  Security Considerations

2615	   This document does not introduce any security considerations on its
2616	   own.

2618	7.  Informative References

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

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

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

2629	   [MATH-JAX] The MathJax Team, "MathJax - Beautiful math in all
2630	              browsers", 2009-2019, <https://www.mathjax.org>.

2632	   [POLA]     Wikipedia, "Principle of least astonishment", 2018,
2633	              <https://en.wikipedia.org/wiki/
2634	              Principle_of_least_astonishment>.

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

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

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

2648	   [RFC6818]  Yee, P., "Updates to the Internet X.509 Public Key
2649	              Infrastructure Certificate and Certificate Revocation List
2650	              (CRL) Profile", RFC 6818, DOI 10.17487/RFC6818, January
2651	              2013, <https://www.rfc-editor.org/info/rfc6818>.

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

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

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

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

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

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

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

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

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

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

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

2698	Appendix A.  Proposed new sections in RFC 7991 bis

2700	A.1.  <u>

2702	   In xml2rfc vocabulary version 3, the elements <author>,
2703	   <organisation>, <street>, <city>, <region>, <code>, <country>,
2704	   <postalLine>, <email>, <seriesInfo>, and <title> may contain non-
2705	   ascii characters for the purpose of rendering author names,
2706	   addresses, and reference titles correctly.  They also have an
2707	   additional "ascii" attribute for the purpose of proper rendering in
2708	   ascii-only media.

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

2719	   The "format" attribute accepts either a simplified format
2720	   specification, or a full format string with placeholders for the
2721	   various possible Unicode expansions.

2723	A.1.1.  Expansion of simplified <u> format specifications

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

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

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

2738	      "name"  The Unicode name(s) of the element text

2740	      "lit"  The literal element text, enclosed in quotes

2742	      "char"  The literal element text, without quotes

2744	      "ascii"  The value of the 'ascii' attribute on the <u> element

2746	   In order to ensure that no specification mistakes can result for
2747	   rendering methods that cannot render all Unicode code points, "num"
2748	   MUST always be part of the specified format.

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

2752	A.1.1.1.  Examples

2754	   Examples:

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

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

2764	      format="num-lit-name":
2765	         Temperature changes in the Temperature Control Protocol are
2766	         indicated by the character U+0394 ("Δ", GREEK CAPITAL LETTER
2767	         DELTA).

2769	      format="num-name-lit":
2770	         Temperature changes in the Temperature Control Protocol are
2771	         indicated by the character U+0394 (GREEK CAPITAL LETTER DELTA,
2772	         "Δ").

2774	      format="name-lit-num":
2775	         Temperature changes in the Temperature Control Protocol are
2776	         indicated by the character GREEK CAPITAL LETTER DELTA ("Δ",
2777	         U+0394).

2779	      format="lit-name-num":
2780	         Temperature changes in the Temperature Control Protocol are
2781	         indicated by the character "Δ" (GREEK CAPITAL LETTER DELTA,
2782	         U+0394).

2784	A.1.1.2.  Expansion of <u> multi-codepoint strings

2786	   If the <u> element encloses a sequence of Unicode codepoints, rather
2787	   than a single one, the rendering reflects this.  The element

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

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

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

2798	A.1.2.  Non-simplified <u> format specifications

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

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

2809	   will be rendered as

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

2813	   As for the simplified format, "num" MUST always be part of the
2814	   specified format in order to ensure that no specification mistakes
2815	   can result for rendering methods that cannot render all Unicode code
2816	   points,

2818	A.1.3.  Split expansion of <u> elements

2820	   There are cases which cannot be handled with either the simplified or
2821	   full <u> format specifications.  One is exemplified in Table 1 of the
2822	   CSS sample document at https://rfc-format.github.io/draft-iab-rfc-
2823	   css-bis/sample2-v2.html#s-3.  Rendering this with <u> elements
2824	   requires that the non-ascii content be rendered in one place (a table
2825	   cell in one column) while the expansion is rendered in another cell
2826	   in a different column.  Provision for this has been made by modifying
2827	   the expansion of <u> when it is referenced by an <xref>.  This table,
2828	   with <u> elements referenced by <xref> instances:

2830	   <table>
2831	     <name>A Sample of Legal Nicknames</name>
2832	     <thead>
2833	       <tr>
2834	          <th>#</th>
2835	          <th>Nickname</th>
2836	          <th>Output for comparison</th>
2837	       </tr>
2838	     </thead>
2839	     <tbody>
2840	       <tr>
2841	          <td>1</td>
2842	          <td>&lt;Foo&gt;</td>
2843	          <td>&lt;foo&gt;</td>
2844	       </tr>
2845	       <tr>
2846	          <td>2</td>
2847	          <td>&lt;foo&gt;</td>
2848	          <td>&lt;foo&gt;</td> </tr>
2849	       <tr>
2850	          <td>3</td>
2851	          <td>&lt;Foo Bar&gt;</td>
2852	          <td>&lt;foo bar&gt;</td>
2853	       </tr>
2854	       <tr>
2855	          <td>4</td>
2856	          <td>&lt;foo bar&gt;</td>
2857	          <td>&lt;foo bar&gt;</td>
2858	       </tr>
2859	       <tr>
2860	         <td>5</td>
2861	         <td>
2862	            &lt;
2863	            <u format="name-num" anchor="greek-upper-sigma">Σ</u>
2864	            &gt;
2865	         </td>
2866	         <td> <xref target="greek-upper-sigma" /> </td>
2867	       </tr>
2868	       <tr>
2869	          <td>6</td>
2870	          <td>
2871	             &lt;
2872	             <u format="name-num" anchor="greek-lower-sigma">σ</u>
2873	             &gt;
2874	          </td>
2875	          <td> <xref target="greek-lower-sigma" /> </td>
2876	       </tr>
2877	       <tr>
2878	          <td>7</td>
2879	          <td>
2880	             &lt;
2881	             <u format="name-num" anchor="greek-final-sigma">ς</u>
2882	             &gt;
2883	          </td>
2884	          <td> <xref target="greek-final-sigma" /> </td>
2885	       </tr>
2886	       <tr>
2887	          <td>8</td>
2888	          <td>
2889	             &lt;
2890	             <u format="name-num" anchor="black-chess-king">♚</u>
2891	             &gt;
2892	          </td>
2893	          <td> <xref target="black-chess-king" format="default"/> </td>
2894	       </tr>
2895	       <tr>
2896	          <td>9</td>
2897	          <td>
2898	             &lt;Richard
2899	             <u format="{char}> ({num})" anchor="richard-iv">Ⅳ</u>
2900	             &gt;
2901	          </td>
2902	          <td>&lt;richard iv&gt;</td>
2903	       </tr>
2904	     </tbody>
2905	   </table>

2907	   comes out as shown below:

2909	       +===+=============+=========================================+
2910	       | # | Nickname    | Output for comparison                   |
2911	       +===+=============+=========================================+
2912	       | 1 | <Foo>       | <foo>                                   |
2913	       +---+-------------+-----------------------------------------+
2914	       | 2 | <foo>       | <foo>                                   |
2915	       +---+-------------+-----------------------------------------+
2916	       | 3 | <Foo Bar>   | <foo bar>                               |
2917	       +---+-------------+-----------------------------------------+
2918	       | 4 | <foo bar>   | <foo bar>                               |
2919	       +---+-------------+-----------------------------------------+
2920	       | 5 | <Σ>         | GREEK CAPITAL LETTER SIGMA (U+03A3)     |
2921	       +---+-------------+-----------------------------------------+
2922	       | 6 | <σ>         | GREEK SMALL LETTER SIGMA (U+03C3)       |
2923	       +---+-------------+-----------------------------------------+
2924	       | 7 | <ς>         | GREEK SMALL LETTER FINAL SIGMA (U+03C2) |
2925	       +---+-------------+-----------------------------------------+
2926	       | 8 | <♚>         | BLACK CHESS KING (U+265A)               |
2927	       +---+-------------+-----------------------------------------+
2928	       | 9 | <Richard Ⅳ> | <richard iv>                            |
2929	       |   | (U+2163)    |                                         |
2930	       +---+-------------+-----------------------------------------+

2932	                    Table 2: A Sample of Legal Nicknames

2934	A.2.  <rendering>

2936	   The preferred ordering of postal address lines differs not only as a
2937	   function of country and region, but also as a function of script for
2938	   some countries (some locales will order addresses in native scripts
2939	   from largest to smallest geographic areas, while romanised addresses
2940	   are ordered from smallest to largest, for instance), and as a
2941	   function of time (i.e., address formats and renderings can change
2942	   over time).

2944	   The current implementation of <postal> rendering relies on an
2945	   external library that provides correct ordering of native and
2946	   romanised address formats as a function of country and region.

2948	   This does however not provide for stability over time -- if the
2949	   address format changes over time, the rendering order indicated by
2950	   the address internationalization library will reflect only what is
2951	   appropriate at a particular point in time, which may be different
2952	   from what was appropriate at the time a document was published.

2954	   In order to capture the appropriate address format for native and
2955	   romanised postal addresses, at the time of publication, the <postal>
2956	   element may have one or more (normally two) <rendering> child
2957	   elements, according to the following Relax-NG Compact schema:

2959	      postal =
2960	        element postal {
2961	          attribute xml:base { text }?,
2962	          attribute xml:lang { text }?,
2963	          (( city | cityarea | code | country | extaddr | pobox | region
2964	             | sortingcode | street)*
2965	           | postalLine+),
2966	          rendering*
2967	        }

2969	      rendering =
2970	        element rendering {
2971	          attribute xml:base { text }?,
2972	          attribute xml:lang { text }?,
2973	          attribute type { "ascii" | "unicode" },
2974	          postalLine+
2975	        }

2977	   When <rendering> elements are present under <postal>, there should be
2978	   one element with attribute type="ascii" if there is no non-Latin
2979	   postal address content, and two elements, with types "ascii" and
2980	   "unicode" respectively if there is non-Latin content present.

2982	   When producing prepped output, the preptool should invoke the address
2983	   internationalization library to get the correct ordering of native
2984	   and romanised address lines if the required <rendering> elements
2985	   aren't already present, and insert <rendering> elements reflecting
2986	   the ordering at the time of prepping.  This will permit the capture
2987	   of address line rendering order at the time of publication, and avoid
2988	   re-invocation of the address internationalization library at a later
2989	   time.

2991	   Renderers MUST use the appropriate <rendering> entries if they are
2992	   present, rather than re-invoking an address internationalization
2993	   library to get the address line ordering.

2995	   The expectation is that authors will provide the appropriate <postal>
2996	   elements (<street>, <city>, <country> etc.), but not <rendering>
2997	   elements; these will be filled in by the preptool and used by the
2998	   renderers for all subsequent rendering.

3000	Author's Address
3001	   Henrik Levkowetz
3002	   Elf Tools AB
3003	   Ollonstigen 8
3004	   SE-18164 Lidingö
3005	   Sweden

3007	   Email: henrik@levkowetz.com