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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 





--On Sunday, August 10, 2008 6:03 PM +0200 Julian Reschke <julian.reschke@xxxxxx> 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@xxxxxxxx
https://www.ietf.org/mailman/listinfo/ietf

[Index of Archives]     [IETF Annoucements]     [IETF]     [IP Storage]     [Yosemite News]     [Linux SCTP]     [Linux Newbies]     [Fedora Users]