version control docbook2epub customizations

[jbzech]

Hi,

I really love the new DocBook to Epub transformation. I've been able to go in there and add a couple files to customize the output a bit, and everything is working great.

However, due to the setup in my organization, I'd like to be able to version control my 2-3 customization files within the version control folder for a project rather than keep them in the frameworks/docbook/xsl/epub folder. But being new to ANT and XSL, I'm not sure how to get them to work outside of the frameworks folder. Every time I try it, something in the ANT or XSL breaks.

Is there a relatively simple way to set this up? Any advice on a simple setup? I'd rather not version control the whole frameworks or docbook/xsl folder, just my custom files.

Any help is appreciated. Thanks.

jz

[Radu]

Hi,

What exactly are the modifications you performed?

Regards,
Radu

[jbzech]

I didn't want to mess with the out-of-the-box transform so I:

1) in the docbook/xsl/epub/bin folder I created myBuild.xml which is a copy of build.xml that references my customization layer instead of the standard docbook.xsl.

<!-- Stylesheet for META-INF/container.xml, OPF and NCX output files. -->
<property name="stylesheetFile" value="../my_epub.xsl"/>

instead of

<!-- Stylesheet for META-INF/container.xml, OPF and NCX output files. -->
<property name="stylesheetFile" value="../docbook.xsl"/>

2) added the customization layer "my_epub.xsl" The file is a copy of "docbook.xsl" with some customizations and it imports file called "CustomEpubFormat.xsl". (I know that a customization layer should properly import docbook.xsl instead of copying it, but I have precedence issues in my customization layer, and this was the only way to fix it.)

What I'd like to do is keep "my_epub.xsl" and "CustomEpubFormat.xsl" in the version control folder for the project they are used to transform (DocBook2ePub). That way anyone involved in this project can do the same transform on their Oxygen-installed computer if they are subscribed to the SVN repository. Might be nice to include the myBuild.xml file from the /bin folder as well.

I just want this transform to be portable, basically, and I want my customizations tracked in version control.

Thanks!

[Radu]

Hi,

About the first customization you made:

1) in the docbook/xsl/epub/bin folder I created myBuild.xml which is a copy of build.xml that references my customization layer instead of the standard docbook.xsl.

<!-- Stylesheet for META-INF/container.xml, OPF and NCX output files. -->
<property name="stylesheetFile" value="../my_epub.xsl"/>

instead of creating another build file you could have overwritten the changed parameter value directly from the ANT scenario configured in Oxygen for Docbook to EPUB.

About the second customization:

2) added the customization layer "my_epub.xsl" The file is a copy of "docbook.xsl" with some customizations and it imports file called "CustomEpubFormat.xsl". ....

So you copied the contents of the XSLT:

OXYGEN_INSTALL_DIR/frameworks/docbook/xsl/epub/docbook.xsl

to a new XSLT called "my_epub.xsl".

The original "docbook.xsl" contains some imports like:

Code: Select all

  <xsl:import href="../xhtml-1_1/docbook.xsl" />

  <xsl:import href="../xhtml-1_1/chunk-common.xsl" />

  <xsl:include href="../xhtml-1_1/chunk-code.xsl" />

which are relative to the place where the stylesheet is defined.
You can replace them with absolute URLs which are solved through the Docbook catalogs to the same locations like:

Code: Select all

  <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/1.76.1/xhtml-1_1/docbook.xsl" />

  <xsl:import href="http://docbook.sourceforge.net/release/xsl-ns/1.76.1/xhtml-1_1/chunk-common.xsl" />

  <xsl:include href="http://docbook.sourceforge.net/release/xsl-ns/1.76.1/xhtml-1_1/chunk-code.xsl" />

These locations will still be solved to the Docbook XSLs from the Oxygen installation directory by using catalog support.

This means that you will be able to copy your "my_epub.xsl" and "CustomEpubFormat.xsl" to a folder in your version controlled project but the references to the other stylsheets will still be solved.

So to connect everything:

1) You modify and copy your custom stylesheets to a new folder under SVN control.
2) In Oxygen you create (if you have not created already) a new Project file in the Project view and save that Project file also to your SVN working copy.
3) Oxygen has the ability to save in a project file preference pages:

http://www.oxygenxml.com/doc/ug-oxygen/ ... aring.html

and transformation scenarios:

http://www.oxygenxml.com/doc/ug-oxygen/ ... aring.html

4) Open a Docbook file, click the Configure Transformation Scenario toolbar button and in the Configure Transformation Scenario dialog select the Project Scenarios radio button then duplicate the default Docbook to EPUB ANT transformation scenario and in the Parameters tab add a new parameter called stylesheetFile with the value ${pd}/custom_dir/my_epub.xsl. The value contains an Oxygen editor variable called ${pd} which expands to the base directory of the current opened project.

5) So if anybody from your team will update and then open in the Project view the custom project file they will automatically be working with the same preferences and transformation scenarios you have saved at project level.

Regards,
Radu

[jbzech]

Thank you. Seems pretty straight forward. I'll let you know if I have any trouble.

You guys are terrific.