[rfc-i] comments on "Format FAQ"

=JeffH Jeff.Hodges at KingsMountain.com
Tue Feb 18 16:40:04 PST 2014


I had some time to try to catch up on IETF happenings and was nosing around 
rfc-i@ archives and such today and ran across this message..

[1] Direction of the RFC Format Development effort
     http://www.ietf.org/mail-archive/web/ietf-announce/current/msg11474.html

..of Heather's.

Noting the pointer to the faq down at the end of the above-referenced msg..

[2] Format FAQ - 1-May-2013
     https://www.rfc-editor.org/rse/FormatFAQ.html

..I took a look and immediately started casting further about trying to 
figure out various things. below is some feedback on the above-referenced 
"format" FAQ [2].

Note that I overall support this effort and the direction it's presently 
headed, I'm just trying to help out here -- not everyone who starts looking 
into this is up-to-speed on all the moving parts.

I also note that i can only find two links to [2] via search engines: the 
link on <https://www.rfc-editor.org/>, and the one embedded in [1]. More 
links to it spread around would be good it seems.

And finally, perhaps consider adding an additional question & answer to [2]..

Q: What are the Internet-Drafts related to the RFC format effort?

A: [rfc-i] A list of I-Ds related to RFC format
https://www.rfc-editor.org/pipermail/rfc-interest/2014-February/006263.html


HTH,

=JeffH


 > "What does this mean for authors who don't use xml2rfc?"

"this" is essentially undefined in the context of FormatFAQ.html.

"this" should be explained to some degree, and a link to [1] provided.


 > In the short term, authors will continue to be able to submit their final
 > I-Ds (those already approved by the streams) in text, nroff, or XML.
 > Authors can expect additional questions regarding potential metadata and
 > element tags as we explore a broader use of XML.
 >
 > Long-term implications for authors who do not use xml2rfc will be better
 > understood after we have explored the full implication of tool changes
 > and determined what seems to work most effectively for the RFC Editor and
 > the community.

The above two paragraphs imply to me that "this" isn't necessarily an 
"experiment" as is essentially stated in [1]..

   "The direction we will be exploring is one where the Canonical format
   ... is XML using the xml2rfc DTD. From that format, the RFC Editor
   will experiment with rendering four Publication formats... The goal
   is to run through this experiment over the next year..."

..because of the unqualified use of the "long-term implications" term.

Also, the statement, "The canonical format will be XML.", is made here by 
Heather speaking as rse at rfc-editor.org..

[3] Re: [rfc-i] Text no longer definitive (was Re: Proposed way
     forwards on backward compatibility with v2)
https://www.rfc-editor.org/pipermail/rfc-interest/2014-February/006295.html


 > "How soon can authors start using non-ASCII characters in UTF-8?"

the phrase "non-ASCII characters in UTF-8" is potentially confusing and 
misleading to readers not immersed in Unicode terminology and lore.

I suggest..

   "How soon can authors start using non-ASCII characters in Internet-Drafts
    and RFCs ?"


 > Several questions remain regarding the inclusion of UTF-8 characters

"UTF-8 characters" is a misnomer and misleading/confusing.

it should be "(non-ASCII) Unicode characters" in this sentence.


 > within RFCs. While we are moving ahead with the intent of permitting
 > UTF-8 characters, these characters will only be allowed in RFCs after the

here I'd do this..

s/UTF-8 characters/UTF-8-encoded Unicode characters/


 > details of where and how new characters will be supported have been
 > determined, when we have tools that can support UTF-8 characters

same here..

s/UTF-8 characters/UTF-8-encoded Unicode characters/


 > deployed, and the RFC Production Center is trained in the handling of
 > such characters.
 >
 > "What do these changes mean for xml2rfc?"
 >
 > Several things, including (but not limited to) further encouraging the
 > deprecation of xml2rfc v1,

there should be a reference to the definition of "xml2rfc v1".

Perhaps referencing these two messages would be sufficient..

[4] Transitioning to xml2rfc v2
http://www.ietf.org/mail-archive/web/ietf-announce/current/msg12251.html

[5] [rfc-i] XML DTD v3 work
https://www.rfc-editor.org/pipermail/rfc-interest/2013-December/005788.html

..tho something that combines [4] and [5] would ostensibly be better.


 >                         code enhancements for v2, some new or changed
 > element definitions, and the archiving of different versions of the tool
 > by the RFC Publisher after major updates.
 >
 > "What happens if an author wants to provide a plain text file rather than
 > an XML file?"
 >
 > Authors will be allowed to submit a plain text file. It will have to be
 > converted to a basic XML file prior to publication, and a tool that will
 > assist with that is necessary for both the RFC Editor and the authors.
 > See also "What does this mean for authors who don't use xml2rfc?"
 >
 > "What Publication formats be available day 1?"
 >
 > This is still under discussion.
 >
 > "Will you republish any RFCs in the new Canonical format?"
 >
 > No changes will be made to published RFCs. However metadata will likely
 > be added to the RFC info pages to indicate what tools are needed to view
 > or edit the canonical version of the RFC.
 >
 > "How will images be handled for the plain text version of an RFC?"
 >
 > The current thinking is that RFCs with images will include a written
 > description and a reference to the PDF version. This is similar current
 > practice.

s/similar/similar to/

 >
 > "How will UTF-8 characters be handled when rendering the plain text
 > version of an RFC?"

s/UTF-8 characters/Unicode characters/


 > Since the question of where and when UTF-8 characters should be permitted

s/UTF-8 characters/Unicode characters/


 > is still under discussion, it is difficult to provide a definitive answer
 > to this question at this time. Current thinking (subject to change as we
 > learn more) is to require an ASCII version of the author names and
 > contact information for indexing and common reading purposes. Both
 > versions of the author's name would be displayed in the Authors'
 > Addresses section, with the ASCII plain text version in the header.
 > Within an RFC, if the subject of the RFC requires non-ASCII characters
 > for implementation and understanding, a Unicode code point may be
 > required (see RFC 5895 as an example of how ASCII and Unicode could be
 > used). If non-ASCII characters are used in examples or other
 > non-normative texts, the ASCII version of the RFC will likely either
 > point to the HTML/PDF version OR a simple substitution will be made (if
 > possible) based on a published table of such substitutions (e.g., "e" for
 > "é").

my pedantic side is thinking that you perhaps ought to footnote "non-ASCII 
characters" as meaning "non-ASCII-equivalent Unicode characters" (or 
whatever the correct terminology would be).


---
end






More information about the rfc-interest mailing list