Best practices for customizing PDF output - maintainability of changes

[IF]

I'm not clear on best practices relating changes to the customization of PDF output when I want to make a change to a "xm_*.xsl" file.

For example, I want to change the glossary from two columns to one column. I can do this by editing line 66 in xm_glosssary.xsl file (  <rx:flow-section column-count="2"  column-gap="27pt">"

But is this the best place to make this change if I want to minimize pain during upgrades or redeployment of the tookit? should i make the change in custom.xls instead?

Using XMetal 6.0, Enhanced PDF via RendexX XEP (and by the way, I am making these changes via a customization folder created according to instructions in http://forums.xmetal.com/index.php/topic,710.0.html)

[Derek Read]

Yes, I would recommend that whenever you can you should try to make any changes using an "override" in the custom.xsl file(s). This sometimes might mean duplicating whole chunks of stuff that won't change.

[IF]

thanks - so just to make sure I understand. A template in custom.xsl (say ProcessGlossarylist) will override a template of the same name in xm_glossary.xsl even though the custom.xsl contains a statement that imports xm_glossary.xsl?

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

Does it matter where I put my ProcessGlossarylist template in custom.xsl? Should it be after the import statements or before?
thanks

[Derek Read]

Things that come later override things previously defined so your statements should come after any imports. This is similar to CSS cascading.

[IF]

There is something odd going on. I cannot override this template.
I have created a file that contains my customization and I import that from customs.xsl.

So custom.xls looks like this.
<?xml version='1.0'?>
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    xmlns:exsl="http://exslt.org/common"
    xmlns:opentopic="http://www.idiominc.com/opentopic"
    xmlns:exslf="http://exslt.org/functions"
    xmlns:opentopic-func="http://www.idiominc.com/opentopic/exsl/function"
    extension-element-prefixes="exsl"
    exclude-result-prefixes="opentopic exslf opentopic-func"
    version="1.1">

    <!--
       
        ****************************************
        Template customization driver file
        v 0.91
        August 8, 2007
        ****************************************
       
        This driver file:
        1. collects the XSL template overrides via xsl:import
        2. sets header and footer content overrides
        (to style headers and footers, see [Customization]/fo/attrs/custom.xsl)
    -->


         

    <xsl:import href="xm_image_size_fix.xsl"/>
    <xsl:import href="xm_marker_fix.xsl"/>
    <xsl:import href="xm_bookmeta_fix.xsl"/>
    <xsl:import href="xm_attr_set_reflection_mod.xsl"/>
    <xsl:import href="xm_static_content.xsl"/>
    <xsl:import href="xm_common_vars.xsl"/>
    <xsl:import href="xm_titlepage.xsl"/>
    <xsl:import href="xm_layout_masters_overrides.xsl" />
    <xsl:import href="xm_commons_mod.xsl"/>
    <xsl:import href="xm_tables.xsl"/>   
    <xsl:import href="xm_choicetable_fix.xsl" />
    <xsl:import href="xm_index.xsl" />
    <xsl:import href="xm_ui_domain.xsl" />
    <xsl:import href="xm_glossary.xsl" />   
    <xsl:import href="xm_toc.xsl" />   
    <xsl:import href="xm_bookmarks.xsl" />

          <xsl:import href="IF_system_guide_draft.xsl" />
       
   
      <!-- Variables and parameters --> 
</xsl:stylesheet>


I can create an output without any problems with this file IF_system_Guide_draft,xsl. That is, i see comments in the PDF output and the appendices don't have a min-toc:


<!--
IF Modifications for draft system guide
-->

<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
    xmlns:fo="http://www.w3.org/1999/XSL/Format"
    xmlns:exsl="http://exslt.org/common"
    xmlns:opentopic="http://www.idiominc.com/opentopic"
    extension-element-prefixes="exsl"
    exclude-result-prefixes="opentopic"
    version='1.1'>

      <!--  IF 22 Oct 2010 Always display draft comments; don't show disposition or status   -->
      <xsl:template match="*[contains(@class,' topic/draft-comment ')]">
            <fo:block xsl:use-attribute-sets="draft-comment" id="{@id}">
               <xsl:apply-templates/>
            </fo:block>
    </xsl:template>


     <!--  IF 22 Oct 2010 Remove mini-TOC from  Appendix   -->
    <xsl:template name="processTopicAppendix">
        <fo:page-sequence master-reference="body-sequence" xsl:use-attribute-sets="__force__page__count">
            <xsl:call-template name="insertBodyStaticContents"/>
            <fo:flow flow-name="xsl-region-body">
                <fo:block xsl:use-attribute-sets="topic">
                    <xsl:attribute name="id">
                        <xsl:value-of select="@id"/>
                    </xsl:attribute>
                    <xsl:if test="not(ancestor::*[contains(@class, ' topic/topic ')])">
                        <fo:marker marker-class-name="current-topic-number">
                            <xsl:number format="1"/>
                        </fo:marker>
                        <fo:marker marker-class-name="current-header">
                            <xsl:for-each select="child::*[contains(@class,' topic/title ')]">
                                <xsl:call-template name="getTitle"/>
                            </xsl:for-each>
                        </fo:marker>
                    </xsl:if>

                    <xsl:apply-templates select="*[contains(@class,' topic/prolog ')]"/>

                    <xsl:call-template name="insertChapterFirstpageStaticContent">
                        <xsl:with-param name="type" select="'appendix'"/>
                    </xsl:call-template>

                    <fo:block xsl:use-attribute-sets="topic.title">
                        <xsl:for-each select="child::*[contains(@class,' topic/title ')]">
                            <xsl:call-template name="getTitle"/>
                        </xsl:for-each>
                    </fo:block>

                    <!--IF 22 Oct 2010 xsl:call-template name="createMiniToc"/-->

                    <xsl:apply-templates select="*[contains(@class,' topic/topic ')]"/>
                </fo:block>
            </fo:flow>
        </fo:page-sequence>
    </xsl:template>

       
</xsl:stylesheet>


But as soon as I add the processglossarylist template to my IF_system_guide_draft.xsl file, i get a build error. I haven't even made changes to the template. the message is this. the filename changes randomly each time i try it.

C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\build_preprocess.xml:186: Failed to copy C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\g_electrocardiogram.xml.pull to C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\g_electrocardiogram.xml due to C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\g_electrocardiogram.xml (Access is denied)

[IF]

after a couple of hours of random troubleshooting, a bit more info: it seems that this is the problematic section if inserted directly into the custom.xls file or into my if_system_guide_draft.xsl file.

  <rx:flow-section column-count="2"  column-gap="27pt">
                        <xsl:apply-templates select="child::*[contains(@class, ' glossentry/glossentry ')]" mode="glossary"/>
                    </rx:flow-section>


 I see this error:

Error reported by XML parser: undeclared name prefix in: rx:flow-section

If I remove the rx:flow statements from the custom.xsl or the if_system_guide_draft.xsl files , I don't get any errors. Also, obviously, the rx:flow statements do work in the xm_glossary.xsl file.

[Derek Read]

In order to use any RenderX XSLT extension (anything that starts with "rx:") you will need to add the following namespace to the XSL file:

xmlns:rx="http://www.renderx.com/XSL/Extensions"

I believe that should fix your issue.

[IF]

I was hopeful but unfortunately it still does not work

I get a BUILD FAILED error followed by this:

C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\build_preprocess.xml:186: Failed to copy C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\c_device_specifications.xml.pull to C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\c_device_specifications.xml due to C:\Users\IFusey\AppData\Roaming\SoftQuad\XMETAL~1\DITA_OT\temp\lbl\c_device_specifications.xml (Access is denied)

[IF]

Problem solved finally. The key was to add the statement xmlns:rx="http://www.renderx.com/XSL/Extensions"
to custom.xsl. It was not good enough to add that statement to the file that is imported by custom.xsl (if_systemguide_draft.xsl).
thanks