docbook-apps

Thanks again to everyone who pointed out WebHelp to me earlier this
week, and provided great hints for adjusting it to our needs!

I've had a look at webhelp.xsl from the DocBook 1.76.1 XSL style sheets.
In parts, this is a "regular" style sheet, in the sense that you can
override default values easily. For example, if I wanted to change the
file name of the start page, I'd look at this line ...

<xsl:param name="webhelp.start.filename">index.html</xsl:param>

... and override this with e.g. in a Makefile with:

--stringparam webhelp.start.filename "toc.htm"

There's one template, though, that consists of more than 120 lines, and
is thus not easily configurable:

<xsl:template name="user.head.content">

Granted, it's a template, rather than a parameter, so there's nothing
like a one-line change, done in a Makefile. :-) Anyway, here's what I
thought I should do -- add a customization layer with this:

<xsl:template name="user.head.content">

</xsl:template>

First question: Is this the right approach? Overriding 120+ lines of a
DocBook style sheet almost feels like modifying the style sheet itself,
which I'd never do because I guess that's considered heresy.

Last question: The user.head.content template has lots of things
hard-coded that I believe should be parametrized. Here's an extreme
example where both a specific jQuery theme and even the version number
are hard-coded:

href="../common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css"/>

Is there any way to parametrize *that* (i.e. within a template)?

If so, that should probably be done in webhelp.xsl, rather than in the
customization layer, so that not only our group would benefit. Assuming
parametrization could be done, what would be the proper way to
contribute such a patch? (OK, that's one more question, but it's related
to the previous one. :-))

Thanks in advance for any pointers!

--
Cheers,

Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation Manager

Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc

ORACLE Deutschland B.V.& Co. KG
Registered Office: Riesstr. 25, 80992 Muenchen, Germany
Commercial Register: Local Court Of Munich, HRA 95603
Managing Director: Jürgen Kunz

General Partner: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
Managing Directors: Alexander van der Ven, Astrid Kepper, Val Maher

Hi Stefan,
I'll be interested to see the other replies to your question. Your
suggestion is exactly what I've done. Even for some largish templates
(and user.head.content as well) I just copy them to my customization
layer and make them do what I need them to do. I know only enough
xslt to get myself in trouble, so hopefully we'll hear from more
knowledgeable folks about the *best* way to go.

good luck!
--Tim Arnold

On Fri, Jan 27, 2012 at 5:48 AM, Stefan Hinz <stefan.hinz@oracle.com> wrote:
> Thanks again to everyone who pointed out WebHelp to me earlier this week,
> and provided great hints for adjusting it to our needs!
>
> I've had a look at webhelp.xsl from the DocBook 1.76.1 XSL style sheets. In
> parts, this is a "regular" style sheet, in the sense that you can override
> default values easily. For example, if I wanted to change the file name of
> the start page, I'd look at this line ...
>
> <xsl:param name="webhelp.start.filename">index.html</xsl:param>
>
> ... and override this with e.g. in a Makefile with:
>
> --stringparam webhelp.start.filename "toc.htm"
>
> There's one template, though, that consists of more than 120 lines, and is
> thus not easily configurable:
>
> <xsl:template name="user.head.content">
>
> Granted, it's a template, rather than a parameter, so there's nothing like a
> one-line change, done in a Makefile. :-) Anyway, here's what I thought I
> should do -- add a customization layer with this:
>
> <xsl:template name="user.head.content">
>  
> </xsl:template>
>
> First question: Is this the right approach? Overriding 120+ lines of a
> DocBook style sheet almost feels like modifying the style sheet itself,
> which I'd never do because I guess that's considered heresy.
>
> Last question: The user.head.content template has lots of things hard-coded
> that I believe should be parametrized. Here's an extreme example where both
> a specific jQuery theme and even the version number are hard-coded:
>
> > href="../common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css"/>
>
> Is there any way to parametrize *that* (i.e. within a template)?
>
> If so, that should probably be done in webhelp.xsl, rather than in the
> customization layer, so that not only our group would benefit. Assuming
> parametrization could be done, what would be the proper way to contribute
> such a patch? (OK, that's one more question, but it's related to the
> previous one. :-))
>
> Thanks in advance for any pointers!
>
> --
> Cheers,
>
> Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation Manager
>
> Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc
>
> ORACLE Deutschland B.V.&  Co. KG
> Registered Office: Riesstr. 25, 80992 Muenchen, Germany
> Commercial Register: Local Court Of Munich, HRA 95603
> Managing Director: Jürgen Kunz
>
> General Partner: ORACLE Deutschland Verwaltung B.V.
> Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
> Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
> Managing Directors: Alexander van der Ven, Astrid Kepper, Val Maher
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail: docbook-apps-help@lists.oasis-open.org
>

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

So the xsls in svn has an empty template called
user.webhelp.head.content that is called at the end of
user.head.content which will help when you only want to add stuff to
. There's also a user.webhelp.content.footer and a
user.webhelp.navheader.content (thanks to Jirka for adding those):


<xsl:template name="user.webhelp.head.content"/>


<xsl:template name="user.webhelp.content.footer"/>

<xsl:template name="user.webhelp.navheader.content"/>

I'll add a note to the documentation about that feature.

It sounds like there's also a need for a $webhelp.jquery.theme.path
param so you can easily switch between themes.

Let me know if there are other things that need to be made easier to
customize. Webhelp is itself a customization layer, so it uses the
normal customization features of the DocBook xsls. It's also different
in that it includes a build script, and css, js, and image files. All
of which are candidates for customization as well.

Thanks,
David

On 01/27/2012 08:10 AM, Tim Arnold wrote:
> Hi Stefan, I'll be interested to see the other replies to your
> question. Your suggestion is exactly what I've done. Even for some
> largish templates (and user.head.content as well) I just copy them
> to my customization layer and make them do what I need them to do.
> I know only enough xslt to get myself in trouble, so hopefully
> we'll hear from more knowledgeable folks about the *best* way to
> go.
>
> good luck! --Tim Arnold
>
> On Fri, Jan 27, 2012 at 5:48 AM, Stefan Hinz
> <stefan.hinz@oracle.com> wrote:
>> Thanks again to everyone who pointed out WebHelp to me earlier
>> this week, and provided great hints for adjusting it to our
>> needs!
>>
>> I've had a look at webhelp.xsl from the DocBook 1.76.1 XSL style
>> sheets. In parts, this is a "regular" style sheet, in the sense
>> that you can override default values easily. For example, if I
>> wanted to change the file name of the start page, I'd look at
>> this line ...
>>
>> <xsl:param name="webhelp.start.filename">index.html</xsl:param>
>>
>> ... and override this with e.g. in a Makefile with:
>>
>> --stringparam webhelp.start.filename "toc.htm"
>>
>> There's one template, though, that consists of more than 120
>> lines, and is thus not easily configurable:
>>
>> <xsl:template name="user.head.content">
>>
>> Granted, it's a template, rather than a parameter, so there's
>> nothing like a one-line change, done in a Makefile. :-) Anyway,
>> here's what I thought I should do -- add a customization layer
>> with this:
>>
>> <xsl:template name="user.head.content"> </xsl:template>
>>
>> First question: Is this the right approach? Overriding 120+ lines
>> of a DocBook style sheet almost feels like modifying the style
>> sheet itself, which I'd never do because I guess that's
>> considered heresy.
>>
>> Last question: The user.head.content template has lots of things
>> hard-coded that I believe should be parametrized. Here's an
>> extreme example where both a specific jQuery theme and even the
>> version number are hard-coded:
>>
>> >> href="../common/jquery/theme-redmond/jquery-ui-1.8.2.custom.css"/>
>>
>>
>>
Is there any way to parametrize *that* (i.e. within a template)?
>>
>> If so, that should probably be done in webhelp.xsl, rather than
>> in the customization layer, so that not only our group would
>> benefit. Assuming parametrization could be done, what would be
>> the proper way to contribute such a patch? (OK, that's one more
>> question, but it's related to the previous one. :-))
>>
>> Thanks in advance for any pointers!
>>
>> -- Cheers,
>>
>> Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation
>> Manager
>>
>> Phone: +49-30-82702940, Fax: +49-30-82702941,
>> http://dev.mysql.com/doc
>>
>> ORACLE Deutschland B.V.& Co. KG Registered Office: Riesstr. 25,
>> 80992 Muenchen, Germany Commercial Register: Local Court Of
>> Munich, HRA 95603 Managing Director: Jürgen Kunz
>>
>> General Partner: ORACLE Deutschland Verwaltung B.V.
>> Hertogswetering 163/167, 3543 AS Utrecht, Niederlande Register Of
>> Chamber Of Commerce: Midden-Niederlande, No. 30143697 Managing
>> Directors: Alexander van der Ven, Astrid Kepper, Val Maher
>>
>> ---------------------------------------------------------------------
>>
>>
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
>> For additional commands, e-mail:
>> docbook-apps-help@lists.oasis-open.org
>>
>
> ---------------------------------------------------------------------
>
>
To unsubscribe, e-mail: docbook-apps-unsubscribe@lists.oasis-open.org
> For additional commands, e-mail:
> docbook-apps-help@lists.oasis-open.org
>

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJPIraaAAoJEMHeSXG7afUhpYUH/iUnDwIOu/SlQ0DojcJ2lYb0
EbFW0zzDnToqVahlS+HAZwpz1UkjpWuNcylG/5bCAf74mkp+463v/yeaiap+pQ1G
RBI1LBRpnY9zbdvsrZrc2OHDY4v27+4z8ICIPXClZ6x/3SHVH3wLIsNdMBb4O1WL
cdjJxYx334uark6gwcMH3wRFkaFxQtEbTVhGMaGbz6/8xlbxi1E3dvKMw1UYucQw
3vPTk1uH9d6Z0N7hjgZGTHJijE/74tbQV1q/RnpnsN4POPi4x6zBBa47IMXhC7Bi
frBBdOpeFb8FgmR82AzTR5RurTi2l4noyr/+qYbAcMqqouLXH1x24RTHdOiSdXM=
=7sVs
-----END PGP SIGNATURE-----

Hi David,

Excuse me for being dense, but are you saying you've put that empty
template in the SVN version of the XSL style sheets? If so, will that
change be in the next release of the DocBook style sheets?

Also, I wonder how user.webhelp.head.content is supposed to work. You're
saying it's called at the end of user.head.content, so I would assume it
becomes part of that template. But if that's correct, it would just
*add* stuff to the user.head.content template, rather than replacing
what's there. This wouldn't make much sense. Apparently, I'm missing
something.

You asked for things that we should be able to configure/customize.
Here's a list:

(1)

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On 01/27/2012 10:01 AM, Stefan Hinz wrote:
> Hi David,
>
> Excuse me for being dense, but are you saying you've put that
> empty template in the SVN version of the XSL style sheets? If so,
> will that change be in the next release of the DocBook style
> sheets?

Yes, the xsls in svn but not yet part of a release are available for
evaluation as part of the snapshot builds. For now, you can use this
url to download the snapshots:

http://snapshots.thingbag.net/

Eventually http://snapshots.docbook.org will take you there.

> Also, I wonder how user.webhelp.head.content is supposed to work.
> You're saying it's called at the end of user.head.content, so I
> would assume it becomes part of that template. But if that's
> correct, it would just *add* stuff to the user.head.content
> template, rather than replacing what's there. This wouldn't make
> much sense. Apparently, I'm missing something.

Yes, the idea is that these empty templates hooks that allow you to
add stuff. In this case it adds whatever you want to user.head.content
at the end in the same way that user.head.content adds stuff to
system.head.content in the base xsls. For example, you might want to
add your own

>> (1)

Hi David,

>> Excuse me for being dense, but are you saying you've put that
>> empty template in the SVN version of the XSL style sheets? If so,
>> will that change be in the next release of the DocBook style
>> sheets?
>
> Yes, the xsls in svn but not yet part of a release are available for
> evaluation as part of the snapshot builds. For now, you can use this
> url to download the snapshots:
>
> http://snapshots.thingbag.net/
>
> Eventually http://snapshots.docbook.org will take you there.

Great, thanks! Admittedly, we've been slow to update to the latest
DocBook XSL style sheet versions here at MySQL docs. We're getting
better about this, though, and I've just proposed that we pull in the
svn snapshots into our infrastructure, which would make it a lot easier
to run tests in our environment.

>> Also, I wonder how user.webhelp.head.content is supposed to work.
>> You're saying it's called at the end of user.head.content, so I
>> would assume it becomes part of that template. But if that's
>> correct, it would just *add* stuff to the user.head.content
>> template, rather than replacing what's there. This wouldn't make
>> much sense. Apparently, I'm missing something.
>
> Yes, the idea is that these empty templates hooks that allow you to
> add stuff. In this case it adds whatever you want to user.head.content
> at the end in the same way that user.head.content adds stuff to
> system.head.content in the base xsls. For example, you might want to
> add your own

Hi David,

> Yes, the xsls in svn but not yet part of a release are available for
> evaluation as part of the snapshot builds. For now, you can use this
> url to download the snapshots:
>
> http://snapshots.thingbag.net/
>
> Eventually http://snapshots.docbook.org will take you there.

While I could wget/curl things from there, updating via SVN would be
preferred. Feeling lucky, I thought I'd try that URL, but SVN just gives
a quite unhelpful response:

svn co http://snapshots.thingbag.net/xsl/ docbook-xsl-snapshot
svn: Repository moved permanently to
'http://snapshots.thingbag.net/xsl/'; please relocate

Got a better URL for me? :-)

--
Cheers,

Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation Manager

Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc

ORACLE Deutschland B.V.& Co. KG
Registered Office: Riesstr. 25, 80992 Muenchen, Germany
Commercial Register: Local Court Of Munich, HRA 95603
Managing Director: Jürgen Kunz

General Partner: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
Managing Directors: Alexander van der Ven, Astrid Kepper, Val Maher

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi Stefan,
So, what you're seeing at http://snapshots.thingbag.net is the result
of our snapshot/CI builds which are built directly from svn on each
checkin. The url http://snapshots.thingbag.net is temporary, btw.
Eventually it will be http://snapshots.docbook.org.

It is possible to checkout the source for the DocBook distribution
from svn [1], but you would then have to build it [2], so typically
working with the snapshot builds is much easier if you need features
that haven't made it into a release yet.

Does that help?

David

[1] http://sourceforge.net/scm/?type=svn&group_id=21935
[2] http://wiki.docbook.org/DocBookXslBuild

On 01/30/2012 10:48 AM, Stefan Hinz wrote:
> Hi David,
>
>> Yes, the xsls in svn but not yet part of a release are available
>> for evaluation as part of the snapshot builds. For now, you can
>> use this url to download the snapshots:
>>
>> http://snapshots.thingbag.net/
>>
>> Eventually http://snapshots.docbook.org will take you there.
>
> While I could wget/curl things from there, updating via SVN would
> be preferred. Feeling lucky, I thought I'd try that URL, but SVN
> just gives a quite unhelpful response:
>
> svn co http://snapshots.thingbag.net/xsl/ docbook-xsl-snapshot svn:
> Repository moved permanently to
> 'http://snapshots.thingbag.net/xsl/'; please relocate
>
> Got a better URL for me? :-)
>

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.11 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iQEcBAEBAgAGBQJPJuFnAAoJEMHeSXG7afUhXe4IAJ6I3viCswnkFw0lAGvAArkf
211sneSaMO2DaJCzoP4kJCSlrOmEDUmEEkZldb1ggDskr6O4H7FbB7AFANQNh71Q
mMSza+vnn9O0eZEhloRwJmX5TuJJ/32i3KChgbqEFAvON3gtCpvUvIprXdekvNvh
ViY3wd9ha7SYf0XNIypUDpFXfG+WqOTwqyxtGCWbqnmSSsNwxtjb+6AcuTn1mfVS
qfEMWDC3xe66+CO5oRHmWN1CneVVVUn5cEZHneRZEw7qkCLz3q8L3vQ1gMchPJ9Y
lnClkaTmu4LvjM4fmfKOiMLtQ/yxJaq95weVN1XG+B3CPLLEeEEGUPlxPd0Vz0c=
=1ZOe
-----END PGP SIGNATURE-----

Hi David,

> It is possible to checkout the source for the DocBook distribution
> from svn [1], but you would then have to build it [2], so typically
> working with the snapshot builds is much easier if you need features
> that haven't made it into a release yet.

Thanks for the info! I'll set things up to pull the snapshot tarball then.

--
Cheers,

Stefan Hinz <stefan.hinz@oracle.com>, MySQL Documentation Manager

Phone: +49-30-82702940, Fax: +49-30-82702941, http://dev.mysql.com/doc

ORACLE Deutschland B.V.& Co. KG
Registered Office: Riesstr. 25, 80992 Muenchen, Germany
Commercial Register: Local Court Of Munich, HRA 95603
Managing Director: Jürgen Kunz

General Partner: ORACLE Deutschland Verwaltung B.V.
Hertogswetering 163/167, 3543 AS Utrecht, Niederlande
Register Of Chamber Of Commerce: Midden-Niederlande, No. 30143697
Managing Directors: Alexander van der Ven, Astrid Kepper, Val Maher