Subject: [lemonade] Symbolic References

From: "Eric Burger" <[email-masked]>
Date: Mon, 23 Apr 2007 16:39:25 -0700

I get to change my position :-)

There was a debate here about whether to use numeric or symbolic
references in documents.  I said I didn't care, but that the tools (and
IEEE :-) use numeric references.

There was a decent discussion on the IETF list about this subject.  Feel
free to follow the archives.  The basic arguments are that numeric
references are easier to find in the References section, but symbolic
references are easier to track through the revision process.  A
suggestion is to ensure you sort your references alphabetically, so they
are easier to find.

Dave has what looks like cool tools; I'll let him post them here.

Notice:  This email message, together with any attachments, may contain information  of  BEA Systems,  Inc.,  its subsidiaries  and  affiliated entities,  that may be confidential,  proprietary,  copyrighted  and/or legally privileged, and is intended solely for the use of the individual or entity named in this message. If you are not the intended recipient, and have received this message in error, please immediately return this by email and then delete it.

_______________________________________________
lemonade mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/lemonade
Supplemental Web Site:
http://www.standardstrack.com/ietf/lemonade

---

From: Dave Cridland <[email-masked]>
Date: Wed, 25 Apr 2007 19:14:05 +0100

> suggestion is to ensure you sort your references alphabetically, so 
<?rfc sortrefs="yes"?>

I went out of my way to ensure that the symbolic references I'm using 
in profile-bis are not only sorted alphabetically, but collated 
according to protocol, by naming them using protocol-like prefixes.

This makes the symbolic reference tags longer than usual (and I'm not 
really recommending doing this unless you have a lot of references), 
but makes them easy to find. (As it happens, I suspect that Niel 
Cook's streaming draft might benefit, since it makes it easy to see 
if it's an IMAP, SIP, etc reference).

> Dave has what looks like cool tools; I'll let him post them here.
They're not cool tools at all, but they are convenient gratuitous 
hacks.

Look at 
http://svn.dave.cridland.net/svn/ietf-drafts/draft-cridland-imap-contexts.xml 
for a simple source document. There are four things of note:

1) I use <?rfc include="..."?> for things like authors. (One day, 
I'll make it so I can switch between editor and author here).

2) References (<xref/> elements) optionally have a dwdrfc-type 
attribute, which is usually (if it's there) "norm", indicating a 
normative use of the reference.

3) <references> elements have a similar attribute, which indicates 
whether they're normative reference sections or not.

4) Inside all references sections, I use <dwdrfc-ref> elements, which 
have an anchor attribute (my choice of anchor), and a src attribute, 
which either contains a full URI, or a short-hand, which points to 
the xml.resource.org bibxml reference fragment.

Next, I have two XSL transforms:

rfc2629-noinc.xsl: Takes my source as input, and outputs a "proper" 
xml2rfc file without any includes. It'll rewrite reference fragments 
as it imports them so the anchors are of my own choosing. Sorting 
them is left to xml2rfc.

rfc2629-refchk.xsl: Outputs an XML file describing missing or unused 
references, or references found in the normative section which are 
never marked as being used normatively, or references which are used 
normatively but not found in the normative reference section. 
(Normally, the latter two checks don't find anything except refernces 
I've not marked up correctly; sometimes, though, I find that while I 
thought a reference was normative, I cannot actually find a case 
where it's used normatively.)

Finally, there's a Makefile which will generate either a *.chk file 
(the output of the refchk XSLT), or a *.txt file (the output of 
xml2rfc over the noinc output). So to produce the text file for 
submission, I run "make draft-cridland-imap-contexts.txt".

Dave.
-- 
Dave Cridland - mailto:[email-masked] - xmpp:[email-masked]
  - acap://acap.dave.cridland.net/byowner/user/dwd/bookmarks/
  - http://dave.cridland.net/
Infotrope Polymer - ACAP, IMAP, ESMTP, and Lemonade