#format rst
.. _article: http://webworks.com/technotes/articles/ePublisherPro/EX_ePub_Project_Format_Overrides.36.1.aspx
.. _paragraphs.xsl: attachment:paragraphs.xsl

====================================================
One Strategy for Xsl Overrides in ePublisher Formats
====================================================

:version: 1.0.1
:date: 2006-12

:Changes: Initial public version.

Abstract
========

One great feature of the older WebWorks Publisher was the 
ability to simply override ordinary formatting by typing 
output directly into a Style object's Macro tab.  This 
document presents a solution for achieving this
functionality on the ePublisher Platform.

Introduction
============

The ePublisher Platform works very well with technologies
that implement a style-based processing model.  In Word and
!FrameMaker, this is usually achieved through the use of 
document templates.  On the ePublisher Platform, styles are
used to delineate the borders of a given document's content. 
The ePublisher Formats are heavily tied to the ePublisher Pro
User Interface.  As such, the XSL files which implement a
given ePublisher Format's output are extremely verbose, with a
moderately high level of complexity which advanced XSL user's
may find challenging.  This document outlines a simple approach
to take a little knowledge of XSL and use it to implement your
own output for a given style.

Getting Started
===============

First, create a new ePublisher Project based on your chosen format. 
Once the project has been created, create a Format override.  
Refer to the following link:

http://www.webworks.com/Technical_Assistance/Tech_Notes/Common/EX_ePub_Project_Format_Overrides.shtml

In particular, you need to override ``Transforms/pages.xsl`` and ``Transforms/content.xsl``.

Changes to pages.xsl
====================

Open ``pages.xsl`` and make the following changes:

 1. Add the following to the ``<xsl:include />`` area::

     <xsl:include href="wwformat:Includes/paragraphs.xsl" />

 2. Add the following line to the ``VarTransformChecksums`` variable::

     <xsl:value-of select="concat(',', wwuri:AsFilePath('wwformat:Includes/paragraphs.xsl'), ':', wwfilesystem:GetChecksum(wwuri:AsFilePath('wwformat:Includes/paragraphs.xsl')))" />

 3. Save the changes and close pages.xsl.

Changes to content.xsl
======================

Open ``content.xsl`` and make the following changes:

 1. Search for ``<xsl:template name="ParagraphTextRuns">``.
 2. Change the line as follows::

    <xsl:template name="ParagraphTextRuns" match="wwdoc:TextRun" mode="wwmode:content">

 3. Save the changes to content.xsl and close.

Adding ``Includes/paragraphs.xsl``
==================================

 1. In the named area of your Format override, add a directory called, "``Includes``" 
    (``Formats/Dynamic HTML/Includes``, for example).
 2. Download paragraphs.xsl_ and put it into the new "``Includes``" directory.

Make Changes
============

The ``paragraphs.xsl`` file that you downloaded matches a paragraph with the stylename,
*SectionQuote* and places a HTML ``<div>`` tag around it with a ``style`` attribute.  This
is just an example.  You will probably want to change the ``@stylename = 'SectionQuote'`` to 
refer to the style you want to process.

Understanding What's Happening
==============================

The most important part of this strategy is that it works because you are creating *a better
match expression*.  The default ``content.xsl`` already includes a match template for 
``wwdoc:Paragraph``. In this strategy, we simply override that default template by including 
one with a better match expression::

 <xsl:template match="wwdoc:Paragraph[@stylename = 'SectionQuote']">
  ...
 </xsl:template>

The XSL processor will only apply-templates once for the best match.  So in this case,
if the ``stylename`` is *SectionQuote*, your match template will be applied instead of
the default template.

Notice that the ``<xsl:template></xsl:template>`` included in paragraphs.xsl passes along a number of 
parameters. It is important to pass these parameters along if you want to pass the
processing flow back to the base Format.  Keep in mind however, you might divert the flow
altogether for processing the contents of the paragraph by introducing your own mode, for
example.

Overriding Other Types of Styles
================================

You can use a similar approach for other types of styles.  For example, you might repeat the
step to create a ``Includes/characters.xsl``.  In such a case, the better match expression
would be for the ``wwdoc:TextRun`` element.  For example::

  <xsl:template match="wwdoc:TextRun[@stylename = 'BoldItalic']">
   ...
  </xsl:template>

However, because other such approaches might be different depending on the Format you are 
using, specifics are not
covered here.

----

Another Override Example - Markers
===================================
See http://wiki.webworks.com/DevCenter/Projects/WebWorksHelp/UsingTopicIdentifiers/Discussion