[rfc-i] v3imp #3 Verbatim text

Sean Leonard dev+ietf at seantek.com
Fri Jan 23 11:59:15 PST 2015


On 1/23/2015 3:30 AM, Julian Reschke wrote:
> 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 :-)

Yes...that others are requesting the same kinds of "specific wishes to 
the format", that aren't being groked.

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

<tt> is the moral equivalent to <b> and <i> -- it blesses a formatting 
convention. In contrast, things like HTML5's <samp> and <kbd> are the 
moral equivalents to <em> and <strong> -- they denote semantically 
distinguishable textual components. I thought that we want to focus on 
semantics rather than.

There also seems to be a strong desire amongst many participants to 
engage in automated extraction, collation, and verification. Saying:
<t>A certificate needs to be signed.</t>

and

<t>A <prod type="asn.1">Certificate</prod> needs to be signed.</t>

has very different implications in the context of the digital 
certificate standard, RFC 5280.

As I stated, I used HTML/HTML5's <code> <var> <samp> <kbd> as the basis 
for my analysis. The existing xml2rfc v2 tool outputs things in <spanx 
style="verb"> as the HTML <samp> element--not the HTML <tt> element, 
even though <tt> is the closer equivalent. Therefore I have not invented 
anything new; I am just trying to make use of what others have been 
observing in a production markup with billions of users.

I would be satisfied with an all-purpose element like <prod> 
(production) or <named> (named item), with a well-defined set of 
attributes like @type (ASN.1 struct, etc.) or @usage (input/output/etc.)

Due to the widespread use of ABNF in IETF docs, there might be 
justification for an <abnf> phrasing or block-level element.

Sean



More information about the rfc-interest mailing list