[xml2rfc] Using [DOCNAME] citations instead of [RFCxxx]

[tony at att.com (Tony Hansen)]

<xref target="RFCXXXX">NOTIFY</xref>

Aaron Stone wrote:
> Hi,
> 
> In the Sieve mail filter series of documents, we use the [DOCNAME]
> citation style rather extensively, and avoid [RFCxxx] references wherever
> possible. This dramatically increases readability. For example (from
> draft-ietf-sieve-notify-xmpp-07.txt):
> 
> 1.1. Overview
> 
>    The [NOTIFY] extension to the [SIEVE] mail filtering language is a
>    framework for providing notifications by employing URIs to specify
>    the notification mechanism.  This document defines how xmpp URIs (see
>    [XMPP-URI]) are used to generate notifications via the Extensible
>    Messaging and Presence Protocol [XMPP], which is widely implemented
>    in Jabber instant messaging technologies.
> 
> I cannot figure out how to do this in xml2rfc :-(
> 
> If there's no mechanism in place, I propose creating one...
> 
> I'm thinking either...
> 
>  o the document reference database include a friendly name in its xml
>    definition.
>  o add a 'nickname' mechanism in the <!ENTITY ...> that includes the 
>    reference from the common database.
> 
> I'm very much against pulling all of the references into the document just
> to add a cute name to it. That defeats the purpose of the common database
> of references.
> 
> Aaron
> 
> _______________________________________________
> xml2rfc mailing list
> [e-mail]
> http://lists.xml.resource.org/mailman/listinfo/xml2rfc
>From dave at cridland.net  Wed Dec  5 19:53:05 2007
From: dave at cridland.net (Dave Cridland)
Date: Wed Dec  5 11:53:29 2007
Subject: [xml2rfc] Using [DOCNAME] citations instead of [RFCxxx]
In-Reply-To: <[e-mail]>
References: <[e-mail]>
Message-ID: <[e-mail]>

On Wed Dec  5 19:29:59 2007, Aaron Stone wrote:
> In the Sieve mail filter series of documents, we use the [DOCNAME]
> citation style rather extensively, and avoid [RFCxxx] references  
> wherever
> possible. This dramatically increases readability. For example (from
> draft-ietf-sieve-notify-xmpp-07.txt):
> 
> 
We do in Lemonade, too.

Take a look at my hacky XSLT preprocessing tools, held in  
http://svn.dave.cridland.net/svn/ietf-drafts/

1) Makefile - simple makefile driver, works with xsltproc.
2) rfc2629-refchk.xsl - generates an XML based report of missing, or  
bad references. In particular, this will check to see if a reference  
is marked normative in usage, and if so, whether it's listed in the  
right section.
3) rfc2629-noinc.xsl - expands all references and <?rfc include ?>  
directives.

An example might be draft-cridland-sasl-tls-sessions.xml, which is  
pretty small.

a) <xref/> elements can be marked with dwdrfc-type='norm' to make the  
refchk XSL think they're normative.
b) So can the <references/> element, to mark the normative section.
c) <references/> can conntain <dwdrfc-ref/> elements, which have a  
src attribute pointing to the fragments, and an anchor attribute to  
specify what goes in the square brackets.

(It's not using namespaces because that appeared to confuse xml2rfc,  
so I did it the hackier way).

I find these useful, YMMV.

Dave.
-- 
Dave Cridland - mailto:[e-mail] - xmpp:[e-mail]
  - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
  - http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade
>From aaron at serendipity.cx  Wed Dec  5 15:19:48 2007
From: aaron at serendipity.cx (Aaron Stone)
Date: Wed Dec  5 15:20:49 2007
Subject: [xml2rfc] Using [DOCNAME] citations instead of [RFCxxx]
In-Reply-To: <[e-mail]>
References: <[e-mail]>
	 <[e-mail]>
Message-ID: <1196896788.6893.13.camel@localhost>

This input...

    The DSN message MUST follow the requirements of
    <xref target="RFC3464">DSN</xref>

...produces this output:

   The DSN message MUST follow the requirements of DSN [RFC3464]

... but what I'd like to get is:

   The DSN message MUST follow the requirements of [DSN]

Aaron


On Wed, 2007-12-05 at 14:47 -0500, Tony Hansen wrote:
> <xref target="RFCXXXX">NOTIFY</xref>
> 
> Aaron Stone wrote:
> > Hi,
> > 
> > In the Sieve mail filter series of documents, we use the [DOCNAME]
> > citation style rather extensively, and avoid [RFCxxx] references wherever
> > possible. This dramatically increases readability. For example (from
> > draft-ietf-sieve-notify-xmpp-07.txt):
> > 
> > 1.1. Overview
> > 
> >    The [NOTIFY] extension to the [SIEVE] mail filtering language is a
> >    framework for providing notifications by employing URIs to specify
> >    the notification mechanism.  This document defines how xmpp URIs (see
> >    [XMPP-URI]) are used to generate notifications via the Extensible
> >    Messaging and Presence Protocol [XMPP], which is widely implemented
> >    in Jabber instant messaging technologies.
> > 
> > I cannot figure out how to do this in xml2rfc :-(
> > 
> > If there's no mechanism in place, I propose creating one...
> > 
> > I'm thinking either...
> > 
> >  o the document reference database include a friendly name in its xml
> >    definition.
> >  o add a 'nickname' mechanism in the <!ENTITY ...> that includes the 
> >    reference from the common database.
> > 
> > I'm very much against pulling all of the references into the document just
> > to add a cute name to it. That defeats the purpose of the common database
> > of references.
> > 
> > Aaron
> > 
> > _______________________________________________
> > xml2rfc mailing list
> > [e-mail]
> > http://lists.xml.resource.org/mailman/listinfo/xml2rfc