docbook: Thread: Updated XSL Stylesheets

Hi Everyone,

A while back I volunteered to try to fix the ldp-xsl stylesheets that 
Dan York originally wrote.  I have gotten them to work with Saxon and 
docbook-xsl-1.61.3.  They probably work with other parsers as well.  If 
anyone is interested in using them, the updated version can be found at: 
http://my.core.com/~dhorton/docbook/tldp-xsl/tldp-xsl-30jun2003.tar.gz

If you do decide to use them, please let me know about your experience.

Dave

On Mon, Jun 30, 2003 at 08:07:03PM -0500, David Horton wrote:
> A while back I volunteered to try to fix the ldp-xsl stylesheets that 
> Dan York originally wrote.  I have gotten them to work with Saxon and 
> docbook-xsl-1.61.3.  They probably work with other parsers as well.  If 
> anyone is interested in using them, the updated version can be found at: 
> http://my.core.com/~dhorton/docbook/tldp-xsl/tldp-xsl-30jun2003.tar.gz

Maybe I don't undersatnd what they're supposed to output...but there are
virtually no line breaks in the document that I get when I use the
following:
	xsltproc 
		-o tldp-testing.html
		/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/fo/tldp-html.xsl
		acpi.xml

I find line breaks immensely useful when trying to grok plain text files.
When I'm done I get the following printed to the screen:
	Making portrait pages on USletter paper (8.5inx11in)

As far as I can tell this is *not* outputing HTML content which makes the
name tldp-html.xsl very misleading to me.

As far as testing it with saxon....I've not had any luck installing the
debian packages, but I'm still trying.

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

On Tue, Jul 01, 2003 at 04:04:13PM -0400, Emma Jane Hogbin wrote:
> On Mon, Jun 30, 2003 at 08:07:03PM -0500, David Horton wrote:
> > A while back I volunteered to try to fix the ldp-xsl stylesheets that 
> > Dan York originally wrote.  I have gotten them to work with Saxon and 
> > docbook-xsl-1.61.3.  They probably work with other parsers as well.  If 
> > anyone is interested in using them, the updated version can be found at: 
> > http://my.core.com/~dhorton/docbook/tldp-xsl/tldp-xsl-30jun2003.tar.gz
> 
> Maybe I don't undersatnd what they're supposed to output...but there are
> virtually no line breaks in the document that I get when I use the
> following:
> 	xsltproc 
> 		-o tldp-testing.html
> 		/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/fo/tldp-html.xsl
> 		acpi.xml
> 
> I find line breaks immensely useful when trying to grok plain text files.
> When I'm done I get the following printed to the screen:
> 	Making portrait pages on USletter paper (8.5inx11in)
> 
> As far as I can tell this is *not* outputing HTML content which makes the
> name tldp-html.xsl very misleading to me.
> 
> As far as testing it with saxon....I've not had any luck installing the
> debian packages, but I'm still trying.

You are correct, it is not outputting HTML.
I haven't used these stylesheets, but
the "Making portait pages ..." messages indicates
it is outputting XSL-FO.  Perhaps changing
the "/fo/" in the path to "/html/" would fix it,
but I don't know why the filename itself includes
"html" if it is putting out FO.

-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: ####@####.####

On Tue, Jul 01, 2003 at 02:15:33PM -0700, Bob Stayton wrote:
> You are correct, it is not outputting HTML.
> I haven't used these stylesheets, but
> the "Making portait pages ..." messages indicates
> it is outputting XSL-FO.  Perhaps changing
> the "/fo/" in the path to "/html/" would fix it,
> but I don't know why the filename itself includes
> "html" if it is putting out FO.

Yup, I put the files into the wrong directory. :/ Fixed now, thanks!!

Some comments on the output of HTML files:
	- the page doesn't validate as HTML or as XHTML (as per the correct
	  directory). The DOCTYPE is missing from the HTML version so
	  validator.w3.org doesn't even bother trying. For the XHTML version
	  there are namespaces put into elements that don't allow them.
	- output looks great in lynx
	- output in firebird-mozilla has a weird character after section
	  numbers and before the text. It's a capital A with a circonflex
	  (hat) accent. Also visible in the plain text output -- perhaps the
	  character encoding meta information is incorrect?
	- same complaints as before re. new lines, but it's much better this
	  time.
	- there are *many* deprecated elements being used. This is a Bad Thing
	  in my opinion. A quick glance shows: b, tt and i
	- there is still some HTML which could be stripped out, I think. For
	  example: <div class="titlepage"><div><div><h3 class="title">
	  <a id="id2800871"></a>8.1. Unpack</h3></div></div><div>
	  What are the extra <div>s for?
	- again: extra HTML around:
		<b class="command">make	<i class="parameter"><tt>menuconfig</tt></i></b>
	  why not just call it <span class="parameter"> and use CSS to style
	  the font to a monospaced font?
	- <div class="blockquote"><table border="0" width="100%"
	  cellspacing="0" cellpadding="0" class="blockquote" summary="Block
	  quote">
	  Argh!! Why not just use the HTML element "blockquote"?
	- <div class="sect1" lang="en" xml:lang="en">
	  are sections some times different languages than the parent
	  document? I don't think this is necessary as my guess is that
	  documents are always written in a single document. Why not simply
	  put the language in the <html> start tag and be done with it?
	  
I haven't worked a lot with XSLT so maybe the problems are in nwalsh's
files, and maybe they're in the revised tldp files? Being an HTML snob I
would not be happy with this output based on the work that I put into (1)
the original HTML document I wrote (2) the amount of effort I put into
converting my HTML file into docbook.

But those are just one person's comments. :)

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

Emma Jane Hogbin wrote:

> On Tue, Jul 01, 2003 at 02:15:33PM -0700, Bob Stayton wrote:
> 
>>You are correct, it is not outputting HTML.
>>I haven't used these stylesheets, but
>>the "Making portait pages ..." messages indicates
>>it is outputting XSL-FO.  Perhaps changing
>>the "/fo/" in the path to "/html/" would fix it,
>>but I don't know why the filename itself includes
>>"html" if it is putting out FO.
> 
> 
> Yup, I put the files into the wrong directory. :/ Fixed now, thanks!!
> 
> Some comments on the output of HTML files:
> 	- the page doesn't validate as HTML or as XHTML (as per the correct
> 	  directory). The DOCTYPE is missing from the HTML version so
> 	  validator.w3.org doesn't even bother trying. For the XHTML version
> 	  there are namespaces put into elements that don't allow them.
> 	- output looks great in lynx
> 	- output in firebird-mozilla has a weird character after section
> 	  numbers and before the text. It's a capital A with a circonflex
> 	  (hat) accent. Also visible in the plain text output -- perhaps the
> 	  character encoding meta information is incorrect?
> 	- same complaints as before re. new lines, but it's much better this
> 	  time.
> 	- there are *many* deprecated elements being used. This is a Bad Thing
> 	  in my opinion. A quick glance shows: b, tt and i
> 	- there is still some HTML which could be stripped out, I think. For
> 	  example: <div class="titlepage"><div><div><h3 class="title">
> 	  <a id="id2800871"></a>8.1.? Unpack</h3></div></div><div>
> 	  What are the extra <div>s for?
> 	- again: extra HTML around:
> 		<b class="command">make	<i class="parameter"><tt>menuconfig</tt></i></b>
> 	  why not just call it <span class="parameter"> and use CSS to style
> 	  the font to a monospaced font?
> 	- <div class="blockquote"><table border="0" width="100%"
> 	  cellspacing="0" cellpadding="0" class="blockquote" summary="Block
> 	  quote">
> 	  Argh!! Why not just use the HTML element "blockquote"?
> 	- <div class="sect1" lang="en" xml:lang="en">
> 	  are sections some times different languages than the parent
> 	  document? I don't think this is necessary as my guess is that
> 	  documents are always written in a single document. Why not simply
> 	  put the language in the <html> start tag and be done with it?
> 	  
> I haven't worked a lot with XSLT so maybe the problems are in nwalsh's
> files, and maybe they're in the revised tldp files? Being an HTML snob I
> would not be happy with this output based on the work that I put into (1)
> the original HTML document I wrote (2) the amount of effort I put into
> converting my HTML file into docbook.
> 
> But those are just one person's comments. :)
> 
> emma
> 

Emma,

I agree with you 100% on the messy HTML output and use of depreciated 
tags.  I'm still in the HTML snob rehab clinic myself.  :^)  I really 
don't know how much of the sloppiness is due to the tldp-xsl 
customizations and how much of it stems from the original docbook-xsl 
stylesheets.  Right now I'm at the bottom of a steep XSLT learning curve.

Some day soon I would like to process the same Docbook XML document 
using both Norman Walsh's docbook-xsl and the tldp-xsl customizations 
and then put the html outputs through a validator.  This should 
determine which one is causing the HTML sloppiness.  If you have the 
time and inclination to do this and can send me your findings it would 
be appreciated.  If it turns out that the docbook-xsl stylesheets are 
the cause I would suggest that we address our concerns to the people 
maintaining them.

In the end I'd love to see these stylesheets be able to turn out nice 
looking valid HTML 4.0, but right now I'm just happy to see text other 
than Saxon's error messages.

Dave

On Tue, Jul 01, 2003 at 08:23:52PM -0500, David Horton wrote:
> I agree with you 100% on the messy HTML output and use of depreciated 
> tags.  I'm still in the HTML snob rehab clinic myself.  :^)

:)

> time and inclination to do this and can send me your findings it would 
> be appreciated.  If it turns out that the docbook-xsl stylesheets are 
> the cause I would suggest that we address our concerns to the people 
> maintaining them.

Sure, I can give it a whirl and let you know what I find. I'll send stuff
through to the list. At a very quick glance it looks like there's at least
a few things in the tldp files that can be cleaned up. Should I go ahead
and make the changes and post them on a site somewhere for others to look
at?

> In the end I'd love to see these stylesheets be able to turn out nice 
> looking valid HTML 4.0, but right now I'm just happy to see text other 
> than Saxon's error messages.

Definitely no error messages with xsltproc...now it just looks like a
matter of tweaking the configuration to suit my snobby HTML requirements.
:)

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

Emma Jane Hogbin wrote:

> > time and inclination to do this and can send me your findings it would 
> > be appreciated.  If it turns out that the docbook-xsl stylesheets are 
> > the cause I would suggest that we address our concerns to the people 
> > maintaining them.
> 
> Sure, I can give it a whirl and let you know what I find. I'll send stuff
> through to the list. At a very quick glance it looks like there's at least
> a few things in the tldp files that can be cleaned up. Should I go ahead
> and make the changes and post them on a site somewhere for others to look
> at?


Yes, I would love to see them cleaned up.  However, I have a feeling
that a lot of the use of older tags is due to the docbook-xsl
stylesheets.  It seems like the tldp-xsl files just tweak variables and
settings.


> 
> > In the end I'd love to see these stylesheets be able to turn out nice 
> > looking valid HTML 4.0, but right now I'm just happy to see text other 
> > than Saxon's error messages.
> 
> Definitely no error messages with xsltproc...now it just looks like a
> matter of tweaking the configuration to suit my snobby HTML requirements.
> :)
> 

Were you able to get the older ldp-xsl stylesheets to work without
errors?  I was under the impression that they were broken.  At least I
could never get them to work with Saxon before making the changes.


Thanks for offering your assistance on this.

Dave

On Wed, Jul 02, 2003 at 09:00:19AM -0400, David Horton wrote:
> Yes, I would love to see them cleaned up.  However, I have a feeling
> that a lot of the use of older tags is due to the docbook-xsl
> stylesheets.  It seems like the tldp-xsl files just tweak variables and
> settings.

There's at least one <table> wrapped around a <pre> in the tldp files.

> Were you able to get the older ldp-xsl stylesheets to work without
> errors?  

I'm using a debian package, so it's possible I have a different version
from you; however, I was able to get them to work with no errors by using
xsltproc (still haven't figured out how to get saxon installed using
debian packages). The output page doesn't validate but it has the exact same
errors as the new tldp-xsl files. (xmlns in elements it's not allowed to
exist in)

> I was under the impression that they were broken.  At least I
> could never get them to work with Saxon before making the changes.

Saxon may be more strict that xsltproc, I'm not sure. If anyone has both
installed maybe they could give it a try?

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]

On Tue, Jul 01, 2003 at 05:27:38PM -0400, Emma Jane Hogbin wrote:
> On Tue, Jul 01, 2003 at 02:15:33PM -0700, Bob Stayton wrote:
> > You are correct, it is not outputting HTML.
> > I haven't used these stylesheets, but
> > the "Making portait pages ..." messages indicates
> > it is outputting XSL-FO.  Perhaps changing
> > the "/fo/" in the path to "/html/" would fix it,
> > but I don't know why the filename itself includes
> > "html" if it is putting out FO.
> 
> Yup, I put the files into the wrong directory. :/ Fixed now, thanks!!
> 
> Some comments on the output of HTML files:

As one of the maintainers of the DocBook XSL stylesheets,
I can confirm that they still output some older HTML tags like <b>.
The debate has been about whether or not the stylesheets should
produce usable output without requiring a CSS stylesheet.
There is a sufficiently large installed base for the stylesheets
that requiring CSS would be disruptive for some.

That said, the stylesheets now have a 'make.valid.html'
parameter whose effect will be to clean up these remaining
problems.  But it is only planned and not yet implemented
in the stylesheets at this moment.  Probably by the
next release.

> 	- the page doesn't validate as HTML or as XHTML (as per the correct
> 	  directory). The DOCTYPE is missing from the HTML version so
> 	  validator.w3.org doesn't even bother trying.

Right.  Coming soon.  But probably 4.01 Transitional,
not Strict. 

>         For the XHTML version
> 	  there are namespaces put into elements that don't allow them.

This is a bug in the version of xsltproc you are using.
Try a later version.

> 	- output looks great in lynx
> 	- output in firebird-mozilla has a weird character after section
> 	  numbers and before the text. It's a capital A with a circonflex
> 	  (hat) accent. Also visible in the plain text output -- perhaps the
> 	  character encoding meta information is incorrect?
> 	- same complaints as before re. new lines, but it's much better this
> 	  time.

The HTML stylesheets use <xsl:output indent="no"/>
for various reasons.  Unfortunately, that indent
attribute cannot be set by a runtime stylesheet parameter.
But the ldp customization could change it.
The custom xsl:output could also produce a DOCTYPE
declaration, if you like.

> 	- there are *many* deprecated elements being used. This is a Bad Thing
> 	  in my opinion. A quick glance shows: b, tt and i

Yes, will be fixed by setting a 'make.valid.html' parameter.

> 	- there is still some HTML which could be stripped out, I think. For
> 	  example: <div class="titlepage"><div><div><h3 class="title">
> 	  <a id="id2800871"></a>8.1. Unpack</h3></div></div><div>
> 	  What are the extra <div>s for?

The DocBook stylesheets have a pretty complex system for
generating headings, using a general "title page" system
that provides a lot of optional control.  It leads to nested
structures, some of which may not appear in your output.

> 	- again: extra HTML around:
> 		<b class="command">make	<i class="parameter"><tt>menuconfig</tt></i></b>
> 	  why not just call it <span class="parameter"> and use CSS to style
> 	  the font to a monospaced font?
> 	- <div class="blockquote"><table border="0" width="100%"
> 	  cellspacing="0" cellpadding="0" class="blockquote" summary="Block
> 	  quote">
> 	  Argh!! Why not just use the HTML element "blockquote"?

The HTML table is used to format the placement of the
attribution child of the DocBook blockquote element.
If you don't use an attribution, you should get the HTML
<blockquote> element.

> 	- <div class="sect1" lang="en" xml:lang="en">
> 	  are sections some times different languages than the parent
> 	  document? I don't think this is necessary as my guess is that
> 	  documents are always written in a single document. Why not simply
> 	  put the language in the <html> start tag and be done with it?

As far as I can tell, there are only two places where the
DocBook XSL stylesheets output a 'lang' attribute, for a
blockquote and foreignphrase if it carries a lang or
xml:lang attribute.  They don't output lang on the
root element, and they don't output xml:lang at all. 
I don't know where that's coming from.
 	  
> I haven't worked a lot with XSLT so maybe the problems are in nwalsh's
> files, and maybe they're in the revised tldp files? Being an HTML snob I
> would not be happy with this output based on the work that I put into (1)
> the original HTML document I wrote (2) the amount of effort I put into
> converting my HTML file into docbook.
> 
> But those are just one person's comments. :)

I'd like to work with you toward getting the DocBook
stylesheets in better HTML compliance, when the 
new parameter is implemented.
-- 

Bob Stayton                                 400 Encinal Street
Publications Architect                      Santa Cruz, CA  95060
Technical Publications                      voice: (831) 427-7796
The SCO Group                               fax:   (831) 429-1887
                                            email: ####@####.####

Apologies in advance for the length. I've moved the bottom bit up to the
top just in case people don't want to read my HTML suggestions. :)

> I'd like to work with you toward getting the DocBook
> stylesheets in better HTML compliance, when the 
> new parameter is implemented.

Cool. :) Please stay in touch via email or through this list when it's
time.

On Wed, Jul 02, 2003 at 10:09:03AM -0700, Bob Stayton wrote:
> On Tue, Jul 01, 2003 at 05:27:38PM -0400, Emma Jane Hogbin wrote:
> > On Tue, Jul 01, 2003 at 02:15:33PM -0700, Bob Stayton wrote:

> As one of the maintainers of the DocBook XSL stylesheets,
> I can confirm that they still output some older HTML tags like <b>.
> The debate has been about whether or not the stylesheets should
> produce usable output without requiring a CSS stylesheet.
> There is a sufficiently large installed base for the stylesheets
> that requiring CSS would be disruptive for some.

It depends on why <b>, <i> and <tt> are being used. Sometimes it's for
foramtting purposes. Here are a couple of examples of how I might change
things:
	- the word Author is wrapped in <i> at the very beginning of 
	  the document. In this case it is for formatting purposes only. I would
	  remove the <i> completely and allow formatting based on CSS only.
	- the <emphasis> DocBook tag is replaced by <i class="emphasis">. This
	  should be replaced by the HTML tag <em>.
	- <th ...><b>Revision History</b></th> By default <th> is centered and
	  bold. Remove the <b> tag which is used for formatting purposes only.
	- <b> is used for either class="userinput" or class="command". In both
	  cases this is for a formatting effect. <b> is for formatting so
	  technically this is correct, although I would probably use <span>
	  instead as <b> is deprecated (and therefore disappears as of XHTML
	  1.0 Strict)

> That said, the stylesheets now have a 'make.valid.html'
> parameter whose effect will be to clean up these remaining
> problems.  But it is only planned and not yet implemented
> in the stylesheets at this moment.  Probably by the
> next release.

The use of <b>, <i> and <tt> is completely acceptable with the correct
DTD! I just wanted to clarify that. It's more how they're being used.
Sometimes I don't feel it's the best choice of HTML markup given the 
content. Plus it's good to move away from elements that are deprecated.

> > 	- the page doesn't validate as HTML or as XHTML (as per the correct
> > 	  directory). The DOCTYPE is missing from the HTML version so
> > 	  validator.w3.org doesn't even bother trying.
> 
> Right.  Coming soon.  But probably 4.01 Transitional, not Strict. 

I'm cool with a validating Transitional document. :) There's also an XHTML
folder for the nwalsh files so you can pick between HTML and XHTML. I
think that's neat option to have.

> >         For the XHTML version
> > 	  there are namespaces put into elements that don't allow them.
> 
> This is a bug in the version of xsltproc you are using.
> Try a later version.

Bah. Debian did all the installing and that is the latest version
according to unstable. This is the version I'm using:
emmajane@debian:/web/ref$ xsltproc -version
Using libxml 20507, libxslt 10030 and libexslt 720
xsltproc was compiled against libxml 20507, libxslt 10030 and libexslt 720
libxslt 10030 was compiled against libxml 20507
libexslt 720 was compiled against libxml 20507

> > 	- output in firebird-mozilla has a weird character after section
> > 	  numbers and before the text. It's a capital A with a circonflex
> > 	  (hat) accent. Also visible in the plain text output -- perhaps the
> > 	  character encoding meta information is incorrect?

Update: it also translates <quote> into something that lynx can read by
firebird-mozilla (and less/more) can't read.

> > 	- same complaints as before re. new lines, but it's much better this
> > 	  time.
> 
> The HTML stylesheets use <xsl:output indent="no"/>
> for various reasons.  Unfortunately, that indent
> attribute cannot be set by a runtime stylesheet parameter.
> But the ldp customization could change it.
> The custom xsl:output could also produce a DOCTYPE
> declaration, if you like.

Will look into this.

> > 	- there is still some HTML which could be stripped out, I think. For
> > 	  example: <div class="titlepage"><div><div><h3 class="title">
> > 	  <a id="id2800871"></a>8.1.? Unpack</h3></div></div><div>
> > 	  What are the extra <div>s for?
> 
> The DocBook stylesheets have a pretty complex system for
> generating headings, using a general "title page" system
> that provides a lot of optional control.  It leads to nested
> structures, some of which may not appear in your output.

*nod* I thought it would be something like that. Sometimes this is the way
things are with automated procedures.

> > 	- <div class="blockquote"><table border="0" width="100%"
> > 	  cellspacing="0" cellpadding="0" class="blockquote" summary="Block
> > 	  quote">
> > 	  Argh!! Why not just use the HTML element "blockquote"?
> 
> The HTML table is used to format the placement of the
> attribution child of the DocBook blockquote element.
> If you don't use an attribution, you should get the HTML
> <blockquote> element.

This would be a *perfect* candidate for something you could do with CSS.
<blockquote>
<div style="text-align: right">attribution</div>
</blockquote>

Just checked the XHTML 1.0 Transitional DTD and this is legal. I'd need to
check the HTML 4 one as well but I'm sure it would be fine. Ultimately the
style attribute would be replaced by class="attribution" and the
attribution class would be styled however you wanted.

> > 	- <div class="sect1" lang="en" xml:lang="en">
> > 	  are sections some times different languages than the parent
> > 	  document? I don't think this is necessary as my guess is that
> > 	  documents are always written in a single document. Why not simply
> > 	  put the language in the <html> start tag and be done with it?
> 
> As far as I can tell, there are only two places where the
> DocBook XSL stylesheets output a 'lang' attribute, for a
> blockquote and foreignphrase if it carries a lang or
> xml:lang attribute.  They don't output lang on the
> root element, and they don't output xml:lang at all. 
> I don't know where that's coming from.

Hmm, I will need to look into this. As a side note: for accessibility purposes 
all documents should have their natural language identified in the <html>
(root) element. http://www.w3.org/TR/WCAG10/#gl-abbreviated-and-foreign
This is to help screen reading software identify which language they are 
reading. I think it would be neat if the documents validated not only as
HTML but also validated under the Web Accessibilty Initiative (WAI)
guidelines. These guidelines are mandatory for many government documents
and are the base for the American Section 508 Guidelines on accessiblity.

As a second side note: I think there should be a little bit of attention
put into the meta data that is output. (I'm notoriously lazy on this point 
when authoring my own documents.) It would be easy to add at least an
author. 

emma

-- 
Emma Jane Hogbin
[[ 416 417 2868 ][ www.xtrinsic.com ]]