Adobe DITA World 2017 - XSLT Magic Tricks with DITA and ... · Which XSLT Engine? •Can use Saxon or XalanXSLT engine •Use Saxon: Supports XSLT 2 and newer •Saxon is the default

XSLT Magic Tricks with

DITA and FrameMaker

EliotKimberContrext

AdobeDITAWorld2017

About the Author• Independent consultant focusing on DITA

analysis, design, and implementation• Doing SGML and XML for cough 30 years cough• Founding member of the DITA Technical

Committee• Founding member of the XML Working Group• Co-editor of HyTime standard (ISO/IEC 10744)• Primary developer and founder of the DITA for

Publishers project• Author of DITA for Practitioners, Vol 1 (XML

Press)

10/16/17 Adobe DITA World 2

Agenda

• XSLT and FrameMaker• XSLT Basics• Configuring Your Structure

Application• Magic Tricks• Resources


XSLT AND FRAMEMAKER


What is XSLT?

• “XML Style Sheet Language Transformations”

• Standard programming language for manipulating XML documents


Why is XSLT Interesting?

• Makes it easy to make small changes• Makes it possible to do big changes• Mature standard with lots of support

in tools• Same transform can be used in many

environments


What Does XSLT Do?

• Takes as input one or more XML documents

• Produces as output any of:– One or more XML documents– Text data of any kind– JSON (XSLT 3)


Transforms• XSLT programs are “transforms”:– One or more XML documents in– One or more XML documents (or other

things) out• Uses XML syntax:

<xsl:stylesheet><xsl:template …>…

</xsl:template></xsl:stylesheet>


XSLT in FrameMaker

• Configured as part of structure applications or associated with a specific document

• Can apply XSLT transforms on document open and document save


Which XSLT Engine?

• Can use Saxon or Xalan XSLT engine• Use Saxon: Supports XSLT 2 and

newer• Saxon is the default• Can use a newer version or licensed

version of Saxon if desired


Why Use XSLT in FrameMaker


?

Alternative to Read/Write Rules

• XSLT applied before read rules and after write rules

• Can make it easier to adjust aspects of the XML on import and export


Generate Additional Outputs

• Use XSLT on export to generate additional outputs– HTML files– Reports– Etc.

• Alternative to using DITA Open Toolkit or FrameMaker-provided features


Adjust XML • Move elements around• Add elements or attributes needed by

FrameMaker• Group and sort elements (e.g., glossary

terms)• Add index entries based on markup• Adjust text details• Control line breaking in examples

– Add zero-width-spaces– Add non-breaking spaces

• Etc.


Validate Editorial and Business Rules

• Check things not checkable with DTDs or EDDs– Rules for content– Co-occurrence rules (e.g., “if A is present

then B must have attribute @foo”)• Check rules not defined in the DTD or

EDD that reflect local usage:– Require elements not required by DTD– Require elements in a specific order

• Check rules for IDs, use of keys, etc.


Generalize on Import/Specialize on Export• Enable use of specialized content

with generic DITA FrameMakerapplication

• “Generalization”: Transforming specialized elements into one of their ancestors

• Generalization is always reversable


Generalization Example• Source element:

<mysectionclass="- topic/section my-d/mysection ”>

• Generalized:<section class="- topic/section my-d/mysection ”>

• @class attribute retains original specialization details


How Do I Do It?


?

Setting Up Structure Applications

• From Structured Application Designer go to “Advanced settings”

• Specify the XSLT transforms to use for preprocessing (before read rules) or postprocessing (after write rules)

• Or set up a transformations XML file and refer to that from the structure application

• See e.g., Structure\xml\DITA_1.3\app\technicalContent\xslt\DitaTransformations.xml


Pre- and Post-Processing Configuration


XSLT BASICS


Style Sheets

• Style sheet document root:

<xsl:stylesheetxmlns:xsl=http://www.w3.org/1999/XSL/Transformxmlns:xs=http://www.w3.org/2001/XMLSchemaexclude-result-prefixes="xs”version="2.0">

… {templates go here}

</xsl:stylesheet>


Templates• Templates apply rules to elements

that match:<xsl:template match="body/p">…</xsl:template>

• Literal result elements:<xsl:template match="body/p">

<new-p someatt="value"><xsl:apply-templates/></new-p>

</xsl:template>


Nodes and Templates• XSLT treats XML documents as trees of

nodes:– Elements– Attributes– Text nodes

• Input document is processed as a tree starting with the document root node

• Templates are “applied” to nodes• The first template that matches a node

handles it


Match Templates and Context

• Templates use XPath expressions to match elements (and other types of nodes):<xsl:template match="body/p">

• XPath expression “body/p” matches any <p> element that is a child of a <body> element


Default Template

• Default template: matches any node and applies templates to its child nodes


Context Node

• The node that matches a template is that template’s context node

• “.” in XPath expressions refers to the context node:

<xsl:sequence select="."/>


Applying Templates to Nodes

• Within a template, process additional nodes by applying templates to those nodes:

<xsl:template match="body/p"><mypara>

<xsl:apply-templates/></mypara>

</xsl:template>

• The xsl:apply-templates instruction applies templates to all child nodes of the current node by default

• Can select specific nodes if you want


Selecting Specific Nodes• Can select specific nodes with xsl:apply-templates:

<xsl:template match="fig"><fig><xsl:apply-templates

select="(image|table|figgroup), title”/>

</fig></xsl:template>

• Here the @select attribute says “process all <image>, <table>, or <figgroup> elements then process any <title> elements.”

• This example puts the <title> after the main contents of the figure


Identity Transformations

• Identity transformations take a document as input and produce the equivalent document as output

• Form the base for most of what you’ll want to do with FrameMaker


Typical Identity Transform<xsl:template match="/"><xsl:apply-templates/>

</xsl:template>

<xsl:template match="*" priority="-1"><xsl:copy><xsl:apply-templates select="@*"/><xsl:apply-templates select="node()"/></xsl:copy>

</xsl:template>

<xsl:templatematch="text()| @* | comment() |

processing-instruction()"><xsl:sequence select="."/>

</xsl:template>


1

2

3

Identity Transform Part 1

• Matches the document root (“/”) and applies templates to all the child nodes of the root:


<xsl:template match="/"><xsl:apply-templates/>

</xsl:template>


• Matches any element node (“*”) • The @priority attribute value of “-1” means

“make this template a lower priority than any template with a default priority.– Makes it easy to add templates for specific

elements without worrying about priority


<xsl:template match="*" priority="-1"><xsl:copy><xsl:apply-templates select="@*"/><xsl:apply-templates select="node()"/></xsl:copy>

</xsl:template>

Identity Transform Part 2• Creates a copy of the element:

<xsl:copy>…

</xsl:copy>

• Applies templates to all the attributes:<xsl:apply-templates select="@*"/>

• Applies templates to all the child nodes:<xsl:apply-templates select="node()"/>



• Handles nodes that can’t have children:– Text nodes, attributes, comments, and

processing instructions• Simply copies the input node to the

output:<xsl:sequence select="."/>




</xsl:template>


• The xsl:sequence instruction simply outputs the value of the @selectattribute

• Here “.” means “the current context node”, which is whatever node matched this template




</xsl:template>

XSLT Modules• Can organize style sheets into two or more files• One file is always the top-level module• Can “import” or “include” modules• For simple transforms always use “import”

– Avoids complexities around template priority– Last module imported has highest priority among

the imported modules– Importing (top-level) module always has highest

priority• Don’t put “catch all” templates in top-level

module– Cannot be overridden by imported modules


Two-Module Identity Transform

• Base module has base identity transform• Top-level module has overrides• Base module: identity.xsl

– Provides the generic identity transform templates• Top-level module: imports identity.xsl:

<xsl:stylesheetxmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">

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

<xsl:template match="fig">...


• Call the top-level module from your structured application


MAGIC TRICKS


Trick: Make Notes Into Hazard Statements

• Find <note> elements with @type of “caution”, “warning”, or “danger”

• Change them into <hazardstatement> elements on document open


Step 1: Implement Transform<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"

xmlns:xs="http://www.w3.org/2001/XMLSchema" exclude-result-prefixes="xs" version="2.0">

<xsl:import href="../common/identity.xsl"/>

<xsl:output indent="yes"/>

<xsl:templatematch="*[contains(@class, ' topic/note ')]

[@type = ('warning', 'caution', 'danger')]"><hazardstatement>

<xsl:sequence select="@*"/><messagepanel>

<typeofhazard>[type of hazard]</typeofhazard><consequence><xsl:apply-templates/></consequence><howtoavoid>{how to avoid}</howtoavoid>

</messagepanel></hazardstatement>



Step 2: Add to Structure Application


Step 3: Try It


Before:

After:

Trick: Move Figure Titles To Bottom of Figure

• DITA content models put figure titles at top of figure

• Typical print layout puts them at bottom of figure

• Nice to have this in the editor


Step 1: Hack the DTDs• Requires hacking DITA <fig> content model to allow

<title> at end of figure• E.g., modify commonElements.mod in the FrameMaker

copy of the DITA DTDs:

<!ENTITY % fig.content

"((%title;)?, (%desc;)?, (%figgroup; | %fig.cnt;)*,((%title;)?,(%desc)?)?)"

>• No need to change the EDD unless you want structure view

to not flag figure content as invalid.


Step 2: Pair of Transforms

• Transform one: moves <title> and <desc> to end of figures on open– Preprocessing transform

• Transform two: moves <title> and <desc> back to top of figures on save– Postprocessing transform

• Both are based on identity transform


One Challenge: DOCTYPE

• Transform needs to set the DOCTYPE declaration correctly, especially on save

• XSLT doesn’t allow dynamically setting of main result file DOCTYPE values

• Two solutions:– One top-level transform per topic type– Use disable-output-escaping to construct

DOCTYPE declaration dynamically• See built-in AdjustTableWidth.xsl for example


Step 3: Update Structure App

• For each topic type add Preprocessing and Postprocessingentries to XSLT Preferences settings


XSLT Preferences Sample


Step 4: Try It


Before: After:

Postprocessing Undoes Preprocessing

• The moved title is only seen in the Author view in FrameMaker

• The postprocessing transform is applied on save

• Also applied when switching to XML view

• No chance of getting invalid DITA content outside of FrameMaker


RESOURCES


Online XSLT Resources• XSLT 2 specification:

http://www.w3.org/TR/xslt20/• XPath specification:

http://www.w3.org/TR/xpath20/• XQuery and Xpath 2 functions and operators:

http://www.w3.org/TR/xpath-functions/• Ken Holman’s XSLT book:

http://www.cranesoftwrights.com/training/index.htm#ptux

• XSL mailing list (searchable with MarkMail): http://mulberrytech.com/xsl/xsl-list/index.html


Books• Mike Kay’s XSLT 2.0 and XPath 2.0

Programmer’s Reference: http://www.wrox.com/WileyCDA/WroxTitle/XSLT-2-0-and-XPath-2-0-Programmer-s-Reference-4th-Edition.productCd-0470192747.html– Authoritative reference to the standard.

Not a beginner’s guide• Search Amazon for “XSLT”. Look for

books that reflect XSLT 2 or later


Questions?

Documents

Adobe DITA World 2017 - XSLT Magic Tricks with DITA and ... · Which XSLT Engine? •Can use Saxon or XalanXSLT engine •Use Saxon: Supports XSLT 2 and newer •Saxon is the default