Single Sourcing PDF and
WebHelp using MadCap Flare
Marjorie Jones
Technical Author, Exony
About Me
• Ex-software developer
• Technical author since 2007
• Sole author using Word (since MS-DOS) and
Flare (since Flare 7)
• Documenting call centre monitoring and
reporting software
• Interrupt with questions if you want
Why Flare?
•
•
•
•
•
•
A major single-sourcing problem
Three different related products (A, B and C)
Two different brandings (ours and a partner’s)
PDF and WebHelp outputs
PDFs from three separate Word documents
WebHelp from out-of-date RoboHelp content
My Aims
•
•
•
•
Single source
Avoid content duplication where possible
Generate PDFs that worked for WebHelp
Ensure clean builds with no errors or warnings
What I’ll Cover
•
•
•
•
•
•
•
•
•
Outputs
Moving parts
TOC
Stylesheets
Target Properties
Cross References
Drop-down Text
Perhaps more?
In Retrospect
What I (Probably) Won’t Cover
• Principles for decomposing into topics
• Single sourcing best practices
• Some web-specifics (CSH and alias files,
relationship tables)
• The “best” WebHelp
• The “only” way to do anything!
Outputs
Exony-branded PDFs
Cisco-branded PDFs
WebHelp Outputs
Moving Parts
Moving Parts I
•
•
•
•
•
•
Six targets (three PDF, three WebHelp)
One TOC
Four Stylesheets
One Table Stylesheet, four media
Conditions (products, brandings, output types)
Variables (product names, company contacts,
issue dates, versions)
• Multiple Glossaries
Moving Parts II
• PDFs
– Page Layouts
• WebHelp
– Master Pages
– Skins
– Relationship Tables
– CSH (Header file and Alias files)
• And finally
– Lots of topics!
Exony Page
Layout
Product A
PDF
Product A
Glossary
Exony Print
Stylesheet
Cisco Print
Stylesheet
Common
Glossary
Common
TOC
Table
Styles
Product A
Skin
Product A
WebHelp
Exony Master
Page
Cisco Page
Layout
Product B
PDF
Product C
PDF
Product B
Glossary
Product C
Glossary
Product B
Skin
Product B
WebHelp
Exony Web
Stylesheet
Cisco Web
Stylesheet
Product C
Skin
Product C
WebHelp
Cisco Master
Page
The TOC
The TOC and Topics
The TOC and Conditions
The TOC and PDF Output
The TOC and WebHelp Output
TOC Book Topics and WebHelp Output
• In WebHelp TOC book entries are not linked to
topics
• Clicking on TOC book expands/collapses book
instead of showing a topic
• To implement this, apply Print-Only condition
on topic, not on TOC entry, not on topic text
• Breadcrumb links won’t work – nothing to link
to
Book Topics in Content Explorer
The TOC, Topics and Print-Only
A Question
Properties for TOC Entries
• Printed Output:
– Set page layout for topics that don’t use default
– Set page type (can use First if required, even if not all
page layouts support it)
– Set Auto-end on Left page if required
– Set page numbering
– Set page, chapter, section breaks as required
• Set auto-numbers (probably not needed for web)
• Set conditions if required (child topics inherit
conditions)
Stylesheets
Stylesheets
• Four separate stylesheets (each using default
medium only) for:
– Exony Print
– Exony Web
– Cisco Print
– Cisco Web
• Each table stylesheet contains all four media
• Several table stylesheets for different table
types
Print and Web Styles I
• Web differences from Print:
– No pagination settings (e.g. page-break-inside:
avoid)
– No numbering for headings, figure captions, table
captions
– No body margin, so full width and aligned styles
(e.g. figure and table positions) are the same
– Different fonts
– Different image settings
Print and Web Styles II
• Print-only styles
– Title
– Header and footer text
– Table of Contents styles
• Web-only styles
– Relationship tables
– Drop-down text (ignored in print output)
– Pseudo classes (e.g. :hover, :visited)
Target Properties
Target Properties - General
• Set appropriate stylesheet for branding
(Exony, Cisco) and for output medium (PDF,
WebHelp)
• Set medium to one of ExonyPrint, ExonyWeb,
CiscoPrint and CiscoWeb (needed for table
styles)
• Set conditions for product (A, B, C), branding
and output medium (Print, WebHelp)
• Set variables for product (A, B, C)
Target Properties - Specific
• For PDF targets:
– set page layout to default body layout for
branding (override in TOC where needed)
– set PDF generation options
• For Web targets
– set skin for product
– set master page for branding
– set Exclude Content not linked directly or indirectly
from target
Target Properties - PDF
Target Properties - Web
Cake Break!
Cross References
Using Cross References
• Aim – avoid having print-only and web-only cross
references if possible
• Plan - think about how output will look
• Beware – don’t reference a TOC book topic (not
present in web output)
• Beware – don’t reference conditional content
unless the reference has the same condition
• Beware - “The figure below shows . . . “ in Web
output
• Beware – don’t reference content in a snippet
Cross Reference Examples
• Print
MadCap|xref.Section
{
text-decoration: none;
mc-format: 'section {paranum} "{paratext}"';
}
• Web
MadCap|xref.Section
{
mc-format: '{paratext}';
}
Conditional Cross References
Drop-down Text
Drop-down Text
• Really useful, to reduce complexity and hide
details until reader needs them
• Drop-down body can include lower level
headings
• Body automatically expanded in PDF
• I set my headings to Web-Only
• I have a pre-formatted snippet template
Drop-down Text in XML Editor
Drop-down Text in WebHelp
Drop-down Text in PDF
More on Drop-down Text
Drop-down Text “Features”
• In Layout (Print), unbinding a multi-page dropdown deletes text from drop-down body
• Styles window only shows styles of the same
type (e.g. <p> for <p>, <h1> for <h1>) unless
content is in a <div>
• Minor formatting problems in PDF (too much
space before headings)
Any more?
• More about the TOC
• Single sourcing and
– Glossaries
– Alias files
– Relationship tables
• Controlling the view in the Flare XML editor
More About the TOC
Duplicated TOC Entries
Needed
• For different content
and/or different TOC text
for different products
• To override target’s
default page layout with
different layout for
different brandings
• To apply different
numbering styles or
sequencing for different
targets
Different Targets – Different Numbers 1
Different Targets – Different Numbers 2
Glossaries
Glossary Styles
• Different styles needed for Web and Print
• Main Print styles
– div.GlossaryPageHeading
– div.GlossaryPageTerm
– div.GlossaryPageDefinition
• Main Web styles
–
–
–
–
–
a.GlossaryPageTerm
a.GlossaryPageTerm:link
a.GlossaryPageTerm:visited
div.GlossaryPageDefinition
Also (for terms in topics) MadCap|glossaryTerm.Expanding,
MadCap|glossaryTerm.Hyperlink, MadCap|glossaryTerm.Popup
Glossaries don’t Single-source
• No variables allowed in terms or descriptions
• No conditional entries in glossaries
• Remember to select only the glossaries
required by your target
Alias Files and Relationship
Tables
Alias Files
• Provide the link between the application CSH
calls and the correct Flare topic.
• To avoid build errors:
– One Alias File for each distinct WebHelp product
– Only include links to the topics that are present in
that output
– Select a single alias file for each target (on
Advanced tab)
Relationship Tables
• A simple, flexible way of collecting topics into
groups and specifying which topics contain
links to which other topics
• To single-source without build errors:
– One relationship table for all related WebHelp
outputs
– But must replicate TOC conditions in relationship
table
– Select relationship table (or tables) required by
target
Relationship Table Example
Multiple Targets and the Flare
XML Editor
Controlling the Flare Editor View
• What you see depends on:
–
–
–
–
The selected Page Layout
The selected Medium
The Master Stylesheet (if you have more than one)
The settings applicable when the cross-references were updated
• By default, all taken from primary target
• You may need to change these to see what you expect
– First two can be done in the Flare XML editor
– Last two must be done by changing Stylesheet in Primary target
– To see WYSIHYG cross references, then select Tools > Update
Cross-References
• What you see does not depend on Layout (Print)/Layout
(Web)
Layout (Print)
Medium (ExonyPrint)
Page Layout (Exony Default)
Medium in primary target:
ExonyPrint
Layout (Print)
Medium (CiscoPrint)
Page Layout (Cisco Default)
Medium in Primary target
(CiscoPrint)
Layout (Web)
Medium (ExonyWeb)
Medium in primary
target: ExonyWeb
Update Cross-references
Layout (Web)
Medium (CiscoWeb)
Primary target medium
CiscoWeb
Update Cross-references
(if required)
In Retrospect
What I’m Glad I Did
• Understood the moving parts first
• Persevered with one TOC
• Separated Stylesheets (far easier to maintain
than four different media in one)
• Distinguished between branding (Exony and
Cisco) and products (A, B and C)
What I’d Do Differently
• Very little
• Topic decomposition into fewer larger topics
with drop-downs
• If so, possibly not relationship tables, perhaps
See Also?
• Investigate linking to a sub-TOC from within a
TOC to get round some of the single-sourcing
issues.
What I Liked
•
•
•
•
•
Lots!
Hands-free PDF generation
Automatic builds
(Almost) true single sourcing
Easy to change styles and layouts
What I Didn’t Like
• Single sourcing issues with
– Glossaries
– Web skins
– Alias files
• Not geared up for multiple stylesheets rather
than multiple mediums
– Assumes primary target, and perhaps another
which is a tweak of primary target
– Not easy to check/compare stylesheets
The End
Marjorie Jones
Email: titch990@outlook.com
Blog: nfasa.wordpress.com
Twitter: @titch990
Contact MadSIG: MadSIG@istc.org.uk