update DocBook xsl from ver 1.76 to ver 1.77

[osprofi]

Hello
I am using OxygenXML ver 13.2 with included DocBook xsl ver 1.76
I want to replace/amend the DocBook xsl ver 1.76 with ver 1.77 because of the EPUB3 support

I did not find an info how to replace/amend DocBook xsl ver 1.76

Can you help me or give me some hinto how this can be done

I appreciate very much your answer

Greetings, Peter

[sorin_ristache]

Hi,

You can upgrade the DocBook XSL stylesheets by replacing the XSLT files of the old version in the directory [Oxygen-install-dir]/frameworks/docbook/xsl with the XSLT files of the new version.

If you want to use both versions of DocBook XSL at the same time, a second option for using the new version of DocBook XSL in Oxygen is to unzip the new version of DocBook XSL in a directory outside [Oxygen-install-dir] and create a duplicate framework of one of the built-in frameworks called DocBook 4 and DocBook 5 which will be based on that directory. In this case there are some Oxygen custom files that you have to copy from [Oxygen-install-dir]/frameworks/docbook/xsl and some changes that you need to apply in the transformation scenario called DocBook EPUB in the duplicate framework. Please let me know if you want the second option and I can give you more details about the customizations that you need in the duplicate framework.


Regards,
Sorin

[sorin_ristache]

Hi,

We tested the stylesheets for EPUB 3 that come in Docbook XSL 1.78.0 (the current version) and they are still in an unfinished form: there are errors in the XSLT transformation, there are validation errors in the result HTML 5 files. We tried the EPUB 3 transformation before with older versions of Docbook XSL (the namespace aware version, that is docbook-xsl-ns) and the errors were not solved yet. We will probably have an EPUB 3 transformation in Oxygen when the EPUB 3 transformation can generate a valid EPUB 3 output. Maybe we can contribute to the stylesheets for this transformation in the future, for improving them/fixing the errors.


Regards,
Sorin

[osprofi]

Hi Sorin
thanks for the quick reply;
I tried your 1st way and I realised that several files were missing afterwards;
So I would be interested in your 2nd way to generate epub3 docs/dirs
Thanks very much for showing me how to do this efficiently
Greetings, Peter

[sorin_ristache]

Hi Peter,

I suggest you rather not go to the second option (a duplicate of the built-in DocBook framework) before you can have a working transformation using the first option because configuring a duplicate framework is more difficult than just dropping the unzipped Docbook XSL distribution in the frameworks/docbook/xsl directory. What files were missing? Did you get transformation errors? Did you run a new transformation which you created based on the EPUB 3 stylesheets?


Regards,
Sorin

[osprofi]

Hello Sorin
I repeated the copying of the 1.77 files into the dir xsl and now no files were missing and with the xsl transformation file epub3/profile-chunk.xsl all epub3 files were issued.
The only thing is that the generated epub file is not readable, e.g. in firefox epubreader, with the message "epub file is corrupted"

Maybe you know the reason ?

regards, Peter

[sorin_ristache]

Please open the EPUB file in Oxygen in the Archive Browser view and validate it using the action Validate on the toolbar of the view. What are the EPUB validation errors?


Regards,
Sorin

[osprofi]

Hello Sorin
when trying to open the .epub file then oxygenxml displays the error : "unknown archive format or corrupted archive file"
What I am doing wrong here ?
Greetings, Peter

[sorin_ristache]

Hi,

That error says that it is a binary file that does not have the file format of a zip archive. An EPUB file is a special type of a zip archive, so first it must be a zip file (a file that can be opened and browsed by a zip archiver application - either the Archive Browser view in Oxygen or any other zip archiver application). If the output file of the Docbook transformation does not have the correct file format of a zip archive then it cannot be an EPUB file.

If you are sure you are working with the (latest) output file of the (latest run of) Docbook EPUB 3 transformation then we can conclude that the transformation does not create an EPUB file.

What does your transformation do? Does it only apply the epub3/profile-chunk.xsl stylesheet to the input Docbook XML document? That will not create the binary zip file, it will create only some files that must be included in the final zip archive. As a model you can look at the file [Oxygen-install-dir]/docbook/xsl/epub/bin/build.xml.


Regards,
Sorin

[osprofi]

Hello Sorin
yes, you are right.
But the docbook xsl ver 1.77/1.78 does not contain anymore the bin/build.xml file needed for the epub creation. What can I do to create an epub3 file in Oxygenxml 13.2 ?
regards, Peter

[sorin_ristache]

Hi Peter,

The build.xml does not come in the Docbook XSL package, it must be created as a custom build file. You can follow the example of that build.xml file which Oxygen added to Docbook XSL for the EPUB 2 output for creating a transformation Docbook EPUB 3. I think you just have to set the correct paths to the EPUB 3 stylesheets in the XSLT tasks of the new build.xml script which you will create for the EPUB 3 output, the rest of the EPUB 3 transformation should be similar to the EPUB 2 one.


Regards,
Sorin

[osprofi]

Hello Sorin
thanks for all your help; Will try to do as you propose and confirm results
Maybe afterwords it will be useful to write a short info how to create epub3 documents from docbook
regards, Peter

[sorin_ristache]

Hi Peter,

Certainly, an article for other Oxygen users would be helpful I guess, and we would gladly write one up should you manage to get an EPUB 3 transformation working. From our tests the EPUB 3 XSLT stylesheets that come in the DocBook XSL packages do not generate yet valid files, so that a simple additional (custom) build.xml script that would zip them up would do the job.

Please let us know about your results.


Regards,
Sorin

[osprofi]

Hello Sorin
finally I succeeded with the epub3 creation, validation.
I used an external zipper to create the .zip archive and then renamed the .zip archive into an .epub archive; No validation errors were found using epubcheck version 3.
The following short notes describe the process.

How to generate valid EPUB3 files with OxygenXML ver 13.2

General
The OxygenXML software version 13.2:

• contains the DocBook XSL stylesheet version 1.76 which does not contain the conversion from docbook to epub3

• contains the epubcheck version optimized for EPUB version 2

What to do:
1. install DocBook XSL stylesheet version 1.77 which contains the conversion from docbook to epub3
- download http://sourceforge.net/projects/docbook ... 1.77.0.zip
- copy the extracted folder over Dir\Oxygen XML Editor 13\frameworks\docbook\xsl
- install epubreader addon in mozilla firefox

2. install epubcheck-3.0 which is a validation tool for EPUB3
- download http://code.google.com/p/epubcheck/down ... ck-3.0.zip

3. convert docbook source file into EPUB3 file
- configure Transformation scenario in OxygenXML via Document/Transformation/Configure Transformation Scenario/New
using DocBook XHTML - Chunk and select the xsl file Dir\Oxygen XML Editor 13/frameworks/docbook/xsl/epub3/profile-chunk.xsl
using XSLT\parameter base.dir ${cfd}/out/${cfn}/OEBPS/
using XSLT\parameter base.dir ${cfd}/out/${cfn}/OEBPS/
using OUTPUT\SaveAs ${cfd}\out\epub\${cfn}.epub

4. create the EPUB3 file
- zip 1stly the file ebook1/mimetype into a zip archive
- zip 2ndly the folders ebook1/META-INF and ebook1/OEBPS into a zip archive
- rename ebook1.zip into ebook1.epub

5. validate the EPUB3 file
- using epubcheck version 3 validate the ebook1,epub file

6. open the epub3 file in mozilla firefox

I hope this helps other users to effectively create valid epub3 files with OxygenXML

regards, Peter

[sorin_ristache]

Thank you Peter for posting the details. We will include DocBook XSL 1.78.1 version (the current release is 1.78.0) in the next Oxygen release and we will add a DocBook EPUB 3 transformation, so that the Oxygen users will be able to create an EPUB 3 output by just running a built-in DocBook transformation with no customization/configuration required.

The EPUB 3 validation step will show if the result is a valid EPUB book. The User Manual already mentions the EPUB validation action.


Regards,
Sorin