Re: [Lcd4linux-devel] how to make documentation ? maybe xslt !

[Xavier V. <xav...@fr...>]

Hello Jerry, hello list !
=20
> Nod.  I have converted my original man page over to docbook.  I've been
> meaning to work more on the conversion to html.
In fact, I d=E0on't think manpage must be necessarily ported to xslt and
friends, as the online documentation won't be just this, but an
explanation page for each driver and plugin, and 'general' docs about
layout and configuration.=20
But we may include the manpage somewhere too.

> I agree that XSLT is easier to use than dsssl and think it would be=20
> a better choice to transform the docbook source to html.
In fact, our use of XSLT (as I see it in my mind) is writing xhtml pages
with tags like <conf></conf>, <code></code> which will be replaced by
the apropriate xhtml/css code. The page should just describe the body
and the rest (head, menus, ...) would be generated by the stylesheet.

So, in this case we can use two stylesheets : one for the online doc
(including php code for the menus, ...) and one for documentation in the
tarball with a little menu and summary.

> > So, then I found the logidee-tools. It's avaible at
> > www.logidee.com/tools/ or in a debian package for the power users ;).
> > It's a compilation of stylesheets and make scripts to write courses and
> > publish them in html or pdf/ps (via LaTeX). And it's written by two
> > frenchies ;)
> Aha!  I should have known! ;)
In fact, I found the logidee tools in the debian distro, without knowing
they were written by frenchies, and then I remembered logidee was an
'SSI' which writes docs (and a distro if I remember well)

> As for as logidee is concerned, one problem with it is the
> documentation.  Since there is no documentation written in English,
> it leaves english-only speakers such as myself in the dark.  You would
> have to do it all...
> Is the logidee package simply a set of XSLT transforms, or is there more
> to it?
It's just a set of xslt/dtd files and makefiles, no binary there. I know
the documentation is in french only, but I just mentionned it, we can't
use the stylesheets as is, I'll write others myself, based on the good
ideas these guys put in there.

> Do you want the documentation that is in (X)html format to be only html,
> or do you need to have php source in them so that they integrate with
> the rest of the website?
Both, read at the beginning. This is why xslt is a good choice IMHO, as
we can generate both static XHTML and PHP with two stylesheets.

Bye !
--=20
Xavier VELLO