--On Sunday, August 10, 2008 6:03 PM +0200 Julian Reschke
<julian(_dot_)reschke(_at_)gmx(_dot_)de> wrote:
Hi,
things I'd like to see done in IDs more consistently:
In an Editorial Note on the front page:
- state on which mailing list discussions should take place
(include mailing list archive and subscription links)
- point to issues lists when available
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 :-(
- use symbolic references
The RFC Editor is still flexible about this, IMO for good
reason. It should not be the prerogative of this document, or
even the IESG, to change the preference to a rule.
...
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:
(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.
(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).
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.
Versioning:
- (this probably is controversial :-) - keep an appendix that
gives a short overview of what changed compared to previous
drafts
Yep, it is controversial. Good idea sometimes, bad idea
others, hence probably a poor checklist guideline beyond,
perhaps, "please consider keeping...".
best,
john
_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www.ietf.org/mailman/listinfo/ietf