DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

djhreg
Posts: 4

DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Tue Feb 21, 2012 10:26 pm

For the last week or so I have been evaluating Oxygen XML Editor for use in creating DocBook5-based real paper books. So far the tool is very nice. :D The DocBook 5 example in Oxygen XML was exactly what I wanted. I am a software developer by background and I like clean and modular source files. As such, it was nice to have a cleaned up example of a DocBook 5 book using Xinclude and Relax NG (Not so easy to figure out the syntax from the published books on the subject)

After entering some text and successfully creating PDFs, I encountered my first bumpy spot -> I need a custom page size. Eventually, by studying forum posts, I was able to figure out how to duplicate the DocBook to PDF conversion, edit the renamed duplicate, select “parameters”, scroll down to “paper.size”, set it to “C5” and generate a new PDF with “C5” paper size. (By the way, the Help file in the tool did not seem to cover this topic)

Unfortunately, this approach does not really get me where I need to go for two reasons:

1. I am making real books, not office documents. When I submit the PDF to Ingram Lightning Source, in order for them to manufacture an 8”x10” book (254x203mm) they need the PDF document size to be slightly larger to allow for paper trimming. In this case, they need the PDF file sized as 8.25”x10.5” (267x210mm) These dimensions don’t match any of the standard European or U.S. office paper sizes.

2. I am going to make a lot of books and I need to be able to set the paper size (and all the other formatting aspects for the book) in an editable file that lives with the book in my source code control system. Ie: what I really want is to have two files:

MyBookContent.xml – the content of the book with validated DocBook 5 markup

MyBookFormat.SomethingML – a structured parameter file that will flow through the tool chain and generate page sizes, margins, and all the other classical “appearance and format” aspects of the PDF file.

I did find this video online:

http://www.oxygenxml.com/demo/DocBook_C ... ation.html

However, it seems to be an older version. Ie: the tool screen shots are rather different than the current tool and it looks like it may be aimed at the previous DTD-oriented version of DocBook (?) In any case, when I typed in the .xsl file as shown in the video, it failed to compile in the tool. I suspect that the URI references shown in the video may not be correct and/or may not be the right approach for use with Relax NG (?)

I also tried making a Relax NG file using Oxygen XML but did not get anywhere. Unfortunately, the two major books on the subject (“DocBook XSL” by Bob Stayton and “DocBook 5”by Norman Walsh) both sort of hint that it should in theory be possible to make a Relax NG customization layer, but neither one contains an actual complete and executable example of one that will do something as simple as setting the paper size.

Another problem with the open source community information is that I could not find a reference that lists what the editable parameters of DocBook XSL Version 5 actually are. A few examples are shown in places, but I could not actually find a reference list. DocBook 5 Language elements are documented in detail, but reference information on formatting parameters seems to be difficult to find.

Suggestions?

Thanks in Advance

David Hetherington
djhreg@yahoo.com
sorin_ristache
Posts: 4144

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Wed Feb 22, 2012 3:40 pm

Hello,

djhreg wrote:2. I am going to make a lot of books and I need to be able to set the paper size (and all the other formatting aspects for the book) in an editable file that lives with the book in my source code control system.



You want a custom paper size (not one of the allowed values of the paper.type parameter) which means you need a customization of the DocBook XSL stylesheet for XSL-FO output which sets the paper size in the XSL-FO output of the DocBook XSL stylesheet. The XSL-FO output will be used for creating the final PDF output.


djhreg wrote:I did find this video online:

http://www.oxygenxml.com/demo/DocBook_C ... ation.html

However, it seems to be an older version. Ie: the tool screen shots are rather different than the current tool and it looks like it may be aimed at the previous DTD-oriented version of DocBook (?) In any case, when I typed in the .xsl file as shown in the video, it failed to compile in the tool. I suspect that the URI references shown in the video may not be correct and/or may not be the right approach for use with Relax NG (?)



That video demonstration is exactly what you need and we will update it to reflect the latest Oxygen user interface.


djhreg wrote:I also tried making a Relax NG file using Oxygen XML but did not get anywhere. Unfortunately, the two major books on the subject (“DocBook XSL” by Bob Stayton and “DocBook 5”by Norman Walsh) both sort of hint that it should in theory be possible to make a Relax NG customization layer, but neither one contains an actual complete and executable example of one that will do something as simple as setting the paper size.


You should create your DocBook 5 XML files using the DocBook document templates from Oxygen. These files are Relax NG files but you don't have to create them from zero. You can start from one of the templates that include the XInclude declaration:

Code: Select all

<?xml-model href="http://www.oasis-open.org/docbook/xml/5.0/rng/docbookxi.rng" schematypens="http://relaxng.org/ns/structure/1.0"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
  ...


djhreg wrote:Another problem with the open source community information is that I could not find a reference that lists what the editable parameters of DocBook XSL Version 5 actually are. A few examples are shown in places, but I could not actually find a reference list.


We will add documentation for the DocBook parameters in the Oxygen user manual. In the current version of Oxygen (13.2) and in all previous versions you can read the documentation of each parameter in the Parameters dialog which is opened from the Parameters button of the transformation scenario dialog.


Regards,
Sorin
djhreg
Posts: 4

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Wed Mar 14, 2012 11:13 pm

Thanks for the detailed reply!

Having now purchased the license, I am continuing to work on this problem.

After some practice with the Editor, the differences in the UI were no longer a problem. I was able to follow the video step-by-step.

Unfortunately, the XSL extension shown does not compile.
(In case I mistyped something) The Extension file is:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    version="1.0">
    <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
    <xsl:param name="paper.type" select="A4landscape"></xsl:param>
    <xsl:param name="page.orientation" select="landscape"></xsl:param>
</xsl:stylesheet>


The error is:
System ID: E:\Projects\Systematic_Martini_Mixing\trunk\DocBookCustomizationA4Landscape.xsl
Scenario: Docbook PDF A4 Landscape
XML file: E:\Projects\Systematic_Martini_Mixing\trunk\DocBookCustomizationA4Landscape.xsl
XSL file: E:\Projects\Systematic_Martini_Mixing\trunk\DocBookCustomizationA4Landscape.xsl
Engine name: Saxon6.5.5
Severity: warning
Description: Failure reading http://docbook.sourceforge.net/release/ ... ocbook.xsl - 500 Internal Server Error for: http://docbook.sourceforge.net/release/ ... ocbook.xsl
Start location: 4:0


At first this seemed mysterious until I tried accessing
docbook.sourceforge.net It seems that this server is rejecting
all requests at the moment with the message:

Too many requests, please try again later.


I also tried to redirect the <xsl:import href="" /> statement to point to the local copy of DocBook.xsl installed with OxygenXML, but I was not able to get that to work. It seems that XSL (and XML) are not friendly to absolute local paths...(?)

Suggestions?

(I have screen shots, but I was not quite able to figure out how to upload attachments to this forum)

Thanks!
djhreg
Posts: 4

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Thu Mar 15, 2012 4:22 am

Actually, I got it working by searching the Oxygen XML documentation and figuring out how to create a catalog to map the URI to the local copy of DocBook.xsl installed by Oxygen XML. When you update the video, you should include the comment that it will be necessary to create this catalog... and perhaps include the steps to do so.

Next question: exactly which DocBook parameters should I set
to create a custom page width and height?

Thanks!
sorin_ristache
Posts: 4144

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Thu Mar 15, 2012 12:34 pm

Hello,

djhreg wrote:At first this seemed mysterious until I tried accessing docbook.sourceforge.net It seems that this server is rejecting
all requests at the moment with the message:

Too many requests, please try again later.


I also tried to redirect the <xsl:import href="" /> statement to point to the local copy of DocBook.xsl installed with OxygenXML, but I was not able to get that to work. It seems that XSL (and XML) are not friendly to absolute local paths...(?)

Suggestions?


Oxygen includes an XML catalog that maps automatically the URLs of the DocBook XSL stylesheets to the local copies from the folder [Oxygen-install-folder]/frameworks/docbook/xsl so that no access to the sourceforge.net server is necessary. The catalog did not kick in for you because you tried to customize the no namespace aware version of the DocBook XSL stylesheets (<xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>) instead of the namespace aware version (<xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/current/fo/docbook.xsl"/>) which comes with Oxygen.


djhreg wrote:

Code: Select all

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
    <xsl:import href="http://docbook.sourceforge.net/release/xsl/current/fo/docbook.xsl"/>
    <xsl:param name="paper.type" select="A4landscape"></xsl:param>
    <xsl:param name="page.orientation" select="landscape"></xsl:param>
</xsl:stylesheet>



A custom stylesheet should be created only for more complex customizations. The values of built-in Docbook XSL parameters can be set directly in the Docbook transformation scenario (Docbook PDF in your case), no new stylesheet is necessary for that. Just select Docbook PDF in the dialog box with all transformation scenarios, press the Edit button and in the new dialog box that is opened for editing a copy of the built-in read-only scenario press the Parameters button. In the Parameters dialog box you can set the values of the paper.type and page.orientation built-in Docbook parameters.


djhreg wrote:Actually, I got it working by searching the Oxygen XML documentation and figuring out how to create a catalog to map the URI to the local copy of DocBook.xsl installed by Oxygen XML. When you update the video, you should include the comment that it will be necessary to create this catalog... and perhaps include the steps to do so.


The catalog for the DocBook XSL stylesheets comes with Oxygen and is located in the folder [Oxygen-install-folder]/frameworks/docbook/xsl.


djhreg wrote:Next question: exactly which DocBook parameters should I set to create a custom page width and height?


Please look at the built-in parameters page.height, page.height.portrait, page.width, page.width.portrait. As you can see in the Parameters dialog box the default values of page.height and page.width are based on the values of paper.type and page.orientation.


Regards,
Sorin
djhreg
Posts: 4

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Thu Mar 15, 2012 6:31 pm

Thank you for the update. Changing the customization to point to the "namespace aware" version at "...../xsl-ns/..." rather than ".../xsl/..." does indeed eliminate the need for a separate catalog.

However, please take a look at your online instruction video:

http://www.oxygenxml.com/demo/DocBook_C ... ation.html

The example shown points to the **WRONG PLACE**. This error in your online instruction video will cause a new customer (like me) to waste many hours trying to figure out why the example does not actually run...

You need to update the video...
sorin_ristache
Posts: 4144

Re: DocBook 5 with Relax NG Custom Paper Size and/or Format Customization Layer

Thu Mar 15, 2012 6:42 pm

Hi David,

djhreg wrote:However, please take a look at your online instruction video:

http://www.oxygenxml.com/demo/DocBook_C ... ation.html

The example shown points to the **WRONG PLACE**. This error in your online instruction video will cause a new customer (like me) to waste many hours trying to figure out why the example does not actually run...

You need to update the video...



We will update the video demonstration.


Regards,
Sorin

Return to “DocBook”

Who is online

Users browsing this forum: No registered users and 2 guests