Subject: [xml2rfc-dev] Renaming reference anchors

From: Julian Reschke <[email-masked]>
Date: Sat, 08 Jan 2011 18:57:51 +0100

Hi there,

the current SoW for a new xml2rfc tool contains the following 
requirement (*):

> Ability to Select Reference Element Anchor
> Add the ability to use a reference element from the citation library, but assign it an
> anchor other than the one provided. This allows the author to use a nickname (such as
> [ABNF]) for the anchor instead of an RFC number or I-D string (such as [RFC5234]).
> For example, while recognizing that these would be different if using ENTITYs instead
> of PIs to pull from the citation libraries:
> <?rfc include="reference.RFC.5234.xml" my_anchor="ABNF" ?>
> <?rfc include="reference.I-D.ietf-mmusic-ice.xml" my_anchor="ICE"
> ?>

I do realize that many people want this. From my point of view, it's a 
non-issue: just get the reference element, paste it in your source, and 
change the anchor attribute.

That being said, the request is out there, and apparently people love it 
to include by reference, even if it means trouble when converting 
documents while traveling, and surprises when the reference target 
changes in unexpected ways (such as ABNF productions being renamed, or 
sections being moved around).

Also, I'm very nervous leaving changes to these to yet-to-determined 
contractors, who may not have a long-term interest in the vocabulary.

So, optimally, we can develop a proposal over here.

I do not like the PI-based inclusion mechanism at all; it replicates 
standard XML-features such as entity inclusion, or even xinclude. So 
IMHO the extension should be part of the vocabulary, and work no matter 
how the reference gets into the document.

Here's a very simple proposal that would not complicate the DTD 
significantly and would preserve ID-checks through DTD validation:

1) Introduce a new element, <aliased-reference>, and allow it where 
<reference> is allowed.

2) <aliased-reference> would have its own anchor attribute, and simply 
wrap the reference element it's aliasing.

Example 1:

<aliased-reference anchor="ABNF">
   <?rfc include="reference.RFC.5234.xml" ?>
</aliased-reference>

Example 2:

<!ENTITY rfc5234 PUBLIC
   "http://xml.resource.org/public/rfc/bibxml/reference.RFC.5234.xml">
  ...
<aliased-reference anchor="ABNF">
   &rfc5234;
</aliased-reference>

Note that the alias would completely eclipse the original anchor ID, so 
all <xref>s would need to reference the new alias.

Feedback appreciated,

Julian

(*) <http://www.ietf.org/mail-archive/web/xml2rfc-dev/current/msg00053.html>

---

From: Tony Hansen <[email-masked]>
Date: Mon, 10 Jan 2011 15:57:58 -0500

> contractors, who may not have a long-term interest in the vocabulary.

absolutely -- defining the mechanism should not be in the hands of the 
contractors

> standard XML-features such as entity inclusion, or even xinclude. 

I personally don't care which mechanism is used. To me it's like saying 
you prefer 2*x instead of x+x. Which one you like seems to be a matter 
of preference, as well as a question of which one you first got taught 
to use.

> So IMHO the extension should be part of the vocabulary, and work no 
> matter how the reference gets into the document.

I agree completely.

> <?rfc include="reference.RFC.5234.xml" ?>

I like the idea of being able to introduce an alias. As it's said:

     all problems in computer science can be solved by adding another 
layer of indirection

This begs the question: should it be possible to add aliases for other 
items that have anchors?

Why not have a more generic capability such as:

<alias anchor="ABNF" target="RFC5234"/>

?

> Note that the alias would completely eclipse the original anchor ID, 
> so all <xref>s would need to reference the new alias.

I don't think that this is necessary, but am willing to be persuaded.

     Tony Hansen

---

From: Julian Reschke <[email-masked]>
Date: Mon, 10 Jan 2011 22:52:24 +0100

On 10.01.2011 21:57, Tony Hansen wrote:
> all problems in computer science can be solved by adding another layer
> of indirection

OK, OK, I'll say it:

Except those which are caused by too many indirections.

> This begs the question: should it be possible to add aliases for other

Maybe, but that would violate the KISS principle :-)

> <alias anchor="ABNF" target="RFC5234"/>

My extension vocabulary does something like that: 
<http://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#ext.element.anchor-alias>

That being said... the proposal I made was optimized for the group of 
people who prefer include-by-reference over copy-and-paste, thus 
minimized typing.

> I don't think that this is necessary, but am willing to be persuaded.

OK, let me rephrase it: they wouldn't need to reference the new value, 
but they would be processed as if they did (otherwise we'd have 
inconsistent names for the reference entries).

Best regards, Julian