Introduction to
DITA and XMetaL



        Simon Bate
        Scriptorium Publishing
        Services
Course Agenda

 Overview of XMetaL     Sections and nested
 Elements and           topics
 structured authoring   Cross-re...
Course purpose

 Learn how to author content using XMetaL
 Author Enterprise Edition
 Understand DITA
 Put theory into pra...
About DITA

 Darwin Information Typing Architecture
 Created at IBM
 Now developed and maintained by OASIS
 Standard XML l...
Role of DITA Tools

 An authoring tool is a user interface for creating
  DITA content
DITA documentation

 DITA Language Reference
  Purpose and content model for each element
  Help > DITA Specifications > D...
Overview of XMetaL
XMetaL Author

 Standard word-processing environment
  Multiple undo (and redo)
  Spell checking & thesaurus
  Change trac...
XMetaL Author Interface: Overview
 Menu


Tool bar




Structure
  View




            View Mode   Document    Element
  ...
Inserting symbols and special
characters
 Insert > Symbols


 Insert > Special Characters


 Or click View > Toolbars,
  T...
Typographical elements

 Bold
 Italic
 Underline
View modes

 Four view modes for the document pane:
  Normal
  Page Preview
  Tags On
  Plain Text
 Controls in bottom lef...
Normal view

 Shows content
 No XML element tags
 Indicated by this icon:
 Use most of the time when writing content
Tags On view

Shows content
Shows XML element tags
Indicated by this icon:
Allows precise insertion
Allows tag deletion/un...
Plain Text view

 Edit all XML markup and content
 Indicated by this icon:
 Does not check validity
 Can create invalid XML
Page Preview view

 Shows a formatted preview
 Indicated by this icon:
 Verify the content is formatted correctly
 XML doc...
Tip:

 Can’ see the menus?
     t
  Open a DITA document
 Want to see the structure view?
  View > Structure View
Workbook Exercise:
Basic File Operations
Options for saving and opening
files
 Click Tools > Options




 To use default toolbars, press CTRL on startup
File and folder naming

 Be systematic and careful
 No spaces
 No special characters
Elements and Structured
Authoring
Elements: Key terms

 Element
 Element type (or name)
 Element contents
 Start tag
 End tag
 Attribute
Structure and validity

 XML must be:
  Well-formed
  Valid
 DITA content model defines validity
  How to order elements
 ...
Validating documents

 Click Tools > Validate
 Errors most common in converted legacy
 documents
 Fix “missing required el...
Structure and quot;Smart Insertquot;

 When pasting XMetaL content:
  XMetaL inserts content at closest valid location
  M...
Identifying the current element

 See context bar (at bottom of screen)
 Also shows ancestors' hierarchy
 Based on:
  Curs...
Identifying the current element

 Be aware of what is selected
ENTER key

 XMetaL inserts the most logical next element
 Often the same type as the current one
Insert menu

 Allows you to insert elements
 Shows most available elements
 Context free
 “Smart Insert”
  Inserts an elem...
Element List

 View > Element List
 Lists available valid
 elements
 Depends on cursor location

 Insert new
 Change selec...
Paragraph menu

 Change paragraphs to notes and long
 quotations
 Specify note types:
  danger
  tip
 Apply and remove bul...
Format markup vs.
Semantic markup
 Separation of content from formatting

 Format markup: how something should look
 Seman...
Inserting domain elements

 Domain elements cross topic types
 Insert > * Element menus
  Programming
  Software
  User In...
Domains in Element List

 Domain elements are listed in Element List
 Tools > DITA Options
 Only affects the Element List
...
Modifying elements

 Change element type
  Radio button in Insert element list
 Expand and collapse content displays
 Dele...
Deleting elements

 Easiest on Tags On view

 To quot;unwrapquot; an element (leave content):
  Click just after the start...
Workbook Exercise:
Working with Elements
Generating Output (Publishing)
DITA Open Toolkit

 Open-source application for publishing DITA
 content to multiple output formats

 Integrated with XMet...
Publishing formats

 XHTML
 PDF
 CHM
 RTF
 Eclipse Help
 JavaHelp
PDF options

 XMetaL Enhanced PDF
  Best all-purpose PDF deliverable type

 XMetaL Enhanced PDF via Acrobat Distiller
  Us...
Generating output

 File > Generate Output for DITA Topic

 Troubleshooting:
  File > View Output Log
Workbook Exercise:
Generating Output
Attributes
Purpose of attributes

 Provide additional information
  width = “250 px”
 Point to a file or URL
  href = “http://www.mic...
Attribute Inspector

 Click View >
 Attribute Inspector
 Allows you to
 examine and change
 values of XML
 attributes
 Cur...
Working with attributes

 XMetaL creates element IDs automatically
 Some dialog boxes set attributes
  Insert Image
  Set ...
Attribute tooltips

 Tip: Hover over a tag in Tags On view to see
 attributes
Workbook Exercise:
Attributes
Images
Supported image formats

 PNG, GIF, JPEG
 SVG (if an appropriate plug-in is installed)
 EPS
  displays in XMetaL if previe...
Working with images

 Inserting images
  Insert > Image
 Insert an image with a title
  Insert > Figure with Title
 Add a ...
Image sizing

Do one of the following:
  Best-supported: Resize the image using a
  graphics editor
  Specify “width” in p...
Workbook Exercise:
Images
Tables
Tables

 Click Table > Insert Table
 Choose type:
  Normal table = table with title
  Simple table = informal table (no ti...
Header rows

 To make the first row of a table a header row:
  Click Table > Insert Table




  Add later with
  Table > T...
Working with table properties

 Tip: Click in a row to change the properties of
 that row. Don’ select the whole row.
    ...
Workbook Exercise:
Tables
Writing topics
Topics

 A Topic is a DITA unit of information
 Has a title, short description, and content
 All topics have the same basi...
Topic types
 Main topic types:
  Generic Topic
  Concepts
  Tasks
  Reference
 DITA also includes:
  Composite or multiple...
Topics: Determining the topics
you need
 Identify a task to document.
 Identify the subtasks for the task.
 Identify the c...
XMetaL authoring templates
 Templates include commonly-needed
 elements to get started
  To delete empty elements, click b...
Common elements in topics
 Title
 Short description
  Briefly introduce the topic and provide a
  concise answer to the qu...
Concept topics

 Concept topics explain and teach.
 Help users build on their experience and
 knowledge.
 Read before usin...
Concept topics: examples

 Concept topics can focus on specific types of
 information:
  Technology
  User concerns
  Deci...
Sections and nested topics
Sections, topics, and headings

 DITA is structured
 Not like HTML or Word
 Cannot put headings where you want

 DITA requ...
Sections
 Use in Concept and Reference topics
 Can have more than one section
 Can’ nest sections
      t
 All following p...
Working with sections

 Use Tags On view to see section boundaries
 Make sure section encloses all following
 content elem...
Sections and subtopics

 To nest information, either:
  Nest topics within a DITA map
  Insert subtopics within the DITA t...
Workbook Exercise:
Creating Topics
Reference topics

 Reference topics provide quick access to facts
 Info users need to complete their tasks
 Often read whe...
Reference topics: examples

 Documents the facts for categories such as:
     device support        settings
     APIs    ...
Task topics
 Task topics document procedures
 About 70% of topics are tasks
 Each task topic presents information in a str...
Task topics: Prerequisites

 DITA element: <prereq>
 Things that users need to know or do before
 starting the task steps
Task topics: Context

 DITA element: <context>
 Background information on the task
Typical task topic

 <steps> element provides numbered steps
Sequence within a <step>
element
 <cmd> (required)
 Any number of the following:
  <info> (tables, images, paragraphs, not...
Example of <steps>
Steps: Example in a step

 DITA element: <stepxmp>
 Optional step element
 Illustrates the successful completion of the
 c...
Steps: Step result

 DITA element: <stepresult>
 Describes the result of the current step
 Optional step element
 Example:...
Steps: Substeps

 DITA elements: <substeps>, <substep>
 Subdivides a major step in a sequence.
 Output is the equivalent o...
Steps: Choices

 DITA elements: <choices>, <choice>
 Decisions within a major step in a sequence
 Output is the equivalent...
Steps: Choice tables

 DITA elements: <choicetable>, <chrow>,
 <choption>, <chdesc>
 Decisions within a major step in a se...
Steps: Choice table output
  Specify how to open new perspectives:

Option              Description
Click in the same   To...
Task with unordered steps

 Bullets instead of numbers
 <steps-unordered> element
Task topics: Results

 DITA element: <result>
 Illustrates the successful completion of the
 task
 Example:
 The device is...
Task topics: Example

 DITA element: <example>
 Illustrates a successful completion of the task
 steps.
 <example> is a ty...
Task topics: Postrequisites

 DITA element: <postreq>
 Things that users need to know or do upon
 completing the task step...
Workbook Exercise:
Task Topics
Cross-references and links
Types of links

 Inline links <xref>
  Cross-reference <xref href=quot;#targetquot;/>
  File reference <xref href=quot;fil...
Inserting links

 Insert > Link > ...
  Cross-reference
  File reference
  Web link
 All add <xref> elements

 Related lin...
Refreshing References

 To update content in cross-references:
  Click Edit > Refresh All References
  Close and reopen th...
Workbook Exercise:
Cross-references and Links
Metadata and index elements
Metadata in DITA

 Maintained in <prolog> element
 Examples: author, publisher, copyright
 information
 Metadata is usuall...
Indexing

 Use <indexterm>
 Can nest <indexterm> elements
 Cannot put in <title> elements

 Place <indexterm> where approp...
Creating index entries

 Click Insert > Index Marker
 Tip: Press Alt+Shift+X
 Use commas to create subentries
Editing index entries

 Braces ({ and }) are XMetaL
 Index entry:

 Nested index entry:


 Nested entry produces:
     “St...
Advanced indexing features

 DITA 1.1
 Page ranges
 See/See also
 Sort as
Workbook Exercise:
Metadata and Index Elements
Track changes
Track changes

 Purpose:
  Communicate to reviewers about what’ new
                                       s
  Have review...
Using change tracking

 Turn on and off:
  Tools > Track Changes
 Accept/reject changes:
  Tools > Accept or Reject Change...
Workbook Exercise:
Track Changes
DITA Maps
DITA maps

 Organize DITA topics in a TOC-like structure
 References to DITA topics
 Analogous to a FrameMaker Book file
 ...
Topics and maps
 Topic
  Unit of information that is meaningful when it
  stands alone
 Map
  Organizes topics into a cohe...
Working with maps

 Map Editor displays maps in a
 GUI
 You can:
  Add and remove topics
  Change topic order
  Nest topic...
Insert a reference to an existing
topic
 Select the map entry under which you want to
 nest the topic
 Click Insert > Topi...
Tips for working with maps

 Plan where to put your map and topic files
  usually close to each other

 Remember file and ...
Insert and create a topic

 Select the topic
 above where you
 want the new topic
 Click Insert > Topic
 Reference
Insert a topic heading

 Click Insert > Topic
 Heading
Create a new map

 Click (small) File > New Map.

  or

 Click (big) File > New
  Then choose the DITA Map template
Insert a submap

 Both maps must exist
 Click (small) Insert >
 Map Reference
Specify map properties

 In the Map Editor, select the Properties button.
 In the Map Properties dialog, click the Special...
Workbook Exercise:
Organizing Topics with Maps
Switch to XML view

 Click (small) File >
 Switch to XML View
 of Map.
Switch to Map Editor

 Select File > Switch
 to Map Editor
Different views for different tasks
 Task                                         Map     XML
                            ...
Relationship tables

 Automatically generate “Related x” sections
 Special type of semantic table
  Columns define informa...
Map metadata

 Metadata in maps
  can fine-tune linking in relationship tables
  can be used instead of topic metadata
  i...
Relationship Tables: XML View
Create a relationship table

 Switch to XML view
 Insert the relationship table
 Add the <topicref> elements
 Generate the...
Insert a relationship table

 Click Table > Insert Relationship Table.
 Choose one of several common formats, then
 click ...
Attributes for managing links

In a <relcell> element:
   collection-type = “family”
    topicrefs in cell link to each ot...
Add topics
 Hold CTRL and drag
 Task topics from the
 navigation portion of
 the map into the
 relationship table. This
 c...
Workbook Exercise:
Relationship Tables
Glossaries
Glossaries

 Writing glossary content
 Assembling glossary content
Glossary content

 Basic markup:
   <glossentry>
      <glossterm></glossterm>
      <glossdef></glossdef>
   </glossentry...
Assembling glossary content

 Create a Bookmap file and point the
 <glossarylist> element to your glossary
 content files....
Publishing glossaries

 During “Generate Output”:
 All glossary content is pulled into the same
 glossary and is sorted al...
Reusing content
Content reuse: overview

 Reuse is about reducing duplication and
 delivering more customized content

 Two main approache...
Conditional text

 Single source file
 Content for multiple deliverables
 Markup identifies different subsets
 For example...
What does conditional text
markup look like?
 No conditional text markup:
                 <p>Press Ctrl+S.</p>


 Conditi...
Conditional text overview

 Configure XMetaL with conditions
 Typically: products, platforms, audiences

 In XMetaL:
  Mar...
Make content conditional

 Select text or an element
 Click Reuse > Apply/Remove Conditions
Assigning conditional attributes

 Windows only:
    <p platform=quot;windowsquot;>Press Ctrl+S.</p>


 Windows and Macint...
What content can you make
conditional?
 DITA allows a high degree of granularity
 Single words can be made conditional
 (B...
Elements that can be made
conditional:
 Yes:                   No:
  Text                   Individual table cells
  Image...
<ph> element

 If you make selected text conditional, XMetaL
 inserts <ph> tags so it can “hang” attributes on
 the <ph> e...
Style conditional text

 Styles help keep
 track of
 conditional text
 XMetaL only, not
 in deliverables
 Reuse > Style
 C...
Generate conditional output

 Choose what
 platforms, products,
 and audiences you
 want to include
How DITA handles multiple
condition types
For an element marked as audience = “Europe”
  and platform = “windows”
In outpu...
Multiple condition types: the rule

 In this example: Content must be for both the
 right platform and the right audience ...
Planning to use conditional text

Determine your team's needs in terms of content
reuse:
   What product variations are si...
Configuring XMetaL conditions

    Edit ct_config.xml
<conditions>
    <attribute name=quot;audiencequot; title=quot;Audie...
Content references (conrefs)

 Standard DITA element attribute
 References another element of same type
 On output, conten...
Content references in XMetaL

Content shown in conref is:
  Read-only
  Updated when a document is opened

To manually ref...
Working with content references

 Open a document containing a content
 reference
 Right-click to switch between viewing l...
Reusable components

 Reusable components:
  Managed snippets of XML
  Have titles, short descriptions, and reusable-
  co...
Reuse strategies
      Reuse Opportunity                       Solution

 Multiple similar deliverables   Flag some conten...
Workbook Exercise:
Reusing Content
Additional resources

 DITA Users group on Yahoo! groups:
 http://tech.groups.yahoo.com/group/dita-users/
 XMetaL-DITA gro...
Thanks!

 Last Questions?
 Drawing!

 sbate@scriptorium.com
Introduction to
DITA and XMetaL



        Simon Bate
        Scriptorium Publishing
        Services




                ...
Course Agenda

 Overview of XMetaL     Sections and nested
 Elements and           topics
 structured authoring   Cross-re...
Course purpose

 Learn how to author content using XMetaL
 Author Enterprise Edition
 Understand DITA
 Put theory into pra...
About DITA

 Darwin Information Typing Architecture
 Created at IBM
 Now developed and maintained by OASIS
 Standard XML l...
Role of DITA Tools

 An authoring tool is a user interface for creating
  DITA content




                               ...
DITA documentation

 DITA Language Reference
  Purpose and content model for each element
  Help > DITA Specifications > D...
Overview of XMetaL




                     7
XMetaL Author

 Standard word-processing environment
  Multiple undo (and redo)
  Spell checking & thesaurus
  Change trac...
XMetaL Author Interface: Overview
 Menu


Tool bar




Structure
  View




            View Mode   Document    Element
  ...
Inserting symbols and special
characters
 Insert > Symbols


 Insert > Special Characters


 Or click View > Toolbars,
  T...
Typographical elements

 Bold
 Italic
 Underline




                         11
View modes

 Four view modes for the document pane:
  Normal
  Page Preview
  Tags On
  Plain Text
 Controls in bottom lef...
Normal view

 Shows content
 No XML element tags
 Indicated by this icon:
 Use most of the time when writing content




 ...
Tags On view

Shows content
Shows XML element tags
Indicated by this icon:
Allows precise insertion
Allows tag deletion/un...
Plain Text view

 Edit all XML markup and content
 Indicated by this icon:
 Does not check validity
 Can create invalid XM...
Page Preview view

 Shows a formatted preview
 Indicated by this icon:
 Verify the content is formatted correctly
 XML doc...
Tip:

 Can’ see the menus?
     t
  Open a DITA document
 Want to see the structure view?
  View > Structure View




    ...
Workbook Exercise:
  Basic File Operations




11/03/08                  18




                               18
Options for saving and opening
      files
        Click Tools > Options




        To use default toolbars, press CTRL o...
File and folder naming

 Be systematic and careful
 No spaces
 No special characters




                             20
Elements and Structured
Authoring




                          21
Elements: Key terms

 Element
 Element type (or name)
 Element contents
 Start tag
 End tag
 Attribute




               ...
Structure and validity

 XML must be:
  Well-formed
  Valid
 DITA content model defines validity
  How to order elements
 ...
Validating documents

 Click Tools > Validate
 Errors most common in converted legacy
 documents
 Fix “missing required el...
Structure and quot;Smart Insertquot;

 When pasting XMetaL content:
  XMetaL inserts content at closest valid location
  M...
Identifying the current element

 See context bar (at bottom of screen)
 Also shows ancestors' hierarchy
 Based on:
  Curs...
Identifying the current element

 Be aware of what is selected




                                  27
ENTER key

 XMetaL inserts the most logical next element
 Often the same type as the current one




                     ...
Insert menu

 Allows you to insert elements
 Shows most available elements
 Context free
 “Smart Insert”
  Inserts an elem...
Element List

 View > Element List
 Lists available valid
 elements
 Depends on cursor location

 Insert new
 Change selec...
Paragraph menu

 Change paragraphs to notes and long
 quotations
 Specify note types:
  danger
  tip
 Apply and remove bul...
Format markup vs.
Semantic markup
 Separation of content from formatting

 Format markup: how something should look
 Seman...
Inserting domain elements

 Domain elements cross topic types
 Insert > * Element menus
  Programming
  Software
  User In...
Domains in Element List

 Domain elements are listed in Element List
 Tools > DITA Options
 Only affects the Element List
...
Modifying elements

 Change element type
  Radio button in Insert element list
 Expand and collapse content displays
 Dele...
Deleting elements

 Easiest on Tags On view

 To quot;unwrapquot; an element (leave content):
  Click just after the start...
Workbook Exercise:
  Working with Elements




11/03/08                  37




                               37
Generating Output (Publishing)




                                 38
DITA Open Toolkit

 Open-source application for publishing DITA
 content to multiple output formats

 Integrated with XMet...
Publishing formats

 XHTML
 PDF
 CHM
 RTF
 Eclipse Help
 JavaHelp




                     40
PDF options

 XMetaL Enhanced PDF
  Best all-purpose PDF deliverable type

 XMetaL Enhanced PDF via Acrobat Distiller
  Us...
Generating output

 File > Generate Output for DITA Topic

 Troubleshooting:
  File > View Output Log




                ...
Workbook Exercise:
  Generating Output




11/03/08               43




                            43
Attributes




             44
Purpose of attributes

 Provide additional information
  width = “250 px”
 Point to a file or URL
  href = “http://www.mic...
Attribute Inspector

 Click View >
 Attribute Inspector
 Allows you to
 examine and change
 values of XML
 attributes
 Cur...
Working with attributes

 XMetaL creates element IDs automatically
 Some dialog boxes set attributes
  Insert Image
  Set ...
Attribute tooltips

 Tip: Hover over a tag in Tags On view to see
 attributes




                                        ...
Workbook Exercise:
  Attributes




11/03/08               49




                            49
Images




         50
Supported image formats

 PNG, GIF, JPEG
 SVG (if an appropriate plug-in is installed)
 EPS
  displays in XMetaL if previe...
Working with images

 Inserting images
  Insert > Image
 Insert an image with a title
  Insert > Figure with Title
 Add a ...
Image sizing

Do one of the following:
  Best-supported: Resize the image using a
  graphics editor
  Specify “width” in p...
Workbook Exercise:
  Images




11/03/08               54




                            54
Tables




         55
Tables

 Click Table > Insert Table
 Choose type:
  Normal table = table with title
  Simple table = informal table (no ti...
Header rows

 To make the first row of a table a header row:
  Click Table > Insert Table




  Add later with
  Table > T...
Working with table properties

 Tip: Click in a row to change the properties of
 that row. Don’ select the whole row.
    ...
Workbook Exercise:
  Tables




11/03/08               59




                            59
Writing topics




                 60
Topics

 A Topic is a DITA unit of information
 Has a title, short description, and content
 All topics have the same basi...
Topic types
 Main topic types:
  Generic Topic
  Concepts
  Tasks
  Reference
 DITA also includes:
  Composite or multiple...
Topics: Determining the topics
you need
 Identify a task to document.
 Identify the subtasks for the task.
 Identify the c...
XMetaL authoring templates
 Templates include commonly-needed
 elements to get started
  To delete empty elements, click b...
Common elements in topics
 Title
 Short description
  Briefly introduce the topic and provide a
  concise answer to the qu...
Concept topics

 Concept topics explain and teach.
 Help users build on their experience and
 knowledge.
 Read before usin...
Concept topics: examples

 Concept topics can focus on specific types of
 information:
  Technology
  User concerns
  Deci...
Sections and nested topics




                             68
Sections, topics, and headings

 DITA is structured
 Not like HTML or Word
 Cannot put headings where you want

 DITA requ...
Sections
 Use in Concept and Reference topics
 Can have more than one section
 Can’ nest sections
       t
 All following ...
Working with sections

 Use Tags On view to see section boundaries
 Make sure section encloses all following
 content elem...
Sections and subtopics

 To nest information, either:
  Nest topics within a DITA map
  Insert subtopics within the DITA t...
Workbook Exercise:
  Creating Topics




11/03/08               73




                            73
Reference topics

 Reference topics provide quick access to facts
 Info users need to complete their tasks
 Often read whe...
Reference topics: examples

 Documents the facts for categories such as:
     device support        settings
     APIs    ...
Task topics
 Task topics document procedures
 About 70% of topics are tasks
 Each task topic presents information in a str...
Task topics: Prerequisites

 DITA element: <prereq>
 Things that users need to know or do before
 starting the task steps
...
Task topics: Context

 DITA element: <context>
 Background information on the task
Typical task topic

 <steps> element provides numbered steps




                                           79
Sequence within a <step>
element
 <cmd> (required)
 Any number of the following:
  <info> (tables, images, paragraphs, not...
Example of <steps>




                     81
Steps: Example in a step

 DITA element: <stepxmp>
 Optional step element
 Illustrates the successful completion of the
 c...
Steps: Step result

 DITA element: <stepresult>
 Describes the result of the current step
 Optional step element
 Example:...
Steps: Substeps

 DITA elements: <substeps>, <substep>
 Subdivides a major step in a sequence.
 Output is the equivalent o...
Steps: Choices

 DITA elements: <choices>, <choice>
 Decisions within a major step in a sequence
 Output is the equivalent...
Steps: Choice tables

 DITA elements: <choicetable>, <chrow>,
 <choption>, <chdesc>
 Decisions within a major step in a se...
Steps: Choice table output
  Specify how to open new perspectives:

Option              Description
Click in the same   To...
Task with unordered steps

 Bullets instead of numbers
 <steps-unordered> element




                              88
Task topics: Results

 DITA element: <result>
 Illustrates the successful completion of the
 task
 Example:
 The device is...
Task topics: Example

        DITA element: <example>
        Illustrates a successful completion of the task
        step...
Task topics: Postrequisites

 DITA element: <postreq>
 Things that users need to know or do upon
 completing the task step...
Workbook Exercise:
  Task Topics




11/03/08               92




                            92
Cross-references and links




                             93
Types of links

 Inline links <xref>
  Cross-reference <xref href=quot;#targetquot;/>
  File reference <xref href=quot;fil...
Inserting links

 Insert > Link > ...
  Cross-reference
  File reference
  Web link
 All add <xref> elements

 Related lin...
Refreshing References

 To update content in cross-references:
  Click Edit > Refresh All References
  Close and reopen th...
Workbook Exercise:
  Cross-references and Links




11/03/08                  97




                               97
Metadata and index elements




                              98
Metadata in DITA

 Maintained in <prolog> element
 Examples: author, publisher, copyright
 information
 Metadata is usuall...
Indexing

 Use <indexterm>
 Can nest <indexterm> elements
 Cannot put in <title> elements

 Place <indexterm> where approp...
Creating index entries

 Click Insert > Index Marker
 Tip: Press Alt+Shift+X
 Use commas to create subentries




        ...
Editing index entries

       Braces ({ and }) are XMetaL
       Index entry:

       Nested index entry:


       Nested ...
Advanced indexing features

 DITA 1.1
 Page ranges
 See/See also
 Sort as




                             103
Workbook Exercise:
  Metadata and Index Elements




11/03/08                 104




                                104
Track changes




                105
Track changes

 Purpose:
  Communicate to reviewers about what’ new
                                       s
  Have review...
Using change tracking

 Turn on and off:
  Tools > Track Changes
 Accept/reject changes:
  Tools > Accept or Reject Change...
Workbook Exercise:
  Track Changes




11/03/08               108




                             108
DITA Maps




            109
DITA maps

     Organize DITA topics in a TOC-like structure
     References to DITA topics
     Analogous to a FrameMaker...
Topics and maps
 Topic
  Unit of information that is meaningful when it
  stands alone
 Map
  Organizes topics into a cohe...
Working with maps

 Map Editor displays maps in a
 GUI
 You can:
  Add and remove topics
  Change topic order
  Nest topic...
Insert a reference to an existing
topic
 Select the map entry under which you want to
 nest the topic
 Click Insert > Topi...
Tips for working with maps

 Plan where to put your map and topic files
  usually close to each other

 Remember file and ...
Insert and create a topic

       Select the topic
       above where you
       want the new topic
       Click Insert > ...
Insert a topic heading

 Click Insert > Topic
 Heading




                         116
Create a new map

 Click (small) File > New Map.

  or

 Click (big) File > New
  Then choose the DITA Map template




  ...
Insert a submap

 Both maps must exist
 Click (small) Insert >
 Map Reference




                          118
Specify map properties

 In the Map Editor, select the Properties button.
 In the Map Properties dialog, click the Special...
Workbook Exercise:
  Organizing Topics with Maps




11/03/08                 120




                                120
Switch to XML view

 Click (small) File >
 Switch to XML View
 of Map.




                        121
Switch to Map Editor

 Select File > Switch
 to Map Editor




                        122
Different views for different tasks
 Task                                         Map     XML
                            ...
Relationship tables

 Automatically generate “Related x” sections
 Special type of semantic table
  Columns define informa...
Map metadata

 Metadata in maps
  can fine-tune linking in relationship tables
  can be used instead of topic metadata
  i...
Relationship Tables: XML View




                                126
Create a relationship table

 Switch to XML view
 Insert the relationship table
 Add the <topicref> elements
 Generate the...
Insert a relationship table

 Click Table > Insert Relationship Table.
 Choose one of several common formats, then
 click ...
Attributes for managing links

In a <relcell> element:
   collection-type = “family”
    topicrefs in cell link to each ot...
Add topics
 Hold CTRL and drag
 Task topics from the
 navigation portion of
 the map into the
 relationship table. This
 c...
Workbook Exercise:
  Relationship Tables




11/03/08                131




                              131
Glossaries




             132
Glossaries

 Writing glossary content
 Assembling glossary content




                               133
Glossary content

 Basic markup:
   <glossentry>
      <glossterm></glossterm>
      <glossdef></glossdef>
   </glossentry...
Assembling glossary content

 Create a Bookmap file and point the
 <glossarylist> element to your glossary
 content files....
Publishing glossaries

 During “Generate Output”:
 All glossary content is pulled into the same
 glossary and is sorted al...
Reusing content




                  137
Content reuse: overview

 Reuse is about reducing duplication and
 delivering more customized content

 Two main approache...
Conditional text

 Single source file
 Content for multiple deliverables
 Markup identifies different subsets
 For example...
What does conditional text
markup look like?
 No conditional text markup:
                 <p>Press Ctrl+S.</p>


 Conditi...
Conditional text overview

        Configure XMetaL with conditions
        Typically: products, platforms, audiences

   ...
Make content conditional

 Select text or an element
 Click Reuse > Apply/Remove Conditions




                          ...
Assigning conditional attributes

 Windows only:
    <p platform=quot;windowsquot;>Press Ctrl+S.</p>


 Windows and Macint...
What content can you make
conditional?
 DITA allows a high degree of granularity
 Single words can be made conditional
 (B...
Elements that can be made
conditional:
 Yes:                   No:
  Text                   Individual table cells
  Image...
<ph> element

 If you make selected text conditional, XMetaL
 inserts <ph> tags so it can “hang” attributes on
 the <ph> e...
Style conditional text

 Styles help keep
 track of
 conditional text
 XMetaL only, not
 in deliverables
 Reuse > Style
 C...
Generate conditional output

 Choose what
 platforms, products,
 and audiences you
 want to include




                  ...
How DITA handles multiple
      condition types
      For an element marked as audience = “Europe”
        and platform = ...
Multiple condition types: the rule

 In this example: Content must be for both the
 right platform and the right audience ...
Planning to use conditional text

Determine your team's needs in terms of content
reuse:
   What product variations are si...
Configuring XMetaL conditions

    Edit ct_config.xml
<conditions>
    <attribute name=quot;audiencequot; title=quot;Audie...
Content references (conrefs)

 Standard DITA element attribute
 References another element of same type
 On output, conten...
Content references in XMetaL

Content shown in conref is:
  Read-only
  Updated when a document is opened

To manually ref...
Working with content references

 Open a document containing a content
 reference
 Right-click to switch between viewing l...
Reusable components

 Reusable components:
  Managed snippets of XML
  Have titles, short descriptions, and reusable-
  co...
Reuse strategies
      Reuse Opportunity                       Solution

 Multiple similar deliverables   Flag some conten...
Workbook Exercise:
  Reusing Content




11/03/08               158




                             158
Additional resources

 DITA Users group on Yahoo! groups:
 http://tech.groups.yahoo.com/group/dita-users/
 XMetaL-DITA gro...
Thanks!

 Last Questions?
 Drawing!

 sbate@scriptorium.com
Upcoming SlideShare
Loading in...5
×

XMetaL DITA Workshop

5,444

Published on

Slides from DocTrain East 2008 Workshop: Introduction to XMetaL and DITA.

Published in: Technology, Art & Photos
0 Comments
6 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
5,444
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
129
Comments
0
Likes
6
Embeds 0
No embeds

No notes for slide

XMetaL DITA Workshop

  1. 1. Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services
  2. 2. Course Agenda Overview of XMetaL Sections and nested Elements and topics structured authoring Cross-references Generating output Metadata and Attributes indexes Images Track changes Tables DITA maps Writing topics Reusing content
  3. 3. Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing
  4. 4. About DITA Darwin Information Typing Architecture Created at IBM Now developed and maintained by OASIS Standard XML language Cost-effective way to create, publish, reuse, and exchange structured content
  5. 5. Role of DITA Tools An authoring tool is a user interface for creating DITA content
  6. 6. DITA documentation DITA Language Reference Purpose and content model for each element Help > DITA Specifications > DITA Language Reference DITA Architectural Specification Describes overall behavior of DITA Very technical Help > DITA Specifications > DITA Architectural Specification
  7. 7. Overview of XMetaL
  8. 8. XMetaL Author Standard word-processing environment Multiple undo (and redo) Spell checking & thesaurus Change tracking Create and edit text Familiar editing features to create content
  9. 9. XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List
  10. 10. Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes
  11. 11. Typographical elements Bold Italic Underline
  12. 12. View modes Four view modes for the document pane: Normal Page Preview Tags On Plain Text Controls in bottom left corner of the pane: Indicate the current view Switch between views
  13. 13. Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content
  14. 14. Tags On view Shows content Shows XML element tags Indicated by this icon: Allows precise insertion Allows tag deletion/unwrapping Click box to expand/collapse: Tip: CTRL+SHIFT toggles Tags On & Normal
  15. 15. Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML
  16. 16. Page Preview view Shows a formatted preview Indicated by this icon: Verify the content is formatted correctly XML document transformed Opens in browser or Acrobat
  17. 17. Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View
  18. 18. Workbook Exercise: Basic File Operations
  19. 19. Options for saving and opening files Click Tools > Options To use default toolbars, press CTRL on startup
  20. 20. File and folder naming Be systematic and careful No spaces No special characters
  21. 21. Elements and Structured Authoring
  22. 22. Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute
  23. 23. Structure and validity XML must be: Well-formed Valid DITA content model defines validity How to order elements Hierarchy of element types Attributes
  24. 24. Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first
  25. 25. Structure and quot;Smart Insertquot; When pasting XMetaL content: XMetaL inserts content at closest valid location May be far from the insertion point May not be pasted at all When pasting Word or HTML content: XMetaL uses DITA elements Closest match to paste and location Best advice: watch when pasting
  26. 26. Identifying the current element See context bar (at bottom of screen) Also shows ancestors' hierarchy Based on: Cursor location Currently selected element Here's a <li> within a <ul> within a <section>…
  27. 27. Identifying the current element Be aware of what is selected
  28. 28. ENTER key XMetaL inserts the most logical next element Often the same type as the current one
  29. 29. Insert menu Allows you to insert elements Shows most available elements Context free “Smart Insert” Inserts an element in the next valid location Sometimes asks if you want to split the current element – usually this is what you want
  30. 30. Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected
  31. 31. Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering
  32. 32. Format markup vs. Semantic markup Separation of content from formatting Format markup: how something should look Semantic markup: what something means Examples: <b> vs. <uicontrol> <li> vs. <step>
  33. 33. Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
  34. 34. Domains in Element List Domain elements are listed in Element List Tools > DITA Options Only affects the Element List Not the Insert menu
  35. 35. Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements
  36. 36. Deleting elements Easiest on Tags On view To quot;unwrapquot; an element (leave content): Click just after the start tag, then press Backspace To delete the element and content: Click a tag to select the entire element, then press Delete or Backspace
  37. 37. Workbook Exercise: Working with Elements
  38. 38. Generating Output (Publishing)
  39. 39. DITA Open Toolkit Open-source application for publishing DITA content to multiple output formats Integrated with XMetaL Help > Third-Party Components > DITA Open Toolkit User Guide
  40. 40. Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp
  41. 41. PDF options XMetaL Enhanced PDF Best all-purpose PDF deliverable type XMetaL Enhanced PDF via Acrobat Distiller Use if your documents have EPS graphics
  42. 42. Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log
  43. 43. Workbook Exercise: Generating Output
  44. 44. Attributes
  45. 45. Purpose of attributes Provide additional information width = “250 px” Point to a file or URL href = “http://www.microsoft.com” href = “images/red_button.gif” Identify an element id = “p_73412763” Conditionalize an element platform = “macintosh”
  46. 46. Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important
  47. 47. Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector
  48. 48. Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes
  49. 49. Workbook Exercise: Attributes
  50. 50. Images
  51. 51. Supported image formats PNG, GIF, JPEG SVG (if an appropriate plug-in is installed) EPS displays in XMetaL if preview information is available in the file requires Acrobat Distiller to produce optimal PDF output TIF, other formats may not display in all output formats
  52. 52. Working with images Inserting images Insert > Image Insert an image with a title Insert > Figure with Title Add a title to an existing image Select Image and wrap in fig Insert > Other Element > Title Modify the properties of an existing image
  53. 53. Image sizing Do one of the following: Best-supported: Resize the image using a graphics editor Specify “width” in pixels, inches, cm, etc. Specify “height” Least-supported: Specify “scale” by a percentage
  54. 54. Workbook Exercise: Images
  55. 55. Tables
  56. 56. Tables Click Table > Insert Table Choose type: Normal table = table with title Simple table = informal table (no title) Step choices (task topics only) Properties (reference topics only) Specify rows and columns Specify header or not
  57. 57. Header rows To make the first row of a table a header row: Click Table > Insert Table Add later with Table > Table Properties
  58. 58. Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t
  59. 59. Workbook Exercise: Tables
  60. 60. Writing topics
  61. 61. Topics A Topic is a DITA unit of information Has a title, short description, and content All topics have the same basic structure and capabilities Long enough to make sense on its own Short enough to provide essential info
  62. 62. Topic types Main topic types: Generic Topic Concepts Tasks Reference DITA also includes: Composite or multiple topic type Glossary entry (DITA 1.1) Specialization
  63. 63. Topics: Determining the topics you need Identify a task to document. Identify the subtasks for the task. Identify the concepts you need to support the task and subtasks. Identify the supporting reference information.
  64. 64. XMetaL authoring templates Templates include commonly-needed elements to get started To delete empty elements, click between the tags, then press Backspace Blue-on-blue placeholder text is not shown in output
  65. 65. Common elements in topics Title Short description Briefly introduce the topic and provide a concise answer to the question “What is this?” Begin with a definition, and then expand upon it Contain the main point of the topic 1-3 sentences, no more than 50 words Body
  66. 66. Concept topics Concept topics explain and teach. Help users build on their experience and knowledge. Read before using the product or completing a task. Can contain paragraphs, lists, tables, sections, images, etc.
  67. 67. Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview
  68. 68. Sections and nested topics
  69. 69. Sections, topics, and headings DITA is structured Not like HTML or Word Cannot put headings where you want DITA requires more planning of your heading hierarchy
  70. 70. Sections Use in Concept and Reference topics Can have more than one section Can’ nest sections t All following paragraphs must be in section
  71. 71. Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements
  72. 72. Sections and subtopics To nest information, either: Nest topics within a DITA map Insert subtopics within the DITA topic DITA maps are far preferred Think about reusability
  73. 73. Workbook Exercise: Creating Topics
  74. 74. Reference topics Reference topics provide quick access to facts Info users need to complete their tasks Often read when the info is needed Little or no background or explanatory detail Links to other closely related reference topics Contents defined by your Style Guide Good use of specialization
  75. 75. Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on
  76. 76. Task topics Task topics document procedures About 70% of topics are tasks Each task topic presents information in a strict chronological sequence: Prerequisites Context Steps (required) Result Example Postrequisites
  77. 77. Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps
  78. 78. Task topics: Context DITA element: <context> Background information on the task
  79. 79. Typical task topic <steps> element provides numbered steps
  80. 80. Sequence within a <step> element <cmd> (required) Any number of the following: <info> (tables, images, paragraphs, notes) <substeps > (2a, 2b, 2c… ) <tutorialinfo> <stepxmp > <choicetable > <choices> <stepresult>
  81. 81. Example of <steps>
  82. 82. Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step
  83. 83. Steps: Step result DITA element: <stepresult> Describes the result of the current step Optional step element Example: When you depress the Lock button, all doors are locked automatically.
  84. 84. Steps: Substeps DITA elements: <substeps>, <substep> Subdivides a major step in a sequence. Output is the equivalent of a nested ordered list within an ordered list. Can use all the elements valid for <step>, except for <choices> and <choicetable>. Example: 3. Do the following: a. Browse for the file. b. Type the file name.
  85. 85. Steps: Choices DITA elements: <choices>, <choice> Decisions within a major step in a sequence Output is the equivalent of a nested unordered list within an ordered list. Can contain any general DITA elements Example: 4. Select one of the following options:  Import all files  Import selected files
  86. 86. Steps: Choice tables DITA elements: <choicetable>, <chrow>, <choption>, <chdesc> Decisions within a major step in a sequence Require a significant amount of information Where there are multiple options Output is the equivalent of a table Can contain any general DITA elements Example: type attribute for the <note> element
  87. 87. Steps: Choice table output Specify how to open new perspectives: Option Description Click in the same To open the perspective in the same window. window When you open the window, it replaces the currently open window. Click in a new To open the perspective in a new window. When window you open the window, it opens in a new window and the currently open window remains open.
  88. 88. Task with unordered steps Bullets instead of numbers <steps-unordered> element
  89. 89. Task topics: Results DITA element: <result> Illustrates the successful completion of the task Example: The device is fully configured and ready for use.
  90. 90. Task topics: Example DITA element: <example> Illustrates a successful completion of the task steps. <example> is a type of <section> element
  91. 91. Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps.
  92. 92. Workbook Exercise: Task Topics
  93. 93. Cross-references and links
  94. 94. Types of links Inline links <xref> Cross-reference <xref href=quot;#targetquot;/> File reference <xref href=quot;file.typquot;/> Web link <xref href=quot;http://...quot;/> Related links <related-links> Links generated by relationship tables
  95. 95. Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
  96. 96. Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document
  97. 97. Workbook Exercise: Cross-references and Links
  98. 98. Metadata and index elements
  99. 99. Metadata in DITA Maintained in <prolog> element Examples: author, publisher, copyright information Metadata is usually company-specific Click Insert > Topic Metadata This dialog can get you started, but best to create your own
  100. 100. Indexing Use <indexterm> Can nest <indexterm> elements Cannot put in <title> elements Place <indexterm> where appropriate DITA Open Toolkit will compile an index
  101. 101. Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries
  102. 102. Editing index entries Braces ({ and }) are XMetaL Index entry: Nested index entry: Nested entry produces: “Stylesheets, troubleshooting....37”
  103. 103. Advanced indexing features DITA 1.1 Page ranges See/See also Sort as
  104. 104. Workbook Exercise: Metadata and Index Elements
  105. 105. Track changes
  106. 106. Track changes Purpose: Communicate to reviewers about what’ new s Have reviewers communicate about what they want Help you manage your writing process XMetaL uses processing instructions to track changes
  107. 107. Using change tracking Turn on and off: Tools > Track Changes Accept/reject changes: Tools > Accept or Reject Changes Can also use: View > Toolbars [Reviewing] To change styles: Name: Tools > Options [General] Format: Tools > Options [Change Tracking]
  108. 108. Workbook Exercise: Track Changes
  109. 109. DITA Maps
  110. 110. DITA maps Organize DITA topics in a TOC-like structure References to DITA topics Analogous to a FrameMaker Book file Can also contain topic metadata
  111. 111. Topics and maps Topic Unit of information that is meaningful when it stands alone Map Organizes topics into a coherent set Typically for different deliverables or media Topics DITA Maps Deliverables
  112. 112. Working with maps Map Editor displays maps in a GUI You can: Add and remove topics Change topic order Nest topics Edit with drag and drop or toolbar buttons Change map properties
  113. 113. Insert a reference to an existing topic Select the map entry under which you want to nest the topic Click Insert > Topic Reference Browse for a topic
  114. 114. Tips for working with maps Plan where to put your map and topic files usually close to each other Remember file and folder naming rules: no spaces, no special characters Make sure you’ using files in the location re you think you’ using re
  115. 115. Insert and create a topic Select the topic above where you want the new topic Click Insert > Topic Reference
  116. 116. Insert a topic heading Click Insert > Topic Heading
  117. 117. Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template
  118. 118. Insert a submap Both maps must exist Click (small) Insert > Map Reference
  119. 119. Specify map properties In the Map Editor, select the Properties button. In the Map Properties dialog, click the Special Attributes tab Interesting attributes include: Navigation title Scope Include in TOC Print
  120. 120. Workbook Exercise: Organizing Topics with Maps
  121. 121. Switch to XML view Click (small) File > Switch to XML View of Map.
  122. 122. Switch to Map Editor Select File > Switch to Map Editor
  123. 123. Different views for different tasks Task Map XML editor View Create the table of contents, a.k.a. the  “hierarchical” part of the map Browse topics by double-clicking  Edit relationship tables  Use conditional text to make parts of the  map conditional Troubleshoot 
  124. 124. Relationship tables Automatically generate “Related x” sections Special type of semantic table Columns define information types Rows define relationships between topics Each <topicref> in a cell will link to the other topic references in that row Can control linking
  125. 125. Map metadata Metadata in maps can fine-tune linking in relationship tables can be used instead of topic metadata is inherited from parent elements
  126. 126. Relationship Tables: XML View
  127. 127. Create a relationship table Switch to XML view Insert the relationship table Add the <topicref> elements Generate the map Review the links Update the relationship table Generate and review Switch to Map Editor
  128. 128. Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK:
  129. 129. Attributes for managing links In a <relcell> element: collection-type = “family” topicrefs in cell link to each other linking = “targetonly” topicrefs can be targets, but cannot be links linking = “sourceonly” topicrefs can be links, but cannot be targets
  130. 130. Add topics Hold CTRL and drag Task topics from the navigation portion of the map into the relationship table. This copies the <topicref>. Think of the Concept and Reference topics that are related to each Task. Paste <topicref>s for those topics on the same row. Generate the map and open the file.
  131. 131. Workbook Exercise: Relationship Tables
  132. 132. Glossaries
  133. 133. Glossaries Writing glossary content Assembling glossary content
  134. 134. Glossary content Basic markup: <glossentry> <glossterm></glossterm> <glossdef></glossdef> </glossentry> One or more <glossentry> elements in a file Specialization of <concept> DITA 1.1
  135. 135. Assembling glossary content Create a Bookmap file and point the <glossarylist> element to your glossary content files. Add a <topicref> to your map file pointing to your Bookmap file.
  136. 136. Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically.
  137. 137. Reusing content
  138. 138. Content reuse: overview Reuse is about reducing duplication and delivering more customized content Two main approaches to reuse: Conditional text Modular reuse: reusing topics in different maps content references (conref)
  139. 139. Conditional text Single source file Content for multiple deliverables Markup identifies different subsets For example, Windows: quot;Press Ctrl+Squot; Macintosh: quot;Press Command+Squot;
  140. 140. What does conditional text markup look like? No conditional text markup: <p>Press Ctrl+S.</p> Conditional text markup: <p platform = quot;windowsquot;>Press Ctrl+S.</p> attribute attribute value
  141. 141. Conditional text overview Configure XMetaL with conditions Typically: products, platforms, audiences In XMetaL: Mark content as conditional Style conditional content Generate output specify conditional content
  142. 142. Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions
  143. 143. Assigning conditional attributes Windows only: <p platform=quot;windowsquot;>Press Ctrl+S.</p> Windows and Macintosh, but not Unix: <p platform=quot;windows macintoshquot;>Press Ctrl+S.</p> All platforms: <p>Press Ctrl+S.</p>
  144. 144. What content can you make conditional? DITA allows a high degree of granularity Single words can be made conditional (But consider practicality) Not limited to text, other types of content
  145. 145. Elements that can be made conditional: Yes: No: Text Individual table cells Images Table columns Cross-references Required elements Index markers Text within required elements is OK Tables Rows in tables Content within content references Topic references in DITA maps
  146. 146. <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.
  147. 147. Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text
  148. 148. Generate conditional output Choose what platforms, products, and audiences you want to include
  149. 149. How DITA handles multiple condition types For an element marked as audience = “Europe” and platform = “windows” In output for this Does the Notes audience and product: element appear? Europe No* The element is for the right audience. Macintosh The element is not for the right platform. North America No* The element is not for the right audience. Windows The element is for the right platform. Europe Yes The element is for the right audience. Windows and The element is for one of the right platforms. Macintosh *Would appear if you used native FrameMaker® 7.x conditions instead of DITA
  150. 150. 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 attribute mentioned in Show/Hide Conditional Text: It doesn't have any values for that attribute, i.e. it is quot;common to allquot; OR it matches at least one value that should be included.
  151. 151. Planning to use conditional text Determine your team's needs in terms of content reuse: 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? Would it make sense to achieve reuse through conditional text, through content modularization, or both?
  152. 152. Configuring XMetaL conditions Edit ct_config.xml <conditions> <attribute name=quot;audiencequot; title=quot;Audiencequot;> <value name=quot;studentquot; title=quot;Studentquot; /> <value name=quot;teacherquot; title=quot;Trainerquot; /> <value name=“self-studyquot; title=“Self-Studyquot; /> </attribute> <attribute name=quot;platformquot; title=quot;Platformquot;> <value name=quot;windowsxpquot; title=quot;Windows XP“ /> <value name=quot;windows2000quot; title=quot;Windows 2000 /> <value name=quot;linuxquot; title=quot;Linuxquot; /> <value name=quot;macosxquot; title=quot;MacOSX“ /> </attribute> </conditions>
  153. 153. Content references (conrefs) Standard DITA element attribute References another element of same type On output, content from referenced element substituted for the conref element Similar to FrameMaker “text insets” Analogous to referencing an image file
  154. 154. Content references in XMetaL Content shown in conref is: Read-only Updated when a document is opened To manually refresh: Click Edit > Refresh All References Or press F11
  155. 155. Working with content references Open a document containing a content reference Right-click to switch between viewing local content and referenced content Local content is highlighted in yellow
  156. 156. Reusable components Reusable components: Managed snippets of XML Have titles, short descriptions, and reusable- content. One reusable component per file Click Reuse > Create Reusable Component XMetaL only; not transportable
  157. 157. Reuse strategies Reuse Opportunity Solution Multiple similar deliverables Flag some content as conditional Include it in different topics using Piece of content used in many content references different contexts (Modular reuse) Include it in different deliverables Topic used in many different through DITA maps deliverables (Modular reuse)
  158. 158. Workbook Exercise: Reusing Content
  159. 159. Additional resources DITA Users group on Yahoo! groups: http://tech.groups.yahoo.com/group/dita-users/ XMetaL-DITA group on Yahoo! groups: http://tech.groups.yahoo.com/group/xmetal-dita/ dita.xml.org www.justsystems.com (webinars, events)
  160. 160. Thanks! Last Questions? Drawing! sbate@scriptorium.com
  161. 161. Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services 1
  162. 162. Course Agenda Overview of XMetaL Sections and nested Elements and topics structured authoring Cross-references Generating output Metadata and Attributes indexes Images Track changes Tables DITA maps Writing topics Reusing content 2
  163. 163. Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing 3
  164. 164. About DITA Darwin Information Typing Architecture Created at IBM Now developed and maintained by OASIS Standard XML language Cost-effective way to create, publish, reuse, and exchange structured content 4
  165. 165. Role of DITA Tools An authoring tool is a user interface for creating DITA content 5
  166. 166. DITA documentation DITA Language Reference Purpose and content model for each element Help > DITA Specifications > DITA Language Reference DITA Architectural Specification Describes overall behavior of DITA Very technical Help > DITA Specifications > DITA Architectural Specification 6
  167. 167. Overview of XMetaL 7
  168. 168. XMetaL Author Standard word-processing environment Multiple undo (and redo) Spell checking & thesaurus Change tracking Create and edit text Familiar editing features to create content 8
  169. 169. XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List 9
  170. 170. Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes 10
  171. 171. Typographical elements Bold Italic Underline 11
  172. 172. View modes Four view modes for the document pane: Normal Page Preview Tags On Plain Text Controls in bottom left corner of the pane: Indicate the current view Switch between views 12
  173. 173. Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content 13
  174. 174. Tags On view Shows content Shows XML element tags Indicated by this icon: Allows precise insertion Allows tag deletion/unwrapping Click box to expand/collapse: Tip: CTRL+SHIFT toggles Tags On & Normal 14
  175. 175. Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML 15
  176. 176. Page Preview view Shows a formatted preview Indicated by this icon: Verify the content is formatted correctly XML document transformed Opens in browser or Acrobat 16
  177. 177. Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View 17
  178. 178. Workbook Exercise: Basic File Operations 11/03/08 18 18
  179. 179. Options for saving and opening files Click Tools > Options To use default toolbars, press CTRL on startup For training, it is useful to turn this option off because having too many files open confuses people 19
  180. 180. File and folder naming Be systematic and careful No spaces No special characters 20
  181. 181. Elements and Structured Authoring 21
  182. 182. Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute 22
  183. 183. Structure and validity XML must be: Well-formed Valid DITA content model defines validity How to order elements Hierarchy of element types Attributes 23
  184. 184. Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first 24
  185. 185. Structure and quot;Smart Insertquot; When pasting XMetaL content: XMetaL inserts content at closest valid location May be far from the insertion point May not be pasted at all When pasting Word or HTML content: XMetaL uses DITA elements Closest match to paste and location Best advice: watch when pasting 25
  186. 186. Identifying the current element See context bar (at bottom of screen) Also shows ancestors' hierarchy Based on: Cursor location Currently selected element Here's a <li> within a <ul> within a <section>… 26
  187. 187. Identifying the current element Be aware of what is selected 27
  188. 188. ENTER key XMetaL inserts the most logical next element Often the same type as the current one 28
  189. 189. Insert menu Allows you to insert elements Shows most available elements Context free “Smart Insert” Inserts an element in the next valid location Sometimes asks if you want to split the current element – usually this is what you want 29
  190. 190. Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected 30
  191. 191. Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering 31
  192. 192. Format markup vs. Semantic markup Separation of content from formatting Format markup: how something should look Semantic markup: what something means Examples: <b> vs. <uicontrol> <li> vs. <step> 32
  193. 193. Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
  194. 194. Domains in Element List Domain elements are listed in Element List Tools > DITA Options Only affects the Element List Not the Insert menu 34
  195. 195. Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements 35
  196. 196. Deleting elements Easiest on Tags On view To quot;unwrapquot; an element (leave content): Click just after the start tag, then press Backspace To delete the element and content: Click a tag to select the entire element, then press Delete or Backspace 36
  197. 197. Workbook Exercise: Working with Elements 11/03/08 37 37
  198. 198. Generating Output (Publishing) 38
  199. 199. DITA Open Toolkit Open-source application for publishing DITA content to multiple output formats Integrated with XMetaL Help > Third-Party Components > DITA Open Toolkit User Guide 39
  200. 200. Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp 40
  201. 201. PDF options XMetaL Enhanced PDF Best all-purpose PDF deliverable type XMetaL Enhanced PDF via Acrobat Distiller Use if your documents have EPS graphics 41
  202. 202. Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log 42
  203. 203. Workbook Exercise: Generating Output 11/03/08 43 43
  204. 204. Attributes 44
  205. 205. Purpose of attributes Provide additional information width = “250 px” Point to a file or URL href = “http://www.microsoft.com” href = “images/red_button.gif” Identify an element id = “p_73412763” Conditionalize an element platform = “macintosh” 45
  206. 206. Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important 46
  207. 207. Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector 47
  208. 208. Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes 48
  209. 209. Workbook Exercise: Attributes 11/03/08 49 49
  210. 210. Images 50
  211. 211. Supported image formats PNG, GIF, JPEG SVG (if an appropriate plug-in is installed) EPS displays in XMetaL if preview information is available in the file requires Acrobat Distiller to produce optimal PDF output TIF, other formats may not display in all output formats 51
  212. 212. Working with images Inserting images Insert > Image Insert an image with a title Insert > Figure with Title Add a title to an existing image Select Image and wrap in fig Insert > Other Element > Title Modify the properties of an existing image 52
  213. 213. Image sizing Do one of the following: Best-supported: Resize the image using a graphics editor Specify “width” in pixels, inches, cm, etc. Specify “height” Least-supported: Specify “scale” by a percentage 53
  214. 214. Workbook Exercise: Images 11/03/08 54 54
  215. 215. Tables 55
  216. 216. Tables Click Table > Insert Table Choose type: Normal table = table with title Simple table = informal table (no title) Step choices (task topics only) Properties (reference topics only) Specify rows and columns Specify header or not 56
  217. 217. Header rows To make the first row of a table a header row: Click Table > Insert Table Add later with Table > Table Properties 57
  218. 218. Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t 58
  219. 219. Workbook Exercise: Tables 11/03/08 59 59
  220. 220. Writing topics 60
  221. 221. Topics A Topic is a DITA unit of information Has a title, short description, and content All topics have the same basic structure and capabilities Long enough to make sense on its own Short enough to provide essential info 61
  222. 222. Topic types Main topic types: Generic Topic Concepts Tasks Reference DITA also includes: Composite or multiple topic type Glossary entry (DITA 1.1) Specialization 62
  223. 223. Topics: Determining the topics you need Identify a task to document. Identify the subtasks for the task. Identify the concepts you need to support the task and subtasks. Identify the supporting reference information. 63
  224. 224. XMetaL authoring templates Templates include commonly-needed elements to get started To delete empty elements, click between the tags, then press Backspace Blue-on-blue placeholder text is not shown in output 64
  225. 225. Common elements in topics Title Short description Briefly introduce the topic and provide a concise answer to the question “What is this?” Begin with a definition, and then expand upon it Contain the main point of the topic 1-3 sentences, no more than 50 words Body 65
  226. 226. Concept topics Concept topics explain and teach. Help users build on their experience and knowledge. Read before using the product or completing a task. Can contain paragraphs, lists, tables, sections, images, etc. 66
  227. 227. Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview 67
  228. 228. Sections and nested topics 68
  229. 229. Sections, topics, and headings DITA is structured Not like HTML or Word Cannot put headings where you want DITA requires more planning of your heading hierarchy 69
  230. 230. Sections Use in Concept and Reference topics Can have more than one section Can’ nest sections t All following paragraphs must be in section 70
  231. 231. Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements 71
  232. 232. Sections and subtopics To nest information, either: Nest topics within a DITA map Insert subtopics within the DITA topic DITA maps are far preferred Think about reusability 72
  233. 233. Workbook Exercise: Creating Topics 11/03/08 73 73
  234. 234. Reference topics Reference topics provide quick access to facts Info users need to complete their tasks Often read when the info is needed Little or no background or explanatory detail Links to other closely related reference topics Contents defined by your Style Guide Good use of specialization 74
  235. 235. Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on 75
  236. 236. Task topics Task topics document procedures About 70% of topics are tasks Each task topic presents information in a strict chronological sequence: Prerequisites Context Steps (required) Result Example Postrequisites 76
  237. 237. Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps 77
  238. 238. Task topics: Context DITA element: <context> Background information on the task
  239. 239. Typical task topic <steps> element provides numbered steps 79
  240. 240. Sequence within a <step> element <cmd> (required) Any number of the following: <info> (tables, images, paragraphs, notes) <substeps > (2a, 2b, 2c… ) <tutorialinfo> <stepxmp > <choicetable > <choices> <stepresult> 80
  241. 241. Example of <steps> 81
  242. 242. Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step 82
  243. 243. Steps: Step result DITA element: <stepresult> Describes the result of the current step Optional step element Example: When you depress the Lock button, all doors are locked automatically. 83
  244. 244. Steps: Substeps DITA elements: <substeps>, <substep> Subdivides a major step in a sequence. Output is the equivalent of a nested ordered list within an ordered list. Can use all the elements valid for <step>, except for <choices> and <choicetable>. Example: 3. Do the following: a. Browse for the file. b. Type the file name. 84
  245. 245. Steps: Choices DITA elements: <choices>, <choice> Decisions within a major step in a sequence Output is the equivalent of a nested unordered list within an ordered list. Can contain any general DITA elements Example: 4. Select one of the following options:  Import all files  Import selected files 85
  246. 246. Steps: Choice tables DITA elements: <choicetable>, <chrow>, <choption>, <chdesc> Decisions within a major step in a sequence Require a significant amount of information Where there are multiple options Output is the equivalent of a table Can contain any general DITA elements Example: type attribute for the <note> element 86
  247. 247. Steps: Choice table output Specify how to open new perspectives: Option Description Click in the same To open the perspective in the same window. window When you open the window, it replaces the currently open window. Click in a new To open the perspective in a new window. When window you open the window, it opens in a new window and the currently open window remains open. 87
  248. 248. Task with unordered steps Bullets instead of numbers <steps-unordered> element 88
  249. 249. Task topics: Results DITA element: <result> Illustrates the successful completion of the task Example: The device is fully configured and ready for use. 89
  250. 250. Task topics: Example DITA element: <example> Illustrates a successful completion of the task steps. <example> is a type of <section> element Haven't introduced <section> yet. 90
  251. 251. Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps. 91
  252. 252. Workbook Exercise: Task Topics 11/03/08 92 92
  253. 253. Cross-references and links 93
  254. 254. Types of links Inline links <xref> Cross-reference <xref href=quot;#targetquot;/> File reference <xref href=quot;file.typquot;/> Web link <xref href=quot;http://...quot;/> Related links <related-links> Links generated by relationship tables 94
  255. 255. Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
  256. 256. Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document 96
  257. 257. Workbook Exercise: Cross-references and Links 11/03/08 97 97
  258. 258. Metadata and index elements 98
  259. 259. Metadata in DITA Maintained in <prolog> element Examples: author, publisher, copyright information Metadata is usually company-specific Click Insert > Topic Metadata This dialog can get you started, but best to create your own 99
  260. 260. Indexing Use <indexterm> Can nest <indexterm> elements Cannot put in <title> elements Place <indexterm> where appropriate DITA Open Toolkit will compile an index 100
  261. 261. Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries 101
  262. 262. Editing index entries Braces ({ and }) are XMetaL Index entry: Nested index entry: Nested entry produces: “Stylesheets, troubleshooting....37” Explain how to correct a misspelling in an index entry 102
  263. 263. Advanced indexing features DITA 1.1 Page ranges See/See also Sort as 103
  264. 264. Workbook Exercise: Metadata and Index Elements 11/03/08 104 104
  265. 265. Track changes 105
  266. 266. Track changes Purpose: Communicate to reviewers about what’ new s Have reviewers communicate about what they want Help you manage your writing process XMetaL uses processing instructions to track changes 106
  267. 267. Using change tracking Turn on and off: Tools > Track Changes Accept/reject changes: Tools > Accept or Reject Changes Can also use: View > Toolbars [Reviewing] To change styles: Name: Tools > Options [General] Format: Tools > Options [Change Tracking] 107
  268. 268. Workbook Exercise: Track Changes 11/03/08 108 108
  269. 269. DITA Maps 109
  270. 270. DITA maps Organize DITA topics in a TOC-like structure References to DITA topics Analogous to a FrameMaker Book file Can also contain topic metadata Can have multiple maps for multiple deliverables. EG: data sheet vs concepts guide 110
  271. 271. Topics and maps Topic Unit of information that is meaningful when it stands alone Map Organizes topics into a coherent set Typically for different deliverables or media Topics DITA Maps Deliverables 111
  272. 272. Working with maps Map Editor displays maps in a GUI You can: Add and remove topics Change topic order Nest topics Edit with drag and drop or toolbar buttons Change map properties 112
  273. 273. Insert a reference to an existing topic Select the map entry under which you want to nest the topic Click Insert > Topic Reference Browse for a topic 113
  274. 274. Tips for working with maps Plan where to put your map and topic files usually close to each other Remember file and folder naming rules: no spaces, no special characters Make sure you’ using files in the location re you think you’ using re 114
  275. 275. Insert and create a topic Select the topic above where you want the new topic Click Insert > Topic Reference Break and re-form a link in a map, by changing the file name for a referenced topic. See how the topic title changes to italics. 115
  276. 276. Insert a topic heading Click Insert > Topic Heading 116
  277. 277. Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template 117
  278. 278. Insert a submap Both maps must exist Click (small) Insert > Map Reference 118
  279. 279. Specify map properties In the Map Editor, select the Properties button. In the Map Properties dialog, click the Special Attributes tab Interesting attributes include: Navigation title Scope Include in TOC Print 119
  280. 280. Workbook Exercise: Organizing Topics with Maps 11/03/08 120 120
  281. 281. Switch to XML view Click (small) File > Switch to XML View of Map. 121
  282. 282. Switch to Map Editor Select File > Switch to Map Editor 122
  283. 283. Different views for different tasks Task Map XML editor View Create the table of contents, a.k.a. the  “hierarchical” part of the map Browse topics by double-clicking  Edit relationship tables  Use conditional text to make parts of the  map conditional Troubleshoot  123
  284. 284. Relationship tables Automatically generate “Related x” sections Special type of semantic table Columns define information types Rows define relationships between topics Each <topicref> in a cell will link to the other topic references in that row Can control linking 124
  285. 285. Map metadata Metadata in maps can fine-tune linking in relationship tables can be used instead of topic metadata is inherited from parent elements 125
  286. 286. Relationship Tables: XML View 126
  287. 287. Create a relationship table Switch to XML view Insert the relationship table Add the <topicref> elements Generate the map Review the links Update the relationship table Generate and review Switch to Map Editor 127
  288. 288. Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK: 128
  289. 289. Attributes for managing links In a <relcell> element: collection-type = “family” topicrefs in cell link to each other linking = “targetonly” topicrefs can be targets, but cannot be links linking = “sourceonly” topicrefs can be links, but cannot be targets 129
  290. 290. Add topics Hold CTRL and drag Task topics from the navigation portion of the map into the relationship table. This copies the <topicref>. Think of the Concept and Reference topics that are related to each Task. Paste <topicref>s for those topics on the same row. Generate the map and open the file. 130
  291. 291. Workbook Exercise: Relationship Tables 11/03/08 131 131
  292. 292. Glossaries 132
  293. 293. Glossaries Writing glossary content Assembling glossary content 133
  294. 294. Glossary content Basic markup: <glossentry> <glossterm></glossterm> <glossdef></glossdef> </glossentry> One or more <glossentry> elements in a file Specialization of <concept> DITA 1.1 134
  295. 295. Assembling glossary content Create a Bookmap file and point the <glossarylist> element to your glossary content files. Add a <topicref> to your map file pointing to your Bookmap file. 135
  296. 296. Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically. 136
  297. 297. Reusing content 137
  298. 298. Content reuse: overview Reuse is about reducing duplication and delivering more customized content Two main approaches to reuse: Conditional text Modular reuse: reusing topics in different maps content references (conref) 138
  299. 299. Conditional text Single source file Content for multiple deliverables Markup identifies different subsets For example, Windows: quot;Press Ctrl+Squot; Macintosh: quot;Press Command+Squot; 139
  300. 300. What does conditional text markup look like? No conditional text markup: <p>Press Ctrl+S.</p> Conditional text markup: <p platform = quot;windowsquot;>Press Ctrl+S.</p> attribute attribute value
  301. 301. Conditional text overview Configure XMetaL with conditions Typically: products, platforms, audiences In XMetaL: Mark content as conditional Style conditional content Generate output specify conditional content ..XMetaLAuthorConditional Textconfigsct_config.xml. 141
  302. 302. Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions 142
  303. 303. Assigning conditional attributes Windows only: <p platform=quot;windowsquot;>Press Ctrl+S.</p> Windows and Macintosh, but not Unix: <p platform=quot;windows macintoshquot;>Press Ctrl+S.</p> All platforms: <p>Press Ctrl+S.</p> 143
  304. 304. What content can you make conditional? DITA allows a high degree of granularity Single words can be made conditional (But consider practicality) Not limited to text, other types of content 144
  305. 305. Elements that can be made conditional: Yes: No: Text Individual table cells Images Table columns Cross-references Required elements Index markers Text within required elements is OK Tables Rows in tables Content within content references Topic references in DITA maps 145
  306. 306. <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element. 146
  307. 307. Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text 147
  308. 308. Generate conditional output Choose what platforms, products, and audiences you want to include 148
  309. 309. How DITA handles multiple condition types For an element marked as audience = “Europe” and platform = “windows” In output for this Does the Notes audience and product: element appear? Europe No* The element is for the right audience. Macintosh The element is not for the right platform. North America No* The element is not for the right audience. Windows The element is for the right platform. Europe Yes The element is for the right audience. Windows and The element is for one of the right platforms. Macintosh *Would appear if you used native FrameMaker® 7.x conditions instead of DITA FM conditions were linked with Boolean OR. Now conditional expressions in FM 8.0 help (a bit). XMetaL conditions linked with Boolean AND. 149
  310. 310. 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 attribute mentioned in Show/Hide Conditional Text: It doesn't have any values for that attribute, i.e. it is quot;common to allquot; OR it matches at least one value that should be included. 150
  311. 311. Planning to use conditional text Determine your team's needs in terms of content reuse: 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? Would it make sense to achieve reuse through conditional text, through content modularization, or both? 151
  312. 312. Configuring XMetaL conditions Edit ct_config.xml <conditions> <attribute name=quot;audiencequot; title=quot;Audiencequot;> <value name=quot;studentquot; title=quot;Studentquot; /> <value name=quot;teacherquot; title=quot;Trainerquot; /> <value name=“self-studyquot; title=“Self-Studyquot; /> </attribute> <attribute name=quot;platformquot; title=quot;Platformquot;> <value name=quot;windowsxpquot; title=quot;Windows XP“ /> <value name=quot;windows2000quot; title=quot;Windows 2000 /> <value name=quot;linuxquot; title=quot;Linuxquot; /> <value name=quot;macosxquot; title=quot;MacOSX“ /> </attribute> </conditions> 152
  313. 313. Content references (conrefs) Standard DITA element attribute References another element of same type On output, content from referenced element substituted for the conref element Similar to FrameMaker “text insets” Analogous to referencing an image file 153
  314. 314. Content references in XMetaL Content shown in conref is: Read-only Updated when a document is opened To manually refresh: Click Edit > Refresh All References Or press F11 154
  315. 315. Working with content references Open a document containing a content reference Right-click to switch between viewing local content and referenced content Local content is highlighted in yellow 155
  316. 316. Reusable components Reusable components: Managed snippets of XML Have titles, short descriptions, and reusable- content. One reusable component per file Click Reuse > Create Reusable Component XMetaL only; not transportable 156
  317. 317. Reuse strategies Reuse Opportunity Solution Multiple similar deliverables Flag some content as conditional Include it in different topics using Piece of content used in many content references different contexts (Modular reuse) Include it in different deliverables Topic used in many different through DITA maps deliverables (Modular reuse) 157
  318. 318. Workbook Exercise: Reusing Content 11/03/08 158 158
  319. 319. Additional resources DITA Users group on Yahoo! groups: http://tech.groups.yahoo.com/group/dita-users/ XMetaL-DITA group on Yahoo! groups: http://tech.groups.yahoo.com/group/xmetal-dita/ dita.xml.org www.justsystems.com (webinars, events) 159
  320. 320. Thanks! Last Questions? Drawing! sbate@scriptorium.com
  1. A particular slide catching your eye?

    Clipping is a handy way to collect important slides you want to go back to later.

×