Upload
lluvia
View
78
Download
5
Tags:
Embed Size (px)
DESCRIPTION
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 - PowerPoint PPT Presentation
Citation preview
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: [email protected] Blog: nfasa.wordpress.com
Twitter: @titch990 Contact MadSIG: [email protected]