XMetaL DITA Workshop

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

XMetaL DITA Workshop

by Scriptorium Publishing on Nov 03, 2008

Accessibility

Categories

Tags

Upload Details

Usage Rights

2 Embeds 73

Statistics

XMetaL DITA Workshop — Presentation Transcript

http://www.redakteuse.de	64
http://www.slideshare.net	9