Subject: [Tools-discuss] New tool: bibxml2rfc

From: Eric Rescorla <[email-masked]>
Date: Thu, 20 Mar 2008 08:09:02 -0700

I've just put up a prototype version of a new tool: bibxml2rfc,
which is a reference tool for xml2rfc in the style of bibtex.

URL: https://svn.resiprocate.org/rep/ietf-drafts/ekr/bibxml2rfc

Here's the description from the internal documentation.

     bibxml2rfc is a bibliography helper program for xml2rfc files.
     One of the motivations for bibxml2rfc is that it's hard
     to work with xml2rfc in offline settings. Either you need
     to download the entire database or manually enter each
     database entry. In either case, you need to significantly
     edit your XML file to add a new reference. bibxml2rfc
     is intended to mitigate these issues.
     
     When handed an XML file, bibxml2rfc tries to identify the
     references and construct an appropriate bibliography. The
     general procedure is as follows:
     
     - Find all <xref> elements in the XML file (<file>)
     - Extract the "target" attributes.
     - Look in the local bibliography cache (references/) for files
       named <target>.xml.
     - If no cached entry is found or the the target appears to be
       an I-D (starts with "I-D."), then try to fetch an entry out
       of the appropriate repository on xml.resource.org.
     - Build two files:
       + <file>-normative containing reference entries for the
         normative references
       + <file>-informative containing reference entries for the
         informative references
     
     bibxml2rfc determines whether a reference is normative or
     informative by looking at the 'norm' attribute in the <xref>
     element. If it is 'true', then the reference is normative.
     Note that a single instance of 'norm="true"' is sufficient
     to mark a reference normative, so if multiple <xref> elements
     are present, only one need be so marked.

There's also a simple tool (bibxml2rfc-merge) to produce merged
xml2rfc files for submission.

Arguably, this should be part of xml2rfc proper, but I was in
a bit of a hurry and this was the easiest thing for me to write.
Comments, bugs, etc. welcome.

-Ekr

_______________________________________________
Tools-discuss mailing list
[email-masked]
https://www.ietf.org/mailman/listinfo/tools-discuss

---

From: "Frank Ellermann" <[email-masked]>
Date: Thu, 20 Mar 2008 16:51:33 +0100

> Comments, bugs, etc. welcome.

Some days ago I had bugs in an xml2rfc source, and for unclear
reasons Bill's validator refused to work.  Therefore I used
the W3C validator to figure out what was wrong, and fixed it.

For these purposes adding norm= to the DTD could make sense.
Or maybe a solution with processing instructions is better,
Julian's XSLT uses this approach.  I'm not sure why you need
norm= at all, or if only validators would hate it. 

 Frank

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 20 Mar 2008 08:55:23 -0700

At Thu, 20 Mar 2008 16:51:33 +0100,

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 20 Mar 2008 08:55:31 -0700

> norm= at all, or if only validators would hate it. 

I'm pretty flexible on this point. We obviously need some way
to indicate that a ref is normative but I don't much care how.
I do believe that it needs to be associated with the reference
in the text and not with the bib entry, since the bib is
shared (by design) and some bib entries are normative with
respect to one i-d and informative with respect to another.

-Ekr

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 20 Mar 2008 18:54:35 +0100

> URL: https://svn.resiprocate.org/rep/ietf-drafts/ekr/bibxml2rfc

Hey!  This is written in Python!  I can read this comfortably!  :-)

> Here's the description from the internal documentation.

...

>      general procedure is as follows:

How to use this wasn't entirely clear to me until I read the
bibxml2rfc-merge code.  So to use this, you add 2 external entity
definitions to your xml2rfc source file, one for the normative and
one for the informative reference files, and use those in their
appropriate reference section.  This replaces the individual entity
definitions for external bibxml* files.

Then you run bibxml2rfc on the source file, which will have the
effect of downloading needed references if not already in the cache,
and building the two files holding references.  If you're off-line,
references not in the local cache will be present in the generated
files with dummy content, so you can run xml2rfc on the source file
without being held up.  If you're on-line, new files will be added
to the cache.  Files already in the cache won't be checked for
updates (should that optionally be done?).

Did I get that right?

> Comments, bugs, etc. welcome.

Neat! 

	Henrik

---

From: Eric Rescorla <[email-masked]>
Date: Thu, 20 Mar 2008 11:02:39 -0700

At Thu, 20 Mar 2008 18:54:35 +0100,
> definitions for external bibxml* files.

Exactly.

> and building the two files holding references. 

Yes, though you can do these in either order.

> If you're off-line,
> without being held up.

Yes, with two caveats:

1. You need to pass -i
2. It only does this for I-Ds and RFCs. Other references it doesn't
   try.

You are expected to preload the cache with non-ID non RFC references.

>  If you're on-line, new files will be added
> to the cache. 

Yep.

> Files already in the cache won't be checked for

Actually, I-Ds are checked for updates unless you pass in 
'-n'. RFCs aren't checked for updates on the theory that
RFCs never change. 

-Ekr

---

From: Henrik Levkowetz <[email-masked]>
Date: Thu, 20 Mar 2008 20:17:47 +0100

...

> You are expected to preload the cache with non-ID non RFC references.

Aha.  Right.

> '-n'. RFCs aren't checked for updates on the theory that

Makes sense.  Cool.

	Henrik