single sourcing pdf and webhelp using madcap flare

Single Sourcing PDF and WebHelp using MadCap Flare

Marjorie JonesTechnical 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!

Product A PDF

Product B PDF

Product C PDF

Common TOC

Table Styles

Exony Page Layout

Cisco Page Layout

Exony Print Stylesheet

Exony Web Stylesheet

Cisco Print Stylesheet

Exony Master Page

Cisco Master Page

Cisco Web Stylesheet

Product A Glossary

Product B Glossary

Product C Glossary

Product B Skin

Product B WebHelp

Common Glossary

Product C Skin

Product C WebHelp

Product A Skin

Product A WebHelp

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

• PrintMadCap|xref.Section{ text-decoration: none; mc-format: 'section {paranum} "{paratext}"';}

• WebMadCap|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 drop-down 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 EntriesNeeded• 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 EndMarjorie Jones

Email: titch990@outlook.com Blog: nfasa.wordpress.com

Twitter: @titch990 Contact MadSIG: MadSIG@istc.org.uk