Title Page Customization Problem

[chrisTS]

Hi Sorin,

I have another docbook 5.0 / oxygen problem and I hope you might be able to help me.

I want to create a customization layer to get a customized title page.
The customization layer should reside in a subdirectory of my project directory.
The first problem is that I want to avoid absolute paths by using something like this in my docbook_custom.xml:

Code: Select all

<xsl:import href="file:${frameworks}/docbook/xsl/fo/docbook.xsl"/>

However only absolute paths working like th e following ssem to be working:

Code: Select all

<xsl:import href="file:/c:/Program Files (x86)/Oxygen XML Editor 14/frameworks/docbook/xsl/fo/docbook.xsl"/>

I created a customized version of "titlepage.templates.xml" as described in http://www.sagehill.net/docbookxsl/Titl ... geSpecfile but I can't figure out how to process it in order to get my customized version of "titlepage.templates.xsl". I created a "XML transformation with XSLT" transformation scenario for my customized spec file using the XSL URL "${frameworks}/docbook/xsl/fo/titlepage.xsl". However I can not process it as several "Variable XY not declared" and other errors (e.g. the variable "$title.fontset" is not declared). It seems like "pagesetup.xsl" needs to be included somehow as the missing variables are defined in this file. However the docu says that one just needs to process "titlepage.templates.xml" using "titlepage.xsl". I have also done this before with docbook 4 in eclipse using an ant script and it worked there as well.

I would really appreciate if you could give me a hint what I am doing wrong!

[chrisTS]

OK I have come 1 step further now.
I created a validation scenario for "titlepage.xsl" using "${frameworks}/docbook/xsl/fo/docbook.xsl" as the "URL of the file to validate". This lets the validation of "titlepage.xsl" succeed as docbook.xsl includes pagesetup.xsl which declares the previously missing variables

However I still can not process my custom spec file - still getting the same errors.

I also defined docbook.xsl and/or pagesetup.xsl as additional XSLT-stylesheets in the transformation scenario => no luck

[sorin_ristache]

Hi Chris,

The sagehill.net book is an excellent manual for the DocBook XSL stylesheets. I assume you want to customize the title page in the PDF output.

As specified in this book you should follow the steps described here. In Oxygen that amounts to:

• Create your own custom version of titlepage spec file, that start from a copy of the file [Oxygen-install-dir]/frameworks/docbook/xsl/fo/titlepage.templates.xml and customize it.
• Generate the custom part of the DocBook XSLT transformation with a new XSLT scenario that you create in Oxygen (we do not include a built-in one for that) and that applies [Oxygen-install-dir]/frameworks/docbook/xsl/template/titlepage.xsl to the XML spec file from the previous step. The result is an XSLT stylesheet, let's call it mytitlepages.xsl.
• In your DocBook XSLT customization layer (which you said you wanted to create) you have to import mytitlepages.xsl. That means in the customization layer you add an import element like the following after other necessary imports in any customization layer:
  

  Code: Select all

  <xsl:import href="subdir_name/mytitlepages.xsl"/>

  For example if you place both the customization layer and mytitlepages.xsl in a directory outside [Oxygen-install-dir] then you should import in your customization layer the DocBook XSL's standard remote URLs (the ones starting with http://docbook.sourceforge.net/release ... ) in order to redirect the remote URL to the local copy of DocBook XSL within [Oxygen-install-dir]/frameworks/docbook/xsl through Oxygen's built-in XML catalog, that is:
  

  Code: Select all

  <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/fo/profile-docbook.xsl"/>

• Create a new DocBook transformation by duplicating the built-in scenario called DocBook PDF, edit the duplicate scenario and set the path of your XSLT customization layer in the text box XSL URL of the dialog box instead of the path of docbook/xsl/fo/docbook_custom.xsl.
• Run this new DocBook transformation. The title page of the PDF result should reflect your customizations.

Regards,
Sorin

[chrisTS]

Hi Sorin,

thank you again for taking the time to answer my (newbie - stupid) questions.
I tried to get working exactly the way you described. However the second step in your list does not work. I am unable to transform my custom title page from xml to the xsl. I suppose I did not configure the transformation properly. This step is when I get all these errors mentioned above:
- failed to compile stylesheet
- Variable title.fontset has not been declared
...

What I did:
I created a new (XSLT) transformation scenario for my custom titlepage xml file.
In "XML URL" I selected "${currentFileURL}"
In "XSL URL" I selected "${frameworks}/docbook/xsl/fo/titlepage.xsl"
For the output filename I entered "${cfn}.xsl"

As I said before I suppose that somehow I must invoke pagesetup.xsl in this transformation as the undeclared variables which the errors complain about are declared there. pagesetup.xsl itself is included in docbook.xsl. However neither using docbook.xsl as the stylesheet for the transformation nor adding docbook.xsl and/or pagesetup.xsl as additional XSLT stylesheets in the transformation scenario works.

I am sure it is just a very basic setting of the transformation which I did not get right.

Any ideas?

[sorin_ristache]

Hi Chris,

In "XSL URL" I selected "${frameworks}/docbook/xsl/fo/titlepage.xsl"

Please read again step 2 in my list above and also the original procedure from which I derived and particularized these steps for the Oxygen tool. You have to apply ${frameworks}/docbook/xsl/template/titlepage.xsl to your custom titlepage spec file.


Regards,
Sorin

[chrisTS]

Sorin - you are my hero!

I knew it is only a little mistake ...
Stupid enough the template I used for the transformation has the same name and exists right there ...
Using the one in the template-subdirectory does the trick !

Thx!

Last question:
Is there a way to work around the problem with avoiding the absolute path to the original docbook.xsl in the import statement of my customized docbook.xsl?

Best regards

chris

[sorin_ristache]

Hi Chris,

Is there a way to work around the problem with avoiding the absolute path to the original docbook.xsl in the import statement of my customized docbook.xsl?

If you want to use a relative file path in the xsl:import element I suggest placing your customization layer stylesheet in the same directory or the parent directory of the imported stylesheet, in your case ${frameworks}/docbook/xsl/fo. This what we did for the ${frameworks}/docbook/xsl/fo/docbook_custom.xsl stylesheet.


Regards,
Sorin

[eskwayrd]

Last question:
Is there a way to work around the problem with avoiding the absolute path to the original docbook.xsl in the import statement of my customized docbook.xsl?

If you create an XML Catalog file, you can keep your custom XSL with your DocBook source files. Any co-contributors to your documentation would need to create/maintain their own Catalog files, particularly if their platform is different from yours (Windows/OSX/Linux).

For example, the following is used locally as part of an FO-based customization. Tweak as necessary. Store it in, say, your home directory, and then add it via Options->Preferences->XML->XML Catalog:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE catalog PUBLIC "-//OASIS//DTD XML Catalogs V1.1//EN"

    "http://www.oasis-open.org/committees/entity/release/1.1/catalog.dtd">

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

    <!-- DTD -->

    <system systemId="http://www.docbook.org/xml/4.5/docbookx.dtd"

            uri="file://<path to oXygen>/frameworks/docbook/4.5/dtd/docbookx.dtd"/>

  

    <!-- RELAX NG schema -->

    <uri name="http://www.oasis-open.org/docbook/xml/5.0/rng/docbook.rng"

         uri="file://<path to oXygen>/frameworks/docbook/5.0/rng/docbook.rng"/>

  

    <!-- W3C XML Schema -->

    <uri name="http://www.w3.org/2004/10/xml.xsd" uri="xml.xsd"/>

  

    <!-- XSLT stylesheets -->

    <uri name="http://docbook.org/xsl/fo/docbook.xsl"

         uri="file://<path to oXygen>/frameworks/docbook/xsl/fo/docbook.xsl"/>

    <uriSuffix uriSuffix="profile-docbook.xsl"

               uri="file://<path to oXygen>/frameworks/docbook/xsl/fo/profile-docbook.xsl"/>

    <uriSuffix uriSuffix="highlight.xsl"

               uri="file://<path to oXygen>/frameworks/docbook/xsl/fo/highlight.xsl"/>

    <uriSuffix uriSuffix="oxygen_custom.xsl"

               uri="file://<path to oXygen>/frameworks/docbook/xsl/oxygen_custom.xsl"/>

</catalog>

Once the Catalog file is installed, your customization layer just refers to the required stylesheets as usual:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>

<xsl:stylesheet 

  xmlns:xsl="http://www.w3.org/1999/XSL/Transform" 

  xmlns:d="http://docbook.org/ns/docbook"

  xmlns:fo="http://www.w3.org/1999/XSL/Format"

  version="1.0">



  <xsl:import href="profile-docbook.xsl"/>

  <!-- Apply XHLTHL extension. -->

  <xsl:import href="highlight.xsl"/>

  <xsl:import href="../oxygen_custom.xsl"/>



  <!-- customizations follow... -->



</xsl:stylesheet>