On 19-jun-2006, at 20:09, John C Klensin wrote:
> (2) If I prepare an RFC draft using some mechanism which > produces a document in form X, where X might include
> * ASCII text, via emacs or vi, with a post processor for > headers, footers, or page numbers > * xml2rfc > * MSWord plus some templates and post processing > * nroff with a profile different from the RFC Editor's standard > * LaTeX or TeX > * Obscure word processor 7b
> then the RFC Editor makes changes, possibly extensive and > returns the revised document in an ASCII text format.
Now I have never written an RFC so I don't know how all of this works, but I have written two books for different publishers so I know how this kind of thing works elsewhere. My question: does the RFC editor really live up to his/her name and perform extensive edits?
The answer is it depends. I've had some documents that were pretty much unchanged while others were edited quite extensively. In recent work I've observed that most edits are good ones, but occasionally the RFC Editor doesn't quite get what's going on and bolixes something up. It is therefore imperative that every change be carefully reviewed by the document authors.
And if so, what are the nature of those edits? I can't imagine they go to the technical content, so either it's language (copy edit) or formatting, right?
Most are editorial in nature. Occasionally there will be a change with technical implications though. We're not dealing with fools here, you know.
> No matter how good my tools are, I'm going to have to do > considerable, mostly manual, work to retrofit those changes into > my source.
I don't know what other authors do, but I edit all the changes back into my xml2rfc source, iterating until my output matches, modulo numbering and paragraphing and whatnot, what the RFC Editor produced. This way I am sure to catch any mistakes introduced by the editing process. I also end up with a source file that's a useful starting point for the next revision of the document. This is quite tedious but not especially difficult as long as you have provided xml2rfc sources to the RFC Editor as a starting point. If you haven't done that my guess is the process isn't nearly as nice.
Ok. If we're talking about copy edits here, then this is one for the problem statement. Note by the way that the formatting authors are normally expected to do is indicating heading levels, block quotes, captures, that kind of thing. This is very easy to do with styles in modern word processing applications, which generally make anything tagged with a style look different. It's also easy to do with old school tools such as nroff and HTML/XML, and unless I'm mistaken, there are tools available to convert between the two approaches. (Word processors generally have a document format in common that preserves the style tags if not their attributes.)
The RFC Editor provides an annotated differences listing showing you what changed between your final draft and what's in the actual RFC. It is a simple matter to duplicate this tool and use it to tweak your sources to match the actual RFC. I've tried using change bars and other fancier tools, but I have concluded they're more trouble than they're worth.
If there is an iterative cycle of changes between the authors and the RFC editor, I think it's necessary that this is done with some form of style tagging.
There already is such a process, but IMO you're mistaken about what's needed to improve it. The thing I'd like to have that isn't already there is a way to get the xml2rfc sources the RFC editor used back for comparison purposes.
In addition, more advanced word processors such as Word and Star/Open Office/Writer support a "track changes" feature where any changes made to a document are identified along with who made them. This makes sending different versions of a document back and forth infinitely easier, but it has the downside that many word processors and other tools don't support this, so the selection in tools is much smaller.
Again, I've tried these things a couple of times and found them to be more pain than gain.
> But, if it is not, then one of the discussions we should be > having, IMO, is about selecting one or two additional input > formats (xml2rfc and Word stand out as candidates to me) in > which the RFC Editor is willing to accept input documents and > return editing results to the authors for review.
As I indicated above, the RFC Editor already accepts xml2rfc source for documents as a starting point. My understanding is that they then do as much of their editing as possible against the xml2rfc source, then generate nroff, then tweak the nroff and possibly even the final output to get exactly what they are after. it would be great if more of the work was done on the xml2rfc and less in the later stages, but I think the RFC Editor is already moving in that direction.
Yes, this makes sense. Especially if the Word format is only used as a "lingua franca" without depending on specific details. I.e., I can write a text in Open Office, tag it with the right styles and export to .doc format. In Word or another word processor that can read those files, the styles will still be present even if the document looks slightly different from the way it did when I wrote it because some information is lost when saving in a non-native file format.
My immediate thought in response to all this is "what a colossal waste of time". I want to focus on document content, not stylistic frills and irrelevant minutiae. That's what the RFC Editors gets the big bucks to do... I therefore want a tool that lets me engage in semantic markup with as little attention paid to layout issues as possible. It is exceedingly unfortunate that some amount of device-level markup is still needed in xml2rfc, but hopefully as the tools improve over time actual use of such facilites will become less necessary. THis is not to say there aren't cases where I want precise control of document output. I run into such cases all the time, and when I do I use TeX. But this has nothing to do with writing RFCs. Something is very wrong if an RFC requires this sort of work.
> Doing so > would solve a large number of problems, not only wrt easily > producing PS/PDF forms when needed, but for producing revised > versions of the relevant documents for updated standards, etc. > That suggestion has been made several times; as far as I know, > the discussion has never gotten off the ground.
THe issues surrounding the production of revised versions are top of my personal list at least.
Let's see if we can do better now.
> (3) Finally, if one adopts the "plates in the back" model, the > PDF (or whatever) document contains the illustrations and _only_ > the illustrations. That makes it fairly insensitive to the RFC > editing process.
I'm not too happy about that. If we're going the route of using images for formulas and drawings, it makes sense to make those available as separate files in an "easy" format such as GIF or PNG, or, in addition or alternatively, a PDF can be produced where the images are present in-line with the text. Having the images separate from the text in a PDF has all the disadvantages of PDF: possibly large files, small selection in viewers, security and compatibility issues, but it's still inconvenient when reading the text and having to hunt for the images separately.
> So I suggest that, generally, we would find > that, in a "text plus figures" model, the editing process would > generally change the text only, permitting the figures/images to > remain unchanged.
That is not my experience. Figures are very hard to get right, they very often require edits.
It depends on what sort of edits you're talking about. Both figures and equations move things away from pure semantic markup and towards presentation specifics. It's unavoidable, and once you enter the presentation realm the list of possible tweaks to make things just a little bit better often seems endless. But I question whether such changes are really necessary in a lot of cases. Sure, I've sometimes spent hours with TeX or in OmniGraffle trying to make those equations or that block diagram look a bit nicer, but after having done so I've rarely believed it was time well spent. Ned _______________________________________________ Ietf@xxxxxxxx https://www1.ietf.org/mailman/listinfo/ietf