Subject: [xml2rfc-dev] RFC 7991 issue #49: Schema Issue, RFC 7991, In Section 2.42, <references>

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

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

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

---
In Section 2.42, <references>

   The v3 schema cannot properly model multiple reference subsections
   contained within one numbered section.  The v2 formatter handled this by
   silently inserting an enclosing section, but with the introduction of
   the preptool, which in theory should produce a master file from which
   various formatters would produce equivalent results, this becomes
   troublesome, as the automatic insertion of a container section is
   specified for the html formatter, in section 9.8. of RFC 7992, but not
   for the text formatter.  It would be much better to make the prepped xml
   explicitly show exactly what should be rendered, and not rely on
   formatters silently insert elements.

   Proposal:        Update the schema to make it possible for <references>
                    to contain <references>, and have the prepped xml
                    explicitly show both the encapsulating section and the
                    subsections.

   Implementation:  Implemented as proposed in the current version of
                    xml2rfc.
---

Regards,
	Henrik

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

Discussion should take place on this list.

---

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

>     for the text formatter.  It would be much better to make the prepped xml

...because essentially nothing is specified for the text formatter - so 
I do not agree this is a valid argument.

IMHO, the output of the text formatter should be equivalent to running 
the HTML format through an HTML-to-text converter.

> ...

Not convinced, because:

1) It hasn't been an issue up until now, and

2) allowing <references> to contain <references> creates a new nesting 
issue.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 8 Oct 2018 18:01:33 +0200

Hi Julian,

> the HTML format through an HTML-to-text converter.

I can understand this viewpoint; I haven't actually tried this, so have
no particular viewpoint on how feasible that would be.

However, this is still an issue, even if we disregard the text vs. html
specification part.
> 1) It hasn't been an issue up until now, and

So the reason it has not been an issue up to now is because the formatters
have been doing 'magic'.  The introduction of a normative xml format makes
that problematic.  I believe that the output of the preptool should ideally
not leave it up to the formatters to do any magic at all; the content should
fully and completely specify what would go into a formatted output.  This is
the underlying issue I see here; apologies if I haven't expressed it well.

> 2) allowing <references> to contain <references> creates a new nesting 

In that case, I think I'd be just as happy with having the <back> contain
a <section> that would hold the two <references>.

Best regards,

	Henrik

---

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

> -----Original Message-----
> From: xml2rfc-dev <[email-masked]> On Behalf Of Henrik
> Levkowetz
> Sent: Monday, October 8, 2018 9:02 AM
> To: Julian Reschke <[email-masked]>; [email-masked]
> Subject: Re: [xml2rfc-dev] RFC 7991 issue #49: Schema Issue, RFC 7991, In
> Section 2.42, <references>
> 
> Hi Julian,
> 
> > ...because essentially nothing is specified for the text formatter -
> > so I do not agree this is a valid argument.
> >
> I can understand this viewpoint; I haven't actually tried this, so have no
> particular viewpoint on how feasible that would be.
> 
> So the reason it has not been an issue up to now is because the formatters have
> been doing 'magic'.  The introduction of a normative xml format makes that
> problematic.  I believe that the output of the preptool should ideally not leave it
> up to the formatters to do any magic at all; the content should fully and
> completely specify what would go into a formatted output.  This is the
> underlying issue I see here; apologies if I haven't expressed it well.

I am sympathetic to the idea that the XML file should have the same structure as any resulting rendering and thus it makes sense to allow for references to be a child of references.

> > 2) allowing <references> to contain <references> creates a new nesting

I don't know that I see what the nesting problem that Julian is talking about here.  While it would be odd to have a three level deep references tree I don't know that this makes a problem for tooling purposes.  I would expect that the current RPC would reject this as not being of the correct form.

> 
> In that case, I think I'd be just as happy with having the <back> contain a
> <section> that would hold the two <references>.

I think this would be a problem as you could end up with a references section in the middle of the set of appendixes.

Jim

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 8 Oct 2018 19:21:49 +0200

Hi Jim,

Some small comments inline:

On 2018-10-08 19:16, Jim Schaad wrote:
> I am sympathetic to the idea that the XML file should have the same
> structure as any resulting rendering and thus it makes sense to allow
> for references to be a child of references.
> 
>> 
>>> 2) allowing <references> to contain <references> creates a new
>>> nesting issue.
> 
> I don't know that I see what the nesting problem that Julian is
> talking about here. While it would be odd to have a three level deep
> references tree I don't know that this makes a problem for tooling
> purposes. I would expect that the current RPC would reject this as
> not being of the correct form.

I could easily enforce this in the preptool, if it is desired.  I have
no particular preferences on limiting the nesting depth or not.

>> In that case, I think I'd be just as happy with having the <back>
>> contain a <section> that would hold the two <references>.
> 
> I think this would be a problem as you could end up with a references
> section in the middle of the set of appendixes.

Ack.  Good point.

	Henrik

---

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

> a <section> that would hold the two <references>.

I thought about that as well, but then people might get the impression 
that they can control the placement of the references section.

Again; I don't see anything broken here.

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 16:12:22 +0200

> Again; I don't see anything broken here.

This is one of three issues that come down to one more basic question:

Should the prepped format fully define the RFC content, or should it leave
some things up to the formatters?

The current specification results in a prepped XML file which does not
contain fully specified renderable content for these 3 parts:

 * Table of Contents
 * References
 * Index

For all of these, the specification requires that the formatter create
some of the content on-the-fly when they render the XML content, 
effectively adding derived content that was not present in the prepped
XML.

RFC 7998 says in Section 1, Introduction:

   "                                                    ... In order to
   ensure as much uniformity in text output as possible across formats
   (and with the canonical XML itself), there is a desire that the
   translation from XML into the other formats will be straightforward
   syntactic translation.  To make that happen, a good amount of data
   will need to be in the XML format that is not there today.  That data
   will be added by a program called the "prep tool", which will often
   run as a part of the xml2rfc process."

Given this statement, it seemed to me that we should make the prepped
format as complete as possible.  The current preptool implemented in
xml2rfc does this; it inserts a complete representation of ToC (if
requested), an enclosing references section, and an Index (if requested).

Issue #49 is a result of implementing this, as providing the enclosing
References section could not be done with the original schema specification.

If we don't provide a way to actually include fully specified ToC,
References, and Index in the prepped output, we need to go back and
look at what RFC 7998 says about this, and reconsider the goal of
running the preptool.

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Oct 2018 17:05:04 +0200

> some things up to the formatters?

IMHO: it depends on how intrusive the change to the vocabulary is.

> effectively adding derived content that was not present in the prepped

Yes.

Note that of the three examples, two fall into the same category (index, 
ToC), and the other one (references) is very different.

For index and ToC, the formatter output is essentially unspecified. I 
don't think this is a problem, *because* it's fully derived content that 
is only decorative. Whether it's there or not does not affect the actual 
meaning of the document; it's just to help navigation.

For references, the situation is a slightly different; the output of the 
prep tool does not contain the container element if there are multiple 
references sections. We *did* discuss this, and we concluded that 
changing the vocabulary just so that the formatter doesn't need to 
derive it wasn't necessary.

Reminder: as author of a processor you are free to augment the 
intermediate format with any information you want. But that doesn't mean 
it needs to surface in the author visible vocabulary.

> requested), an enclosing references section, and an Index (if requested).

It would be helpful if you could paste snippets for ToC and index - to 
keep a valid XML representation, they'd need to live in <note>/<section> 
right? Is inserting these containers not a problem in itself? What 
happens if you re-run the preptool on the prepped XML?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 17:56:39 +0200

> it needs to surface in the author visible vocabulary.

Agreed.  But that's a somewhat different issue.  Here I'm concerned with
the incompleteness of the published archival XML, in view of the RFC7998
statement below, rather than whatever bells processors may choose to add.

> happens if you re-run the preptool on the prepped XML?

For both the preptool and the v2v3 converter, I've tried to make them
idempotent, so you should be able to run the output through the processor
again with no change.

Here's a ToC snippet.  I'm not claiming this is optimal; if we reach
consensus on what 7998 requires, we can look at other implementations:

    <boilerplate>
    <!-- Copyright and Status of this Memo sections snipped -->
      <section numbered="false" removeInRFC="false" toc="exclude" pn="section-boilerplate.3">
        <name slugifiedName="name-table-of-contents">Table of Contents</name>
        <ul bare="true" empty="true" spacing="compact" pn="section-boilerplate.3-1">
          <li pn="section-boilerplate.3-2">
            <t pn="section-boilerplate.3-3">
               <xref derivedContent="1" format="counter" target="section-1"/>.  RFC 2119 key words
            </t>
          </li>
          <li pn="section-boilerplate.3-4">
            <t pn="section-boilerplate.3-5">
               <xref derivedContent="2" format="counter" target="section-2"/>.  Unordered list with sub-elements
            </t>
          </li>
          <li pn="section-boilerplate.3-6">
            <t pn="section-boilerplate.3-7">
               <xref derivedContent="3" format="counter" target="section-3"/>.  Ordered list with sub-elements
            </t>
          </li>
          <!-- Additional entries snipped -->
        </ul>
      </section>
    </boilerplate>

And here's the start of an index:

   <back>
    <!-- Earlier appendix snipped -->
    <section numbered="false" removeInRFC="false" toc="exclude" pn="section-appendix.b">
      <name slugifiedName="name-index">Index</name>
      <t anchor="rfc.index.index" pn="section-appendix.b-1">
        <xref derivedContent="L" format="default" target="rfc.index.L">L</xref>
        <xref derivedContent="T" format="default" target="rfc.index.T">T</xref>
      </t>
      <ul bare="true" empty="true" spacing="compact" pn="section-appendix.b-2">
        <li pn="section-appendix.b-3">
          <t anchor="rfc.index.L" pn="section-appendix.b-4">
            <xref derivedContent="L" format="default" target="rfc.index.L">L</xref>
          </t>
          <ul bare="true" empty="true" spacing="compact" pn="section-appendix.b-5">
            <li pn="section-appendix.b-6">
              <t pn="section-appendix.b-7">list</t>
              <t pn="section-appendix.b-8">
                <xref derivedContent="list" format="default" target="section-a.7-96">list</xref>
                <xref derivedContent="list" format="default" target="section-a.7-81">list</xref>
              </t>
   ....

Best regards,

	Henrik

---

From: Paul Hoffman <[email-masked]>
Date: Tue, 9 Oct 2018 16:01:10 +0000

> statement below, rather than whatever bells processors may choose to add.

That is indeed a different issue. Is the problem that you're trying to solve here that an RFC that has a reference to BCP X or STD Y does not say what are the contents of X or Y at the time of RFC publication?

--Paul Hoffman

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 18:13:55 +0200

Hi Paul,

On 2018-10-09 18:01, Paul Hoffman wrote:
> That is indeed a different issue. Is the problem that you're trying
> to solve here that an RFC that has a reference to BCP X or STD Y does
> not say what are the contents of X or Y at the time of RFC
> publication?

Not at all.

The current schema does not permit the generation of a prepped XML that has
the content and structure that a renderer is expected to render.

You could say (see below) that the schema does not make it possible to
produce a prepped XML that permit a "straightforward syntactic translation"
(RFC 7998).

For this particular issue (#49), the XML of a document with multiple
reference section cannot with the current schema capture the enclosing
References section which a formatter is expected to show (and for that
matter, which a ToC is expected to show, correctly numbered, with correctly
numbered Normative and Informative sub-sections).

 * Table of Contents
 * References
 * Index

   "                                                    ... In order to

---

From: Jim Schaad <[email-masked]>
Date: Tue, 9 Oct 2018 09:53:41 -0700

> Sent: Tuesday, October 9, 2018 7:12 AM
> To: Julian Reschke <[email-masked]>; [email-masked]; RFC Editor
> <[email-masked]>
> >> So the reason it has not been an issue up to now is because the
> >> formatters have been doing 'magic'.  The introduction of a normative
> >> xml format makes that problematic.  I believe that the output of the
> >> preptool should ideally not leave it up to the formatters to do any
> >> magic at all; the content should fully and completely specify what
> >> would go into a formatted output.  This is the underlying issue I see here;
> apologies if I haven't expressed it well.
> >>
> Should the prepped format fully define the RFC content, or should it leave some
> things up to the formatters?
> 
> The current specification results in a prepped XML file which does not contain
> fully specified renderable content for these 3 parts:
> 
>  * Table of Contents
>  * References
>  * Index
> 
> For all of these, the specification requires that the formatter create some of
> the content on-the-fly when they render the XML content, effectively adding
> derived content that was not present in the prepped XML.
> 
> Given this statement, it seemed to me that we should make the prepped format
> as complete as possible.  The current preptool implemented in xml2rfc does
> this; it inserts a complete representation of ToC (if requested), an enclosing
> references section, and an Index (if requested).
> 
> If we don't provide a way to actually include fully specified ToC, References,
> and Index in the prepped output, we need to go back and look at what RFC 7998
> says about this, and reconsider the goal of running the preptool.

The problem is that I don't think that you can do a fully specified ToC or Index as how these are going to be presented are going to be extremely renderer specific.  What is there for HTML vs a paged format are completely different and for the paged format requires that the page no be computed.   Also, how indexing is presented for multiple levels can be very different between renderers. I don't believe that References suffers from the same problem.

Jim

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 19:28:54 +0200

Hi Jim,

On 2018-10-09 18:53, Jim Schaad wrote:
> The problem is that I don't think that you can do a fully specified
> ToC or Index as how these are going to be presented are going to be
> extremely renderer specific. What is there for HTML vs a paged format
> are completely different and for the paged format requires that the
> page no be computed. Also, how indexing is presented for multiple
> levels can be very different between renderers. I don't believe that
> References suffers from the same problem.

Yes, well, I expect I'll run headlong into this, and find out how big an
issue it is, when I've now started to work on the v3 HTML renderer, as
the current approach will be generating the html from the same XML ToC as
the v3 text renderer ,:-)

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Oct 2018 19:30:21 +0200

> statement below, rather than whatever bells processors may choose to add.

And I don't think that the absence of ToC and Index are a problem. Not 
do I think that inserting the container for the references is a problem.

> ..

1) I then believe that we need to clarify what <boilerplate> should 
contain. I never considered the ToC to be part of it.

2) How exactly does this content help in producing the ToC for HTML 
(which will require special CSS) or in paged formats (where one would 
expect page numbers)?

>                  <xref derivedContent="list" format="default" target="section-a.7-81">list</xref>

Now do you prevent additional index sections from being inserted when 
the preptool is run multiple times?

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Tue, 9 Oct 2018 19:44:58 +0200

> do I think that inserting the container for the references is a problem.

Problem?  Depends on what you expect from the prepped archival document.

You could use v2 xml as archival XML, if you wanted; it would not be a
'problem', either.

But what is really desired from the archival format?

> contain. I never considered the ToC to be part of it.

Yes.  I'd be perfectly happy with building this in a <note> or in some
other fashion, if that would be cleaner.

> (which will require special CSS) or in paged formats (where one would 

Of course the details of the rendering based on this will be specific to
the individual renderers.  You can look at the v3 text-renderer code now;
I can point at the html-renderer code when I've written it.  The
representation above is true to the document structure and provides the
<xref>s needed for linkage, which is where any ToC rendering needs to
start.

> the preptool is run multiple times?

There are two reasonable approaches, I think: skip new insertion if already
prepped, and replace wholly if already prepped.  The current code does the
first, but I don't have any particular preference in the matter.

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Tue, 9 Oct 2018 19:53:53 +0200

> But what is really desired from the archival format?

That's a good question.

I already wasn't a fan of the "insert derived content", because, well, 
it can be derived.

The difference here is that the information you are missing truly is 
insignificant for the meaning of the RFC.

> <xref>s needed for linkage, which is where any ToC rendering needs to

In a paged medium, I'd expect the inserted page number on the right hand 
side, with the line filled by dots (missing a more technical term).

This really is different from a regular list.

> first, but I don't have any particular preference in the matter.

The point was: on an input document, how do you detect that a <section> 
inside <back> already contains an index?

Best regards, Julian

---

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

Hola a todos,

> But what is really desired from the archival format?

Complete content. I tried to capture this in RFC 7990, Section 6.1 "XML 
for RFCs"

Key points regarding the XML format:

    o  The canonical format for RFCs is XML using the xml2rfc version 3
       (xml2rfc v3) vocabulary.  The XML file must contain all
       information necessary to render a variety of formats; any question
       about what was intended in the publication will be answered from
       this format.

    o  Authors may submit documents using the xml2rfc v2 vocabulary, but
       the final publication will be converted to use the xml2rfc v3
       vocabulary.

    o  SVG is supported and will be embedded in the final XML file.

    o  There will be automatically generated identifiers for sections,
       paragraphs, figures, and tables in the final XML file.

    o  The XML file will not contain any xml2rfc v3 vocabulary elements
       or attributes that have been marked deprecated.

    o  A DTD will no longer be used.  The grammar will be defined using
       RELAX NG [RNC].

    o  The final XML file will contain, verbatim, the appropriate
       boilerplate as applicable at time of publication specified by RFC
       7841 [RFC7841] or its successors.

    o  The final XML will be self-contained with all the information
       known at publication time.  For instance, all features that
       reference externally defined input will be expanded.  This
       includes all uses of xinclude, src attributes (such as in
       <artwork> or <sourcecode> elements), include-like processing
       instructions, and externally defined entities.

    o  The final XML will not contain comments or processing
       instructions.

    o  The final XML will not contain src attributes for <artwork> or
       <sourcecode> elements.

Does this answer your question?

Heather

---

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

Hi Heather,

> Does this answer your question?

For me, I guess it does; for me it means that ToC, enclosing References
section, and Index should all be part of the canonical format.  For me,
RFC 7998 Section 1, Introduction, points in the same direction.

Best regards,

	Henrik

---

From: Jim Schaad <[email-masked]>
Date: Tue, 9 Oct 2018 11:26:56 -0700

> From: xml2rfc-dev <[email-masked]> On Behalf Of Julian
> Reschke
> Sent: Tuesday, October 9, 2018 10:54 AM
> To: Henrik Levkowetz <[email-masked]>; [email-masked]; RFC
> Editor <[email-masked]>
> >>>> intermediate format with any information you want. But that doesn't
> >>>> mean it needs to surface in the author visible vocabulary.
> >>>
> >>> Agreed.  But that's a somewhat different issue.  Here I'm concerned
> >>> with the incompleteness of the published archival XML, in view of
> >>> the RFC7998 statement below, rather than whatever bells processors may
> choose to add.
> >>
> >> And I don't think that the absence of ToC and Index are a problem.
> >> Not do I think that inserting the container for the references is a
problem.
> I already wasn't a fan of the "insert derived content", because, well, it
can be
> derived.
insignificant
> for the meaning of the RFC.
> 
>  > ...
> > Of course the details of the rendering based on this will be specific
> > to the individual renderers.  You can look at the v3 text-renderer
> > code now; I can point at the html-renderer code when I've written it.
> > The representation above is true to the document structure and
> > provides the <xref>s needed for linkage, which is where any ToC
> > rendering needs to start.
> 

Additionally, the rendering now needs to detect this both of these as
special sections and not do the normal rendering on them.  If they just do
the derivation themselves they can treat it however they want.  This would
include things like depth of ToC, different formatting for different levels.
I agree w/ Julian that this seems to be totally un-interesting from an
archival point of view.

> >>>             <ul bare="true" empty="true" spacing="compact"
pn="section-
> appendix.b-5">
> >>>                   <xref derivedContent="list" format="default"
target="section-
> a.7-96">list</xref>
> >>>                   <xref derivedContent="list" format="default"
target="section-
> a.7-81">list</xref>
> > There are two reasonable approaches, I think: skip new insertion if
> > already prepped, and replace wholly if already prepped.  The current
> > code does the first, but I don't have any particular preference in the
matter.
> The point was: on an input document, how do you detect that a <section>
inside
> <back> already contains an index?

So you need to detect that there is an index or a ToC and change behavior
based on if it is there or not?  If it was there I think that replacing it
with a newly computed one is far preferable.  If I change things in the prep
version, like insert a new index reference, then it should be picked up and
rendered.  Similarly if I change the ordering of sections this needs to be
detected as dealt with as well.

Jim

> 
> Best regards, Julian
> 
> _______________________________________________
> xml2rfc-dev mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc-dev

---

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

> Sent: Tuesday, October 9, 2018 11:26 AM
> To: Heather Flanagan <[email-masked]>; [email-masked]
> > Complete content. I tried to capture this in RFC 7990, Section 6.1
> > "XML for RFCs"
> >
> For me, I guess it does; for me it means that ToC, enclosing References section,
> and Index should all be part of the canonical format.  For me, RFC 7998 Section
> 1, Introduction, points in the same direction.

I agree w/ the References.  I don't agree w/ the ToC or index as this information can be derived from the XML file in a deterministic fashion and would not change.

Jim

---

From: Julian Reschke <[email-masked]>
Date: Wed, 10 Oct 2018 07:01:42 +0200

> I agree w/ the References.  I don't agree w/ the ToC or index as this information can be derived from the XML file in a deterministic fashion and would not change.

The same is true for <references>. We have proof of that because we've 
been doing it without problems for over 10 years.

Best regards, Julian

---

From: Heather Flanagan <[email-masked]>
Date: Thu, 11 Oct 2018 10:20:30 -0700

On 10/9/18 10:01 PM, Julian Reschke wrote:
>> I agree w/ the References.  I don't agree w/ the ToC or index as this 
>> information can be derived from the XML file in a deterministic 
>> fashion and would not change.
>

I am willing to agree re: ToC, but references must be expanded in the 
document. Anything that requires pulling in external information, e.g., 
from the bibxml library, must be incorporated in the final XML.

-Heather

---

From: Julian Reschke <[email-masked]>
Date: Thu, 11 Oct 2018 20:17:51 +0200

> from the bibxml library, must be incorporated in the final XML.

Yes, nobody argues with that.

Henrik's issue is only about inserting a container when there is more 
than one references section.

Best regards, Julian

---

From: Paul Hoffman <[email-masked]>
Date: Thu, 11 Oct 2018 21:52:53 +0000

> I agree w/ the References.  I don't agree w/ the ToC or index as this information can be derived from the XML file in a deterministic fashion and would not change.

+1 to Jim's formulation.

--Paul Hoffman

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Oct 2018 05:59:04 +0200

>> I agree w/ the References.  I don't agree w/ the ToC or index as this information can be derived from the XML file in a deterministic fashion and would not change.

I keep disagreeing, because what Jim says for Toc and Index is trivially 
true for References as well. If you disagree, please explain why.

Best regards, Julian

---

From: Jim Schaad <[email-masked]>
Date: Thu, 11 Oct 2018 21:06:38 -0700

> Sent: Thursday, October 11, 2018 8:59 PM
> To: Paul Hoffman <[email-masked]>; XML Developer List <xml2rfc-
> [email-masked]>
> Subject: Re: [xml2rfc-dev] [Ext] RFC 7991 issue #49: Schema Issue, RFC
7991, In
> >>> For me, I guess it does; for me it means that ToC, enclosing
> >>> References section, and Index should all be part of the canonical
> >>> format.  For me, RFC 7998 Section 1, Introduction, points in the same
> direction.
> >>
> information can be derived from the XML file in a deterministic fashion
and
> would not change.
true for
> References as well. If you disagree, please explain why.

If I build a third party tool that does things like extract the TOC from the
section/reference markers, if the extra references is there then I don't
need to special case anything.  If it is not there then I need to special
case things.   This is one case where adding the extra reference element
makes things easier for external tool writers.  These people are not going
to be doing the same thing for indexes because that would require doing a
full rendering. 

Jim

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Oct 2018 06:25:14 +0200

> need to special case anything.  If it is not there then I need to special

Yes. About two lines.

> to be doing the same thing for indexes because that would require doing a

The question is whether better support for these tools justifies a 
change to the grammar which I believe is unnecessary and might cause 
more confusion (for instance, with respect to what can nested where).

Best regards, Julian

---

From: Henrik Levkowetz <[email-masked]>
Date: Fri, 12 Oct 2018 08:49:17 +0200

Hi Heather,

A bit more of an explanation and background information, below:

Yes.

Up until ca. RFC 3500, references weren't split up into separate
normative and informative references.  Then some people starting
to do so, and xml2rfc rendered those as 2 top-level numbered sections.

Some people felt that there should just be one top level 'References'
section, with the Normative and Informative parts as sub-sections.

This was not implemented by updating the schema, but by doing 'magic'
inside xml2rfc: If there was one <references> element, it was rendered
as a top-level section; if there were multiple <references>, they
were rendered as sub-sections inside a top-level section.

I feel that it's time to update the schema so that the published
XML reflects this, instead of having rendering tools continue to add
magic.  Instead of this:

<references>
  <name>Normative References</name>
  <!-- reference instances go here -->
</references>

<references>
  <name>Informative References</name>
  <!-- reference instances go here -->
</references>

being rendered with a magically appearing top-level "References"
section, we should have this in the prepped output and published
XML:

<references>
  <name>References</name>

  <references>
    <name>Normative References</name>
    <!-- reference instances go here -->
  </references>

  <references>
    <name>Informative References</name>
    <!-- reference instances go here -->
  </references>

<references>

I believe this conforms to this point from 7990, in that a renderer
must otherwise know that it needs to do 'magic' to produce the
top-level "References" section:

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Oct 2018 09:14:09 +0200

>      <!-- reference instances go here -->

Henrik,

thanks for adding more explanations so everybody knows what we're 
talking about :-)

(And FWIW, I sort of agree that the current behavior was a hack just in 
order to avoid touching the vocabulary).

That said:

1. The insertion of the container really truly is trivial.

2. *If* we change the vocabulary, we'll need to make sure that we don't 
make things more confusing. For instance, would <reference> be allowed 
as sibling of <references>? And what if you had multiple instances of 
<references> inside <back>? Would that still be allowed, and how would 
it be rendered?

Best regards, Julian

---

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

Hi Julian,

Snipping some, in order to talk about the particular points you
raised:

...

> as sibling of <references>?

I'd say no for <reference>.

And <references> should have <references> siblings only within an outer
enclosing <references> element.

> And what if you had multiple instances of 

I'd say to disallow this in v3, and let the v2v3 converter transform
it to a v3-compliant form when found in v2.

How would you prefer to do it?

Best regards,

	Henrik

---

From: Julian Reschke <[email-masked]>
Date: Fri, 12 Oct 2018 09:36:07 +0200

> How would you prefer to do it?

I note that none of these can be trivially expressed in the grammar, so 
I fear it causes confusion.

There's also the new <referencegroup> element for which we'd need 
additional constraints.

So I remain unconvinced that this is an improvement.

Best regards, Julian

---

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

> I fear it causes confusion.

I was thinking (in Relax NG compact):

   back =
     element back {
       attribute xml:base { text }?,
       attribute xml:lang { text }?,
       displayreference*,
       references,
       section*
     }

   references =
     element references {
       attribute xml:base { text }?,
       attribute xml:lang { text }?,
       attribute pn { text }?,
       attribute anchor { xsd:ID }?,
       attribute title { text }?,
       name?,
       (references+ | (reference | referencegroup)*)
     }

Best regards,

	Henrik