Subject: RE: Alternative formats for IDs

From: Bob Braden <[email-masked]>
Date: Thu, 12 Jan 2006 13:31:03 -0800 (PST)

*> From [email-masked]  Wed Jan 11 13:53:32 2006
  *> X-Spam-Status: No, score=-2.5 required=5.0 tests=AWL,BAYES_00 autolearn=ham 
  *> 	version=3.1.0
  *> Date: Wed, 11 Jan 2006 16:52:31 -0500
  *> From: John C Klensin <[email-masked]>
  *> To: Bob Braden <[email-masked]>, [email-masked], [email-masked]
  *> cc: [email-masked]
  *> Subject: RE: Alternative formats for IDs
  *> Content-Transfer-Encoding: 7bit
  *> X-ISI-4-43-8-MailScanner: Found to be clean, Found to be clean
  *> 
  *> 
  *> 
  *> --On Wednesday, 11 January, 2006 13:02 -0800 Bob Braden
  *> <[email-masked]> wrote:
  *> 
  *> >  *> 	The RFC editor has some problems which have not, to my
  *> > knowledge,   *> been	enumerated.
  *> >   *> 
  *> > 
  *> > Your knowledge is apparently incomplete.  The RFC Editor has
  *> > been actively experimenting with using xml2rfc for
  *> > publication, and we have been passing our problems along to
  *> > the tools team.  As we get more experience, new ones show up.
  *> > There is not currently a version of xml2rfc that meets our
  *> > needs.  Some of our editors do the major editing in XML, but

  *> Bob,
  *> 
  *> Let me suggest a way to look at the above, deriving in large
  *> measure from the experiences Ned Freed and I (mostly Ned, who
  *> did the heavy lifting) had with what are now RFCs 4288 and 4289.
  *> To the extent to which authors can hand XML to you, and get XML
  *> back with whatever substantive/ editorial changes you have made,
  *> it should ultimately not be a concern of anyone in the community
  *> how you make the transition between the final XML, with all of
  *> the text worked out, and the final formatting.  In particular,
  *> if that step requires you to convert the XML to nroff and then
  *> massage the nroff, I don't think it should be an issue.  The
  *> issue arises from handing you a format that contains generic
  *> markup and is editable but, because of your "via nroff" process,
  *> requires authors to deduce substantive and editorial changes
  *> from diffs and then retrofit them back into the XML for future
  *> use.

John,

We have thought about what you suggest, and it may be workable.
The problem with it is this: during the "AUTH48" stage, we give the
author(s) the exact final version ready for publication, for
final verification.  (There was a time when this was mostly pro forma,
but for a variety of reasons, some good and some bad, the
AUTH48 stagetoday not infrequently invovles significant changes to a
document.)  Suppose that we edit the document in XML (we are already
doing this part of the time), do a final nroffing pass to get the
format just right, and then give the author(s) the edited xml,
final .txt, and a diff file.  (We could easily do this today).
The author(s) change the .xml (or give us a patch file for us
to make the changes.)  We have to make a new nroff version and
PUT THE SAME CHANGES INTO IT THAT WE DID THE FIRST TIME.

Now, this may not actually be too bad; most of the changes at the nroff
stage are very cosmetic, and we could use diffs and perhaps other tools
to make it quite easy.  OR, we could change the AUTH48 policy to let
the author(s) deal only with the edited xml, without the final
formatting cleanups.  We would then translate to nroff and do the
final formatting AFTER AUTH48.  (Or, we could have two stages of
AUTH48). 

Perhaps we should run some more experiments.

Bob Braden for the RFC Editor

_______________________________________________
Ietf mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/ietf

---

From: Julian Reschke <[email-masked]>
Date: Thu, 12 Jan 2006 22:40:54 +0100

Bob Braden wrote:
> ...

I think, the latter (two stages) is clearly the best way to do that. I 
would appreciate it if this would be tried (optimally, with one of my 
documents :-).

Best regards, Julian

---

From: Dave Crocker <[email-masked]>
Date: Thu, 12 Jan 2006 14:07:29 -0800

Bob,

>   Suppose that we edit the document in XML (we are already

This sound like quite a good approach.

d/

-- 

Dave Crocker
Brandenburg InternetWorking
<http://bbiw.net>

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Thu, 12 Jan 2006 18:16:26 -0500

> This sound like quite a good approach.

It sounds like an awful waste of time and effort to me.

It seems like the more efficient approach would be to essentially have two 
stages, where the authors first sign off on the result of copy-editing, and 
then on whatever cosmetic changes are needed after the final conversion.

In the few cases where I've had the chance to observe the AUTH48 process on 
a large, complex document (mostly as a WG chair), the majority of issues 
have been related to changes in wording the authors were unhappy with, 
missed spelling errors, etc.  If these issues were resolved using only the 
XML and the output of xml2rfc, with the nroff and final text not being 
generated until the authors were happy with the copy, I'd bet that 95% of 
documents would result in no additional comments from the author based on 
the final text.

-- Jeff

---

From: "Steven M. Bellovin" <[email-masked]>
Date: Thu, 12 Jan 2006 20:27:44 -0500

In message <[email-masked]>, Jeffrey Hutzelman 
writes:

>then on whatever cosmetic changes are needed after the final conversion.
That assumes that the xml->nroff conversion is always error-free.  I 
think that that's an overassumption.

		--Steven M. Bellovin, http://www.cs.columbia.edu/~smb

---

From: Keith Moore <[email-masked]>
Date: Thu, 12 Jan 2006 20:46:07 -0500

> think that that's an overassumption.

I've seen several cases where "cosmetic changes" introduced technical errors
in a document.

Keith

---

From: Jeffrey Hutzelman <[email-masked]>
Date: Thu, 12 Jan 2006 21:03:11 -0500

On Thursday, January 12, 2006 08:27:44 PM -0500 "Steven M. Bellovin" 
<[email-masked]> wrote:

> In message <[email-masked]>, Jeffrey
> Hutzelman  writes:
>>
>
>>
>> It seems like the more efficient approach would be to essentially have
>> two  stages, where the authors first sign off on the result of
>> copy-editing, and  then on whatever cosmetic changes are needed after
>> the final conversion.
>>

I don't think it makes that assumption.  It assumes that the conversion
is usually error-free with respect to content, and thus that the vast
majority of problems will be discovered in the first phase, when any
corrections can be incorporated into XML that will then hopefully be 
available when the time comes to work on the next protocol version.

Of course, any changes introduced in the XML->nroff conversion would have 
to be corrected, which is why the authors would still need to sign off
on the final published text.

-- Jeff

---

From: Barry Leiba <[email-masked]>
Date: Fri, 13 Jan 2006 14:26:06 -0500

...
> We have to make a new nroff version and
> stage are very cosmetic

Maybe we're attacking that part of it the wrong way.
What is it that makes those "cosmetic" changes, to "get the format
just right", so important?  Do we really care whether there's an
extra blank line, or the indentation is one character too much?

When I run xml2rfc and look at the results, the formatting looks
"just right" to me, at least for any value of "just right" that
I care about.  Why does the IETF (or others) care for a greater
value of "just right"?

Or am I missing something basic in the formatting changes you're
looking at, at that stage?

Barry

--
Barry Leiba, Pervasive Computing Technology  ([email-masked])
http://www.research.ibm.com/people/l/leiba
http://www.research.ibm.com/spam

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 13 Jan 2006 11:49:53 -0800

> copy-editing, and then on whatever cosmetic changes are needed after

It's worth mentioning that this is exactly how book publication
works. Indeed, the copy-edit stage is often done on something
with entirely different formatting from the final version
(e.g., double-spaced). The proofreader is then responsible
for ensuring that (1) Each proposed copy-edit change actually
gets handled and (2) No superfluous changes are introduced
in the typesetting/page layout stage. Then there's a final
author approval of the galleys.

-Ekr

---

From: "Steven M. Bellovin" <[email-masked]>
Date: Fri, 13 Jan 2006 14:56:31 -0500

>author approval of the galleys.
Right.  And I've heard authors gripe that they wrote their books with 
state-of-the-art distributed systems and version control, but because 
the publisher's typesetting was done on a different, incompatible 
system, the copy-edit changes were not fed back into the authors' 
system, making any second edition much more difficult.

AUTH48 is often quite prolonged and painful -- and I've experienced 
this as an author, WG chair, and AD.  Let's not make it any worse.

---

From: "Spencer Dawkins" <[email-masked]>
Date: Fri, 13 Jan 2006 13:57:07 -0600

Agree with Barry that we need to balance things wisely.

If we are routinely taking up RFC-Editor resources for cosmetic reformatting 
of XML2RFC output, I'm thinking that this is not a good use of resources.

If someone submitted one XML2RFC input that triggered some XML2RFC boundary 
condition bug and caused a blank page to be emitted in the middle of a 
document, maybe it's "better" to quickly fix the output than to fix XML2RFC, 
but I'd really like to get to the point where there is no reformatting of 
XML2RFC output for most/all XML2RFC input files that were submitted for 
publication as RFCs.

Thanks,

Spencer

From: "Barry Leiba" <[email-masked]>

---

From: Dave Crocker <[email-masked]>
Date: Fri, 13 Jan 2006 11:58:38 -0800

> works. 

Exactly right.  So, the question is whether the IETF needs to use an operational 
model that guarantees certain, high overhead, or whether we can enjoy a model 
that permits us to move much of the grunt work out to the authors. 
(Interestingly, we can have the second-stage copy-editing either way, but with 
far more of the grunt work done by authors, for one of the models.)

The quality of the copy-editing that the rfc editor does is quite high.  But it 
also imposes a very high aggregate cost on the IETF.  Do we *really* need to 
spend that money, for that benefit?

d/

-- 

Dave Crocker

---

From: Eric Rescorla <[email-masked]>
Date: Fri, 13 Jan 2006 12:08:30 -0800

> system, making any second edition much more difficult.

Fair enough, but consider that this problem already exists in the
RFC-Ed system because the RFC-Ed's final version is in a set
of tools that almost nobody uses. This includes many nroff
users, btw, because the RFC-Ed's nroff is too primitive to
really edit with yourself.

-Ekr

---

From: "Spencer Dawkins" <[email-masked]>
Date: Fri, 13 Jan 2006 14:14:02 -0600

Agree with EKR that such a two-stage author review SHOULD make sense, and if 
our median time in AUTH48 wasn't something like 10 days now[1], I'd be a lot 
more excited about adopting this and going through AUTH48 (or its nearest 
equivalent) twice ...

:-(

Spencer

[1] ftp://ftp.rfc-editor.org/in-notes/IETFreports/2005/ietf64-report.pdf and 
http://www3.ietf.org/proceedings/05nov/slides/plenaryw-2.pdf

---

From: Bob Braden <[email-masked]>
Date: Fri, 13 Jan 2006 12:04:00 -0800

>extra blank line, or the indentation is one character too much?

Well, yes, we do.  At least, the RFC Editor cares, and we believe
you should care too.  Blank lines are not just randomly inserted... they 
are put in
to enhance readability, and they can make a significant difference.

RFCs are input to human readers, not machines.

Bob Braden

---

From: Barry Leiba <[email-masked]>
Date: Fri, 13 Jan 2006 15:52:51 -0500

> you should care too.  Blank lines are not just randomly inserted...
> they are put in to enhance readability

Oh, sure, I get that, and I'm not suggesting that we ignore that.  I'm
asking this: If the author and the last-call commentors think the
output of xml2rfc looks good, what is that that you "tweak" with nroff
that's necessary at that point?

When you say that you make cosmetic changes beyond what's been done
with xml2rfc, and agreed to by those who've reviewed it, I presume
you're making stylistic changes that the RFC editor cares about that
"we" didn't (if we did, we'd have already made those changes).  I'm
wonder what sorts of things those are, and whether they're really worth
all the extra overhead.

Barry

---

From: Dave Crocker <[email-masked]>
Date: Fri, 13 Jan 2006 12:57:11 -0800

> Well, yes, we do.  

Bob, the question is not whether it is good to have a standard format, design 
for easy readability.

The question how much it is worth ensuring that all the spacing is always and 
exactly correct.  How much is it worth in time/delay and how much is it worth in 
dollars?

And specifically, how bad would it be to spend far less -- bordering on nothing 
-- and get "pretty close" to that desired format?

For a community built upon the construct of efficient use of scarce resources, 
we do an impressively good job of ignoring that construct in our own operation.

d/

-- 

Dave Crocker

---

From: "Spencer Dawkins" <[email-masked]>
Date: Fri, 13 Jan 2006 15:11:45 -0600

(clipped down to)

> wonder what sorts of things those are, and whether they're really worth

... and whether it would be good if the working group had been reviewing a 
more-readable version of the document, and had forwarded a more-readable 
version for last call and IESG review...

Given that the RFC Editor has published more documents than I've written in 
my life, I don't question what's being done. I'm just asking if it might be 
done automatically, and be done earlier in the process.

I'm guessing these are changes that the RFC Editor has been feeding to the 
XML2RFC authors via Bill Fenner in 
http://rtg.ietf.org/Members/BillFenner/rfced-xml/FrontPage/issuetracker, and 
that we're moving closer to "fire and forget" XML2RFC operation, so maybe 
all is well, or at least improving?

Spencer

---

From: Ned Freed <[email-masked]>
Date: Fri, 13 Jan 2006 14:37:37 -0800 (PST)

> this as an author, WG chair, and AD.  Let's not make it any worse.

If by "worse" you mean I'll get back the vast majority of changes in the form
of a revised version of the XML file I handed in, which I can then edit and
send back, saving me hours of work retrofitting the changes into my copy, them
I'm for making this as "worse" as possible.

In my case at least this changes the first pass of AUTH48 to a simple
differences check-and-merge. I do these routinely, often on much larger
documents than any RFC I've written, and it is rare for the process to take
more than 15-20 minutes. (It does help to have sharp tools for this: BBEdit in
my case.)  In contrast, the two recent RFCs I recently dealt with required
several hours of work apiece. That pushes things from an activity I can pretty
much squeeze in anywhere to one I have to budget time for, and that in turn
tends to stretch AUTH48 into the realm of AUTH96 or even more.

As long as the second pass doesn't involve wording changes I don't anticipate
it taking very long. I view layout as the RFC Editor's for the most part.

Bottom line: This will be a HUGE improvement for anyone that uses xml2rfc. I
would not be adverse to retaining the old process for RFCs submitted to the
editor as ASCII text, but holding xml2rfc users hostage to the old way of
working makes no sense whatsoever.

				Ned