Subject: [TOOLS-DEVELOPMENT] V2toV3 conversion -00

From: Robert Sparks <[email-masked]>
Date: Mon, 23 Jun 2014 15:58:13 -0500

Lightweight beginning attached. Please review and identify what needs to 
be added.

RjS

---

From: Julian Reschke <[email-masked]>
Date: Mon, 23 Jun 2014 23:04:18 +0200

> Lightweight beginning attached. Please review and identify what needs to

I think this needs to be put aside until we actually know what the delta 
between v2 and v3 is.

If we don't mess up things, this will be a very simple tool, which 
doesn't even deserve a SOW.

Best regards, Julian

---

From: Robert Sparks <[email-masked]>
Date: Mon, 23 Jun 2014 16:18:56 -0500

On 6/23/14, 4:04 PM, Julian Reschke wrote:
> I think this needs to be put aside until we actually know what the 
> delta between v2 and v3 is.
>
I hope you're right, and I hope we're _very_ close to knowing what that 
delta is. Please help push bringing that to closure.

The thinking around what this project would look like if you turn out to 
be wrong needs to be beyond square-one when
we do have that closure. So, please make that assumption and help flesh 
this out, unless you think you cause the last of the definition of v3 to 
finish very quickly.

I suspect converting lists will turn out to be easy. Removing <vspace/> 
might be less easy, and dealing with the changes in <figure> 
(particularly mapping attributes) may turn out to be hard. I'd be happy 
if that turns out to not be the case.

---

From: "Heather Flanagan (RFC Series Editor)" <[email-masked]>
Date: Mon, 23 Jun 2014 14:20:01 -0700

> doesn't even deserve a SOW.

While we have a couple of important things to get through with v3
(tables and figures, as well as input from the review you've been
planning), my impression is that the majority of the v3 doc is fairly
stable at this point.  I think there is enough of a delta, as evinced by
the various deprecated items and suggestions for alternatives that are
mentioned in the v3 draft, that we can at least start thinking about the
tool needed to do the conversion.  I think will be a big enough set of
changes that a tool to make life easier for authors and editors is
important, and probably not so small that we can avoid a SoW.

-Heather

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 23 Jun 2014 23:25:33 +0200

Hi Robert,

> Lightweight beginning attached. Please review and identify what needs to 

Some meta thoughts:

I have assumed that xml2rfc will be able to handle both v2 and v3 documents,
validating them against different dtds, and if necessary having different
code paths for elements that should be treated differently.  I believe the
overlap is so large that anything else doesn't quite make sense.

- That first begs the question of why a conversion is needed.

- After that, given that xml2rfc already has a mode where it emits a
  standalone xml file, after having processed and included all external
  references, does it make sense ( _if_ conversion is necessary given
  the point immediately above) to simply make converted document output
  another xml2rfc output mode?

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Mon, 23 Jun 2014 23:26:03 +0200

> delta is. Please help push bringing that to closure.

If it was my call, any valid V2 document would be a valid V3 document.

> might be less easy, and dealing with the changes in <figure>

My understanding of "deprecated" is that it's still allowed, but might 
go away in the future. That is, you don't need to remove <vspace>. 
<http://tools.ietf.org/html/draft-hoffman-xml2rfc-08#appendix-E> kind of 
supports this; it contains <vspace>.

If my interpretation is wrong we better clarify that ASAP.

> ...

Best regards, Julian

---

From: Tony Hansen <[email-masked]>
Date: Mon, 23 Jun 2014 23:25:23 -0400

On 6/23/14, 5:26 PM, Julian Reschke wrote:
> <http://tools.ietf.org/html/draft-hoffman-xml2rfc-08#appendix-E> kind 
> of supports this; it contains <vspace>.
>

There are two aspects to deprecated that people should be aware of:

1) The deprecated elements are still supported by the processor.
2) The RFC Editor will not allow the deprecated elements to appear in 
the canonical xml files.

See sections 1.2.3 and C.1 of draft-hoffman-xml2rfc.

     Tony Hansen

---

From: Tony Hansen <[email-masked]>
Date: Mon, 23 Jun 2014 23:28:09 -0400

> - That first begs the question of why a conversion is needed.
Section C.1 of draft-hoffman-xml2rfc:

    The canonical format for RFCs have a number of restrictions that the
    RFC Processor needs to enforce before a document can be published in
    its final form.  In this "final" mode, the processor will give a hard
    error when an input XML file has:

    o  any element or attribute listed as "deprecated" in the v3
       vocabulary

>    another xml2rfc output mode?

Absolutely.

     Tony Hansen

---

From: Tony Hansen <[email-masked]>
Date: Tue, 24 Jun 2014 01:23:09 -0400

On 6/23/14, 5:18 PM, Robert Sparks wrote:
> I hope you're right, and I hope we're _very_ close to knowing what 
> that delta is. Please help push bringing that to closure.
>
> The thinking around what this project would look like if you turn out 
> to be wrong needs to be beyond square-one when
> we do have that closure. So, please make that assumption and help 
> flesh this out, unless you think you cause the last of the definition 
> of v3 to finish very quickly.
>
> I suspect converting lists will turn out to be easy. Removing 
> <vspace/> might be less easy, and dealing with the changes in <figure> 
> (particularly mapping attributes) may turn out to be hard. I'd be 
> happy if that turns out to not be the case.

As part of my review of the two xml2rfc v2 and v3 drafts, I wanted to 
understand more thoroughly the differences between them, in particular 
with respect to what was deprecated.

So I wrote a prototype of a V2 to V3 converter that removes all 
deprecated elements and replaces them with their intended replacements. 
It can be found at <http://zinfandel.tools.ietf.org/~tonyh/convertv2v3/>.

Shortcomings:
     *) attributes will always be surrounded with single quotes in the 
output
     *) inherited list styles are not handled well

The option "Output Comments About Conversions" will cause the output to 
be sprinkled with comments such as:

     <!-- CONVERT moving PI rfc tocInclude='yes'  to <rfc> element -->
     <!-- CONVERT title= moved to <titleelement> -->

Search for the string CONVERT to find them.

There may also be WARNINGS in the output, such as

     <!-- CONVERT WARNING: unknown <list style=numbered> value -->

I THINK that it is otherwise complete and working okay. A link to the 
code can be found at the bottom of the page.

     Tony Hansen

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Jun 2014 07:43:33 +0200

> See sections 1.2.3 and C.1 of draft-hoffman-xml2rfc.

Ack. Right. Sorry.

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Jun 2014 07:45:47 +0200

> overlap is so large that anything else doesn't quite make sense.

I think this assumption is wrong. In general, when elements change in v3 
is because their content model was extended. That implies you can use 
the same code to process v2 and v3.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 24 Jun 2014 11:38:10 +0200

Hi Julian,

> the same code to process v2 and v3.

So I understand you as saying that we should be able to assume that xml2rfc will
be able to handle both v2 and v3 documents, validating against the v3 schema,
and using the same code paths.  Did I get that right?

Best regards,

	Henrik

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 24 Jun 2014 11:48:51 +0200

Whoo!  Cool :-)

	Henrik

On 2014-06-24 07:23 Tony Hansen said:
> _______________________________________________
> TOOLS-DEVELOPMENT mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-development
>

---

From: Julian Reschke <[email-masked]>
Date: Tue, 24 Jun 2014 11:51:03 +0200

> and using the same code paths.  Did I get that right?

That's how I'll do things in my XSLT code. I'm pretty sure it would be 
the right approach for the Python code as well.

Best regards, Julian