In this webinar, Suite Solutions developer Renah Scarowsky will discuss - how to include a watermark in your custom PDF Plugin to the DITA Open Toolkit using XSL-FO - considerations for the design and placement of the watermark on the page - advanced techniques for conditionally displaying the watermark based on your requirements.

1. Adding a Watermark to your PDF
Output
Renah Scarowsky, Suite Solutions

2. Who am I?
Renah Scarowsky
• Senior developer and project manager at Suite Solutions
• Background in computer science, education and web development
• Extensive expertise implementing DITA
• Help companies get it right the first time

3. About Suite Solutions
Our Vision: Enable companies to engage their customers by providing quick
access to relevant information
• Help companies get it right the first time
• XML-based Authoring/Publishing Solutions
• Enterprise Intelligent Dynamic Content
• Consultancy, Systems Integration, Application Development
• Cross-Industry Expertise
• High Tech, Aerospace & Defense
• Healthcare, Discrete Manufacturing
• Blue Chip Customer Base
• Hundreds of Person Years of Experience on Staff

4. Main Topics
 Watermark Design: Considerations for design and placement
 Including your Watermark: How to include your watermark in your
customized PDF stylesheets
 Optional Watermarks: Modify display based on your requirements

5. Watermark Design
 What is a watermark?
 Placement of watermark in the page margin
 Design of watermark as background or overlay

6. Watermark Design
What is a watermark?
• Traditional watermarks: faint imprints on paper that can only be seen at
a specific angle
• Watermarks in presentation software: often an image or text used as a
background
• It is meant to enhance, but not to be the main point of focus

7. Watermark Design
Placement of watermark in the page margin
• Watermark can be included as part of the header or footer
• Watermark can be included in the side margin and rotated to fit
• In order to rotate text on page, wrap the block of text in an <fo:block-
container> and provide angle of rotation in the reference-orientation
attribute:
<fo:block-container
position="absolute"
reference-orientation="90"
left="16pt"
height="100%">

8. Watermark Design
Design of watermark as background or overlay
• If watermark is placed behind the text, it will be partially blocked by the
text and mostly blocked by large images
• To prevent this, the watermark can be created as a transparent image
and placed above the text so that both text and watermark will be
clearly visible
• The image background should be completely transparent and the
foreground partially transparent
• Degree of opacity should be chosen in order to hide or highlight
watermark as desired
• However, if the watermark lies above the text in an <fo:block-
container>, this can cause difficulty for authors editing the file in Adobe
Acrobat.

9. Watermark Design
 What is a watermark?
 Placement of watermark in the page margin
 Design of watermark as background or overlay

10. Including your Watermark
 Inclusion in static content
• Overview of static content
• Watermark in the headers and footers
• Overview of regions
• Watermark in the side margins
• Watermark as an overlay
 Inclusion as background to text
• Overview of layout-masters
• Watermark as a background

11. Including your Watermark
Overview of static content
• Content inserted by the stylesheet unrelated to source DITA is called
static content.
• Includes headers and footers
• Divided by document section
 TOC, main body, index etc can each have distinct static content
• Divided by page position
 odd/even pages, first pages and last pages can all differ from
each other

12. Including your Watermark
• Static-content.xsl includes templates that address the above scenarios.
• Watermarks should be processed in each of the relevant templates
• Design attributes for watermarks should be included in the relevant
attribute sets in static-content-attr.xsl

13. Including your Watermark
Watermark in the headers and footers
• A watermark included as part of the header/footer can utilize the
existing templates for headers and footers in static-content.xsl
<xsl:template name="insertBodyOddFooter">
<fo:static-content flow-name="odd-body-footer">
<xsl:call-template name="insertUnitOddFooter“/>
</fo:static-content>
<xsl:call-template name="insertWatermark"/>
</xsl:template>

14. Including your Watermark
Overview of regions
• XSL-FO uses region elements to define the regions of a page:
• <fo:region-body> defines the body
• <fo:region-before> defines the header
• <fo:region-after> defines the footer
• <fo:region-start> defines the sidebar
preceding the text
• <fo:region-end> defines the sidebar
following the text
• Before/after and start/end depend on the
language direction

15. Including your Watermark
Watermark in the side margins
• A watermark included in the side margins should define new templates
in static-content.xsl
• fo:region-start and fo:region-end should be defined in layout-
masters.xsl to contain the watermarks
• The region-name attribute of fo:region-start must correspond to
the flow-name attribute of fo:static-content
<xsl:template name="insertBodyLeftSidebar">
<fo:static-content flow-name=“left-watermark">
<xsl:call-template name="insertWatermark"/>
</fo:static-content>
</xsl:template>
...
<fo:region-start extent="{$page-margin-left}" display-
align="center" region-name=“left-watermark"/>

16. Including your Watermark
Watermark as an overlay
• A watermark included as overlay to text can be included in the existing
header/footer templates in an fo:block-container with absolute
positioning
• Static content templates should be used in order to place the
watermark on each page
<xsl:template name="insertBodyEvenHeader">
<fo:static-content flow-name=“even-body-header">
<fo:block-container position="absolute“ left=“3in"
top=“4in">
<fo:external-graphic src="{$watermark-url}"
xsl:use-attribute-sets=“watermark“/>
</fo:block-container>
</fo:static-content>
</xsl:template>

17. Including your Watermark
Overview of layout-masters
• Layout masters are used to organize and define the various sections of
the document
• One fo:layout-master-set is created for each document
• The fo:layout-master-set contains fo:simple-page-master elements
to define the sizes, margins and regions of each document section.
These are the “building blocks” of the document
• The fo:layout-master-set also contains fo:page-sequence-master
elements which reference the simple-page-masters and put them
together to build each document section (for example, TOC, body,
etc.)

18. Including your Watermark
Watermark as a background
• A background image can be included on each relevant fo:region in
layout-masters.xsl to create a watermark
• Relevant attributes should be collected and defined in a new
xsl:attribute-set in layout-masters-attr.xsl
<fo:region-body background-image="$watermark-url"
margin-top="{$page-margin-top}"
margin-bottom="{$page-margin-bottom}"
margin-left="{$page-margin-left}"
margin-right="{$page-margin-right}"/>

19. Including your Watermark
 Inclusion in static content
• Overview of static content
• Watermark in the headers and footers
• Overview of regions
• Watermark in the side margins
• Watermark as an overlay
 Inclusion as background to text
• Overview of layout-masters
• Watermark as a background

20. Optional Watermark
 Use ANT parameter to conditionally display watermark
• Choose existing parameter OR
• Define custom parameter
 Add condition to watermark display
 Send parameter and value to DITA-OT

21. Optional Watermark
Choose existing parameter
1. Determine which ANT parameter is logically correct for your
requirements, for example args.draft.
2. Determine the name of the parameter as passed to the stylesheets, for
example DRAFT
• Note: Detailed documentation on available parameters is included
in each version of the DITA-OT.

22. Optional Watermark
Define custom parameter
1. In the transform.topic2pdf.init target, add a property defining your
custom parameter
<property name=“protect.content" value=""/>
2. In the transform.topic2fo.main target, add a parameter to the <xslt>
task including your custom parameter
<param name="ProtectContent"
expression="${protect.content}"/>
• Note: Names of ANT targets and tasks may differ slightly in earlier
versions of the DITA-OT
3. Define parameter in basic-settings.xsl in your customized stylesheets
<param name="ProtectContent"/>

23. Optional Watermark
Add condition to watermark display
• Wrap watermark logic in a condition testing the value of the parameter
<xsl:template name="insertWatermark">
<xsl:if test="$DRAFT = ‘true' and $Product !=
'Presentation'">
<fo:static-content flow-name="watermark">
<fo:block-container position="absolute"
height="100%" reference-orientation="90" left="16pt"
margin-right="2in">
<xsl:call-template
name="insertWatermarkInternal"/>
</fo:block-container>
</fo:static-content>
</xsl:if>
</xsl:template>

24. Optional Watermark
Send parameter and value to DITA-OT
• Include parameter and appropriate value when calling the DITA-OT
ant -f build.xml -Dargs.draft=true -DProduct=Handbook
• Note: Some CMS solutions already have various ANT parameters
configured in the CMS, particularly args.draft.

25. Optional Watermark
 Use ANT parameter to conditionally display watermark
• Choose existing parameter OR
• Define custom parameter
 Add condition to watermark display
 Send parameter and value to DITA-OT

26. Main Topics
 Watermark Design: Considerations for design and placement
 Including your Watermark: How to include your watermark in your
customized PDF stylesheets
 Optional Watermarks: Modify display based on your requirements

27. Hmmm, this looks interesting…
For additional information, contact us:
Joe Gelb
solutions@suite-sol.com
U.S. Office EMEA Office
(609) 360-0650 +972-2-993-8054
www.suite-sol.com