lcd4linux-devel

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

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

Hello list ! (Jerry, I put you in CC in case you weren't in the list)

While browsing blogs, I found a discussion about php versus xslt versus
m4 versus docbook versus Perl ... on how to automatically generate html
pages with scripts, and I remembered our little project (which seems
sleeping this month).

I don't renounce to php, don't panic ;) But there was the problem of
documentation. Somebody (me ?) proposed to look at docbook, but it's
definitely too hard for me to create dsssl stylesheets, and moreover my
docbook installation seems broken :/ Another solution was to use XML
stylesheets with docbook, but the situation is even worse in my poor
woody.
A good solution appeared to me : XSLT. Don't rush on
google.[fr|at|com|de|...] and read more : XSLT works with a xml document
containing the text and some markup and a xsl stylesheet, which defines
how to do the transfomation from xml to whatever other markup language
(in our case, xhtml). The best (most complete) xslt processor seems to
be xsltproc and it does very well its job.

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 ;)
We can't use the stylesheets as is, but I'll be easy to adapt them to
our needs (one for the website, another for documentation in the
tarball). I'll try work on it soon, but I have to go back to school
tomorrow :(

Bye !
--------
Xavier VELLO

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

[Jerry S. <ye...@th...>]

Hello,

On Sun, Apr 18, 2004 at 10:30:20PM +0200, Xavier VELLO wrote:
> Hello list ! (Jerry, I put you in CC in case you weren't in the list)
> 
> documentation. Somebody (me ?) proposed to look at docbook, but it's
> definitely too hard for me to create dsssl stylesheets, and moreover my
> docbook installation seems broken :/ Another solution was to use XML
> stylesheets with docbook, but the situation is even worse in my poor
> woody.

Nod.  I have converted my original man page over to docbook.  I've been
meaning to work more on the conversion to html.

> A good solution appeared to me : XSLT. Don't rush on
> google.[fr|at|com|de|...] and read more : XSLT works with a xml document
> containing the text and some markup and a xsl stylesheet, which defines
> how to do the transfomation from xml to whatever other markup language
> (in our case, xhtml). The best (most complete) xslt processor seems to
> be xsltproc and it does very well its job.

I agree that XSLT is easier to use than dsssl and think it would be 
a better choice to transform the docbook source to html.

> 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! ;)

> We can't use the stylesheets as is, but I'll be easy to adapt them to
> our needs (one for the website, another for documentation in the
> tarball). I'll try work on it soon, but I have to go back to school
> tomorrow :(

Bah.  lcd4linux will still be here once school is done. :)

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?

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?

Jerry

-- 
Jerry Seutter

Email: ye...@th...
Web: http://www.thegeeks.net/~yello
Gallery: www.thegeeks.net/~yello/gallery (email me for username and password).

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

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

[Jerry S. <ye...@th...>]

Hi Xavier,

I played around with the docbook source and got it to export to
html using xsl.  Is this what you were looking for? See:

http://www.thegeeks.net/~yello/lcd4linux.html  <-- html
http://www.thegeeks.net/~yello/lcd4linux.sgml  <-- docbook source
http://www.thegeeks.net/~yello/lcd4linux.1     <-- man page

Technically the .sgml file is now xml as well...

The command line I used to generate the html was:

xsltproc /usr/share/xml/docbook/stylesheet/nwalsh/html/docbook.xsl \
lcd4linux.sgml > lcd4linux.html

I had to install the xsltproc and docbook-xsl packages in order to do
this.


Jerry

-- 
Jerry Seutter

Email: ye...@th...
Web: http://www.thegeeks.net/~yello
Gallery: www.thegeeks.net/~yello/gallery (email me for username and password).

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

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

Hi Jerry
 
> I played around with the docbook source and got it to export to
> html using xsl.  Is this what you were looking for? See:
In fact the file we need to be processed with xsltproc isn't a bare html
file, there will not be head, and not too much tags. And docbook isn't a
good choice to get html, get the source ;)

I think we need :
- <h1> <h2> and others 'headings', which won't be interpreted by
xsltproc, but correspond to css styles.
- <code> <conf> <link> <image> which will be processed by xsltproc and
be replaced by xhtml code.
- other html formating tags (<b> <i> <ul> <li> <table> and others) not
processed, like <h*>.

I'll try to think about the complete set of tags and rewrite the manpage
to give and example.

Bye !
-----
Xavier