[rfc-i] Potential RFC format approach: HTML

Joe Hildebrand jhildebr at cisco.com
Fri Mar 23 23:12:30 PDT 2012


It should surprise nobody that I think HTML is a good fit for the
requirements I've heard thus far for a new RFC format.  Here is a set of
steps that might be able to get us there.


- Subset HTML.  The subset would be decided upon based on current wide
support, expectation that it will continue to work, repeatability, stability
of output, etc.  However, as long as old-ish browsers can render the output,
they might not need to get the full experience.

- Make the decision that the files will ALWAYS be encoded UTF-8.

- Define a very strict structure, using a microformat/semantic style, that
makes it easy to pull out information semantically with a little bit of
jQuery in post-processing tools.  Make a choice about XML-style
well-formedness, which is probably not needed.

- Ensure that the document is self-contained, embedding styles and images,
so that we can do signatures easily.  This means that newer files may look
different from older files, and that's ok.  Greasemonkey or it's successors
can swap in whatever styles you want.

- Define requirements for how we can add new capabilities over time.

- Define requirements for accessibility.

- Build libraries that know about the structure for several programming
languages.  Survey folks that parse the current text format for their
requirements.  It seems like JavaScript might be a good staring point.

- Write a tool that checks the HTML for the structure, then the several
hundred nits that will grow up over time.

- Ensure that we know how to refer to pieces of the document in ways other
than page and line number.  Doing this programmatically is easy with the
right structure, but we may need to think about what humans do.  It may be
easiest to just give the humans good tools to do review comments, like the
WHATWG does.

- Ensure we've got good diff tools.  There are several adequate ones for
HTML already.

- Tweak the output from xml2rfc to generate the agreed-upon structure,
either for transition, or for people that want to have a high probability of
passing the nit checks the first time.

- Begin the transition to HTML being the authoring format as well as the
archive format.  Help people set up their graphical HTML editors to generate
the structure.  With a good template, snippets, instructions, and hooks to
the nit tool, this seems achievable.  It should also be possible to write a
pretty comprehensive editing suite that runs right in the browser, if
someone has the time.

- Spend a little money to hire a real designer to make the output sing.  The
goals would be readability and the perception of expertise and stability.

- Allow the RFC Editor to start accepting HTML-formatted entries that pass
all the nit checks.  For a transition period, the text format could still be
required, but in order to get the tooling situation straightened out, the
Editor would have to start accepting HTML-only submissions earlier than some
might find comfortable.

There are likely other steps, and there's a lot of personal opinion strewn
throughout this proposal, but I figured it would be nice to have a starting
point.

-- 
Joe Hildebrand



More information about the rfc-interest mailing list