Decisions, decisions

We had something like a meeting with Karsten and a couple of others after the FDSCo weekly meeting yesterday night. The storage format of man/info pages in the wiki has been an open question ever since I started. We made some decisions on that yesterday.

We are probably going to use DocBook XML a lot. That’s the format in which the Docs project does their work mainly. There was a GSoC project last year improving Moin’s DocBook handling but the code was never merged into mainline. If that code helps this project, I will look into merging it with my code. We’re also going to use some DocBook related tools that are already available, like doclifter that converts man source into DocBook XML.

The plan is to do “phase 1” as I call it, the publication phase, like this:

• Take the man page sources (from CVS, repositories etc.) and run them through doclifter
• Organize the resulting DocBook XML cleanly under separate namespaces
• Let Moin show the XML as “normal” wiki pages to the user
• Improve Moin’s diff feature to support diffs between different pages, not just different revisions of the same page

The same needs to be done for info page sources too, here the problem is that we would need the original Texinfo sources, not the Info sources (these are two different formats). The GNU makeinfo program already outputs DocBook XML from Texinfo, so that can be used instead of doclifter with info pages.

The plan for “phase 2” as I call it, editing and getting the edits upstream, is:

• Switch the storage format to wiki markup, which is easy to edit
• Generate DocBook XML from the wiki markup, probably using the code from last year’s GSoC project
• The XML can then be transformed into “any” format that is needed (via XSLT, docbook2x etc.)

We are doing it like this because both man and info pages, but especially man pages, can be originally produced from different source formats, Perl POD and many others. So we could then write whichever translators are needed to get the wanted format out of DocBook XML. This way the solution can be extended by community members, too.

There’s one problem in this approach: how usable are the generated patches going to be? If we generate DocBook XML from wiki pages and then transform that into eg. man source, making a patch from that file against the “real” upstream man source might produce patches that also change some markup details and not only the content visible to the end user. But I guess this is a risk we’re just going to have to take. Computer generated source just may be different than that written from scratch by a human…

Comments, suggestions?