Re: [Monotone-devel] Documentation Texinfo XML to Wiki converter

[Daniel Carosone]

On Thu, Feb 26, 2009 at 12:09:45AM +0100, Philipp Gr?schler wrote:
> Philipp Gr?schler schrieb:
> > In the course of the current Mini Summit I spent the afternoon hacking
> > on a (yet still) small XSLT file whose purpose will be the conversion of
> > Monotone's Texinfo Documentation to a set of multiple files which can be
> > used for the Wiki.
> > ....
> 
> I just committed the first release of this thing, in a very *pre-alpha*
> state. 

I saw the commits before this thread, and was curious what you were up to.
Alas, I missed the mini-summit this time.

But - excellent!

As far as output format goes, mdwn or others can be deal with by
ikiwiki.  The limitations there are around some of the more specific
semantic markup: noting that this represents a command, or an option,
or a literal vs a variable, and getting this information through to
the point where CSS can render it with visual distinctions.  

Markdown offers some basic notations, and the opportunity to revert to
html elements for more detailed cases, but this can be a little
disruptive as a document author writing a wiki page (it's a sudden
shift from minimal to more extensive internal markup).  That is much
less an issue if, at least in the first phases, we're talking about
keeping the source in texinfo and rendering to something that ikiwiki
can consume to produce a better-integrated output on the website
(indexing, etc). 

These are good examples of the discontinuity, by the way, because many
of these element types native to texinfo are focused on software
documentation, where markdown is more focused on general writing.

Longer term, we need to develop a strategy for more unified
documentation.  That may involve changing the markup source for some
components, and potentially integrating your work into ikiwiki
(allowing it to read essentially another markup input language).  It
almost certainly involves unifying the stylesheet, both in terms of
the output rendering and the selection of styles available.

It also would involve allowing the creation of narrative navigaton
paths through the page collection, both as a reading guide online and
to structure the generation of offline formats (e.g. PDF output of
documents similar to the current manual, in an organised sequence of
chapters and sections).

This means we'll have pages on the site intended for differnet
purposes, generated from a number of mechanisms (including automatic
aggregation via some of ikiwiki's tricks), and potentially from
sources in different markup styles.

The great thing about this work is it (begins to) breaks the coupling
between purpose and style, which means content can be used for
multiple purposes regardless of style, in turn meaning that
"unification" doesn't get confused with "markup conversion".

So, really, yay, and yay again.

--
Dan.

pgpAlDJL7LaH8.pgp
Description: PGP signature