[rfc-i] including external resources in RFCs with xml2rfc

Erik Wilde dret at berkeley.edu
Thu Nov 7 15:37:36 PST 2013


hello.

i apologize if this has been brought up before. i searched the archives 
a little and couldn't find it, so here's a problem and a proposal:

i often use examples i then have to copy/paste into the RFC XML, and 
sometimes when editing the XML, the spacing gets mixed up. so i manage 
those examples as external files, and recently started using XInclude 
for preprocessing files before using xml2rfc. this is nice because 
XInclude 1.1 also supports text fragment identifiers, allowing to 
include fragments of the included file. (my XInclude processor XIPr 
https://github.com/dret/XIPr does not yet support XInclude 1.1, but 
that's on the to-do list.)

here are some advantages:

- no risk to mess up sometimes carefully formatted example files when 
editing the XML in some XML editor that may do pretty-printing.

- standards-based: many XML processors support XInclude, and with an 
XSLT implementation such as XIpr, it's easy to use when XSLT is supported.

- the external resources could be published with the RFC, making it 
trivial for people to download examples, no copy/paste needed. also, 
potentially bulky examples can be included without the need to fully 
list them in the RFC text.

- HTML formatting can represent the included part, and the link to the 
included file, making it easy to both read the RFC, and quickly get 
access to the included text 
(http://dret.net/lectures/xml-fall13/basics#%285%29 is how i use that in 
web-based presentations, clicking on the file names links to the 
included resources).

depending on how you look at it, i am proposing two things:

1) supporting XInclude for xml2rfc so that including examples in RFCs 
gets a little easier. this could just be used for generating the RFC 
text, in which case it would just be a new xml2rfc feature.

2) supporting "transclusion" in RFCs, so that external files are an 
integral part of an RFC, and are easily available for download.

thanks and cheers,

dret.

-- 
erik wilde | mailto:dret at berkeley.edu  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |


More information about the rfc-interest mailing list