Subject: [xml2rfc] Vanity Reference Tags

From: "Jim Schaad" <[email-masked]>
Date: Wed, 30 Oct 2013 16:33:26 -0700

One of the things that I was thinking about as a project for the code sprint
was to implement the ability to do vanity reference tagging.  In doing this
I do not want to touch the reference itself, because then one cannot use the
references on the web site for that purpose.

I can see two ways that this can be done

1.  Use a new ?rfc command along the lines of <?rfc forRefeference="RFC5652"
use"SMIME"?>

Or

2.  Insert a new item in the DTD either in the headers or the references
section which has the same information.

You should be able to use either of the tags as a target for a reference
with the code emitting a consistent tag.

Comments?

Jim

---

From: Paul Hoffman <[email-masked]>
Date: Wed, 30 Oct 2013 16:40:51 -0700

> with the code emitting a consistent tag.

The XML DTD for the future will be changing, and will be incorporating some of the ideas you mention here. See the announcement sent to the rfc-interest list earlier today, and definitely come to the BoF.

There are probably other tasks with longer applicability that you can find at the sprint.

--Paul Hoffman

---

From: Nico Williams <[email-masked]>
Date: Wed, 30 Oct 2013 20:29:04 -0500

> references on the web site for that purpose.

Yes, this.  I've long wanted vanity reference names.

> I can see two ways that this can be done

My initial inclination is to prefer #2, however, one could do this with
XSLT and keep all of this external to xml2rfc, and thinking of it that
way, #1 seems more correct: we're rewriting part of the doc
automatically, and that feels more like a directive.

Nico
--

---

From: Julian Reschke <[email-masked]>
Date: Thu, 31 Oct 2013 08:07:48 +0100

> automatically, and that feels more like a directive.

No, by any means, don't put stuff like that into processing directives.

There already is a trac ticket with respect to this feature: 
<http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/106>

Best regards, Julian

---

From: "Martin J. Dürst" <[email-masked]>
Date: Thu, 31 Oct 2013 16:28:11 +0900

I changed the subject because I think "vanity" is the wrong word here. 
Using [SMIME] instead of [RFC5652], for the majority of readers, is an 
usability feature.

I hope that makes it clear that I'd appreciate this feature.

> No, by any means, don't put stuff like that into processing directives.

Fully agreed. PIs (processing instructions) are a leftover from SGML, 
and at W3C, we had (and I guess have) a longstanding policy of not using 
them (the XML stylesheet PI is the exception that proves the rule). 
There are all kinds of good reasons for this, but I'd have to go and dig 
out mails from 10 or more years ago to help me remember them; I didn't 
have any need recently to argue against them.

But in this specific case, it's very clear: the "SMIME" is textual 
content that appears in the final document, and such content should not 
come from PIs.

> <http://trac.tools.ietf.org/tools/xml2rfc/trac/ticket/106>

The title of that ticket reads "reference for an STD or BCP that 
contains multiple RFCs". I'm rather sure that's not what Jim's request 
is about. It may be that some of the implementation solutions for that 
ticket would be usable for what we are talking about here, too, but that 
would be accidental. So unless you mistyped the ticket number, we should 
create another ticket so that the feature is clearly tracked.

Regards,   Martin.

---

From: Julian Reschke <[email-masked]>
Date: Thu, 31 Oct 2013 09:03:07 +0100

On 2013-10-31 08:28, "Martin J. Dürst" wrote:
> ...
> ...

The proposal in the ticket would address the target renaming use case as 
well...

Best regards, Julian

---

From: "Jim Schaad" <[email-masked]>
Date: Thu, 31 Oct 2013 22:44:10 -0700

Julian,

Having read the data tracker item, from an XML point of view this makes
perfect sense as a way to do things.

>From a usability point of view I think that the approach outlined makes
things difficult.

1.  Consider if I create an entity reference for BCP0101 and use that
directly.  Either the file needs to include the set of references in total,
or I am now going to get a series of undefined references that I cannot find
a reason to exist in my original document.  For RFCs this is not a big
issue, for other standards documents this may be a problem as I would not
necessarily know what they reference.

2.  This makes it difficult for me to have a single file in which I keep
track of all of my vanity tags that I use.  Instead I will need a new file
for each different tag.  Using a directive of some type would allow for a
single file to be included and then the contents would be used in the event
that I actually include and use the reference in question.

3.  Based on what is given in the ticket, there is an interesting question
if one has a reference to BCP9 and one also has a reference to RFC 5657 that
is independent.  Should both of these items be different references so that
when an aggregation is done the tags on the inner references are hidden and
the document would be included in the references twice, once as part of the
BCP9 and once as an independent document

Since this is not fully ironed out I may or may not look at this on
Saturday, will think about it.

Jim

> -----Original Message-----
> From: Julian Reschke [mailto:[email-masked]]
> Sent: Thursday, October 31, 2013 12:08 AM
> To: Nico Williams; Jim Schaad
> Cc: [email-masked]
> Subject: Re: [xml2rfc] Vanity Reference Tags
> 
> >> One of the things that I was thinking about as a project for the code
> >> sprint was to implement the ability to do vanity reference tagging.
> >> In doing this I do not want to touch the reference itself, because
> >> then one cannot use the references on the web site for that purpose.
> >
> > My initial inclination is to prefer #2, however, one could do this
> > with XSLT and keep all of this external to xml2rfc, and thinking of it
> > that way, #1 seems more correct: we're rewriting part of the doc