Single Sourcing PDF and WebHelp using MadCap Flare

1. Single Sourcing PDF and WebHelp using MadCap Flare Marjorie Jones Technical Author, Exony

2. 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

3. 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

4. My Aims • Single source • Avoid content duplication where possible • Generate PDFs that worked for WebHelp • Ensure clean builds with no errors or warnings

5. What I’ll Cover • Outputs • Moving parts • TOC • Stylesheets • Target Properties • Cross References • Drop-down Text • Perhaps more? • In Retrospect

6. 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!

7. Outputs

8. Exony-branded PDFs

9. Cisco-branded PDFs

10. WebHelp Outputs

11. Moving Parts

12. 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

13. Moving Parts II • PDFs • Page Layouts • WebHelp • Master Pages • Skins • Relationship Tables • CSH (Header file and Alias files) • And finally • Lots of topics!

14. Exony Page Layout Exony Print Stylesheet Cisco Print Stylesheet Cisco Page Layout Common Glossary Product C Glossary Common TOC Product B Glossary Product A Glossary Product B PDF Product C PDF Product A WebHelp Product B WebHelp Product C WebHelp Product A PDF Cisco Web Stylesheet Table Styles Product A Skin Product B Skin Product C Skin Cisco Master Page Exony Master Page Exony Web Stylesheet

15. The TOC

16. The TOC and Topics

17. The TOC and Conditions

18. The TOC and PDF Output

19. The TOC and WebHelp Output

20. 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

21. Book Topics in Content Explorer

22. The TOC, Topics and Print-Only

23. A Question

24. 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)

25. Stylesheets

26. 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

27. 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

28. 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)

29. Target Properties

30. 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)

31. 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

32. Target Properties - PDF

33. Target Properties - Web

34. Cake Break!

35. Cross References

36. 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

37. Cross Reference Examples • Print MadCap|xref.Section { text-decoration: none; mc-format: 'section {paranum} "{paratext}"'; } • Web MadCap|xref.Section { mc-format: '{paratext}'; }

38. Conditional Cross References

39. Drop-down Text

40. 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

41. Drop-down Text in XML Editor

42. Drop-down Text in WebHelp

43. Drop-down Text in PDF

44. More on Drop-down Text

45. 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)

46. Any more? • More about the TOC • Single sourcing and • Glossaries • Alias files • Relationship tables • Controlling the view in the Flare XML editor

47. More About the TOC

48. 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

49. Different Targets – Different Numbers 1

50. Different Targets – Different Numbers 2