Transcript Single Sourcing PDF and WebHelp using MadCap Flare
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 Product B PDF Product B Glossary Cisco Page Layout Product C PDF Product C Glossary Product A Skin Product A WebHelp Exony Master Page Table Styles Exony Web Stylesheet Cisco Web Stylesheet Product B Skin Product B WebHelp Cisco Master Page Product C Skin Product C 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 • 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 drop down deletes text from drop-down body Styles window only shows styles of the same type (e.g.
for
,
for ) unless content is in a 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 (CiscoPrint) Page Layout (Cisco Default) Medium in Primary target (CiscoPrint) Layout (Print) Medium (ExonyPrint) Page Layout (Exony Default) Medium in primary target: ExonyPrint
Layout (Web) Medium (CiscoWeb) Primary target medium CiscoWeb Update Cross-references (if required) Layout (Web) Medium (ExonyWeb) Medium in primary target: ExonyWeb Update Cross-references
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: [email protected]
Blog: nfasa.wordpress.com Twitter: @titch990 Contact MadSIG: [email protected]
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 (CiscoPrint) Page Layout (Cisco Default) Medium in Primary target (CiscoPrint) Layout (Print) Medium (ExonyPrint) Page Layout (Exony Default) Medium in primary target: ExonyPrint
Layout (Web) Medium (CiscoWeb) Primary target medium CiscoWeb Update Cross-references (if required) Layout (Web) Medium (ExonyWeb) Medium in primary target: ExonyWeb Update Cross-references
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: [email protected]
Blog: nfasa.wordpress.com Twitter: @titch990 Contact MadSIG: [email protected]