Subject: [rfc-i] deprecating relref

From: Peter Saint-Andre <[email-masked]>
Date: Thu, 8 Apr 2021 18:20:55 -0600

Hi all,

The RFC XML and Style Guide change management team [1] recently
discussed the differences between xref and relref elements [2] and
determined that (a) relref has not been used in source documents
provided by authors and (b) if it had been used, the xml2rfc tool would
have transformed relref to xref while adding any of the attributes
defined in RFC 7991 for relref but not xref (sectionFormat, section,
relative, derivedLink). Therefore our recommendation is to deprecate
relref in 7991bis and likely add some or all of the relref attributes to
xref.

Peter

[1]
https://mailarchive.ietf.org/arch/msg/rfc-interest/_13Fne0Pxv233coED2BiRY_IJR4/

[2] https://github.com/rfc-format/draft-iab-xml2rfc-v3-bis/issues/172

_______________________________________________
rfc-interest mailing list
[email-masked]
https://www.rfc-editor.org/mailman/listinfo/rfc-interest

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 9 Apr 2021 06:41:57 +0200

On 9. Apr 2021, at 02:20, Peter Saint-Andre <[email-masked]> wrote:
> 
> Therefore our recommendation is to deprecate
> relref in 7991bis

+1

> and likely add some or all of the relref attributes to
> xref.

De facto v3 already has those attributes, and I hope we can simply stick to those, specifically:

section
sectionFormat (of, comma, parens, bare)

Usage in published RFCs so far:

 336 sectionFormat=“bare"
 391 sectionFormat=“comma"
42726 sectionFormat=“of"
   1 sectionFormat=“parens”

The value for sectionFormat=“of” is inflated as this is the default value, I think I'm only seeing 2215 actual section references in total, so it should really be 1487.
The one occurrence of “parens” in RFC 8768 is interesting as this is really a numbered Table reference (which is not supported today so this is in prose), adorned by a section number.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 9 Apr 2021 09:17:44 +0200

> sectionFormat (of, comma, parens, bare)

Yes. These were proposed during the developmen of 7991 (and I believe at
some point in an unreleased draft), but later replaced by <relref>.

> The value for sectionFormat=“of” is inflated as this is the default value, I think I'm only seeing 2215 actual section references in total, so it should really be 1487.

Inserting the "sectionFormat" default when indeed no section is
referenced IMHO is a bug in the preptool.

> ...

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 9 Apr 2021 10:11:19 +0200

> On 2021-04-09, at 09:17, Julian Reschke <[email-masked]> wrote:
> 
>> 42726 sectionFormat=“of"
>>    1 sectionFormat=“parens”
>> 

Curious: How do you think this should be implemented?
Should the dependency of the presence of @sectionFormat on the presence of @section be hand-coded, or is there a way to do this in a schema-driven way?  
(As you can see, my Relax-NG is getting a bit rusty.  
This could easily be done in CDDL, but that doesn’t support XML.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Fri, 9 Apr 2021 10:18:40 +0200

> This could easily be done in CDDL, but that doesn’t support XML.)

I don't think you can do this with RelaxNG based information alone.

FWIW, I believe the direction to insert *all* defaults is totally
misguided; it leads to "canonical" XML that's full with completely
useless information.

Best regards, Julian

---

From: Julian Reschke <[email-masked]>
Date: Fri, 9 Apr 2021 10:22:32 +0200

> This could easily be done in CDDL, but that doesn’t support XML.)

FWIW, a simple fix for *this* case would be not to give @sectionFormat a
default in the grammar. The author really does not care where the
defaulting originates from, as long as it happens.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 9 Apr 2021 10:28:07 +0200

> I don't think you can do this with RelaxNG based information alone.

Actually, CDDL’s co-occurrence capabilities here were entirely stolen from Relax-NG's:

   xref =
     element xref {
       attribute xml:base { text }?,
       attribute xml:lang { text }?,
       attribute target { xsd:IDREF },
       [ a:defaultValue = "false" ]
       attribute pageno { "true" | "false" }?,
       [ a:defaultValue = "default" ]
       attribute format { "default" | "title" | "counter" | "none" }?,
       attribute derivedContent { text }?,
       (
         attribute section { text },
         [ a:defaultValue = "of" ]
         attribute sectionFormat { "of" | "comma" | "parens" | "bare" }?
       )?,
       attribute relative { text }?,
       attribute derivedLink { text }?,
       (text | em | strong | sub | sup | tt)*
     }

Grüße, Carsten

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 9 Apr 2021 13:38:19 -0600

> misguided; it leads to "canonical" XML that's full with completely

Agreed. The whole point of a default is you don't need to include it (as
long as the schema doesn't change from under you, so let's not do that).

Peter

---

From: Peter Saint-Andre <[email-masked]>
Date: Fri, 9 Apr 2021 13:38:50 -0600

On 4/9/21 2:22 AM, Julian Reschke wrote:
>>>> The value for sectionFormat=“of” is inflated as this is the default
>>>> value, I think I'm only seeing 2215 actual section references in
>>>> total, so it should really be 1487.
>>>
>> Should the dependency of the presence of @sectionFormat on the
>> presence of @section be hand-coded, or is there a way to do this in a
>> schema-driven way?

+1

Peter

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 9 Apr 2021 21:53:15 +0200

>> defaulting originates from, as long as it happens.

Yeah, except that I already showed how to do this right.

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Fri, 9 Apr 2021 21:57:21 +0200

> long as the schema doesn't change from under you, so let's not do that).

XML was meant to be useful without a schema.

Requiring canonical (“prepped”) RFCXML to be a PSVI makes a lot of sense.

It makes less sense to allow attributes to be present when they don’t mean anything.

Grüße, Carsten

---

From: "Joel M. Halpern" <[email-masked]>
Date: Fri, 9 Apr 2021 15:59:25 -0400

There may well be a better answer than filling in all the defaults 
during prep.
But if so, it has to address proper rendering if the defaults have 
changed since the XML was produced.  In most cases, it probably doesn't 
matter.  But if there was an explicit reason to want the old default, 
then things get itneresting when the default changes.  I don't think we 
want to archvie the schema with each and every RFC.

Yours,
Joel

---

From: "John Levine" <[email-masked]>
Date: 9 Apr 2021 19:29:29 -0400

>long as the schema doesn't change from under you, so let's not do that).

If you look at RFC 7998, the reason the preptool fills in all the
defaults is exactly so that the defaults can change later.

I don't think that is a terribly compelling argument, particularly since we have yet to
see a default we'd want to change, but it's not an accident.

R's,
John

---

From: Jay Daley <[email-masked]>
Date: Sat, 10 Apr 2021 11:52:47 +1200

> On 10/04/2021, at 11:29 AM, John Levine <[email-masked]> wrote:
> 

I would be interested in how people think we can get around this problem.  I can see a couple of solutions

- when a default changes then at that point the prep tool inserts this new 'default' everywhere so in fact the default isn’t changing but we still get the effect of it changing.  That way we only add all the extra stuff when we have to.

- the style guide version (or wherever the defaults are documented) is encoded in the XML in machine readable format.

Jay

-- 
Jay Daley
IETF Executive Director
[email-masked]

---

From: "John R Levine" <[email-masked]>
Date: 9 Apr 2021 19:55:17 -0400

> - the style guide version (or wherever the defaults are documented) is encoded in the XML in machine readable format.

Another possibility is to leave all the stuff in the published RFCs and 
consider those are for programs to read, not for people.  If you want to 
edit something, un-prep it with a tool that has whatever defaults you 
like, so it takes out anything that matches its defaults.

Regards,
John Levine, [email-masked], Taughannock Networks, Trumansburg NY
Please consider the environment before reading this e-mail. https://jl.ly

---

From: Julian Reschke <[email-masked]>
Date: Sat, 10 Apr 2021 06:41:27 +0200

> It makes less sense to allow attributes to be present when they don’t mean anything.

Absolutely.

We should have a close look at these defaults, and either exclude some,
or switch to a positive list.

For example:

   <section anchor="toc" numbered="false" removeInRFC="false"
toc="exclude" pn="section-toc.1">

Of the attributes inserted here, which ones would we ever change the
defaults for?

Or here:

   <t indent="0" pn="section-1-1">

Inserting things that at the preptool stage isn't bad per se, we just
need to keep in mind what it is for.

There are other things where we do *not* insert generated stuff. For
instance, the code for <u> and <address> consults external resources not
under IETF control for content, but then does not insert that
information into the canonoical XML.

On the other hand, stuff is inlined where it doesn't make any sense at
all, like the Toc or the Authors section are inserted, with very
interesting side effects on the author visible grammar.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 10 Apr 2021 08:07:22 +0200

On 10. Apr 2021, at 01:55, John R Levine <[email-masked]> wrote:
> 
> If you want to edit something, un-prep it with a tool that has whatever defaults you like, so it takes out anything that matches its defaults.

Yep, we need that unprep tool.
It would not only take out default values, but also all the generated/derived data.

Is the unprep tool an any roadmap?

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Sat, 10 Apr 2021 09:34:27 +0200

I haven't tried it yet, but xml2rfc *does* have an "unprep" mode:

>  --unprep              reduce prepped xml to unprepped

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Sat, 10 Apr 2021 14:21:28 +0200

>> --unprep              reduce prepped xml to unprepped

Nice!
I completely missed that.

In a sample, this worked well for me.
It left in a few too many derivedCounter attributes (in ol>li), and it took away all CDATA sections (which is only relevant if work continues on the XML), but apart from these, the upconversion looked perfect.
(I’m not sure I understand the sequence it chose for the individual attributes, so it is not always easy to do a diff, but that is of course a known problem with diffing XML.)

Grüße, Carsten

---

From: "John R Levine" <[email-masked]>
Date: 10 Apr 2021 09:28:06 -0400

> Is the unprep tool an any roadmap?

$ xml2rfc --unprep prepped-file.xml

Regards,

---

From: Peter Saint-Andre <[email-masked]>
Date: Mon, 26 Apr 2021 09:12:17 -0600

Hi Kent,

If (as explained below) the unique attributes of relref were migrated to
xref, would you still have a separate need for relref?

Peter

On 4/23/21 4:48 PM, Kent Watsen wrote:
> I’m a drive-by tourist here and just noticing this thread, but I’ve been making extensive use of <relref> in my documents.  Enabling authors to link to the specific section in an RFC is very useful.   
> 
> Looking into <xref>, I’m guessing that linking to an “anchor” is better because it would automatically update if the linked-section moves, such as when the target document is a work-in-progress - yes?
> 
> Kent
> 
> 
> 
>> On Apr 8, 2021, at 8:20 PM, Peter Saint-Andre <[email-masked]> wrote:
>>
>> Hi all,
>>

---

From: Kent Watsen <[email-masked]>
Date: Mon, 26 Apr 2021 15:33:43 +0000

No, especially if there’s a graceful migration, as I’d rather not have to update my 10+ I-Ds using <relref>  ;)

I think what I’m missing is that it seems the current <xref> definition has the ability to reference an anchor point in a document already, but maybe not, as the examples in RFC 7991 don’t speak to the case directly...

Assuming a document current has:

    <relref section=‘2.1.4.7' target='I-D.ietf-foobar’/>

    ["I-D.ietf-foobar" is a work-in-progress]

And that Section 2.1.4.7 is defined as:

    <section title=‘The “foo-grouping” Grouping' anchor=‘foo-grouping'>

Would this work, or planned to work?

    <xref target='I-D.ietf-foobar#foo-grouping'>  

PS: It would be an improvement to reference an “anchor”, so that relocations in a base document don’t require a manual update to other documents referencing it.

Thanks,
Kent

> On Apr 26, 2021, at 11:12 AM, Peter Saint-Andre <[email-masked]> wrote:
> 
> Hi Kent,
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 26 Apr 2021 17:48:43 +0200

> Would this work, or planned to work?

The specific syntax that you are using is broken, but please see:

https://xml2rfc.tools.ietf.org/xml2rfc-doc.html#name-xref-2

Grüße, Carsten

---

From: Kent Watsen <[email-masked]>
Date: Mon, 26 Apr 2021 17:30:22 +0000

That text looks broken ;)

1) typically, this is "#" for HTML documents

The tools should know what kind of document is being rendered and use the right syntax - right?

2) If the reference is not an RFC or Internet-Draft in the v3 format, and no "relative" attribute has been provided, it is an error.

Shouldn’t this sentence be under the “relative” section?

What the <xref> link for the example given in my last message?

Kent

> On Apr 26, 2021, at 11:48 AM, Carsten Bormann <[email-masked]> wrote:
>

---

From: Julian Reschke <[email-masked]>
Date: Tue, 27 Apr 2021 06:05:21 +0200

> The tools should know what kind of document is being rendered and use the right syntax - right?

No, it's a completely syntactical operation.

The only way the "relative" attribute can work in *general* is by using
the base URL for the reference, and concatenate the relative part to it.

For a simple HTML document, that would indeed mean that "relative" will
start with a "#". But there can be more complex cases where there's a
document hierarchy involved.

 From RFC 7749:

   <xref target="CSS" section="4.3.2" relative="syndata.html#length-units"/>

and

   <reference anchor='CSS'
              target='http://www.w3.org/TR/2011/REC-CSS2-20110607/'>
     <front>
       <title>Cascading Style Sheets Level 2 Revision 1 (CSS 2.1)
Specification</title>
       <author fullname='Bert Bos' surname='Bos' initials='B.'/>
       <author fullname='Tantek Celik' surname='Celic' initials='T.'/>
       <author fullname='Ian Hickson' surname='Hickson' initials='I.'/>
       <author fullname='Hakon Wium Lie' surname='Lie' initials='H. W.'/>
       <date year='2011' month='June' day='07'/>
     </front>
     <seriesInfo name='W3C Recommendation' value='REC-CSS2-20110607'/>
     <annotation>
       Latest version available at
       <eref target='http://www.w3.org/TR/CSS2'/>.
     </annotation>
   </reference>

> Shouldn’t this sentence be under the “relative” section?

Both maybe.

> What the <xref> link for the example given in my last message?

If you are referring to:

That makes the value of the target attribute incompatible with XML's
referential integrity checks.

Best regards, Julian