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(_at_)ietf(_dot_)org
https://www.ietf.org/mailman/listinfo/ietf