[rfc-i] v3imp #8 Fragment tagging on sourcecode

Julian Reschke julian.reschke at gmx.de
Sat Jan 24 00:26:05 PST 2015


On 2015-01-24 06:35, Sean Leonard wrote:
> ...
> As a technical matter, I believe that the vocabulary should support all
> three.

Yes.

> As an editorial matter, avoiding duplication is superior: duplicated
> content raises the risk of inconsistency.

Unless the duplicated ABNF is built automatically; such as in RFC723*.

> Rather than wishing for interspersed rules in figures /plus/ a collected
> appendix, consider that a tool that processes the xml v3 format should
> be able to show various views of the content, including a view where all
> of the ABNF is concatenated together. Thus consider a RFC viewer
> (probably some web app) with three tabs: Specification, ABNF, and
> Attachments. The Specification tab just shows some regular text view(s).
> The ABNF tab collects all of the (inline) ABNF and displays them in a
> nice way--possibly with hyperlinks that show all cross-references to the
> main text. (Being ABNF-aware, the ABNF tab could also fold/eliminate
> duplicate rules, so if you really want to intersperse rules in the text
> AND have your appendix, the tool should be smart about that.) Similarly,
> the Attachments tab collects all of the attachments so they can all be
> saved to disk in one fell swoop.

I wouldn't want to require basic tool processors to understand ABNF (and 
other notations).

> Thus if you have an ABNF rule:
>
> <sourcecode type="abnf">
> abnfFooRule = 5*ALPHA
> </sourcecode>
>
> Then in some spec-text, you might say:
>
> <t>The <named type="abnf">abnfFooRule</named> is an identifier for foo
> things. It MUST be at least 5 letters.</t>
>
> ...in which case, the tools can automatically generate anchors and links
> between the <named> element and the abnfFooRule in the figure
> (<sourcecode> element)...no need to create unnecessary anchors. This is
> a specific motivator for Improvement #3.

In rfc2629.xslt I have a generic extensions for this type of linking, 
and we have used it to produce the HTML versions of the HTTP specs.

 > ...

Best regards, Julian


More information about the rfc-interest mailing list