1 / 68

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

lluvia
Télécharger la présentation

Single Sourcing PDF and WebHelp using MadCap Flare

An Image/Link below is provided (as is) to download presentation Download Policy: Content on the Website is provided to you AS IS for your information and personal use and may not be sold / licensed / shared on other websites without getting consent from its author. Content is provided to you AS IS for your information and personal use only. Download presentation by click this link. While downloading, if for some reason you are not able to download a presentation, the publisher may have deleted the file from their server. During download, if you can't get a presentation, the file might be deleted by the publisher.

E N D

Presentation Transcript

  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

More Related