Re: [pkix] [rfc-i] v3imp #3 Verbatim text

[Sean Leonard <[e-mail]>]

On 1/23/2015 1:03 AM, Sean Leonard wrote:
> Improvement Need
> #3 Verbatim text

I would like to narrow this Improvement down to very modest and focused 
proposals for phrasing content (specification text), below.

The samples in the attachments are taken from PKIX-related documents 
draft-josefsson-pkix-textual-10 and RFC 5280, and further discussed below.


    Elements

• named items: <named> (or <keyword> — extend the current element in the 
model). A named item is a keyword or key phrase of semantic significance 
in the specification, and is expected to occur in normative block-level 
text such as text found in <sourcecode>, <artwork>, and (if accepted) 
<attachment> elements. Examples of named items include variables, 
computer language keywords, field names, and ABNF rule names. Tools can 
generate automatic links or cross-references between <named> elements 
and the texts where the named elements occur. When rendered, named items 
may use the same typeface as <artwork> and <sourcecode> elements. A 
named item is a sequence of Unicode code points.
HTML5 ≈ <var> <code>

• literals: <lit> (or <verb> for verbatim). A literal serves as 
exemplary data in the specification. Examples of literals include sample 
output, sample input, magic numbers, labels, and specific identifiers or 
values (e.g., TRUE, 777). When rendered, literals should appear visually 
distinct from non-literal content, and should use the same typeface as 
<tt>, <artwork>, and <sourcecode> elements. A literal is a sequence of 
Unicode code points. Tools can provide affordances and functions to 
display and extract the exact code points. Apparently replaces <spanx 
style="verb"> and <spanx style="vbare">, with the semantics.
HTML5 ≈ <samp> <kbd> ~<q>

◦ teletype: <tt> (already in v3 draft—therefore no change required). 
Monospace style only. Apparently replaces <spanx style="verb"> and 
<spanx style="vbare">, without any semantics. Compare with <lit> above.
HTML5 ≈ ‼ apparently <tt> was removed from HTML5...


    Notes and Quotes

<q> was considered (as the phrasing content equivalent to <blockquote>), 
both for literals and for prose quotations from other documents, but was 
rejected: quotation marks are working out just fine. The spec-text is 
US-English so we can stick with regular English punctuation marks.

We may wish to have an editorial policy that changes "" to “” and ‘’. 
The left and right quotation marks are much clearer than the US-ASCII 
generic (and overloaded) " and ' marks. When delimiting or quoting 
US-ASCII content, “” is extremely clear since “ and ” characters are not 
US-ASCII. For example, quoting the quotation mark sometimes looks like 
""" — “"” is much clearer. Other standards organizations such as ISO use 
left and right quotation marks in their standards.


    Samples

The attached samples are extracts from the canonical plain text versions 
of draft-josefsson-pkix-textual-10 and RFC 5280. I have marked up the 
plain text with the following PDF annotations:
Cyan-blue highlight
	named items/keywords
Green highlight
	literals
_Red underline_
	teletype (monospace) text


These samples should make the broad utility of this proposal clear.

Sean