Re: Call for review of proposed update to ID-Checklist

John C Klensin wrote:
> ...
>> References:
>>
>> - check that if the document obsoletes or updates another
>> document, that one appear in the references section, and make
>> sure that the document actually says what's going on with
>> respect to the other documents (such as "Normative Changes
>> from RFC xxxx")
> 
> Of course, if one does this, the automated nits checker complains about 
> a reference to an obsolete RFC :-(
> ...

It's only a warning if it is an informative reference...

> ...
>> Code:
>>
>> - when using xml2rfc, add type parameters to artwork so that
>> things like ABNF can be automatically extracted and checked
> 
> FWIW, I continue to believe, based on experience with a few fairly large 
> and complex documents (most recently rfc2821bis) that the xml2rfc 
> approach of treating ABNF as a special type of artwork is seriously 
> broken for at least two reasons:

I do agree that the approach of "either it is prose or it is artwork" 
does not work well for things lik e BNF, example mssages and so on...

>    (1) It effectively forces the author to do formatting on a
>    line by line basis, which is not what generic markup is
>    supposed to be all about and is pathological for
>    pretty-print applications (including HTML and Postscript
>    output) because it prevents taking advantage of different
>    line length and wrapping options.  That problem gets more
>    severe if productions extend over several lines and/or
>    contain comments.

That sounds a bit like the problem is more related to the RFC line 
length, and the ABNF comment placement rules. If there's something that 
can be done in xml2rfc, I'd be interested to discuss this further 
(preferably on the xml2rfc mailing list).

>    (2) It prevents indexing and use of XML elements to identify
>    and organize portions of the ABNF (e.g., distinguishing rule
>    names (LHS) from definitions (RHS) and comments).

I'm working around that by using custom extensions in rfc2629.xslt, and 
by translating these extensions into something xml2rfc understands 
(example: 
<http://greenbytes.de/tech/webdav/draft-ietf-httpbis-p1-messaging-03.html>).

> For both of these, use of hanging <list> elements can actually work 
> better than the artwork model even those that option has more than its 
> share of disadvantages as well.
> 
> While I understand that this is a sufficiently large change to xml2rfc 
> that I should not hold my breath, I think it would be very unfortunate 
> to use the Checklist and/or its automatic instantiation to aggressively 
> push a sometimes-unfortunate practice.

Sounds like we need better tools. If automatic line wrapping for BNF is 
the issue, maybe a preprocessor would be sufficient.

> ...

BR, Julian
_______________________________________________
Ietf mailing list
Ietf@ietf.org
https://www.ietf.org/mailman/listinfo/ietf