gmane.ietf.rfc.interest

Towards Consensus

Phillip Hallam-Baker — 2012-05-25T15:46:34

Watching this discussion I can see some points that I think that most
reasonable people can agree on and I would like to suggest that these
actually give us a pretty clear way forward as far as at least a first step
goes.

*Proposition 0: The objective of having IDs and RFCs is to communicate
information to readers. Format proposals should be judged on their
effectiveness as a communication medium and the demands they impose on
document producers*
*
*
It is very easy to make a case for one particular format by choosing some
bizarre corner case that begs the question. The purpose of RFCs is to
communicate. A format that has a high overhead is going to be unacceptable
as is a format that has a high probability of introducing unchecked errors.


*Proposition 1: It is reasonable for a participant to request the ability
to read IDs and RFCs in a particular format.
Proposition 2: It is utterly unreasonable for anyone to demand that others
read IDs and RFCs in a particular format unless there are specific reasons
w

A proposal: HTML

Iljitsch van Beijnum — 2012-05-24T20:16:02

It seems to me that the discussion is veering off in unproductive directions. So I'll explain the HTML format I have in mind and why I think HTML is a good direction, better than any of the alternatives.

Note that I'm not an HTML expert, there are probably better ways to do many of the things that I'm suggesting here.

A big problem today is that the draft/RFC format can't easily be generated by widely used tools, and the tool(s) that _can_ generate it are not exactly user friendly. There is no magic bullet that will make that problem disappear completely, but HTML gets us at least a good part of the way there. So let's discuss that part first.

WRITING

Writing a draft/RFC has three main parts:

1. The front matter, with author names, publication dates, titles, etc
2. The main body text and headings
3. The references

At this point, I'm going to refrain from complaining about how XML2RFC handles part 1, but rather assume that there is no reasonable way to make this completely painless, and suggest that alt

Speaking of presenting RFCs

Tim Bray — 2012-05-16T19:33:03

Check out http://pretty-rfc.herokuapp.com

for example http://pretty-rfc.herokuapp.com/RFC3986

Works great on my mobile; even shifts the ToC in and out depending
whether the phone is in landscape or portrait. A fine piece of work.
-T

RFC Format - final requirements and next steps

Heather Flanagan (RFC Series Editor — 2012-05-11T16:50:00

Hi all -

Thanks to the feedback from the community, I've modified the 
requirements for the format of RFCs (which ties in I-D format 
as well, though any actual change to I-D format is outside my 
purview).  I've collapsed two categories in to one (Edit and 
Review) since they have almost exactly the same requirements.  
RFC Editor requirements in most cases are similar to Edit/Review, 
but with a few unique ones important to the editors.  Archive 
and End consumption still vary.

http://www.rfc-editor.org/rse/wiki/doku.php?id=formatreq
(point of order - is it better for me to include a link as above, 
or copy the list in to the email?)
 
At this point, I would like to encourage people to submit (or 
point to existing) I-Ds with these requirements and requests as 
input.  I do not expect any proposed solution can meet all the
needs and wants listed by the community, but I'd like to see how 
close we can get.

Note that the deadline for I-D submission for an initial document
to be discussed at IETF 84 in Van

support for tables (from RFC 5892)

Larry Masinter — 2012-04-24T22:13:17

This is also a good example of "Better support for tables". While XML2RFC supports tables, the ASCII output is hard to read.

Should authors be allowed or discouraged from styling tables? (Separating lines, alignment, etc.)?



Larry



-----Original Message-----
From: rfc-interest-bounces< at >rfc-editor.org [mailto:rfc-interest-bounces< at >rfc-editor.org] On Behalf Of Peter Saint-Andre
Sent: Tuesday, April 24, 2012 1:08 PM
To: Iljitsch van Beijnum
Cc: rfc-interest< at >rfc-editor.org
Subject: Re: [rfc-i] Use of unicode



On 4/24/12 1:51 PM, Iljitsch van Beijnum wrote:






That's really all we're talking about here. Can we agree that we're in

violent agreement and end this thread?



As one instance of such examples, consider the six lines at the bottom

of page 7 of RFC 5892:



00DF; PVALID     # LATIN SMALL LETTER SHARP S

03C2; PVALID     # GREEK SMALL LETTER FINAL SIGMA

06FD; PVALID     # ARABIC SIGN SINDHI AMPERSAND

06FE; PVALID     # ARABIC SIGN SINDHI POSTPOSITION

Now tell me how to communicate this as effectively inplaintext

Phillip Hallam-Baker — 2012-04-23T16:28:14

I have been working on the attached document for several months. It
describes a proposal to change the structure of PKI. Note that none of
the other proposals referenced are described in RFC form either, nor
do the authors have any intention of using that format.

The subject matter is neither simple nor straightforward. The
arguments are not straightforward either. PKI is a complicated subject
because it deals with the real world and the real world is complex.

While all the diagrams and illustrations are described in the text, it
is much more likely that people will understand the diagrams than the
text.


Now while I could convert this into plaintext format I am not going
to. I am going to make my argument in the format I think is going to
be most effective for communication.

I have the following questions:

1) Does anyone seriously want to argue that the document would be
easier to interpret in plaintext format without any diagrams?

2) Do people respect the fact that it would take me a great deal of
ti

Guidelines for illustrations

Larry Masinter — 2012-04-23T22:39:52

I think some simple guidelines for illustrations would go a long way. Maybe not "rules", but "guidelines". But engineers often get carried away since most people who author Internet Drafts are not professional designers and don't think about simple things like accessibility and whether the diagram will print out.

For text, the RFC editor can actually fix grammar errors and missing references and periods in the wrong place.
For graphics, the RFC editor can only fix things for which the RFC editor has tools which can edit the graphics that are delivered to the RFC editor. 

That won't be true for graphics delivered as images -- not editable. And while Adobe illustrator can be used to edit SVG, the kinds of edits needed are probably not really supported.

Some guidelines:

Keep the diagram or illustration to something that could reasonably be done in ASCII art. That's not because we like ASCII art, but just as a matter of insuring maximum interoperability. For example, diagrams and illustrations could be kept

Use of unicode

Larry Masinter — 2012-04-23T10:14:30

Locations:


Authors' names (ID/RFC author, author of cited document)
EAI Authors' email addresses
Titles of cited documents
IRIs for cited documents
Examples for protocols about I18N and non-ASCII characters
Other examples
Unicode art
Normative text


I think these have different priority and different impact.  The problems are quite similar to the problems of URIs vs. IRIs: there is a tradeoff between global transcription (everyone can copy text from one device to another, visually, even if haltingly) and local optimization (people get the names and characters they are familiar with).

Some guidelines:

Avoid spurious uses, like upside-down letters written for fun, dingbats, emoji, etc.
Only use non-ASCII when absolutely necessary; preferably provide ASCII alternative also.
If characters are used for which fonts are not universally available, release at least one format with embedded fonts (PDF/A, ePub).

Accessibility requirements

Larry Masinter — 2012-04-18T06:52:27

One of the requirements we must be aware of and optimize for is accessibility.

* Non-ASCII characters: I do not know the deployment of support for Unicode strings in screen readers, but I imagine that it isn't as consistent as support for ASCII strings, especially for obscure characters (dingbats, emoji, etc.)
* Equations: I am told that MathML has a better story for accessibility than other forms of equations. Treating equations as illustrations reduces accessibility.
* Illustrations, diagrams:  Explicitly requiring accessibility for illustrations (alternate descriptions) might make documents MORE accessible over ASCII art.

I think we should be EXTREMELY conservative about making accessibility of documents WORSE for ANY audience, and so explicit attention to accessibility is important.


The W3C recommendation     "Web Content Accessibility Guidelines (WCAG) 2.0" is a must-read. 

"Web Content Accessibility Guidelines (WCAG) are part of a series of Web accessibility guidelines published by the W3C's Web A

Reclassification of RFC 2223

SM — 2012-04-17T23:49:47

Hi Nevil,

According to http://www.rfc-editor.org/info/rfc2223 RFC 2223 is not 
Obsolete.  According to the RFC Editor website, RFC Document Style is 
documented at http://www.rfc-editor.org/rfc-style-guide/rfc-style and 
Instructions to Request for Comments (RFC) Authors is documented at 
http://www.rfc-editor.org/rfc-editor/instructions2authors.txt

I gather that the information provided in RFC 2223 is out of 
date.  Between you and me, it's a bit like V'Ger.  Instead of waiting 
until 2273, I suggest reclassifying RFC 2223 as  Historic within the 
immediate future.

Regards,
-sm

Problems and requirements for RFC Format

Heather Flanagan (RFC Series Editor — 2012-04-17T21:13:08

Hi all -

Thank you all for your patience and input to the RFC Format question.
One of the things I've been working on is an organized list of what
problems we're trying to solve and what the requirements actually are
for the RFC series.  As Larry Masinter mentioned in the BoF, there are
several different constituencies that have their own particular problems
and concerns, and that will in turn influence whatever we decide
regarding the future of the RFC format.

What I would like from the folks on the rfc-interest list is feedback on
whether or not I've captured consensus on the problem space.  Note that
I'm avoiding formal use of MUST and SHOULD right now, though I have
tried to indicate level of requirement as I understand it so far.

======

Draft-Edit (what authors worry about when writing an I-D)
* Respect for authors names (Limit to character set prevents proper
display of all names)
* Authors need a way to update documents easily and see how they might
look when published
* Need to be able to include

Withdrawing Authors, Editors, and Contributors doc

Heather Flanagan (RFC Series Editor — 2012-04-16T17:55:32

Hello everyone -

A few months ago, I sent out a document for review (Authors,
Contributors, Editors, and overload" to the rfc-interest list
(http://www.rfc-editor.org/pipermail/rfc-interest/2012-January/002840.html)
and my advisory group.  The overwhelming feedback regarding the
creation and standardization of a Contributing Authors section and
potential modification to the authors and affiliations on the main
page was negative.  As such, that document is being withdrawn from
consideration for becoming RFC Editor policy.

For the recurring question of number of authors and editors, we will
address this in the revised style guide (in progress).  The current policy
(http://www.rfc-editor.org/policy.html#policy.authresp) is in place until
the revised style guide is available

Thank you all for your feedback!

Heather Flanagan, RSE

must vs. MUST and conformance requirements

Larry Masinter — 2012-04-11T05:54:06

I'm less concerned about the syntactic representation of conformance requirements, and much more concerned about the poor job many document editors and working groups do at establishing conformance criteria that are testable, or even meaningful. 

Wishful thinking: some tooling that gathers together the context of normative keywords would help encourage better spec-writing?

draft-rfc-image-files-03

Iljitsch van Beijnum — 2012-04-08T18:16:22

I just had a look at http://tools.ietf.org/id/draft-rfc-image-files-03.txt

I think this is a spectacularly bad idea. This way, we would have all the downsides of PDF, all the downsides of formatted ASCII text, and lose the advantage that we only have a single file.

This also locks us into pagination even deeper, while IMO that's something we should move away from, because the number of times when US letter pagination is convenient are dwarfed by the number of times when it is not.

There are lots of tools that read and write PDFs, but that doesn't mean it's necessarily reasonably possible to round trip an image from an image editing program to PDF and back without losing a lot of information. For instance, the image may be rasterized so what was a vector image is now a high resolution bitmap. Or logical structures are broken up in lots of small structures but the relationship between them is lost.

I don't think these issues are easily avoidable without blessing a specific tool. And tools tend to go away o

RFC Server Outage Report

Glen — 2012-04-06T22:09:51

All -

Yesterday (April 5) at 8:54 AM Pacific time the RFC Editor server was attacked
and compromised by an outside party.  As a result of this hack, the server's
operation became erratic.  Staff were unable to login, and the website was
returning invalid search results for searches against the RFC Editor database.

AMS IT staff took immediate action, halting the server and performing an
investigation.  We restored service 90 minutes later, after repairing and
restoring the damaged server, and doing a thorough check to make sure we
hadn't missed anything.

At the time, notifications were sent out to RFC and IETF leadership; this
follow-up message is being sent to the community at the request of the
IAOC chair.

AMS took steps to identify the attack vector and remove the discovered
vulnerability.  A variety of other steps were taken to ensure that no other
systems were compromised, and that future attacks of the same type would fail.
No data was lost, no permanent damage was done, and the total downtime for
t

Timely Spec Restyling Proposal from W3C

Martin J. Dürst — 2012-04-02T01:17:06

Given all the intense discussions last week about how to move forward 
with new format(s) for RFCs and Internet Drafts, I'm glad to be able to 
forward this timely proposal from W3C, in the hope that it will provide 
some additional stimulation for our discussion.

I'm sorry if this proposal is slightly late is some parts of the world, 
it's already Monday here but it should have gone out on Sunday.

Acknowledgments got to Fantasai for the explanatory text below and to 
Tab Atkinson for the new design.

Regards,    Martin.

-------- Original Message --------
Subject: Spec Restyling Proposal
Resent-Date: Sun, 01 Apr 2012 22:38:07 +0000
Resent-From: spec-prod< at >w3.org
Date: Sun, 01 Apr 2012 15:37:33 -0700
From: fantasai <fantasai.lists< at >inkedblade.net>
To: spec-prod <spec-prod< at >w3.org>

Hello spec-prod!

The CSS Working Group has finally prepared a spec restyling proposal that
we feel captures the mission of the W3C. I've sent a preview as applied to
several of our CSS specs to www-archive:
 
http://lists.w3.org/A

Meetecho session recording available

Meetecho IETF support — 2012-03-29T17:12:47

Dear all,

the full recording (synchronized video, audio, slides and jabber room)
of RFCFORM session at IETF-83 is available.

You can watch it by either clicking the proper link on the remote 
participation page 
(http://www.ietf.org/meeting/83/remote-participation.html#Meetecho), or 
by directly accessing the following URL:
http://ietf83.conf.meetecho.com/index.php/Recorded_Sessions#RFCFORM_IETF83

For the chair(s): please feel free to put the link to the recording in 
the minutes, if you think this might be useful.

In case of problems with the playout, just drop an e-mail to
team< at >meetecho.com.

Cheers,
the Meetecho team

Pagination and some other stuff

Iljitsch van Beijnum — 2012-03-28T12:44:22

The pagination question is very important. Even more so than creating the required line length, coming up with the pagination in drafts is problematic. Tools commonly used today simply don't output in this format, and it's hard to create it manually, too.

Now that would be one thing if it's useful for people who want to read drafts and RFCs, but I'm afraid that's rarely the case. 55-line pages don't fit well on screens (large and small alike, although more of an issue on small ones) or on European paper sizes.

However, if we want to get rid of pagination we need to be able to live without page number references. Are we prepared for that? Obviously a ToC can be generated for the PDF versions (yes, multiple: one for each common paper size), but otherwise they can't be used anymore. Someone mentioned paragraph numbers for referencing stuff, but I'm not sure that would work well. In practice today we use a section number or quote the offending text, which seems to work well enough. But I could be mistaken.

Af

illustrations & equations rare: extra overhead for creating them acceptable

Larry Masinter — 2012-03-28T09:31:33

Opinion: Illustrations and equations should continue to be very rare:
 Because:   Reviewers must review the legibility of the document without the illustration, and the equivalence of the illustration to the non-illustration text.
   
Opinion: extra overhead for creators of illustrations and equations is OK
   Because: they are (and should remain) rare.  
                       No matter what technology is used to display, they're not usually edited "by hand" anyway.
                     There are numerous tools for creating and converting to (perhaps not for editing of) mathml / svg
            
   Opinion: equations and diagrams should have accessible alt-text / longdescs 
      Because: needed for accessibility,  for creating text-only renditions.

Observation:     diagrams and equations don't work well on small-screen devices, no matter what file format
       (ASCII art, PDF, jpeg, SVG, whatever), unless the diagrams and equations are really small.

Next steps in the RFC Format discussion

Heather Flanagan (RFC Series Editor — 2012-03-28T09:24:56

Hi all -

I believe my next steps are to filter through what's been said on the
list and in the BoF in order to determine the global requirements for
the input, archiving, and display of RFC.  I'm going to avoid specific
technologies and/or protocols at this point in favor of documenting what
the problems and requirements are that those technologies may be solving.

Some of you are working on tools to demonstrate your point, and others
are working on Internet-Drafts to describe your proposal.  That's fine,
though you may find it useful to hold off for a bit to incorporate my
findings.  Your call.

Thank you all.  This has been a useful conversation for me, and in
particular, a useful BoF.

-Heather

Normalized HTML

Larry Masinter — 2012-03-28T08:16:04

After listening to the BOF discussions and reading the email, I've changed my thinking. 

I'm leaning toward a marked up profile of HTML where the authoring format and distribution format is a canonicalization of the authoring format. That is, I think we could move away from XML/XML2RFC and instead have a "cleaned profile" HTML with a tidy-step that does the work that xml2rfc does but which is idempotent (i.e., the output is suitable for input and generates the same HTML.)   

Having the output format suitable for input and production of other formats trivializes the re-use issues. 

"View Source" is powerful.


ID-editor: edit in simplified profile of HTML, or else edit in some tool and generate ("clean") HTML.

ID-submission: 
Preprocessor run through a 'tidy' which does things like "make head/title match h1 header", fixing up metadata, annotating or styling references, fix cross-references.
Postprocessor: generate ASCII-only view of HTML by substituting longdesc for diagrams, changing cross-references, et