[Koha-devel] Koha docs in XML?

[Stephen Hedges]

I've been thinking about the best format for storing the Koha
documentation, and I've got some ideas I'd like to share.

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.

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.

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.

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.

Any comments?  Any ideas about the best way to store these files?

BTW, I have almost no experience with XML.  Please feel free to correct
anything you see above that is not right.

-- 
Stephen Hedges
Skemotah Solutions, USA
www.skemotah.com  --  shedges at skemotah.com