Subject: [xml2rfc-dev] RFC 7991 issue #48: Schema Issue, RFC 7991, In Section 2.40.2, "quoteTitle"

From: [email-masked]
Date: Mon, 08 Oct 2018 07:47:27 -0700

This captures an issue noted during implementation, also described in
https://tools.ietf.org/html/draft-levkowetz-xml2rfc-v3-implementation#section-3.1.8

Specification: https://tools.ietf.org/html/rfc7991#section-2.40.2

---
In Section 2.40.2, "quoteTitle"

   The version two xml2rfc processors already support the attribute "quote-
   title".  The attribute name change introduces an incompatibility.  This
   in particular impacts existing bibxml reference files, which should work
   with both version 2 and 3 vocabulary documents.

   Proposal:        Change the attribute name back to the value supported
                    by the vocabulary version 2 modes of xml2rfc.

   Implementation:  The current version of xml2rfc converts "quote-title"
                    to "quoteTitle" during v2v3 conversion, but this is
                    really sub-optimal.
---

Regards,
	Henrik

---
This issue is tracked at:
   https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/48

Discussion should take place on this list.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 8 Oct 2018 17:21:01 +0200

>     with both version 2 and 3 vocabulary documents.

This is an interesting point which we really should discuss first and 
separately, as it also affects "seriesInfo", which is a much bigger change.

That said, this is not an incompatibility. It's awkward if you need to 
support both, yes. That said, it's not in RFC 7791, so apparently it 
slipped into xml2rfc between v2 and v3.

I see it used in the XML sources of ca. 10 RFCs.

FWIW, the reason why we switched to camel case was consistency with 
other attributes.

 > ...

Best regards, Julian

---

From: Jim Schaad <[email-masked]>
Date: Mon, 8 Oct 2018 10:23:12 -0700

> -----Original Message-----
> From: xml2rfc-dev <[email-masked]> On Behalf Of Julian
> Reschke
> Sent: Monday, October 8, 2018 8:21 AM
> To: [email-masked]; [email-masked]
> Subject: Re: [xml2rfc-dev] RFC 7991 issue #48: Schema Issue, RFC 7991, In
> Section 2.40.2, "quoteTitle"
> 
separately,
> as it also affects "seriesInfo", which is a much bigger change.

I am not sure that I see what is being said here.  Can you give an example?

Jim

> That said, this is not an incompatibility. It's awkward if you need to
support
> both, yes. That said, it's not in RFC 7791, so apparently it slipped into
xml2rfc
> between v2 and v3.
> FWIW, the reason why we switched to camel case was consistency with other
> attributes.
> 
>  > ...
> 
> Best regards, Julian
> 
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev

---

From: Julian Reschke <[email-masked]>
Date: Mon, 8 Oct 2018 19:59:09 +0200

> I am not sure that I see what is being said here.  Can you give an example?

I *believe* we have changes in seriesInfo that will cause references 
using the v3 vocabulary not to work properly with v2 processors - but 
it's a really long time ago that I looked into this, so my memory might 
trick me.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Mon, 8 Oct 2018 20:08:16 +0200

> it's a really long time ago that I looked into this, so my memory might 

I didn't. We move <seriesInfo> into <front>. Existing v2 <reference> 
files are already broken in that they use the deprecated format.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 8 Oct 2018 22:20:40 +0200

> files are already broken in that they use the deprecated format.

But the old <seriesInfo> placement is recognised, even if deprecated.

The issue with "quote-title" is that it's not in the schema at all.

FWIW, it was introduced in the xml2rfc v2 formatter on 2015-03-08.

Best regards,

	Henrik

---

From: Jim Schaad <[email-masked]>
Date: Mon, 8 Oct 2018 13:38:16 -0700

> From: Henrik Levkowetz <[email-masked]>
> Sent: Monday, October 8, 2018 1:21 PM
> To: Julian Reschke <[email-masked]>; Jim Schaad
> <[email-masked]>; [email-masked]
> >> it's a really long time ago that I looked into this, so my memory
> >> might trick me.
> >>
> >> Best regards, Julian
> >

Yes, but if the v2 processor does a DTD check it is still going to cause problems with the ones in the new location.  It may be that different bibxml entries are going to be needed for v2 and v3 because of validation of DTD/schema.

Ji

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 8 Oct 2018 23:41:34 +0200

On 2018-10-08 22:38, Jim Schaad wrote:

> Yes, but if the v2 processor does a DTD check it is still going to
> cause problems with the ones in the new location. It may be that
> different bibxml entries are going to be needed for v2 and v3 because
> of validation of DTD/schema.

Currently, reference files are only being created according to the v2
schema.  If we begin to create them according to v3 (because of richer
semantics) we may have to maintain separate, parallel bibxml repositories,
yes.

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Oct 2018 06:51:15 +0200

> semantics) we may have to maintain separate, parallel bibxml repositories,

That wiil lead to friction.

Maybe we should reconsider any change that makes those incompatible.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 07:20:07 +0200

> Maybe we should reconsider any change that makes those incompatible.

Ack; looking at those again makes sense, in view of the possibility of
having to maintain different reference repositories.

Best regards,

	Henrik

---

From: Heather Flanagan <[email-masked]>
Date: Tue, 9 Oct 2018 11:05:44 -0700

> having to maintain different reference repositories.

Hola a todos,

Two questions: first, I'm not sure what this means for when we do switch 
over to v3 - there will be changes to the reference format, so does that 
mean we'll have to be ready with a 100% switchover to an alternate 
repository when we go live? Second, when you say "reconsider any change 
that makes those incompatible" are you proposing changes to the v3 
vocabulary to avoid incompatible changes to v2?

Thanks!

Heather

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Oct 2018 20:11:58 +0200

> repository when we go live? Second, when you say "reconsider any change 

I guess it would be an additional repository.

> vocabulary to avoid incompatible changes to v2?

Yes. I believe we should undo the change to <seriesInfo> (moving under 
<front>), and just restore what we have in v2.

Best regards, Julian

---

From: Jim Schaad <[email-masked]>
Date: Tue, 9 Oct 2018 12:33:05 -0700

> Sent: Tuesday, October 9, 2018 11:12 AM
> To: Heather Flanagan <[email-masked]>; [email-masked]
> >>>> Currently, reference files are only being created according to the
> >>>> v2 schema.  If we begin to create them according to v3 (because of
> >>>> richer
> >>>> semantics) we may have to maintain separate, parallel bibxml
> >>>> repositories, yes.
> >>>> ...
> >> Ack; looking at those again makes sense, in view of the possibility
> >> of having to maintain different reference repositories.
> >>
> >
> > Hola a todos,
> >
> > Two questions: first, I'm not sure what this means for when we do
> > switch over to v3 - there will be changes to the reference format, so
> > does that mean we'll have to be ready with a 100% switchover to an
> > alternate repository when we go live? Second, when you say "reconsider
> > any change
> 

What about the seriesInfo that is in the front for identifying the document?  Are you going to move that to the same level as front, middle, back?

Jim

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2018 06:44:18 +0200

> What about the seriesInfo that is in the front for identifying the document?  Are you going to move that to the same level as front, middle, back?

No, my proposal would be to entirely back out the change, and to restore 
the attributes that we had on <rfc> instead.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Wed, 10 Oct 2018 13:27:08 +0200

> the attributes that we had on <rfc> instead.

I strongly support this.  I mention a number of issues related to the
changes to seriesInfo in draft-levkowetz-xml2rfc-v3-implementation-notes;
in Sections 3.1.10, 3.1.11, 3.1.12, 3.2.1, 4.1.5, 4.4.11, and 4.4.12.

Best regards,

	Henrik

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 11 Oct 2018 09:51:36 -0700

> in Sections 3.1.10, 3.1.11, 3.1.12, 3.2.1, 4.1.5, 4.4.11, and 4.4.12.

Before we go down this path, it might be worth reviewing some of the 
earlier discussions around <seriesInfo> in Ye Olde Archive. See:

https://www.rfc-editor.org/pipermail/rfc-interest/2014-December/008543.html

Does this information change your recommendation?

Thanks,

Heather

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 11 Oct 2018 09:52:51 -0700

> https://www.rfc-editor.org/pipermail/rfc-interest/2014-December/008543.html 

(To be clear, I don't expect anyone to have remembered that particular 
thread - this project has been going on for a very long time, and the 
original conversations are easily lost.)

-hf

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 11 Oct 2018 19:33:31 +0200

Hi Heather,

On 2018-10-11 18:51, Heather Flanagan wrote:
>>>> What about the seriesInfo that is in the front for identifying
>>>> the document? Are you going to move that to the same level as
>>>> front, middle, back?

Thank you.  Reviewed and understood.

Having thought about the points made in the thread, and the issues
I've listed in the draft, it turns out that the premise of that thread:

"The -14 draft has only one significant change: it makes <seriesInfo>
a child of <front>, and deprecated it as a child of <reference>. The
purpose of this is to allow the information for RFCs to come from just
one source instead of the disparate sources now."

while laudable, does not turn out to work very well in practice.  My
draft gives more details on the individual issues, but the summary is:

 * This makes v3 reference files incompatible with the v2 processor,
   which drives us into having to maintain separate parallel
   reference repositories.  (A point not made in the draft, but
   very relevant).

 * This makes use of the <seriesInfo> element to capture data which
   doesn't really fit into the <seriesInfo> concept, and makes the
   rules for the <seriesInfo> element really complicated.  (A number
   of the issues I ran into during implementation is a consequence
   of this).

 * This moves some essential _processing_ information for the document
   as a whole out of a fairly natural place as xml root element
   attributes into a much less obvious place.  (Also relevant to a
   number of the issues I ran into during implementation).

I think an intermediate solution, where <seriesInfo> is permitted
directly after <front> also under <rfc>, as within <reference>, and
there holds only what is actual series information the way it's
already used in v2, but not any of the additional attributes like
RFC number and docName, would work too.  That would make series
information for the document itself map directly to series information
as used in <reference>, without having any of the drawbacks mentioned
above.

Best regards,

	Henrik

---

From: Jim Schaad <[email-masked]>
Date: Thu, 11 Oct 2018 11:18:12 -0700

> From: xml2rfc-dev <[email-masked]> On Behalf Of Henrik
> Levkowetz
> Sent: Thursday, October 11, 2018 10:34 AM
> >>>>> From: xml2rfc-dev <[email-masked]> On Behalf Of
> >>>>> Julian Reschke
> >>>>> Subject: Re: [xml2rfc-dev] RFC 7991 issue #48: Schema Issue, RFC
> >>>>> 7991, In Section 2.40.2, "quoteTitle"
> >>>>>
> >>>>>>>>> v2 schema.  If we begin to create them according to v3
> >>>>>>>>> (because of richer
> >>>>>>> Ack; looking at those again makes sense, in view of the
> >>>>>>> possibility of having to maintain different reference repositories.
> >>>>>>>
> >>>>>> Hola a todos,
> >>>>>>
> >>>>>> switch over to v3 - there will be changes to the reference
> >>>>>> format, so does that mean we'll have to be ready with a 100%
> >>>>>> switchover to an alternate repository when we go live? Second,
> >>>>>> when you say "reconsider any change
> >>>>>> that makes those incompatible" are you proposing changes to the
> >>>>>> v3 vocabulary to avoid incompatible changes to v2?
> >>>>> Yes. I believe we should undo the change to <seriesInfo> (moving
> >>>>> under <front>), and just restore what we have in v2.
> >>>> What about the seriesInfo that is in the front for identifying the
> >>>> document? Are you going to move that to the same level as front,
> >>>> middle, back?
> >>> No, my proposal would be to entirely back out the change, and to
> >>> restore the attributes that we had on <rfc> instead.
> >> changes to seriesInfo in
> >> draft-levkowetz-xml2rfc-v3-implementation-notes;
> Having thought about the points made in the thread, and the issues I've listed in
> the draft, it turns out that the premise of that thread:
> 
> "The -14 draft has only one significant change: it makes <seriesInfo> a child of
> <front>, and deprecated it as a child of <reference>. The purpose of this is to
> allow the information for RFCs to come from just one source instead of the
> disparate sources now."
> 
> while laudable, does not turn out to work very well in practice.  My draft gives
> more details on the individual issues, but the summary is:
> 

Which ones made for the most problems?  Are they things that might want to be put in a reference anyway?

> I think an intermediate solution, where <seriesInfo> is permitted directly after
> <front> also under <rfc>, as within <reference>, and there holds only what is
> actual series information the way it's already used in v2, but not any of the
> additional attributes like RFC number and docName, would work too.  That
> would make series information for the document itself map directly to series
> information as used in <reference>, without having any of the drawbacks
> mentioned above.

It might be more natural to have it between the links and the front rather than after the front.  It seems to be similar info to what is there.

Jiim

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 11 Oct 2018 21:15:38 +0200

Hi Jim,

> want to be put in a reference anyway?

Of this kind, the <rfc> attributes category, number, and docName, and
I don't think they would be of interest in <reference>.

> It might be more natural to have it between the links and the front
> rather than after the front. It seems to be similar info to what is
> there.

I have no strong opinion on this, except I'd note that <reference>
has it after <front>, and that's the reason I suggested the same
location under <rfc>.  Makes things more regular, which might help
generation of xml from markdown, for instance.

Best regards,

	Henrik

---

From: Martin J. Dürst <[email-masked]>
Date: Fri, 12 Oct 2018 07:09:48 +0000

Hello everybody,

>     reference repositories.  (A point not made in the draft, but

This point is indeed extremely relevant. Needing two separate 
repositories is a very bad idea from an engineering perspective.

But while I was thinking "we really need to do everything we can to 
avoid this", I realized that there was one aspect that may make it 
really difficult NOT to have two separate repositories: Non-ASCII author 
names,... As far as I understand, v2 doesn't allow that, but it's one of 
the goals of v3.

Speaking from personal experience, I'd strongly prefer old RFCs I 
co-authored to be referenced from newer RFCs with my "real" 
(not-ASCII-only) name than with the ASCII simplification. I'm not sure 
this is possible with a single repository.

Regards,   Martin.

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 12 Oct 2018 09:19:36 +0200

Hi Martin,

> names,... As far as I understand, v2 doesn't allow that, but it's one of 

Actually, xml2rfc has has had a --utf8 switch for quite some time, so
even if you're not running the latest version, it should be possible
to use reference files containing non-ascii.

That has not been particularly useful until recently, but when the
IESG approved a change in draft submission policy last week, to allow
non-ascii characters in draft submission, it becomes more relevant.

I think it may be possible to change the default for the --utf8 switch
to be default on, going forward.

> this is possible with a single repository.

Hmm.  _That_ is a slightly more complex issue, because it also requires
those references to be manually corrected, rather than (as now)
automatically generated from the published information.

Best regards,

	Henrik

---

From: Heather Flanagan <[email-masked]>
Date: Fri, 19 Oct 2018 11:38:44 -0400

Hola a todos,

AFAICT, we are talking about two issues: whether it should revert to 
being quote-title versus a consistent-with-the-rest-of-the-spec 
quoteTitle; and, whether we should back out the v3 changes to 
<seriesInfo>. Both seem to have implications to the reference library.

For the smaller change around quote title, I like the idea of being more 
consistent, especially since it seems to be something that can be dealt 
with and has only used been used in 10 XML sources. But, I don't 
understand what implications that actually has when it comes to the 
bigger issue around <seriesInfo>. Could someone help me with this?

If we go ahead with the v3 changes to <seriesInfo>, we'll end up needing 
a parallel reference library. We seem to have two proposals on the table:

1) Revert the change entirely back to v2

2) An intermediate suggestion from Henrik:

Technically, we could itemize a third proposal to go ahead with the 
changes as defined in v3, but I don't think anyone has argued for that. 
Let me know if that's not correct.

So, second question: Would the intermediate suggestion also require a 
parallel reference library?

Thanks!

Heather

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 19 Oct 2018 17:52:13 +0200

Hi Heather,

> parallel reference library?

I believe we won't, no.  That was a factor in proposing this.

Best,

	Henrik