[KI-LC] Proposal for discussion: Tool chain for Connected Life specs

Eve Maler eve at xmlgrrl.com
Thu Jul 2 12:38:02 CDT 2015

I have had conversations with Heather and Nat, and learned a lot.

First (from Heather), the xml2rfc DTD will go from V2 to V3 in the next 6-12 months to support additional output formats, which will probably involve some additions but also some incompatible changes.

Second (from Nat), there is an older Tcl/Tk tool set and a newer Python tool set for xml2rfc; apparently the hosted one uses the older tool set. Nat had simply swapped a data file in the older one to make it product OIDF’s required copyright file, and had forked the newer tool set to try and do some other changes, but ultimately saw no uptake by OIDF spec editors.

Heather’s very good advice was to think carefully about forking V2, given that V3 would come along soon enough, and any conversion tools they supply might break with a forked V2.

Nat’s advice was manyfold...

- Beware of forking, as engineering-type spec editors tend to hate that.

- Consider the wide range of doc editor “personas" that Kantara has, across the two types of work streams. The lack of XML editing software hurts its cause with less technical doc editors (pains me to admit, but it’s true).

- Consider non-XML formats. He suggested markdown, which I personally hate (and think is too geeky as well), but he also suggested epub, which he says has lots of editing software available and could produce lots of output formats.

This all makes me want to step back from xml2rfc a bit and gives me some interesting new avenues to explore, which I will do before our next meeting. If anyone has experience using epub, or other thoughts, please let me know!


> On 1 Jul 2015, at 2:33 PM, Eve Maler <eve at xmlgrrl.com> wrote:
> I can foresee a very near future in which the UMA, CIS, and other Connected Life groups will need to produce new technical specs (such as new and updated specs, profiles, extensions, errata, and so on). So far, the UMA group has been using the “xml2rfc” XML DTD (http://xml2rfc.ietf.org/public/rfc/html/rfc2629.html) to very good effect. We chose it because we have been contributing our specs to IETF as Internet-Drafts, and will ultimately pursue Informational RFC status for UMA V1.0.
> I’d like to suggest that Kantara put some effort into developing a small variant of the xml2rfc tool (http://xml2rfc.ietf.org) that emits HTML/CSS that has correct Kantara style and also correct Kantara IPR language, and also ideally hosting that variant tool (the way it is hosted at the link just prior) on ki.org for spec editor use so that it would be easy for WGs to generate HTML files on demand. We had to ask Oliver Maerz to do these edits by hand repeatedly during the Public Review/Draft Recommendation/Recommendation process for our two documents.
> We might be able to leverage knowledge (and even code?) from the OpenID Foundation, which has some sort of tool chain for doing a very similar thing using a variant of xml2rfc and has a copyright statement that differs from IETF's.
> Thoughts?
> 	Eve

Eve Maler | cell +1 425.345.6756 | Skype: xmlgrrl | Twitter: @xmlgrrl | Calendar: xmlgrrl at gmail.com

More information about the LC mailing list