[rfc-i] v3imp #3 Verbatim text

Sean Leonard dev+ietf at seantek.com
Fri Jan 23 01:03:09 PST 2015


Improvement Need
#3 Verbatim text

This improvement calls for markup for verbatim text in spec-text. 
"Verbatim text" is text that in v2 was marked with {<spanx 
style="verb">} or {<spanx style="vbare">}. Examples of such text are 
rampant throughout RFCs, but most recently, can be seen in 
draft-josefsson-pkix-textual (are we noticing a trend?).

HTML5 has a variety of elements that are traditionally displayed in 
monospace, but have specific semantics. These HTML5 elements should be 
considered as a starting point: <code> <var> <samp> <kbd>.

The specific v3 elements proposed in this improvement are:
• sample output: <sampout> or <out> or <output> (cf HTML5 <samp>)

• sample input: <sampin> or <input> or <in> (cf HTML5 <kbd>)

  -- TIP: <kbd> represents "user input (typically keyboard input, 
although it may also be used to represent other input, such as voice 
commands)". For IETF purposes, we may wish to distinguish between user 
input and input from a process (i.e., input provided by a 
sender/generator to a receiver/parser). Suggested: <userin>, <procin>, 
<user>, <recv>. Similarly, we may wish to distinguish between "sample 
output" in the sense of executing a computer program for user 
consumption (showing error messages, warnings, extraneous verbose 
details, and the like), and output from a process (i.e., ouput provided 
by a sender/generator to a receiver/parser). Suggested: <userout>, 
<procout>, <disp> (for "display"), <dispout> ("display output"), <send>.

• samples that are neither exclusively inputs nor outputs, e.g., 
examples of formats: <samp>

• code snippets: <sourcecode> (overload <sourcecode> so that it can 
appear within spec-text, in which case it does not have block-level 
semantics) or <codefrag> (cf HTML5 <code>)

• named elements, variables, functions, and productions: <abnf>, <prod 
type="abnf">, <var>, <struct>, <func>, or some mixture of all of these. 
A named thing in a protocol ("ClientHello", "ACK") is semantically quite 
different from a named thing in a computer language ("send()", "recv()", 
"ldap_bind()"); named things in formats ("SubjectAltName", "<keygen>") 
kind of straddle the line between these two.

I was under the impression that since IETF 90, some of these ideas were 
considered. However I combed the list and draft-hoffman-xml2rfc-15; I 
have found no evidence of incorporation yet.

With respect to Improvement #1, it's worth considering that some of 
these elements should have different default whitespace controls--but 
the whitespace behavior ought to be overridable. For example, "named 
things" should always default to the equivalent of CSS "white-space: 
pre"(respect line breaks; no auto-wrapping; do not collapse whitespace). 
Sample input/output should probably default to the equivalent of CSS 
"white-space: pre-wrap" (respect line breaks; auto-wrap; do not collapse 
whitespace).

Sean



More information about the rfc-interest mailing list