ietf
[Top] [All Lists]

Re: RFC production center XML format usage, was: [IAOC] xml2rfc and legal services RFPs

2011-02-25 12:00:34

Colleagues,

With respectful apologies to both the posters I'm quoting, I'm going
to reframe this conversation slightly, in hopes of pointing out what I
think we're really talking about, or should be.

On Thu, Feb 24, 2011 at 05:59:02PM +0100, Henrik Levkowetz wrote:
On 2011-02-24 17:38 Andrew Sullivan said:
On Thu, Feb 24, 2011 at 05:11:00PM +0100, Henrik Levkowetz wrote:
The ratio of gripes against idnits to actual bug reports is getting to
be a bit annoying; and I'd like to suggest that people either submit
bug reports, or direct the complaints against the requirements of
1id-guidelines.txt rather than against the tool which checks the
requirements if the problem is that the requirements are too strict.

You're quite right that I'm using "idnits" as a portmanteau for the
whole "1id-guidelines checking at submission" bundle.  My apologies
for being imprecise.  I am indeed complaining about the latter and not
about the former.

Ah.  Ok.  I'll go tweak some code, then :-)

The whole process needs work. Focusing on a specific piece is useful
on the merits, but also misses an important point.

I'm a long-time IETF participant who's currently editor on a WG draft
for the first time in several years.

The process of submitting the -00 of the WG draft I'm responsible for
was an eye-opener, and not a happy one.

I knew to use xml2rfc, and I'm familiar with the relevant XML, and I
took a lot of the formatting of meta-boilerplate from a previous
generation of the document. However, the document was still rejected
for automatic submission as a -00 for no reason I could immediately
understand.

A big deal? No, it took two people half an hour to muddle through, and
the obvious backup (email submission) was available, and there were
no deadlines immediately at hand.

Harder than it needed to be? I venture to say yes. The mechanics of
submitting the draft, as opposed to the substance of writing it or the
process of getting WG chair pre-approval, was simply opaque even to an
experienced participant who just hadn't attempted this specific task
before.

I can't tell how much of the wrestling with the tools occurred because
it's been a few years and the process had changed so much, how much
that I had to be reminded to use idnits separately (having looked,
perhaps in the wrong places, for a simple "how to"), how much that the
guidelines document is overly-particular, and how much the submission
tool itself. (The problem was a missing version number in the internal
"filename" parameter, which led to a failed match for the pre-approved
name. The submission tool error was "no previous version found". The
idnits error was that the internal filename didn't have a version
number. Putting those together was harder than it had to be,
especially as I was fooled by the fact I was submitting a file named
exactly what we'd agreed it should be.)

As someone trying to make a contribution as editor of a document
needed by a WG to do its work, I don't care exactly where the problem
lies. I don't even care to characterize it as a documentation error, a
tools error, or a UI (confusing output) error. 

I know that the details of making something like this work can be
arcane, particularly as it evolves. My appreciation for Henrik,
Andrew, and everybody else who makes the whole infrastructure function
is sincere.

But wouldn't it be easier for them, and everyone else, as well as for
me and others who don't write several RFCs a year, if the whole
document submission pipeline could be reviewed and perhaps made easier
to work with?


Suzanne




_______________________________________________
Ietf mailing list
Ietf(_at_)ietf(_dot_)org
https://www.ietf.org/mailman/listinfo/ietf

<Prev in Thread] Current Thread [Next in Thread>