[rfc-i] draft-iab-html-rfc-02: references

HANSEN, TONY L tony at att.com
Tue Mar 1 10:59:36 PST 2016

On 3/1/16, 12:57 PM, "rfc-interest on behalf of Joe Hildebrand (jhildebr)" <rfc-interest-bounces at rfc-editor.org on behalf of jhildebr at cisco.com> wrote:

>On 3/1/16, 10:50 AM, "Julian Reschke" <julian.reschke at gmx.de> wrote:
>>I think you're making assumptions about formatters that may not be 
>>correct. For instance, *I* am maintaining a formatter (and plan to 
>>support V3), but I'll not be able to rely on the preptool (for entirely 
>>technical reasons).
>Remember, the output of the preptool is the *canonical* document that we will publish as the RFC's XML.  New output formatters that we come up with years from now will use those documents as input, and we'd like them to get the output as close to today's formatters as is practical.  In particular, all of the section numbers MUST come out the same.
>>We may have terminology problem.
>I thought you and I had been using this terminology for several years successfully.  If we really have a disconnect, I'd love the chance to chat and clear up any misunderstandings.
>>For me a "formatter" is something that takes the user's V3 source and 
>>generates output from that. You seem to propose a formatter that does 
>>two passes, a preparation pass and a formatting pass. That's an entirely 
>>fine way to implement the formatting (and yes, the prep stage is needed 
>>to get the canonical format for archival), but it's not the only way to 
>>implement things.
>I think what we said at some point was that formatters had to act *as if* they had run the preptool steps, but they didn't have to actually output the prep'd format.

Let me paraphrase this to make sure I understand the issue.

The problem with <referencessection> not being a part of the grammar and not being present is that the output format requires a virtual placeholder for it to appear only when there are multiple <references> blocks. When it's there, there are naming choices to be made. When it's not there, there are different naming choices to be made.

    One <references> block:
	4. Normative References (name is "p4_normative_references")

    Two <references> blocks. Oops, now a virtual referencessection holder appears:
	4. References (name is "p4_references")
	4.1. Normative References (name is "p4_1_normative_references")
	4.2. Informative References (name is "p4_2_informative_references")

When processing the first Normative <references> block, you don't know whether you can use a "p4_" or a "p4_1_" name. It's not until you hit that second <references> block that you know for sure. So Joe wants there to be a signal (called <referencessection>) before going into that first <references> block that lets you know right there and then that you can use "p4_1" instead of "p4_".

In all the other cases where there are named sections, there is also a container required when there are multiple items. This obviates the need for making multiple passes.

I think my biggest reaction to <referencessection> as Joe first expressed it was an ugh at the complexity due to it being optional and knowing that existing processors work around it just fine today.

The V1 and V2 XML2RFC processors resolve this by using two passes. They make a note during the first pass if it needs to be generated or not, and fix up the reference section naming when doing the second pass. Another common method that can be used is "back patching", where there are pointers maintained into the generated text and things are patched up before actually being printed. Another common method is to add a layer of dereference and back patch the referenced string.

I see three choices:

1) Require the processors to all follow the multiple pass rules, or act like it did by back-patching
2) Add these funky "okay, there's this optional <referencessection> block that you can use if you want to, but you don't really need to, cause some interpreters don't need it and can just ignore it if it's there, but some interpreters really do need it cause they can't do multiple passes, and . . . ."
3) Just make <referencessection> a part of the v3 grammar and >require< that it to be used when there are multiple <references> blocks.

I prefer #1. I can live with #3. I'm not happy with #2.


More information about the rfc-interest mailing list