Subject: [xml2rfc] Seeking a larger can...

From: Elwyn Davies <[email-masked]>
Date: Sat, 21 Jun 2014 14:17:01 +0100

Hi.

I seem to have fallen foul of the old adage:
"Never open a can of worms unless you have a larger can handy."

I made a start on reviewing draft-reschke-xml2rfc-latest last night.  

I reached <annotation> and did a slight double take because I hadn't
realized that it was a (new) part of the v2 vocabulary - I had thought
it was an add-on goody for v3. So I thought I would go check that the
online processor accepted <annotation>.  And indeed it does.  

So far, so good.

I pasted in the example from the draft into my draft template
(draft-davies-template-bare.xml):
        <annotation>
        Latest version available at <eref
        target='http://www.w3.org/TR/xml'/>.
        </annotation>

and used the online processor.

I had only half remembered that <eref>'s are, by default, replaced by
numeric references and an extra sub-section title "URIs" is
automatically added to the References section with the value/content of
the <eref> indexed by the reference.

Problem 1: <eref>'s in the body of the draft work as expected but an
<eref> in an annotation inserts the URI reference ([2] in this case)
inline but it doesn't appear in the "URIs" section.  Ticket #260
addresses this problem.

So having looked at the output from Julian's draft where the <eref>
content appears in line, I was trying to remember which PI controlled
this.  I realized that the "inline" PI is overloaded to do this (It is
mainly associated with <cref>).

Problem 2: Should "inline" be overloaded?

Ok, so I added <?rfc inline="yes" ?> to the test file and tried again.
Initially nothing changed - I got the same output as previously. Tried
again and still got the same anaswer.  Having scratched my head and
tried another file (Julian's draft) I came back to the test file, and
now I got the expected inline result - but changing back to inline="no"
I was now stuck with the inline result and couldn't get back to the
original result with a "URIs" section.  At this point I gave up and went
to bed, thinking maybe my brain was addled.

Problem 3: There is some sort of memory effect where changing the inline
PI value doesn't have an immediate effect in the online xml2rfc v2 tool.
Sounds like something is not being reinitialized for subsequent runs.

Retrying this morning the memory effect is still there: Tried it
initially with inline="no" and was stuck with that result.  So I checked
whether the memory effect showed with other PIs.  Changed to
symrefs="no".  Oops.  No, it didn't show the memory effect *but* I
realized that the numeric references for <eref>s are not integrated with
the <xref> references so now there are two different [1]'s etc., one for
<xref>s and one for <eref>s.

Problem 4: With <?rfc symrefs="no"?> and <?rfc inline="no"?> the
numbering sequences for <xref>'s and <eref>'s overlap so it isn't
possible to distinguish which ref is being referred to in the text.

Problem 5: There isn't a way to give a symbolic name for an <eref>.
Maybe it should have an anchor attribute.

Oh, and another nit.

Problem 6: The old v1 processor doesn't handle the permanent redirects
for xml.resource.org.  Entities using xml.resource.org are now flagged
as errors and have to be rewritten to use xml2rfc.tools.ietf.org.  I got
it out of retirement to check what used to happen with <eref>'s.

Guess I better write some more tickets!

If you can help, please send jumbo sized empty can by express
delivery. ;-)

Cheers,
Elwyn

---

From: Tony Hansen <[email-masked]>
Date: Sun, 22 Jun 2014 21:13:27 -0400

On 6/21/14, 9:17 AM, Elwyn Davies wrote:
> as errors and have to be rewritten to use xml2rfc.tools.ietf.org.

I've fixed this, but only because the RFC Editor still occasionally 
checks things under v1.

     Tony Hansen