[rfc-i] comments on "Format FAQ"

Heather Flanagan (RFC Series Editor) rse at rfc-editor.org
Wed Feb 19 10:05:52 PST 2014


(Top posting on purpose)

Jeff, you make a good point that the Format FAQ needs to be brought up
to date and marketed a bit more heavily.  I'll see what I can do before
IETF 89.  If anyone else has something they would like to see added to
the FAQ, please let me know.

-Heather

On 2/18/14 4:40 PM, =JeffH wrote:
> 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
> 
> 
> 
> 
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest



More information about the rfc-interest mailing list