[Koha-devel] Koha docs in XML?

[Nicholas Rosasco]

Responding to Stephen Hedges <shedges at skemotah.com>:

> It seems to me that the best way to store Koha documents is as a set of
> XML source trees.  All of these could be pulled together into one XML
> document that uses entity references to grab them.  We could then use a
> variety of tools to process the XML and create finished documents in many
> formats and many languages.

Sounds good.

> Since gathering content is the biggest problem in documenting Koha, it
> also seems to me that we do not want to require that people submit their
> documents in XML.  Instead, I think we should accept documents in any
> format (well, practically any format), which would then be converted by
> the documentation manager to XML source trees.

I actually have a pair of GPLd wiki tools (one java, one usually the older
wiki2xml tool) I've been using to make the conversions easier, but have had no
place to host them for production/general use.  These let someone input
standard wiki text, and offer a "button" for XML (instead of HTML) output.
Neither is perfect, but either offer a serious improvment over hand tagging. 
The material I've converted so far has largely been done with the simpler of
the two of them.


> For example, I currently link to several documents from the skemotah.com
> website.  I can take these documents and convert them to XML, storing each
> as a separate XML source tree.  Then I could reference each of these XML
> files as an entity from a "master" XML source tree that pulls all of the
> the documents together.  This master XML file could be processed with XSL
> or CSS or some other tool and converted to HTML or Docbook or pdf or
> whatever.  The processing tool could even select only those elements that
> contain German text, or French text, etc.  Or only those elements of
> interest to librarians, or OPAC users, etc.

Several of the things hosted at archive I've already converted to the Docbook
XML flavor.

[note to self, get ahold of Mike Reavey, who has this material at his site...!]

> Keeping the documentation up to date then would involve modifying the
> individual XML documents to include new information, or modifying the
> master XML source tree to add new entity references to new XML documents.

Incidentally, one service that we've always missed, but was never sure how to
accomplish (short of subjecting even more people to CVS a la sourceforge, which
is a little dicey IMO) was some sort of update notice for those willing to
translate docs.  Similar to the CVS notifier, I guess, informing them that
changes (with perhaps a severity indication...?) were made to the
original/English versions.  Something automated would eliminate the
sometimes-iffy reliance on memory to notify the various int'l groups of
important changes.

As far as the storage question goes, there are a few ways to address this.  One
is the XMl-backended wiki (unfortunately this tool has a quirk or two, but is
the best I've stumbled across so far.... I await with interest more news re
neodoc from Paul).  There is also a mandrake-related webtool called Borges, but
I've only ever seen a "mock up" install... Kartouche (sp?) has also been kicked
around as a possibility [I seem to have mislaid the link to that, but I recall
MJ Ray mentioning it].

Nick