docbook-apps

Hello,

I'm interested in achieving the effects that I see on the title page of
DocBook V5.0: The Transition Guide [1]--namely, the "this version",
"latest version", "previous versions", and "authors" lists I see on this
HTML article and at the top of all W3C specifications.

Is this achieved through a customization layer, server-side processing,
or something else entirely?

On a related note, have I mentioned that a DocBook
"cookbook"--publishing effects and how to achieve them--would be a
really great resource?

Cheers,

Brett

[1] http://www.docbook.org/docs/howto

Brett Leber <bleber+@cs.cmu.edu>, 2007-08-24 16:28 -0400:

> I'm interested in achieving the effects that I see on the title page of
> DocBook V5.0: The Transition Guide [1]--namely, the "this version", "latest
> version", "previous versions", and "authors" lists I see on this HTML
> article and at the top of all W3C specifications.
>
> Is this achieved through a customization layer, server-side processing, or
> something else entirely?

A customization layer; the sources are here:

https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/

> On a related note, have I mentioned that a DocBook "cookbook"--publishing
> effects and how to achieve them--would be a really great resource?

Might be an interesting project to try to work on with a
collaboratively with a group of other people, and publish it under
an open-source license. Or, I can think of some tech-book publishers
who would be happy to publish such a book if they could find a
good author willing to put time into working on it, and who could
commit to a delivery schedule.

--Mike

--
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/

On 8/25/2007 1:04 AM, Michael(tm) Smith wrote:
> Brett Leber <bleber+@cs.cmu.edu>, 2007-08-24 16:28 -0400:
>
>> I'm interested in achieving the effects that I see on the title page of
>> DocBook V5.0: The Transition Guide [1]--namely, the "this version", "latest
>> version", "previous versions", and "authors" lists I see on this HTML
>> article and at the top of all W3C specifications.
>>
>> Is this achieved through a customization layer, server-side processing, or
>> something else entirely?
>
> A customization layer; the sources are here:
>
> https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/

Thanks, Michael. I tried building this document on my local machine, and
it appears that the customization doesn't work when using the DocBook 5
stylesheets (docbook-xsl-ns-1.73.1). Should I use the
namespace-stripping stylesheets again, or is there an easy fix to make
the customization work with the namespace-aware stylesheets?

As I'm really an XSL novice, I might have more questions about using the
customization. I've started by copying lines 16-143 into my
customization layer.

>> On a related note, have I mentioned that a DocBook "cookbook"--publishing
>> effects and how to achieve them--would be a really great resource?
>
> Might be an interesting project to try to work on with a
> collaboratively with a group of other people, and publish it under
> an open-source license. Or, I can think of some tech-book publishers
> who would be happy to publish such a book if they could find a
> good author willing to put time into working on it, and who could
> commit to a delivery schedule.

I'd like to involved in such a project, although my utility as an author
may be limited. Still, what first steps would you recommend (assuming
it's easiest to start with a collaboration of DocBook users)? Do you
think the DocBook wiki is a reasonable place to start notes on such a
collaboration?

Thanks,

Brett

Brett Leber <bleber+@cs.cmu.edu>, 2007-08-28 14:25 -0400:

> On 8/25/2007 1:04 AM, Michael(tm) Smith wrote:
>> A customization layer; the sources are here:
>>
>> https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/
>
> Thanks, Michael. I tried building this document on my local machine, and it
> appears that the customization doesn't work when using the DocBook 5
> stylesheets (docbook-xsl-ns-1.73.1).

Sorry, I didn't understand that you were also using the XSL-NS
stylesheets. The existing HTML and FO customization layers there
are for use with the XSL (non-namespaced) stylesheets. It's
basically not possible to use an unmodified XSL customization
layer with the XSL-NS stylesheets, nor to use an unmodified XSL-NS
one with the XSL stylesheets.

Anyway, I've now added namespace-aware html-ns.xsl and fo-ns.xsl
files to the directory at the URL above. Those files are for use
with the XSL-NS stylesheets.

> Should I use the namespace-stripping stylesheets again, or is
> there an easy fix to make the customization work with the
> namespace-aware stylesheets?

To show what sort of changes you need to make in order to modify
an existing customization layer for use with the XSL-NS
stylesheets, I ran a diff between the html.xsl and html-ns.xsl at
the URL above, and have attached that.

It is mostly just a matter of adding namespace prefixes to all
your template matches, tests, etc. Though there are usually some
other complications; for example, in this case, the non-namespaced
stylesheet was expecting to find an articleinfo element. But it
won't find an articleinfo element in the (non-stripped) DocBook 5
howto.xml file, because articleinfo is not valid in DocBook 5.
It'll find an info element instead. So sometimes it's not enough
to just add a namespace prefix; in this case, I had to modify the
customization layer to look for a d:info instead of d:articleinfo.

By the way, I notice that when I use the original XSL
customization layer, all the links in the HTML output contain
@target=_top attributes. But if I use the XSL-NS customization
layer, they don't. I'm not sure why that is, but I don't think
it's due to any problems in the XSL-NS customization layer itself.
It seems to instead be a difference in the XSL-NS stylesheets.


[on the DocBook XSL "cookbook" idea]
> I'd like to involved in such a project, although my utility as an author
> may be limited. Still, what first steps would you recommend (assuming it's
> easiest to start with a collaboration of DocBook users)? Do you think the
> DocBook wiki is a reasonable place to start notes on such a collaboration?

Yeah, the Wiki is a good place to start. If you don't already have
edit access to, please let me know your username, and I'll add you.

Another way you might be able to get in touch with others that are
interested is by dropping by the #docbook channel on irc.freenode.net.

--Mike

--
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/

"Michael(tm) Smith" <smith@sideshowbarker.net>, 2007-08-29 14:46 +0900:

> To show what sort of changes you need to make in order to modify
> an existing customization layer for use with the XSL-NS
> stylesheets, I ran a diff between the html.xsl and html-ns.xsl at
> the URL above, and have attached that.

Sorry, forgot to attach it to my previous message. I've attached
it to this one.

--Mike

--
Michael(tm) Smith
http://people.w3.org/mike/
http://sideshowbarker.net/

Hi Mike,

Thanks for all the good information about the stylesheets. Your response to
Brett has prompted me to ask a few, hopefully related, questions:

I notice that the howto.xml file you pointed to at
https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/is
slightly different than the one at
http://docbook.org/docs/howto/2006-10-22/howto.xml -- is this intentional?

The Transition Guide talks about moving from DocBook 4.5 to 5.0, but doesn't
really cover changes to how the "ns" stylesheets could be used. Presumable a
future version of the document should recommend using the "ns" versions of
the stylesheets for DocBook 5.0 documents and also talk about how
customization layers would need to be changed (adding namespace prefixes,
etc.)?

The section on stylesheets
<http://www.docbook.org/docs/howto/#dbxsl>includes a link to
"experimental stylesheets" from
http://sagehill.net/xml/docbook5ns/ -- perhaps the link should be updated to
something like http://docbook.sourceforge.net/release/xsl-ns/current/ and
strike the part about the stylesheets being experimental?

Ken



On 8/29/07, Michael(tm) Smith <smith@sideshowbarker.net> wrote:
>
> Brett Leber <bleber+@cs.cmu.edu>, 2007-08-28 14:25 -0400:
>
> > On 8/25/2007 1:04 AM, Michael(tm) Smith wrote:
> >> A customization layer; the sources are here:
> >>
> >>
> https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/
> >
> > Thanks, Michael. I tried building this document on my local machine, and
> it
> > appears that the customization doesn't work when using the DocBook 5
> > stylesheets (docbook-xsl-ns-1.73.1).
>
> Sorry, I didn't understand that you were also using the XSL-NS
> stylesheets. The existing HTML and FO customization layers there
> are for use with the XSL (non-namespaced) stylesheets. It's
> basically not possible to use an unmodified XSL customization
> layer with the XSL-NS stylesheets, nor to use an unmodified XSL-NS
> one with the XSL stylesheets.
>
> Anyway, I've now added namespace-aware html-ns.xsl and fo-ns.xsl
> files to the directory at the URL above. Those files are for use
> with the XSL-NS stylesheets.
>
> > Should I use the namespace-stripping stylesheets again, or is
> > there an easy fix to make the customization work with the
> > namespace-aware stylesheets?
>
> To show what sort of changes you need to make in order to modify
> an existing customization layer for use with the XSL-NS
> stylesheets, I ran a diff between the html.xsl and html-ns.xsl at
> the URL above, and have attached that.
>
> It is mostly just a matter of adding namespace prefixes to all
> your template matches, tests, etc. Though there are usually some
> other complications; for example, in this case, the non-namespaced
> stylesheet was expecting to find an articleinfo element. But it
> won't find an articleinfo element in the (non-stripped) DocBook 5
> howto.xml file, because articleinfo is not valid in DocBook 5.
> It'll find an info element instead. So sometimes it's not enough
> to just add a namespace prefix; in this case, I had to modify the
> customization layer to look for a d:info instead of d:articleinfo.
>
> By the way, I notice that when I use the original XSL
> customization layer, all the links in the HTML output contain
> @target=_top attributes. But if I use the XSL-NS customization
> layer, they don't. I'm not sure why that is, but I don't think
> it's due to any problems in the XSL-NS customization layer itself.
> It seems to instead be a difference in the XSL-NS stylesheets.
>
>
> [on the DocBook XSL "cookbook" idea]
> > I'd like to involved in such a project, although my utility as an author
> > may be limited. Still, what first steps would you recommend (assuming
> it's
> > easiest to start with a collaboration of DocBook users)? Do you think
> the
> > DocBook wiki is a reasonable place to start notes on such a
> collaboration?
>
> Yeah, the Wiki is a good place to start. If you don't already have
> edit access to, please let me know your username, and I'll add you.
>
> Another way you might be able to get in touch with others that are
> interested is by dropping by the #docbook channel on irc.freenode.net.
>
> --Mike
>
> --
> Michael(tm) Smith
> http://people.w3.org/mike/
> http://sideshowbarker.net/
>
>

Ken Morse <kenneth.morse@gmail.com>, 2007-08-29 14:23 -0400:

> Thanks for all the good information about the stylesheets. Your response to
> Brett has prompted me to ask a few, hopefully related, questions:
>
> I notice that the howto.xml file you pointed to at
> https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxng/docbook/howto/is
> slightly different than the one at
> http://docbook.org/docs/howto/2006-10-22/howto.xml -- is this intentional?

I don't know. I guess I should point out that I'm not the owner of
that howto (Norm and Jirka and Dick Hamilton are, I think) and
didn't really contribute anything to development of it or to the
original build system for it. I just stepped in to try to help
answer Brett's questions about it and help him do what he needed.

> The Transition Guide talks about moving from DocBook 4.5 to 5.0, but doesn't
> really cover changes to how the "ns" stylesheets could be used. Presumable a
> future version of the document should recommend using the "ns" versions of
> the stylesheets for DocBook 5.0 documents and also talk about how
> customization layers would need to be changed (adding namespace prefixes,
> etc.)?

Yeah, I agree that should be added. The only issue with that is
the same one we always have: Finding somebody who has time and
interest in doing it. Somebody on the project may find time to do
it, but we also welcome editorial/content contributions from
anybody else who might want to send something. The sources are
available, so it'd mostly be a matter of checking those out,
making changes/additions, then sending those to us as a patch.

> The section on stylesheets
> <http://www.docbook.org/docs/howto/#dbxsl>includes a link to
> "experimental stylesheets" from
> http://sagehill.net/xml/docbook5ns/ -- perhaps the link should be updated to
> something like http://docbook.sourceforge.net/release/xsl-ns/current/ and
> strike the part about the stylesheets being experimental?

I've gone ahead and done a quick edit/update of that section, and
checked it back in. So the change is included in the source and
will be in the next published revision of the document (unless one
of the owners chooses to revert it).

As an example of what I mean about sending about patch, I've
attached to this message the diff for that change.

--Mike

Ken and Michael,
>
> Ken Morse <kenneth.morse@gmail.com>, 2007-08-29 14:23 -0400:
>
> > Thanks for all the good information about the stylesheets.
> > Your response to Brett has prompted me to ask a few, hopefully
> > related, questions:
> >
> > I notice that the howto.xml file you pointed to at
> >
https://docbook.svn.sourceforge.net/svnroot/docbook/trunk/docbook/relaxn
g/docbook/howto/
> > is slightly different than the one at
> > http://docbook.org/docs/howto/2006-10-22/howto.xml -- is
> > this intentional?
>
> I don't know. I guess I should point out that I'm not the owner of
> that howto (Norm and Jirka and Dick Hamilton are, I think) and
> didn't really contribute anything to development of it or to the
> original build system for it. I just stepped in to try to help
> answer Brett's questions about it and help him do what he needed.
>
As far as I can tell, the differences (other than the recent changes
Michael mentions below) are superficial and don't make any substantive
difference. That's probably why there hasn't been a new issue of the
howto. I haven't updated it myself in a while, so I suspect that Jirka
made the changes (some of them are just to parameterize the version
number, and most of the rest seem to be white space differences).
>
> > The Transition Guide talks about moving from DocBook 4.5 to 5.0, but
doesn't
> > really cover changes to how the "ns" stylesheets could be used.
Presumable a
> > future version of the document should recommend using the "ns"
versions of
> > the stylesheets for DocBook 5.0 documents and also talk about how
> > customization layers would need to be changed (adding namespace
prefixes,
> > etc.)?
>
> Yeah, I agree that should be added. The only issue with that is
> the same one we always have: Finding somebody who has time and
> interest in doing it. Somebody on the project may find time to do
> it, but we also welcome editorial/content contributions from
> anybody else who might want to send something. The sources are
> available, so it'd mostly be a matter of checking those out,
> making changes/additions, then sending those to us as a patch.
>
If no one leaps up and raises their hand, I'll take a look at that
section, but it may take me a little while; I use the ns stylesheets,
but I haven't looked at the internals except at a superficial level.
>
> > The section on stylesheets
> > <http://www.docbook.org/docs/howto/#dbxsl>includes a link to
> > "experimental stylesheets" from
> > http://sagehill.net/xml/docbook5ns/ -- perhaps the link should be
updated to
> > something like http://docbook.sourceforge.net/release/xsl->
ns/current/ and
> > strike the part about the stylesheets being experimental?
>
> I've gone ahead and done a quick edit/update of that section, and
> checked it back in. So the change is included in the source and
> will be in the next published revision of the document (unless one
> of the owners chooses to revert it).
>
Thanks for adding that note.

Dick Hamilton

Dick Hamilton wrote:

> As far as I can tell, the differences (other than the recent changes
> Michael mentions below) are superficial and don't make any substantive
> difference. That's probably why there hasn't been a new issue of the
> howto. I haven't updated it myself in a while, so I suspect that Jirka
> made the changes (some of them are just to parameterize the version
> number, and most of the rest seem to be white space differences).

I intended to add some new content and publish new version after final
5.0 is out. But I also supposed that 5.0 will be finalized in August
which is not the case anymore. So I will add new stuff (related to
validation tools) during next weeks and then publish new revision.

Jirka

--
------------------------------------------------------------------
Jirka Kosek e-mail: jirka@kosek.cz http://xmlguru.cz
------------------------------------------------------------------
Professional XML consulting and training services
DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------

> -----Original Message-----
> From: Michael(tm) Smith
>
> By the way, I notice that when I use the original XSL
> customization layer, all the links in the HTML output contain
> @target=_top attributes. But if I use the XSL-NS customization
> layer, they don't. I'm not sure why that is, but I don't think
> it's due to any problems in the XSL-NS customization layer itself.
> It seems to instead be a difference in the XSL-NS stylesheets.


In some places, the stylesheets lag behind schema changes between DocBook 4
and 5.

In the XSL-NS version of html/xref.xsl, @target is supposed to be assigned a
value in the the template with match="d:ulink". But that template is never
applied, since there is no ulink element in DocBook 5.

A similar case is the one pointed out by Ken Morse in another message today,
regarding ulink.footnotes in FO output.

Mauritz

Mike and Brett,
>>
>> On a related note, have I mentioned that a DocBook
"cookbook"--publishing
>> effects and how to achieve them--would be a really great resource?
>
> Might be an interesting project to try to work on with a
> collaboratively with a group of other people, and publish it under
> an open-source license. Or, I can think of some tech-book publishers
> who would be happy to publish such a book if they could find a
> good author willing to put time into working on it, and who could
> commit to a delivery schedule.
>
This seems like an intriguing idea, though potentially challenging,
since Bob's book covers so much ground already.

But, I can see how the cookbook format could be a great resource
and good supplement to what Bob has done, and of course, there's
a lot of DocBook beyond the stylesheets that could be covered.

I'd be interested in collaborating on this kind of project, and
might even have time for it if I can wrap up my current project:-).

Dick Hamilton