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

Joe Hildebrand (jhildebr) jhildebr at cisco.com
Tue Mar 1 11:48:25 PST 2016

On 3/1/16, 11:59 AM, "HANSEN, TONY L" <tony at att.com> wrote:

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

Numbering *and* naming choices.

>When it's not there, there are different naming choices to be made.
>    One <references> block:
>	4. Normative References (name is "p4_normative_references")

That should get pn='s-4'.  The <references> might have an @anchor, but the <name> element inside it will get slugifiedName='n-references'.

>    Two <references> blocks. Oops, now a virtual referencessection holder appears:
>	4. References (name is "p4_references")

slugifiedName='n-references' pn='s-4'

>	4.1. Normative References (name is "p4_1_normative_references")

slugifiedName='n-normative-references' pn='s-4.1'

>	4.2. Informative References (name is "p4_2_informative_references")

slugifiedName='n-informative-references' pn='s-4.2'

But yes, you're essentially right so far.

>When processing the first Normative <references> block, you don't know whether you can use a "p4_" or a "p4_1_" name. 

I also have to count the number of sections in <middle>, and hope that I got the same answer as all of the other output formatters, in order to come up with the number 4.

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

That's one possible approach, yes.

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

Multiple passes by the output formatter, correct.  The preptool still needs to make 2 passes in order to get section numbers into xref's correctly.

>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 output format is more complex than expected here.  It would be easier if we were willing to say that the output format always had at least two references sections, or that if there's only one you get:

4. References
4.1 My References

(which makes naming section 4.1 difficult...)

Another approach would be to have Normative References and Informative References both be top-level sections, which gets rid of the need for a container.

>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'm not at all concerned with the number of passes, or the internal details of the output formatter.  I'm concerned that different output formatters might make different choices, since there is nowhere that it is specified that a containing section springs into existence if there are more than one <references>.

>I see three choices:
>1) Require the processors to all follow the multiple pass rules, or act like it did by back-patching

They still have to get the section number right.  Remember that <references> are in <back>, but are numbered as if they are in <middle>, which is surprising as a output formatter author.

Another approach I'd be fine with is number the references sections as R.1 ... R.n, which would conflict with an Appendix R, which I hope never happens.

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

That is in no way what I proposed.  What I proposed was that <referencessection> will be added by the preptool if needed, so that the input to the formatter always has exactly one reference-like child of <back>.  The preptool step is there so that people don't have to change the way they author documents today.  By "some interpreters", I think you mean "some output formatters", and the answer to that is no.  All formatters would always see a consistent input.

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

I'd rather have machines fix up the bits that are trivial for them to fix up.  This is no worse than any of the other prep tool steps.

Joe Hildebrand

More information about the rfc-interest mailing list