[rfc-i] [IAB] draft-iab-xml2rfc-03, "1.3.3 Elements and Attributes Deprecated from v2"

[jhildebr at cisco.com (Joe Hildebrand (jhildebr))]

On 3/16/16, 1:49 AM, "Julian Reschke" <julian.reschke at gmx.de> wrote:



>Well, until I see what "..." is I can't comment. I believe that 
>pretending that nothing is auto-generated when there is text content is 
>incorrect, and a breaking change compared to what the existing tools 
>have been doing for plain text output for ages.

OK, let's assume we're going to un-deprecate format='none'.  The current tooling is lightly-documented here, and produces to my mind odd output.  We need to nail down what this means.  Here's valid v2 input (except with numbers in [brackets] for referencability):

"""
    <section anchor="introduction" title="Introduction">
      <t>
        <list style='numbers'>
[1]       <t anchor='one'><xref target='one'/></t>
[2]       <t><xref target='one'>ONE</xref></t>
[3]       <t><xref target='one' format='counter'/></t>
[4]       <t><xref target='one' format='counter'>ONE</xref></t>
[5]       <t><xref target='one' format='default'/></t>
[6]       <t><xref target='one' format='default'>ONE</xref></t>
[7]       <t><xref target='one' format='none'/></t>
[8]       <t><xref target='one' format='none'>ONE</xref></t>
[9]       <t><xref target='one' format='title'/></t>
[10]      <t><xref target='one' format='title'>ONE</xref></t>
        
[11]      <t><xref target='introduction'/></t>
[12]      <t><xref target='introduction'>ONE</xref></t>
[13]      <t><xref target='introduction' format='counter'/></t>
[14]      <t><xref target='introduction' format='counter'>ONE</xref></t>
[15]      <t><xref target='introduction' format='default'/></t>
[16]      <t><xref target='introduction' format='default'>ONE</xref></t>
[17]      <t><xref target='introduction' format='none'/></t>
[18]      <t><xref target='introduction' format='none'>ONE</xref></t>
[19]      <t><xref target='introduction' format='title'/></t>
[20]      <t><xref target='introduction' format='title'>ONE</xref></t>
        </list>
      </t>
    </section>

"""


xml2rfc v2.5.1 generates (again, with [numbers] added for reference):

"""
    <ol>
[1]   <li><a href='#one'>Paragraph 1</a></li>
[2]   <li><a href='#one'>ONE</a> <cite title='NONE'>[one]</cite></li>
[3]   <li><a href='#one'>1</a></li>
[4]   <li><a href='#one'>ONE</a> <cite title='NONE'>[one]</cite></li>
[5]   <li><a href='#one'>Paragraph 1</a></li>
[6]   <li><a href='#one'>ONE</a> <cite title='NONE'>[one]</cite></li>
[7]   <li><a href='#one'/></li>
[8]   <li><a href='#one'>ONE</a> <cite title='NONE'>[one]</cite></li>
[9]   <li><a href='#one'/></li>
[10]  <li><a href='#one'>ONE</a> <cite title='NONE'>[one]</cite></li>

[11]  <li><a href='#introduction'>Section 1</a></li>
[12]  <li><a href='#introduction'>ONE</a><cite title='NONE'>[introduction]</cite></li>
[13]  <li><a href='#introduction'>1</a></li>
[14]  <li><a href='#introduction'>ONE</a> <cite title='NONE'>[introduction]</cite></li>
[15]  <li><a href='#introduction'>Section 1</a></li>
[16]  <li><a href='#introduction'>ONE</a> <cite title='NONE'>[introduction]</cite></li>
[17]  <li><a href='#introduction'/></li>
[18]  <li><a href='#introduction'>ONE</a><cite title='NONE'>[introduction]</cite></li>
[19]  <li><a href='#introduction'>Introduction</a></li>
[20]  <li><a href='#introduction'>ONE</a> <cite title='NONE'>[introduction]</cite></li>
    </ol>

"""


1. Is somewhat surprising, but I'm not sure what else you'd do.  I can't imagine ever wanting that.
2. I can live with that, but I guess I don't what understand the <cite> tag, and I really don't understand the cite title.
3. I get this.  It's what counter is for.
4. Same as 2.  The format was ignored.
5. Same as 1.  Expected if the default format is "default", which seems reasonable.
6. Same as 2.  Expected if the default format is "default", which seems reasonable.
7. I wish this had generated an error instead of this output.  Useless.
8. Same as 2.  The format was ignored.
9. Same as 7, but is fine below in 19.
10. Same as 2. The format was ignored.
17. Same as 7.  I wish this had generated an error.

You'll note that in all of the cases where the xref contains text, the format is ignored.  7 and 17, the cases where there is no text in the xref, and the format is "none", nothing useful is generated.

Other tools generate other things, but in the absence of documentation about what is *supposed* to happen, and evidence that the main xml2rfc tooling is doing only stupid things with format="none", we decided to deprecate it, the last time we had this discussion.

-- 
Joe Hildebrand