Single Sourcing PDF and WebHelp using MadCap Flare
description
Transcript of Single Sourcing PDF and WebHelp using MadCap Flare
![Page 1: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/1.jpg)
Single Sourcing PDF and WebHelp using MadCap Flare
Marjorie JonesTechnical Author, Exony
![Page 2: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/2.jpg)
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
![Page 3: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/3.jpg)
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
![Page 4: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/4.jpg)
My Aims
• Single source• Avoid content duplication where possible• Generate PDFs that worked for WebHelp• Ensure clean builds with no errors or warnings
![Page 5: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/5.jpg)
What I’ll Cover
• Outputs• Moving parts• TOC• Stylesheets• Target Properties• Cross References• Drop-down Text• Perhaps more?• In Retrospect
![Page 6: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/6.jpg)
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!
![Page 7: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/7.jpg)
Outputs
![Page 8: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/8.jpg)
Exony-branded PDFs
![Page 9: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/9.jpg)
Cisco-branded PDFs
![Page 10: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/10.jpg)
WebHelp Outputs
![Page 11: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/11.jpg)
Moving Parts
![Page 12: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/12.jpg)
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
![Page 13: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/13.jpg)
Moving Parts II
• PDFs– Page Layouts
• WebHelp– Master Pages– Skins– Relationship Tables– CSH (Header file and Alias files)
• And finally– Lots of topics!
![Page 14: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/14.jpg)
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
![Page 15: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/15.jpg)
The TOC
![Page 16: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/16.jpg)
The TOC and Topics
![Page 17: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/17.jpg)
The TOC and Conditions
![Page 18: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/18.jpg)
The TOC and PDF Output
![Page 19: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/19.jpg)
The TOC and WebHelp Output
![Page 20: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/20.jpg)
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
![Page 21: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/21.jpg)
Book Topics in Content Explorer
![Page 22: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/22.jpg)
The TOC, Topics and Print-Only
![Page 23: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/23.jpg)
A Question
![Page 24: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/24.jpg)
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)
![Page 25: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/25.jpg)
Stylesheets
![Page 26: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/26.jpg)
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
![Page 27: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/27.jpg)
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
![Page 28: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/28.jpg)
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)
![Page 29: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/29.jpg)
Target Properties
![Page 30: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/30.jpg)
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)
![Page 31: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/31.jpg)
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
![Page 32: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/32.jpg)
Target Properties - PDF
![Page 33: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/33.jpg)
Target Properties - Web
![Page 34: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/34.jpg)
Cake Break!
![Page 35: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/35.jpg)
Cross References
![Page 36: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/36.jpg)
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
![Page 37: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/37.jpg)
Cross Reference Examples
• PrintMadCap|xref.Section{ text-decoration: none; mc-format: 'section {paranum} "{paratext}"';}
• WebMadCap|xref.Section{
mc-format: '{paratext}';}
![Page 38: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/38.jpg)
Conditional Cross References
![Page 39: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/39.jpg)
Drop-down Text
![Page 40: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/40.jpg)
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
![Page 41: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/41.jpg)
Drop-down Text in XML Editor
![Page 42: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/42.jpg)
Drop-down Text in WebHelp
![Page 43: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/43.jpg)
Drop-down Text in PDF
![Page 44: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/44.jpg)
More on Drop-down Text
![Page 45: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/45.jpg)
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)
![Page 46: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/46.jpg)
Any more?
• More about the TOC• Single sourcing and– Glossaries– Alias files– Relationship tables
• Controlling the view in the Flare XML editor
![Page 47: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/47.jpg)
More About the TOC
![Page 48: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/48.jpg)
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
![Page 49: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/49.jpg)
Different Targets – Different Numbers 1
![Page 50: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/50.jpg)
Different Targets – Different Numbers 2
![Page 51: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/51.jpg)
Glossaries
![Page 52: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/52.jpg)
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
![Page 53: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/53.jpg)
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
![Page 54: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/54.jpg)
![Page 55: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/55.jpg)
Alias Files and Relationship Tables
![Page 56: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/56.jpg)
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)
![Page 57: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/57.jpg)
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
![Page 58: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/58.jpg)
Relationship Table Example
![Page 59: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/59.jpg)
Multiple Targets and the Flare XML Editor
![Page 60: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/60.jpg)
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)
![Page 61: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/61.jpg)
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)
![Page 62: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/62.jpg)
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)
![Page 63: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/63.jpg)
In Retrospect
![Page 64: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/64.jpg)
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)
![Page 65: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/65.jpg)
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.
![Page 66: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/66.jpg)
What I Liked
• Lots!• Hands-free PDF generation• Automatic builds• (Almost) true single sourcing• Easy to change styles and layouts
![Page 67: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/67.jpg)
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
![Page 68: Single Sourcing PDF and WebHelp using MadCap Flare](https://reader036.fdocuments.in/reader036/viewer/2022062316/56816858550346895dde85cc/html5/thumbnails/68.jpg)
The EndMarjorie Jones
Email: [email protected] Blog: nfasa.wordpress.com
Twitter: @titch990 Contact MadSIG: [email protected]