XMetaL DITA Workshop
 

XMetaL DITA Workshop

on

  • 8,332 views

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

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

Statistics

Views

Total Views
8,332
Slideshare-icon Views on SlideShare
8,225
Embed Views
107

Actions

Likes
5
Downloads
107
Comments
0

3 Embeds 107

http://www.redakteuse.de 96
http://www.slideshare.net 9
http://www.linkedin.com 2

Accessibility

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    XMetaL DITA Workshop XMetaL DITA Workshop Presentation Transcript

    • Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services
    • 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
    • Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing
    • 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
    • Role of DITA Tools An authoring tool is a user interface for creating DITA content
    • DITA documentation DITA Language Reference Purpose and content model for each element Help > DITA Specifications > DITA Language Reference DITA Architectural Specification Describes overall behavior of DITA Very technical Help > DITA Specifications > DITA Architectural Specification
    • Overview of XMetaL
    • 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
    • XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List
    • Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes
    • Typographical elements Bold Italic Underline
    • 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
    • Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content
    • Tags On view Shows content Shows XML element tags Indicated by this icon: Allows precise insertion Allows tag deletion/unwrapping Click box to expand/collapse: Tip: CTRL+SHIFT toggles Tags On & Normal
    • Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML
    • Page Preview view Shows a formatted preview Indicated by this icon: Verify the content is formatted correctly XML document transformed Opens in browser or Acrobat
    • Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View
    • Workbook Exercise: Basic File Operations
    • Options for saving and opening files Click Tools > Options To use default toolbars, press CTRL on startup
    • File and folder naming Be systematic and careful No spaces No special characters
    • Elements and Structured Authoring
    • Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute
    • Structure and validity XML must be: Well-formed Valid DITA content model defines validity How to order elements Hierarchy of element types Attributes
    • Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first
    • 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
    • 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>…
    • Identifying the current element Be aware of what is selected
    • ENTER key XMetaL inserts the most logical next element Often the same type as the current one
    • Insert menu Allows you to insert elements Shows most available elements Context free “Smart Insert” Inserts an element in the next valid location Sometimes asks if you want to split the current element – usually this is what you want
    • Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected
    • Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering
    • 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>
    • Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
    • Domains in Element List Domain elements are listed in Element List Tools > DITA Options Only affects the Element List Not the Insert menu
    • Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements
    • 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
    • Workbook Exercise: Working with Elements
    • Generating Output (Publishing)
    • 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
    • Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp
    • PDF options XMetaL Enhanced PDF Best all-purpose PDF deliverable type XMetaL Enhanced PDF via Acrobat Distiller Use if your documents have EPS graphics
    • Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log
    • Workbook Exercise: Generating Output
    • Attributes
    • Purpose of attributes Provide additional information width = “250 px” Point to a file or URL href = “http://www.microsoft.com” href = “images/red_button.gif” Identify an element id = “p_73412763” Conditionalize an element platform = “macintosh”
    • Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important
    • Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector
    • Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes
    • Workbook Exercise: Attributes
    • Images
    • Supported image formats PNG, GIF, JPEG SVG (if an appropriate plug-in is installed) EPS displays in XMetaL if 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
    • 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
    • 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
    • Workbook Exercise: Images
    • Tables
    • 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
    • Header rows To make the first row of a table a header row: Click Table > Insert Table Add later with Table > Table Properties
    • Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t
    • Workbook Exercise: Tables
    • Writing topics
    • Topics A Topic is a DITA unit of information Has a title, short description, and content All topics have the same basic structure and capabilities Long enough to make sense on its own Short enough to provide essential info
    • Topic types Main topic types: Generic Topic Concepts Tasks Reference DITA also includes: Composite or multiple topic type Glossary entry (DITA 1.1) Specialization
    • 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.
    • 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
    • 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
    • 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.
    • Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview
    • Sections and nested topics
    • 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
    • Sections Use in Concept and Reference topics Can have more than one section Can’ nest sections t All following paragraphs must be in section
    • Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements
    • 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
    • Workbook Exercise: Creating Topics
    • 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
    • Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on
    • 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
    • Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps
    • Task topics: Context DITA element: <context> Background information on the task
    • Typical task topic <steps> element provides numbered steps
    • Sequence within a <step> element <cmd> (required) Any number of the following: <info> (tables, images, paragraphs, notes) <substeps > (2a, 2b, 2c… ) <tutorialinfo> <stepxmp > <choicetable > <choices> <stepresult>
    • Example of <steps>
    • Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step
    • 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.
    • 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.
    • 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
    • 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
    • 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.
    • Task with unordered steps Bullets instead of numbers <steps-unordered> element
    • Task topics: Results DITA element: <result> Illustrates the successful completion of the task Example: The device is fully configured and ready for use.
    • Task topics: Example DITA element: <example> Illustrates a successful completion of the task steps. <example> is a type of <section> element
    • Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps.
    • Workbook Exercise: Task Topics
    • Cross-references and links
    • Types of links Inline links <xref> Cross-reference <xref href=quot;#targetquot;/> File reference <xref href=quot;file.typquot;/> Web link <xref href=quot;http://...quot;/> Related links <related-links> Links generated by relationship tables
    • Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
    • Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document
    • Workbook Exercise: Cross-references and Links
    • Metadata and index elements
    • 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
    • Indexing Use <indexterm> Can nest <indexterm> elements Cannot put in <title> elements Place <indexterm> where appropriate DITA Open Toolkit will compile an index
    • Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries
    • Editing index entries Braces ({ and }) are XMetaL Index entry: Nested index entry: Nested entry produces: “Stylesheets, troubleshooting....37”
    • Advanced indexing features DITA 1.1 Page ranges See/See also Sort as
    • Workbook Exercise: Metadata and Index Elements
    • Track changes
    • Track changes Purpose: Communicate to reviewers about what’ new s Have reviewers communicate about what they want Help you manage your writing process XMetaL uses processing instructions to track changes
    • 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]
    • Workbook Exercise: Track Changes
    • DITA Maps
    • DITA maps Organize DITA topics in a TOC-like structure References to DITA topics Analogous to a FrameMaker Book file Can also contain topic metadata
    • 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
    • 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
    • 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
    • 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
    • Insert and create a topic Select the topic above where you want the new topic Click Insert > Topic Reference
    • Insert a topic heading Click Insert > Topic Heading
    • Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template
    • Insert a submap Both maps must exist Click (small) Insert > Map Reference
    • Specify map properties In the Map Editor, select the Properties button. In the Map Properties dialog, click the Special Attributes tab Interesting attributes include: Navigation title Scope Include in TOC Print
    • Workbook Exercise: Organizing Topics with Maps
    • Switch to XML view Click (small) File > Switch to XML View of Map.
    • Switch to Map Editor Select File > Switch to Map Editor
    • Different views for different tasks Task Map XML 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 
    • 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
    • Map metadata Metadata in maps can fine-tune linking in relationship tables can be used instead of topic metadata is inherited from parent elements
    • Relationship Tables: XML View
    • 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
    • Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK:
    • 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
    • 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.
    • Workbook Exercise: Relationship Tables
    • Glossaries
    • Glossaries Writing glossary content Assembling glossary content
    • Glossary content Basic markup: <glossentry> <glossterm></glossterm> <glossdef></glossdef> </glossentry> One or more <glossentry> elements in a file Specialization of <concept> DITA 1.1
    • 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.
    • Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically.
    • Reusing content
    • 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)
    • 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;
    • 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
    • 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
    • Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions
    • Assigning conditional attributes Windows only: <p platform=quot;windowsquot;>Press Ctrl+S.</p> Windows and Macintosh, but not Unix: <p platform=quot;windows macintoshquot;>Press Ctrl+S.</p> All platforms: <p>Press Ctrl+S.</p>
    • 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
    • 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
    • <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element.
    • Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text
    • Generate conditional output Choose what platforms, products, and audiences you want to include
    • How DITA handles multiple condition types For an element marked as audience = “Europe” and platform = “windows” In 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
    • 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.
    • 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?
    • 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>
    • 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
    • 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
    • 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
    • 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
    • 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)
    • Workbook Exercise: Reusing Content
    • 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)
    • Thanks! Last Questions? Drawing! sbate@scriptorium.com
    • Introduction to DITA and XMetaL Simon Bate Scriptorium Publishing Services 1
    • 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
    • Course purpose Learn how to author content using XMetaL Author Enterprise Edition Understand DITA Put theory into practice, learn by doing 3
    • 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
    • Role of DITA Tools An authoring tool is a user interface for creating DITA content 5
    • 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
    • Overview of XMetaL 7
    • 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
    • XMetaL Author Interface: Overview Menu Tool bar Structure View View Mode Document Element buttons Pane List 9
    • Inserting symbols and special characters Insert > Symbols Insert > Special Characters Or click View > Toolbars, Then toggle appropriate checkboxes 10
    • Typographical elements Bold Italic Underline 11
    • View modes Four view modes for the document pane: Normal Page Preview Tags On Plain Text Controls in bottom left corner of the pane: Indicate the current view Switch between views 12
    • Normal view Shows content No XML element tags Indicated by this icon: Use most of the time when writing content 13
    • 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
    • Plain Text view Edit all XML markup and content Indicated by this icon: Does not check validity Can create invalid XML 15
    • 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
    • Tip: Can’ see the menus? t Open a DITA document Want to see the structure view? View > Structure View 17
    • Workbook Exercise: Basic File Operations 11/03/08 18 18
    • Options for saving and opening files Click Tools > Options To use default toolbars, press CTRL on startup For training, it is useful to turn this option off because having too many files open confuses people 19
    • File and folder naming Be systematic and careful No spaces No special characters 20
    • Elements and Structured Authoring 21
    • Elements: Key terms Element Element type (or name) Element contents Start tag End tag Attribute 22
    • Structure and validity XML must be: Well-formed Valid DITA content model defines validity How to order elements Hierarchy of element types Attributes 23
    • Validating documents Click Tools > Validate Errors most common in converted legacy documents Fix “missing required element” problems first 24
    • 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
    • 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
    • Identifying the current element Be aware of what is selected 27
    • ENTER key XMetaL inserts the most logical next element Often the same type as the current one 28
    • 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
    • Element List View > Element List Lists available valid elements Depends on cursor location Insert new Change selected 30
    • Paragraph menu Change paragraphs to notes and long quotations Specify note types: danger tip Apply and remove bullets and numbering 31
    • 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
    • Inserting domain elements Domain elements cross topic types Insert > * Element menus Programming Software User Interface Utilities Other
    • Domains in Element List Domain elements are listed in Element List Tools > DITA Options Only affects the Element List Not the Insert menu 34
    • Modifying elements Change element type Radio button in Insert element list Expand and collapse content displays Delete elements 35
    • 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
    • Workbook Exercise: Working with Elements 11/03/08 37 37
    • Generating Output (Publishing) 38
    • DITA Open Toolkit Open-source application for publishing DITA content to multiple output formats Integrated with XMetaL Help > Third-Party Components > DITA Open Toolkit User Guide 39
    • Publishing formats XHTML PDF CHM RTF Eclipse Help JavaHelp 40
    • PDF options XMetaL Enhanced PDF Best all-purpose PDF deliverable type XMetaL Enhanced PDF via Acrobat Distiller Use if your documents have EPS graphics 41
    • Generating output File > Generate Output for DITA Topic Troubleshooting: File > View Output Log 42
    • Workbook Exercise: Generating Output 11/03/08 43 43
    • Attributes 44
    • Purpose of attributes Provide additional information width = “250 px” Point to a file or URL href = “http://www.microsoft.com” href = “images/red_button.gif” Identify an element id = “p_73412763” Conditionalize an element platform = “macintosh” 45
    • Attribute Inspector Click View > Attribute Inspector Allows you to examine and change values of XML attributes Cursor position is important 46
    • Working with attributes XMetaL creates element IDs automatically Some dialog boxes set attributes Insert Image Set Conditional Text Use Attribute Inspector 47
    • Attribute tooltips Tip: Hover over a tag in Tags On view to see attributes 48
    • Workbook Exercise: Attributes 11/03/08 49 49
    • Images 50
    • Supported image formats PNG, GIF, JPEG SVG (if an appropriate plug-in is installed) EPS displays in XMetaL if 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
    • 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
    • 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
    • Workbook Exercise: Images 11/03/08 54 54
    • Tables 55
    • Tables Click Table > Insert Table Choose type: Normal table = table with title Simple table = informal table (no title) Step choices (task topics only) Properties (reference topics only) Specify rows and columns Specify header or not 56
    • Header rows To make the first row of a table a header row: Click Table > Insert Table Add later with Table > Table Properties 57
    • Working with table properties Tip: Click in a row to change the properties of that row. Don’ select the whole row. t 58
    • Workbook Exercise: Tables 11/03/08 59 59
    • Writing topics 60
    • Topics A Topic is a DITA unit of information Has a title, short description, and content All topics have the same basic structure and capabilities Long enough to make sense on its own Short enough to provide essential info 61
    • 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
    • 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
    • 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
    • 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
    • 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
    • Concept topics: examples Concept topics can focus on specific types of information: Technology User concerns Decisions Background Overview Relationships Process overview 67
    • Sections and nested topics 68
    • 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
    • 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
    • Working with sections Use Tags On view to see section boundaries Make sure section encloses all following content elements 71
    • 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
    • Workbook Exercise: Creating Topics 11/03/08 73 73
    • Reference topics Reference topics provide quick access to facts Info users need to complete their tasks Often read 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
    • Reference topics: examples Documents the facts for categories such as: device support settings APIs symbols messages language elements schemas and so on 75
    • 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
    • Task topics: Prerequisites DITA element: <prereq> Things that users need to know or do before starting the task steps 77
    • Task topics: Context DITA element: <context> Background information on the task
    • Typical task topic <steps> element provides numbered steps 79
    • Sequence within a <step> element <cmd> (required) Any number of the following: <info> (tables, images, paragraphs, notes) <substeps > (2a, 2b, 2c… ) <tutorialinfo> <stepxmp > <choicetable > <choices> <stepresult> 80
    • Example of <steps> 81
    • Steps: Example in a step DITA element: <stepxmp> Optional step element Illustrates the successful completion of the current step 82
    • 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
    • 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
    • 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
    • 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
    • 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
    • Task with unordered steps Bullets instead of numbers <steps-unordered> element 88
    • Task topics: Results DITA element: <result> Illustrates the successful completion of the task Example: The device is fully configured and ready for use. 89
    • 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
    • Task topics: Postrequisites DITA element: <postreq> Things that users need to know or do upon completing the task steps. 91
    • Workbook Exercise: Task Topics 11/03/08 92 92
    • Cross-references and links 93
    • Types of links Inline links <xref> Cross-reference <xref href=quot;#targetquot;/> File reference <xref href=quot;file.typquot;/> Web link <xref href=quot;http://...quot;/> Related links <related-links> Links generated by relationship tables 94
    • Inserting links Insert > Link > ... Cross-reference File reference Web link All add <xref> elements Related links added at end of topic
    • Refreshing References To update content in cross-references: Click Edit > Refresh All References Close and reopen the document 96
    • Workbook Exercise: Cross-references and Links 11/03/08 97 97
    • Metadata and index elements 98
    • Metadata in DITA Maintained in <prolog> element Examples: author, publisher, copyright information Metadata is usually company-specific Click Insert > Topic Metadata This dialog can get you started, but best to create your own 99
    • Indexing Use <indexterm> Can nest <indexterm> elements Cannot put in <title> elements Place <indexterm> where appropriate DITA Open Toolkit will compile an index 100
    • Creating index entries Click Insert > Index Marker Tip: Press Alt+Shift+X Use commas to create subentries 101
    • 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
    • Advanced indexing features DITA 1.1 Page ranges See/See also Sort as 103
    • Workbook Exercise: Metadata and Index Elements 11/03/08 104 104
    • Track changes 105
    • Track changes Purpose: Communicate to reviewers about what’ new s Have reviewers communicate about what they want Help you manage your writing process XMetaL uses processing instructions to track changes 106
    • 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
    • Workbook Exercise: Track Changes 11/03/08 108 108
    • DITA Maps 109
    • DITA maps Organize DITA topics in a TOC-like structure References to DITA topics Analogous to a FrameMaker Book file Can also contain topic metadata Can have multiple maps for multiple deliverables. EG: data sheet vs concepts guide 110
    • 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
    • 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
    • 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
    • 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
    • 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
    • Insert a topic heading Click Insert > Topic Heading 116
    • Create a new map Click (small) File > New Map. or Click (big) File > New Then choose the DITA Map template 117
    • Insert a submap Both maps must exist Click (small) Insert > Map Reference 118
    • Specify map properties In the Map Editor, select the Properties button. In the Map Properties dialog, click the Special Attributes tab Interesting attributes include: Navigation title Scope Include in TOC Print 119
    • Workbook Exercise: Organizing Topics with Maps 11/03/08 120 120
    • Switch to XML view Click (small) File > Switch to XML View of Map. 121
    • Switch to Map Editor Select File > Switch to Map Editor 122
    • Different views for different tasks Task Map XML 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
    • 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
    • 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
    • Relationship Tables: XML View 126
    • 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
    • Insert a relationship table Click Table > Insert Relationship Table. Choose one of several common formats, then click OK: 128
    • 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
    • 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
    • Workbook Exercise: Relationship Tables 11/03/08 131 131
    • Glossaries 132
    • Glossaries Writing glossary content Assembling glossary content 133
    • Glossary content Basic markup: <glossentry> <glossterm></glossterm> <glossdef></glossdef> </glossentry> One or more <glossentry> elements in a file Specialization of <concept> DITA 1.1 134
    • 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
    • Publishing glossaries During “Generate Output”: All glossary content is pulled into the same glossary and is sorted alphabetically. 136
    • Reusing content 137
    • 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
    • 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
    • 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
    • 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
    • Make content conditional Select text or an element Click Reuse > Apply/Remove Conditions 142
    • 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
    • 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
    • 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
    • <ph> element If you make selected text conditional, XMetaL inserts <ph> tags so it can “hang” attributes on the <ph> element. 146
    • Style conditional text Styles help keep track of conditional text XMetaL only, not in deliverables Reuse > Style Conditional Text 147
    • Generate conditional output Choose what platforms, products, and audiences you want to include 148
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • 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
    • Workbook Exercise: Reusing Content 11/03/08 158 158
    • Additional resources DITA Users group on Yahoo! groups: http://tech.groups.yahoo.com/group/dita-users/ XMetaL-DITA group on Yahoo! groups: http://tech.groups.yahoo.com/group/xmetal-dita/ dita.xml.org www.justsystems.com (webinars, events) 159
    • Thanks! Last Questions? Drawing! sbate@scriptorium.com