XMetaL DITA Workshop

Loading...

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

0 comments

Post a comment

    Post a comment
    Embed Video
    Edit your comment Cancel

    2 Favorites

    XMetaL DITA Workshop - Presentation Transcript

    1. Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services
    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. Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing
    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. Role of DITA Tools An authoring tool is a user interface for creating DITA content
    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. Overview of XMetaL
    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. XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List
    10. Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes
    11. Typographical elements Bold Italic Underline
    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. Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content
    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. Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML
    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. Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View
    18. Workbook Exercise: Basic File Operations
    19. Options for saving and opening files Click Tools > Options To use default toolbars, press CTRL on startup
    20. File and folder naming Be systematic and careful No spaces No special characters
    21. Elements and Structured Authoring
    22. Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute
    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. Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first
    25. Structure and \"Smart Insert\" 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. 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. Identifying the current element Be aware of what is selected
    28. ENTER key XMetaL inserts the most logical next element Often the same type as the current one
    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. Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected
    31. Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering
    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. Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
    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. Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements
    36. Deleting elements Easiest on Tags On view To \"unwrap\" 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. Workbook Exercise: Working with Elements
    38. Generating Output (Publishing)
    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. Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp
    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. Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log
    43. Workbook Exercise: Generating Output
    44. Attributes
    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. Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important
    47. Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector
    48. Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes
    49. Workbook Exercise: Attributes
    50. Images
    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. 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. 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. Workbook Exercise: Images
    55. Tables
    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. Header rows To make the first row of a table a header row: Click Table > Insert Table Add later with Table > Table Properties
    58. Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t
    59. Workbook Exercise: Tables
    60. Writing topics
    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. 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. 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. 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. 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. 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. Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview
    68. Sections and nested topics
    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. 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. Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements
    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. Workbook Exercise: Creating Topics
    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. Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on
    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. Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps
    78. Task topics: Context DITA element: <context> Background information on the task
    79. Typical task topic <steps> element provides numbered steps
    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. Example of <steps>
    82. Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step
    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. 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. 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. 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. 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. Task with unordered steps Bullets instead of numbers <steps-unordered> element
    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. Task topics: Example DITA element: <example> Illustrates a successful completion of the task steps. <example> is a type of <section> element
    91. Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps.
    92. Workbook Exercise: Task Topics
    93. Cross-references and links
    94. Types of links Inline links <xref> Cross-reference <xref href=\"#target\"/> File reference <xref href=\"file.typ\"/> Web link <xref href=\"http://...\"/> Related links <related-links> Links generated by relationship tables
    95. Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
    96. Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document
    97. Workbook Exercise: Cross-references and Links
    98. Metadata and index elements
    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. Indexing Use <indexterm> Can nest <indexterm> elements Cannot put in <title> elements Place <indexterm> where appropriate DITA Open Toolkit will compile an index
    101. Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries
    102. Editing index entries Braces ({ and }) are XMetaL Index entry: Nested index entry: Nested entry produces: “Stylesheets, troubleshooting....37”
    103. Advanced indexing features DITA 1.1 Page ranges See/See also Sort as
    104. Workbook Exercise: Metadata and Index Elements
    105. Track changes
    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. 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. Workbook Exercise: Track Changes
    109. DITA Maps
    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. 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. 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. 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. 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. Insert and create a topic Select the topic above where you want the new topic Click Insert > Topic Reference
    116. Insert a topic heading Click Insert > Topic Heading
    117. Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template
    118. Insert a submap Both maps must exist Click (small) Insert > Map Reference
    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. Workbook Exercise: Organizing Topics with Maps
    121. Switch to XML view Click (small) File > Switch to XML View of Map.
    122. Switch to Map Editor Select File > Switch to Map Editor
    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. 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. 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. Relationship Tables: XML View
    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. Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK:
    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. 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. Workbook Exercise: Relationship Tables
    132. Glossaries
    133. Glossaries Writing glossary content Assembling glossary content
    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. 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. Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically.
    137. Reusing content
    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. Conditional text Single source file Content for multiple deliverables Markup identifies different subsets For example, Windows: \"Press Ctrl+S\" Macintosh: \"Press Command+S\"
    140. What does conditional text markup look like? No conditional text markup: <p>Press Ctrl+S.</p> Conditional text markup: <p platform = \"windows\">Press Ctrl+S.</p> attribute attribute value
    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. Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions
    143. Assigning conditional attributes Windows only: <p platform=\"windows\">Press Ctrl+S.</p> Windows and Macintosh, but not Unix: <p platform=\"windows macintosh\">Press Ctrl+S.</p> All platforms: <p>Press Ctrl+S.</p>
    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. 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. <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.
    147. Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text
    148. Generate conditional output Choose what platforms, products, and audiences you want to include
    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. 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 \"common to all\" OR it matches at least one value that should be included.
    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. Configuring XMetaL conditions Edit ct_config.xml <conditions> <attribute name=\"audience\" title=\"Audience\"> <value name=\"student\" title=\"Student\" /> <value name=\"teacher\" title=\"Trainer\" /> <value name=“self-study\" title=“Self-Study\" /> </attribute> <attribute name=\"platform\" title=\"Platform\"> <value name=\"windowsxp\" title=\"Windows XP“ /> <value name=\"windows2000\" title=\"Windows 2000 /> <value name=\"linux\" title=\"Linux\" /> <value name=\"macosx\" title=\"MacOSX“ /> </attribute> </conditions>
    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. 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. 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. 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. 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. Workbook Exercise: Reusing Content
    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. Thanks! Last Questions? Drawing! sbate@scriptorium.com
    161. Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services 1
    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. Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing 3
    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. Role of DITA Tools An authoring tool is a user interface for creating DITA content 5
    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. Overview of XMetaL 7
    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. XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List 9
    170. Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes 10
    171. Typographical elements Bold Italic Underline 11
    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. Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content 13
    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. Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML 15
    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. Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View 17
    178. Workbook Exercise: Basic File Operations 11/03/08 18 18
    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. File and folder naming Be systematic and careful No spaces No special characters 20
    181. Elements and Structured Authoring 21
    182. Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute 22
    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. Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first 24
    185. Structure and \"Smart Insert\" 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. 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. Identifying the current element Be aware of what is selected 27
    188. ENTER key XMetaL inserts the most logical next element Often the same type as the current one 28
    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. Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected 30
    191. Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering 31
    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. Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
    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. Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements 35
    196. Deleting elements Easiest on Tags On view To \"unwrap\" 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. Workbook Exercise: Working with Elements 11/03/08 37 37
    198. Generating Output (Publishing) 38
    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. Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp 40
    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. Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log 42
    203. Workbook Exercise: Generating Output 11/03/08 43 43
    204. Attributes 44
    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. Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important 46
    207. Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector 47
    208. Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes 48
    209. Workbook Exercise: Attributes 11/03/08 49 49
    210. Images 50
    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. 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. 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. Workbook Exercise: Images 11/03/08 54 54
    215. Tables 55
    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. 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. Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t 58
    219. Workbook Exercise: Tables 11/03/08 59 59
    220. Writing topics 60
    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. 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. 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. 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. 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. 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. Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview 67
    228. Sections and nested topics 68
    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. 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. Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements 71
    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. Workbook Exercise: Creating Topics 11/03/08 73 73
    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. Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on 75
    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. Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps 77
    238. Task topics: Context DITA element: <context> Background information on the task
    239. Typical task topic <steps> element provides numbered steps 79
    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. Example of <steps> 81
    242. Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step 82
    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. 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. 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. 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. 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. Task with unordered steps Bullets instead of numbers <steps-unordered> element 88
    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. 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. Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps. 91
    252. Workbook Exercise: Task Topics 11/03/08 92 92
    253. Cross-references and links 93
    254. Types of links Inline links <xref> Cross-reference <xref href=\"#target\"/> File reference <xref href=\"file.typ\"/> Web link <xref href=\"http://...\"/> Related links <related-links> Links generated by relationship tables 94
    255. Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
    256. Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document 96
    257. Workbook Exercise: Cross-references and Links 11/03/08 97 97
    258. Metadata and index elements 98
    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. 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. Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries 101
    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. Advanced indexing features DITA 1.1 Page ranges See/See also Sort as 103
    264. Workbook Exercise: Metadata and Index Elements 11/03/08 104 104
    265. Track changes 105
    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. 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. Workbook Exercise: Track Changes 11/03/08 108 108
    269. DITA Maps 109
    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. 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. 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. 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. 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. 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. Insert a topic heading Click Insert > Topic Heading 116
    277. Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template 117
    278. Insert a submap Both maps must exist Click (small) Insert > Map Reference 118
    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. Workbook Exercise: Organizing Topics with Maps 11/03/08 120 120
    281. Switch to XML view Click (small) File > Switch to XML View of Map. 121
    282. Switch to Map Editor Select File > Switch to Map Editor 122
    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. 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. 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. Relationship Tables: XML View 126
    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. Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK: 128
    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. 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. Workbook Exercise: Relationship Tables 11/03/08 131 131
    292. Glossaries 132
    293. Glossaries Writing glossary content Assembling glossary content 133
    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. 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. Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically. 136
    297. Reusing content 137
    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. Conditional text Single source file Content for multiple deliverables Markup identifies different subsets For example, Windows: \"Press Ctrl+S\" Macintosh: \"Press Command+S\" 139
    300. What does conditional text markup look like? No conditional text markup: <p>Press Ctrl+S.</p> Conditional text markup: <p platform = \"windows\">Press Ctrl+S.</p> attribute attribute value
    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 ..\\XMetaL\\Author\\Conditional Text\\configs\\ct_config.xml. 141
    302. Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions 142
    303. Assigning conditional attributes Windows only: <p platform=\"windows\">Press Ctrl+S.</p> Windows and Macintosh, but not Unix: <p platform=\"windows macintosh\">Press Ctrl+S.</p> All platforms: <p>Press Ctrl+S.</p> 143
    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. 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. <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element. 146
    307. Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text 147
    308. Generate conditional output Choose what platforms, products, and audiences you want to include 148
    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. 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 \"common to all\" OR it matches at least one value that should be included. 150
    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. Configuring XMetaL conditions Edit ct_config.xml <conditions> <attribute name=\"audience\" title=\"Audience\"> <value name=\"student\" title=\"Student\" /> <value name=\"teacher\" title=\"Trainer\" /> <value name=“self-study\" title=“Self-Study\" /> </attribute> <attribute name=\"platform\" title=\"Platform\"> <value name=\"windowsxp\" title=\"Windows XP“ /> <value name=\"windows2000\" title=\"Windows 2000 /> <value name=\"linux\" title=\"Linux\" /> <value name=\"macosx\" title=\"MacOSX“ /> </attribute> </conditions> 152
    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. 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. 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. 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. 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. Workbook Exercise: Reusing Content 11/03/08 158 158
    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. Thanks! Last Questions? Drawing! sbate@scriptorium.com

    + ScriptoriumScriptorium, 8 months ago

    custom

    1498 views, 2 favs, 1 embeds more stats

    Slides from DocTrain East 2008 Workshop: Introducti more

    More Info

    © All Rights Reserved

    Go to text version
    • Total Views 1498
      • 1480 on SlideShare
      • 18 from embeds
    • Comments 0
    • Favorites 2
    • Downloads 27
    Most viewed embeds
    • 18 views on http://www.redakteuse.de

    more

    All embeds
    • 18 views on http://www.redakteuse.de

    less

    Flagged as inappropriate Flag as inappropriate
    Flag as innappropriate

    Select your reason for flagging this presentation as inappropriate. If needed, use the feedback form to let us know more details.

    Cancel

    Categories