docbook-apps

Richard wrote:
> X-No-Archive: yes
>
> Hi. I'm using the DocBook XSL stylesheets to generate HTML output *.
> Some
> things about the output seem unusual to me. I am relatively new to
> DocBook XSL though.
> Issues:
> a) Limited accessibility with rendered HTML elements.

Specific examples please?
We did review this some time back, but we may have missed something.
(I'm part of WAI so very interested)


> b) Command synopsis arguments do not have attributes for CSS
> referencing,
> nor any semantic markup.

What do you want to identify for CSS processing?


> c) The parameter(s) to make output HTML be valid ... do not output
> valid HTML.
>
> * DocBook XML 4.4, stylesheets 1.71.0, xsltproc, on Debian.


How about updating your setup first?




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Am Donnerstag, den 22.11.2007, 14:01 +0000 schrieb Dave Pawson:
> Richard wrote:

[..]
> > c) The parameter(s) to make output HTML be valid ... do not output
> > valid HTML.
> >
> > * DocBook XML 4.4, stylesheets 1.71.0, xsltproc, on Debian.
>
>
> How about updating your setup first?

This is a Debian Etch. Updates are only available for security issues or
grave bugs. None of these packages have grave bugs or security issues
(I'm the maintainer for the DocBook XML and docbook-xsl packages).

*But* if you want to use updated packages, then you should be able to
get and install docbook-xml and docbook-xsl from Sid. The dependencies
can be fulfilled on Etch systems too. That's the reason, why there are
no packages at backports.org.

Regards, Daniel

Thank you to all who replied so far.

> [DaveP] How about updating your setup first?

In this case, the stylesheets version is not the culprit. I tried with
the latest SourceForge.net release [1.73.2] just now to make sure,
and the relevant HTML is identical. I had checked building with the
newer minor
version release the other day, to see if things rendered broadly the
same (as
they should) and they did. I don't recall if I checked each issue in
the
original message, but I *did* make sure to read each changelog entry
between
the 1.71.0-1.73.2 versions, to see if something like this were
mentioned (it
wasn't). To iterate: even using the param(s) I mentioned in the message
you
replied to, the doctype is omitted (including with v1.73.2). The other
issues
in the original mail, i.e. a, b, also continue with the newer release
version.

Here, the software I am documenting is a webapp. The app is usually
deployed on
production servers. This is why the tool versions used happen to match
those in
Debian Stable (Etch), as Daniel pointed out. For 'production' servers
using
Debian, the Stable variant is recommended. My desktop happens to use
Debian Lenny
(Testing), but I try to make sure the docs build with tool versions
available
in the Stable repository if possible. End-users are most likely to
generate the
webapp docs using those versions. Of course, should a newer stylesheet
version
be required then so be it.

You asked for specific examples and details on the other points. I'm a
little confused
as I tried to include some in the original mail? I'm more than happy to
re-write
those parts if they don't make the issues clear. Just to check please:
It sounds as if those parts may not have come through for you? They
show on the list web archives
[http://lists.oasis-open.org/archives/docbook/200710/msg00013.html]
The only reason I can think of why they might not, is the five-dashes
line I used to
separate the summary and specifics. It shouldn't have been a problem
though, since
the sig. indicator is 2 lines, followed by a space, then a carriage
return.
Like I say, I'm happy to try and give more details; just thought I'd
first better check if the original listmail arrived but with text
*chopped* ... or the examples just weren't sufficiently
detailed/useful.

Regards, Richard.

--- Richard <...> wrote:

[SNIP]
> It sounds as if those parts may not have come through for you? They
> show on the list web archives [SNIP]
> The only reason I can think of why they might not [SNIP]

Whoops. The list archive message URL should've been
http://lists.oasis-open.org/archives/docbook-apps/200711/msg00110.html
The one I pasted was one I'd looked at the other day, since it had some
useful bits. Apologies! :)

Richard wrote:
> --- Richard <...> wrote:
>
> [SNIP]
>> It sounds as if those parts may not have come through for you? They
>> show on the list web archives [SNIP]
>> The only reason I can think of why they might not [SNIP]
>
> Whoops. The list archive message URL should've been
> http://lists.oasis-open.org/archives/docbook-apps/200711/msg00110.html
> The one I pasted was one I'd looked at the other day, since it had some
> useful bits. Apologies! :)


That's clearer. No, you're right. I didn't read below the lines.

"a) Limited accessibility with rendered HTML elements.
Which HTML elements get output, for the same 'effect', seems to vary
depending on which tag(s) were used in the XML source, and where they
were used.
Sometimes the element is used for bolded text, though this is
deprecated
and works poorly with assistive technologies like screenreaders.
In other cases the tag is output."


That's simply an aspect of going from a richer vocabulary to a lesser
one. HTML has far less elements than docbook.

Jaws is quite happy with bold, which AT are you referring to please?

The logic seems quite predictable in the examples you quote.
Heading content is rendered bold for that class of formal block.
A list, of a different class of markup, gets the role attribute
mapped over to a span (which is an authors choice btw through
customization).
Again you could customize the XSLT if you always wanted a particular
markup in the output?

Re the cmdsynopsis, I guess we could argue all day as to what is right
and neither of us could be definitive. That's the way it is, if
you want to customize it please do.


I don't regard that as 'limited accessibility'.


You say
b) Command synopsis arguments when output do not have attributes for
CSS
referencing, nor any semantic markup.

Yet the class information is passed through for CSS use. What are you
looking for here?

The semantic markup is in the XML, not the HTML.


c) The parameter(s) to make output HTML be valid ... do not output
valid HTML.
Using <xsl:param name="make.valid.html" select="1"></xsl:param>
(am also using <xsl:param name="html.cleanup" select="1"></xsl:param>),
the HTML output is not
valid, because no doctype [http://www.alistapart.com/stories/doctype/]
is
included. This makes popular browsers render the pages in "quirks
mode", etc.



Some users clearly don't want the decl output. You found the parameter
to get what you wanted though?

With the complexity of the docbook markup it's often the case that
the output is invalid. The parameter does say this?




regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk

Dave Pawson [mailto:davep@dpawson.co.uk] wrote:

> Richard wrote:
...
> "a) Limited accessibility with rendered HTML elements.
> Which HTML elements get output, for the same 'effect', seems to vary
> depending on which tag(s) were used in the XML source, and where they
> were used.
> Sometimes the element is used for bolded text, though this is
> deprecated
> and works poorly with assistive technologies like screenreaders.
> In other cases the tag is output."
>
>
> That's simply an aspect of going from a richer vocabulary to a lesser
> one. HTML has far less elements than docbook.

and...

> Yet the class information is passed through for CSS use. What are you
> looking for here?
>
> The semantic markup is in the XML, not the HTML.


I think Richard's point, which I agree with, is that the HTML should be
as semantically valid as it can be--which is to say, no hardcoded
formatting tags when a class name will do nicely. I haven't used or
within raw HTML in years, because (a) there's no need anymore, and
(b) it doesn't tell you anything about what you're marking up.

Certainly something like this:

(1) args

makes more semantic sense than this:

(1) args


We've modified the XSL to do this for quite a few inline elements, which
in our case has also allowed us to divide up authoring tasks more
easily. You can customize the formatting of the output with a CSS file,
without having to know the more complex XSLT.


Rob Cavicchio
Senior Technical Writer
EMC Captiva
EMC Corporation
10145 Pacific Heights Boulevard, 6th Floor
San Diego, CA 92121-4234

P: (858) 320-1208
F: (858) 320-1010
E: Cavicchio_Rob@emc.com

The opinions expressed in this message are my own and should in no way
be interpreted to reflect the opinions of EMC.

Richard wrote:
> Thank you to all who replied so far.
>
>> [DaveP] How about updating your setup first?
>
> In this case, the stylesheets version is not the culprit. I tried with
> the latest SourceForge.net release [1.73.2] just now to make sure,
> and the relevant HTML is identical.


> To iterate: even using the param(s) I mentioned in the message
> you
> replied to, the doctype is omitted (including with v1.73.2).

Are you saying that is an accessibility issue, or an HTML validity issue?




>
> You asked for specific examples and details on the other points. I'm a
> little confused
> as I tried to include some in the original mail? I'm more than happy to
> re-write
> those parts if they don't make the issues clear. Just to check please:
> It sounds as if those parts may not have come through for you? They
> show on the list web archives
> [http://lists.oasis-open.org/archives/docbook/200710/msg00013.html]

Sorry Richard. I hadn't connected the two emails. One about
developing using XSLT, the other about accessibility and validity.
My bad. Ian S. Worthington is the author? You sign yourself Richard.
I guess there's some confusion here.







regards

--
Dave Pawson
XSLT XSL-FO FAQ.
http://www.dpawson.co.uk