Subject: RE: Alternative formats for IDs

From: John C Klensin <[email-masked]>
Date: Wed, 11 Jan 2006 16:52:31 -0500

--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
> they find it most efficient and effective to switch to nroff
> for the final cleanup of the (ASCII) document format.

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.

Just my opinion, of course -- others may have other perspectives
or agendas.

   john

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

---

From: Dave Crocker <[email-masked]>
Date: Wed, 11 Jan 2006 14:53:38 -0800

>> needs. 

I do not recall seeing any input from the RFC Editor, on the XML2RFC mailing 
list, citing xml2rfc's deficiencies.

That makes it difficult to get those deficiencies fixed.

Please, please, please. Post those deficiencies to that list.

>   The

This point has been made a number of times, recently.  Its importance appears to 
remain under-appreciated.

IETF documents are subject to revision by new editors.  They currently find it 
difficult or impossible to ensure that they are starting from the correct master 
version.

To the extent that they must start from the .txt version, they have significant 
startup costs (with significant potential for introducing new errors) in order 
to convert the document to a format better suited to editing -- e.g., better 
able to manipulate the document's structure.

What the IETF community needs is to be able to obtain an accurate, 
revisable-form version of published documents.  xml2rfc is the best candidate 
for that form.  We therefore need to find a way for the RFC Editor to maintain 
the master version of RFCs in that form.

d/

-- 

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

---

From: Ned Freed <[email-masked]>
Date: Wed, 11 Jan 2006 15:26:15 -0800 (PST)

> Please, please, please. Post those deficiencies to that list.

Absolutely.

> difficult or impossible to ensure that they are starting from the correct master

These are issues even when the editor doesn't change.

> the master version of RFCs in that form.

While I agree that this needs to be the goal, when the RFC does use xml2rfc for
most of the editing process getting back a revised XML spec from the RFC Editor
that has all the changes made prior to the nroff step would be a HUGE
improvement. The time needed to retrofit all the RFC Editor changes into the
XML is nonnegligable - I wish I didn't epeak from recent experience, but I do.

For once let's not let the best be the enemy of the good.

				Ned

---

From: Dave Crocker <[email-masked]>
Date: Wed, 11 Jan 2006 15:53:06 -0800

when the RFC does use
> xml2rfc for

Agree completely.

1. Constraining the initial requirement -- for maintaining the master in xml2rfc 
format -- to apply only to documents that are submitted to the RFC Editor in 
that format -- that is, the RFC Editor does not create a conversion, they merely 
retain the format -- strikes me as far too pragmatic to disagree with, and for 
the reason you cite.

2. Given that the RFC Editor has the current practice of converting .txt 
submissions to nroff, it is equally reasonable to pursue their changing that 
conversion, to instead be into xml2rfc.  By 'equally reasonable' I mean as a 
parallel effort, on its own schedule.  As with any transition, the folks doing 
the work need to remain productive; this requires concessions in the details of 
the transition process.

3. I believe that we should not plan to prohibit nroff submissions, for the 
foreseeable future.  I'd rather deprecate the activity by virtue of community 
preference than by imposition of a rule.

d/

-- 

Dave Crocker

---

From: Douglas Otis <[email-masked]>
Date: Wed, 11 Jan 2006 15:54:01 -0800

On Jan 11, 2006, at 1:52 PM, John C Klensin wrote:
>> 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 they find it most efficient and  
>> effective to switch to nroff for the final cleanup of the (ASCII)  
>> document format.
>
> Bob,
>
> 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.

The xml2rfc tools permits injection of unformatted text using the  
following syntax:

   <figure title="">
     <artwork name="" type="" height="" width="" xml:space="preserve">
    This text represents the desired structure (without formatting)...

    blah, blah, blah...
     blah, blah, blah, ...

        blah, blah, blah, ...
     </artwork>
   </figure>

This mechanism allows authors to bypass the formatting limitations  
within the xlm2rfc tool.  As nroff is also a support input, nroff  
represents yet another method of achieving a desired output.

-Doug

---

From: Bill Fenner <[email-masked]>
Date: Thu, 12 Jan 2006 22:18:50 -0500

On 1/11/06, Dave Crocker <[email-masked]> wrote:
> conversion, to instead be into xml2rfc.

I don't think that converting to xml is the same class of work. 
There's a great deal of semantic information that should be encoded in
the XML that isn't in the submitted text and doesn't have to be in the
nroff.

  Bill

---

From: Dave Crocker <[email-masked]>
Date: Thu, 12 Jan 2006 21:44:05 -0800

> the XML that isn't in the submitted text and doesn't have to be in the

Strictly speaking, you are certainly right.

But I lived with nroff for quite a few years and I have had to do quite a few 
txt-2-xml2rfc conversions recently.  The difference in semantic encoding, that 
you cite, is offset by how easily nroff formatting errors can be made and not 
readily detected.

Mostly, this sort of conversion work has a small, relatively standardized 
"vocabulary" of text to add or change and one gets into a rhythm. From that 
perspective, I suspect the work is about the same.  The real difference is that 
debugging the xml2rfc conversion is probably MUCH easier.

d/

-- 

Dave Crocker