XMetaL DITA Workshop

6,681 views
6,463 views

Published on

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

Published in: Technology, Art & Photos

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

×