[rfc-i] v3imp #3 Verbatim text

Julian Reschke julian.reschke at gmx.de
Fri Jan 23 03:30:59 PST 2015


On 2015-01-23 10:03, Sean Leonard wrote:
> 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?).

The trend *I* notice is that you have very specific wishes to the 
format, that may not be shared or may not be shared yet by others. Is 
there another trend I should see :-)

> 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>)

v3 already has <tt>. Please explain why that isn't sufficient.

>   -- 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>.

-1000

Please do not invent whole families of new elements unless there's a 
demonstrated use for this kind of granulariy.

> • 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, if we did all you're asking for we'd end up with something as 
complex as DocBook. I believe that's a bad idea; all these things you're 
asking for have limited use, will be ignored by most users, make 
learning the language harder, and will make implementations complex and 
more expensive.

Best regards, Julian


More information about the rfc-interest mailing list