Customizing Content with DITA Conditional Text and XMetaL

  • 3,173 views
Uploaded on

With XMetaL and DITA, you can create documents customized for various audiences, products, and platforms from a single set of source files. XMetaL includes a sophisticated and easy-to-use set of …

With XMetaL and DITA, you can create documents customized for various audiences, products, and platforms from a single set of source files. XMetaL includes a sophisticated and easy-to-use set of features for applying consistent tags to conditionalize content, for color-coding conditional text in authoring views, and for generating customized output. In this webinar, we’ll take a close look at how to set up and use conditional text in DITA with XMetaL.

A recording of the webinar is here:
https://justsystems.webex.com/justsystems/lsr.php?AT=pb&SP=EC&rID=43143747&rKey=8e21588799156c20

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
    Be the first to like this
No Downloads

Views

Total Views
3,173
On Slideshare
0
From Embeds
0
Number of Embeds
2

Actions

Shares
Downloads
63
Comments
0
Likes
0

Embeds 0

No embeds

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 1. in 37 minutes
    Episode 9Customizing Content with DITA Conditional Text
    Su-Laine Yeo, Solutions Consultant
    July 15, 2010
  • 2. Conditional text with the DITA (Darwin Information Typing Architecture) XML language
    Practical steps for using conditional text in XMetaL Author Enterprise
    Fairly detailed level, but not difficult
    Specific examples
    Not using DITA? Keep watching, and also come back for our next 37-minute webinar on July 29
    Today’s webinar
  • 3. Customization and content reuse
    Reuse lets you deliver customized content without duplicating it
    Approaches:
    Modular reuse:
    reusing whole topics
    content references (conref) to reuse phrases and parts of topics
    Conditional text
  • 4. What is conditional text?
    “Conditional text” refers to:
    The practice of marking up the content in a single source file, so you can create deliverables with different subsets of the file.
    The contentthat is marked up so you can filter it out of some deliverables. In DITA,conditional "text" can be words, images, tables, index markers, links, etc.
  • 5. Conditional text
    Marking up the content in a single source file, so you can create deliverables with different subsets of the file.
    E.g. Windows-only content (Ctrl+S) and Macintosh-only content (Command+S)
  • 6. attribute
    attribute value
    Under the covers: XML
    A paragraph that is not conditional:
    <p>Press Ctrl+S.</p>
    A paragraph that applies to the Windows platform only:
    <p platform = "windows">Press Ctrl+S.</p>
  • 7. Steps for using conditional text
    Plan
    Make a list of your audiences, products, and platforms that require similar documentation
    Configure
    Configure the system to use the conditions you want
    Style conditional content so that you can keep track of it when writing
    Write
    Mark content as conditional
    Generate output
    Choose a particular product/platform/audience combination
  • 8.
    • Make lists:
    What product variations are similar enough they could be documented through one set of source files?
    What audiences do you want to customize documentation for?
    Example for today’s webinar: two platforms
    A software application that has different keyboard shortcuts for Macintosh and Windows platforms
    Step 1: Plan
  • 9. Step 2: Define conditional attribute values
    Edit the XMetaL ditabase_ct_config.xml file.
    This file is installed in your C:Program FilesXMetaL 6.0AuthorConditional Textconfigs folder.
    <attribute name="platform" title="Platform">
    <value name="windows" title="Windows" />
    <value name="macintosh" title="Macintosh" />
    </attribute>
  • 10. Distribute settings files
    You can standardize conditions within a team by distributing the ditabase_ct_config.xmlfile.
    When you start XMetaL, XMetaL automatically configures its Conditional Text dialogs to use the values in this file.
  • 11. Style conditional text
    You'll want to be able to keep track of conditions when you are writing, preferably in real-time via color-coding.
  • 12. Configure styling
    Styling affects what you see in XMetaL, not in output
    Click Reuse > Style Conditional Text.
  • 13. To make content conditional:
    Click in an element, or select some text
    Click Reuse > Apply/Remove Conditions
    Step 3: Write
  • 14. Under the covers
    Content for Windows only:
    <p platform="windows">Press Ctrl+S.</p>
    Content for Windows and Macintosh, but not Unix:
    <p platform="windows macintosh">Press Ctrl+S.</p>
    Content for all platforms:
    <p>Press Ctrl+S.</p>
  • 15. What content can you make conditional?
    Yes:
    Text
    Images
    Cross-references
    Index markers
    Tables
    Rows in tables
    Content within content references
    Topic references in DITA maps
    No:
    • Individual table cells
    • 16. Table columns
    • 17. Required elements (you can conditionalize text within required elements)
  • <ph> element
    If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.
  • 18. Best practices
    To make a whole topic conditional, conditionalize the corresponding topic referencein the DITA map file.
    Do not conditionalize content that is "common to all."
    If an element is common to all deliverables, do not put conditional attributes on it.
    If an element is common to all products, do not put any "product" attributes on it.
    If your content will be translated, it is safest to conditionalize entire sentences, not parts of sentences.
  • 19. Step 4: Generate conditional output
    In XMetaL: File > Generate Output
    Choose what platforms, products, and audiences you want to include
  • 20. What about DITAVAL files?
    <prop att="platform" val="macintosh" action="exclude"/>
    You don’t need to write one. XMetaL generates the DITAVAL file automatically:
  • 21. Multiple Condition Types
  • 22. Multiple condition types
    Say you have:
    Three platforms: “Windows” and “Macintosh” and "Unix"
    Two audience types: “Europe” and “North America”
  • 23. How DITA handles multiple condition types
    For an element marked as audience = “Europe” and platform = “windows”
    *Would appear if you used native FrameMaker® conditions instead of DITA
  • 24. Multiple condition types: the rule
    In this example: Content must be for both the right platform and the right audience in order to be included.
    The general rule: An element is included if, for each conditional attribute:
    • It doesn't have any values for that attribute, i.e. it is "common to all"
    • 25. OR it matches at least one value that should be included.
  • Of the 4 steps, planning is the most challenging:
    Plan
    Configure
    Write
    Generate output
    Putting it into practice
  • 26. DITA attributes
    DITA attributes for conditional text are:
    product
    platform
    audience
    otherprops
    For anything else, including other audience types
    props
    Create new attributes by specializing the “props” attribute
  • 27. Example
    You are documenting a product with Macintosh, Windows, and Unix versions
    For this example:
    the attribute you need is "platform".
    you will allow the values of the platform attribute to be "Macintosh", "Windows", and "Unix".
  • 28. List the attributes, and values of each attribute, that you want to use.
    These will go into your ct_config.xml file
    Do not overload the “audience” attribute:
    E.g. have an “audience_skill_level” attribute and a “audience_region” attribute. Do not put your lists of skill levels and regions all into the “audience” attribute.
    Make lists
  • 29. Summary: Why DITA for conditional text?
    Scalable:
    Handles multiple condition types well
    Easily standardized across a team
    Standards-based:
    Multiple output formats
    Can work with dynamic content delivery systems
    Within reach:
    No programming needed
    Does not require a sophisticated CMS or publishing system
  • 30. Q&A
    • Contact Su-Laine at: syeo at justsystems dot com
    • 31. Today’s slides are at http://www.slideshare.net/XMetaL
    contactsales-na@justsystems.com
    1-866-793-1542