Embed Size (px)
DESCRIPTION
Slides from DocTrain East 2008 Workshop: Introduction to XMetaL and DITA.
Citation preview
Introduction to DITA and XMetaL
Simon BateScriptorium Publishing Services
Course Agenda
Overview of XMetaLElements and structured authoringGenerating output AttributesImagesTablesWriting topics
Sections and nested topicsCross-referencesMetadata and indexesTrack changesDITA mapsReusing content
Course purpose
Learn how to author content using XMetaL Author Enterprise EditionUnderstand DITAPut theory into practice, learn by doing
About DITA
Darwin Information Typing ArchitectureCreated at IBMNow developed and maintained by OASISStandard 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 ReferencePurpose and content model for each elementHelp > DITA Specifications > DITA Language Reference
DITA Architectural SpecificationDescribes overall behavior of DITAVery technicalHelp > DITA Specifications > DITA Architectural Specification
Overview of XMetaL
XMetaL Author
Standard word-processing environmentMultiple undo (and redo)Spell checking & thesaurusChange tracking
Create and edit textFamiliar editing features to create content
XMetaL Author Interface: OverviewMenu
Structure View
Tool bar
Document Pane
View Mode buttons
Element List
Inserting symbols and special characters
Insert > Symbols
Insert > Special Characters
Or click View > Toolbars, Then toggle appropriate checkboxes
Typographical elements
BoldItalicUnderline
View modes
Four view modes for the document pane:NormalPage PreviewTags OnPlain Text
Controls in bottom left corner of the pane: Indicate the current viewSwitch between views
Normal view
Shows content No XML element tagsIndicated by this icon: Use most of the time when writing content
Tags On view
Shows content Shows XML element tagsIndicated by this icon: Allows precise insertionAllows tag deletion/unwrappingClick box to expand/collapse:Tip: CTRL+SHIFT toggles Tags On & Normal
Plain Text view
Edit all XML markup and contentIndicated by this icon: Does not check validityCan create invalid XML
Page Preview view
Shows a formatted preview Indicated by this icon: Verify the content is formatted correctlyXML document transformedOpens in browser or Acrobat
Tip:
Can�t see the menus?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 carefulNo spacesNo special characters
Elements and Structured Authoring
Elements: Key terms
Element Element type (or name)Element contentsStart tagEnd tagAttribute
Structure and validity
XML must be:Well-formedValid
DITA content model defines validityHow to order elements Hierarchy of element typesAttributes
Validating documents
Click Tools > ValidateErrors most common in converted legacy documentsFix �missing required element� problems first
Structure and "Smart Insert"
When pasting XMetaL content:XMetaL inserts content at closest valid locationMay be far from the insertion pointMay not be pasted at all
When pasting Word or HTML content:XMetaL uses DITA elementsClosest match to paste and locationBest advice: watch when pasting
Identifying the current element
See context bar (at bottom of screen)Also shows ancestors' hierarchyBased on:
Cursor locationCurrently selected element
Here's a <li> within a <ul> within a <section>�
Be aware of what is selected
Identifying the current element
ENTER key
XMetaL inserts the most logical next element Often the same type as the current one
Insert menu
Allows you to insert elementsShows most available elementsContext free�Smart Insert�
Inserts an element in the next valid locationSometimes asks if you want to split the current element � usually this is what you want
Element List
View > Element ListLists available valid elementsDepends on cursor location
Insert newChange selected
Paragraph menu
Change paragraphs to notes and long quotationsSpecify note types:
dangertip
Apply and remove bullets and numbering
Format markup vs. Semantic markup
Separation of content from formatting
Format markup: how something should lookSemantic markup: what something means
Examples:<b> vs. <uicontrol><li> vs. <step>
Inserting domain elements
Domain elements cross topic typesInsert > * Element menus
ProgrammingSoftwareUser InterfaceUtilitiesOther
Domains in Element List
Domain elements are listed in Element ListTools > DITA Options Only affects the Element List
Not the Insert menu
Modifying elements
Change element typeRadio button in Insert element list
Expand and collapse content displaysDelete elements
Deleting elements
Easiest on Tags On view
To "unwrap" an element (leave content):Click just after the start tag, then press Backspace
To delete the element and content:Click a tag to select the entire element, then press Delete or Backspace
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
XHTMLPDFCHMRTFEclipse HelpJavaHelp
PDF options
XMetaL Enhanced PDFBest all-purpose PDF deliverable type
XMetaL Enhanced PDF via Acrobat DistillerUse 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 informationwidth = �250 px�
Point to a file or URLhref = �http://www.microsoft.com�href = �images/red_button.gif�
Identify an elementid = �p_73412763�
Conditionalize an elementplatform = �macintosh�
Attribute Inspector
Click View > Attribute InspectorAllows you to examine and change values of XML attributesCursor position is important
Working with attributes
XMetaL creates element IDs automaticallySome dialog boxes set attributes
Insert ImageSet 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, JPEGSVG (if an appropriate plug-in is installed)EPS
displays in XMetaL if preview information is available in the filerequires Acrobat Distiller to produce optimal PDF output
TIF, other formatsmay not display in all output formats
Working with images
Inserting imagesInsert > Image
Insert an image with a titleInsert > Figure with Title
Add a title to an existing imageSelect Image and wrap in figInsert > 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 editorSpecify �width� in pixels, inches, cm, etc.Specify �height�Least-supported: Specify �scale� by a percentage
Workbook Exercise:Images
Tables
Tables
Click Table > Insert TableChoose type:
Normal table = table with titleSimple table = informal table (no title)Step choices (task topics only) Properties (reference topics only)
Specify rows and columnsSpecify 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�t select the whole row.
Workbook Exercise:Tables
Writing topics
Topics
A Topic is a DITA unit of informationHas a title, short description, and content All topics have the same basic structure and capabilitiesLong enough to make sense on its own Short enough to provide essential info
Topic typesMain topic types:
Generic TopicConceptsTasksReference
DITA also includes:Composite or multiple topic typeGlossary 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 templatesTemplates 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 topicsTitleShort 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 topic1-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:
TechnologyUser concernsDecisionsBackgroundOverviewRelationshipsProcess overview
Sections and nested topics
Sections, topics, and headings
DITA is structuredNot like HTML or WordCannot put headings where you want
DITA requires more planning of your heading hierarchy
SectionsUse in Concept and Reference topicsCan have more than one sectionCan�t nest sectionsAll following paragraphs must be in section
Working with sections
Use Tags On view to see section boundariesMake sure section encloses all following content elements
Sections and subtopics
To nest information, either:Nest topics within a DITA mapInsert subtopics within the DITA topic
DITA maps are far preferredThink about reusability
Workbook Exercise:Creating Topics
Reference topics
Reference topics provide quick access to factsInfo users need to complete their tasksOften read when the info is neededLittle or no background or explanatory detailLinks to other closely related reference topics
Contents defined by your Style GuideGood use of specialization
Reference topics: examples
Documents the facts for categories such as:
device supportAPIsmessagesschemas
settingssymbolslanguage elementsand so on
Task topics
Task topics document proceduresAbout 70% of topics are tasksEach task topic presents information in a strict chronological sequence:
PrerequisitesContextSteps (required)ResultExamplePostrequisites
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 elementIllustrates the successful completion of the current step
Steps: Step result
DITA element: <stepresult>Describes the result of the current stepOptional step elementExample:
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 sequenceOutput 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 informationWhere there are multiple options
Output is the equivalent of a tableCan contain any general DITA elementsExample:
type attribute for the <note> element
Steps: Choice table output
Option Description
Click in the same window
To open the perspective in the same window. When you open the window, it replaces the currently open window.
Click in a new window
To open the perspective in a new window. When you open the window, it opens in a new window and the currently open window remains open.
Specify how to open new perspectives:
Task with unordered steps
Bullets instead of numbers <steps-unordered> element
Task topics: Results
DITA element: <result>Illustrates the successful completion of the taskExample: 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="#target"/>File reference <xref href="file.typ"/>Web link <xref href="http://..."/>
Related links <related-links>Links generated by relationship tables
Inserting links
Insert > Link > ...Cross-referenceFile referenceWeb link
All add <xref> elements
Related links added at end of topic
Refreshing References
To update content in cross-references: Click Edit > Refresh All ReferencesClose and reopen the document
Workbook Exercise:Cross-references and Links
Metadata and index elements
Metadata in DITA
Maintained in <prolog> elementExamples: author, publisher, copyright informationMetadata is usually company-specificClick Insert > Topic Metadata
This dialog can get you started, but best to create your own
Indexing
Use <indexterm>Can nest <indexterm> elementsCannot put in <title> elements
Place <indexterm> where appropriateDITA Open Toolkit will compile an index
Creating index entries
Click Insert > Index MarkerTip: Press Alt+Shift+XUse commas to create subentries
Editing index entries
Braces ({ and }) are XMetaLIndex entry:
Nested index entry:
Nested entry produces: “Stylesheets, troubleshooting....37”
Advanced indexing features
DITA 1.1 Page rangesSee/See alsoSort as
Workbook Exercise:Metadata and Index Elements
Track changes
Purpose:Communicate to reviewers about what�s newHave reviewers communicate about what they wantHelp you manage your writing process
XMetaL uses processing instructions to track changes
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 structureReferences to DITA topicsAnalogous to a FrameMaker Book fileCan also contain topic metadata
Topics and mapsTopic
Unit of information that is meaningful when it stands alone
MapOrganizes topics into a coherent setTypically for different deliverables or media
Topics DITA Maps Deliverables
Working with maps
Map Editor displays maps in a GUIYou can:
Add and remove topicsChange topic orderNest topicsEdit with drag and drop or toolbar buttonsChange map properties
Insert a reference to an existing topic
Select the map entry under which you want to nest the topicClick Insert > Topic ReferenceBrowse for a topic
Tips for working with maps
Plan where to put your map and topic filesusually close to each other
Remember file and folder naming rules:no spaces, no special characters
Make sure you�re using files in the location you think you�re using
Insert and create a topic
Select the topic above where you want the new topicClick Insert > Topic Reference
Insert a topic heading
Click Insert > Topic Heading
Create a new map
Click (small) File > New Map.
or
Click (big) File > NewThen 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 tabInteresting attributes include:
Navigation titleScopeInclude in TOCPrint
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 tasksTask Map
editorXML 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� sectionsSpecial type of semantic table
Columns define information typesRows define relationships between topicsEach <topicref> in a cell will link to the other topic references in that rowCan control linking
Map metadata
Metadata in mapscan fine-tune linking in relationship tablescan be used instead of topic metadatais inherited from parent elements
Relationship Tables: XML View
Create a relationship table
Switch to XML viewInsert the relationship tableAdd the <topicref> elementsGenerate the mapReview the linksUpdate the relationship tableGenerate and reviewSwitch 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 otherlinking = �targetonly�
topicrefs can be targets, but cannot be linkslinking = �sourceonly�
topicrefs can be links, but cannot be targets
Add topicsHold 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 contentAssembling glossary content
Glossary content
Basic markup:<glossentry>
<glossterm></glossterm><glossdef></glossdef>
</glossentry>
One or more <glossentry> elements in a fileSpecialization 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 textModular reuse:
reusing topics in different mapscontent references (conref)
Conditional text
Single source fileContent for multiple deliverablesMarkup identifies different subsetsFor example,
Windows: "Press Ctrl+S"Macintosh: "Press Command+S"
What does conditional text markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = "windows">Press Ctrl+S.</p>
attribute attribute value
Conditional text overview
Configure XMetaL with conditionsTypically: products, platforms, audiences
In XMetaL:Mark content as conditionalStyle conditional contentGenerate output
specify conditional content
Make content conditional
Select text or an element Click Reuse > Apply/Remove Conditions
Assigning conditional attributes
Windows only:<p platform="windows">Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:<p platform="windows macintosh">Press Ctrl+S.</p>
All platforms:<p>Press Ctrl+S.</p>
What content can you make conditional?
DITA allows a high degree of granularitySingle words can be made conditional(But consider practicality)Not limited to text, other types of content
Elements that can be made conditional:
Yes:TextImagesCross-referencesIndex markersTablesRows in tablesContent within content referencesTopic references in DITA maps
No:Individual table cellsTable columnsRequired elements
Text within required elements is OK
<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 textXMetaL only, not in deliverablesReuse > Style Conditional Text
Generate conditional output
Choose what platforms, products, and audiences you want to include
How DITA handles multiple condition types
In output for this audience and product:
Does the element appear?
Notes
EuropeMacintosh
No* The element is for the right audience. The element is not for the right platform.
North AmericaWindows
No* The element is not for the right audience. The element is for the right platform.
Europe Windows and Macintosh
Yes The element is for the right audience. The element is for one of the right platforms.
For an element marked as audience = �Europe� and platform = �windows�
*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 "common to all"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="audience" title="Audience"> <value name="student" title="Student" />
<value name="teacher" title="Trainer" /> <value name=�self-study" title=�Self-Study" />
</attribute>
<attribute name="platform" title="Platform"> <value name="windowsxp" title="Windows XP� />
<value name="windows2000" title="Windows 2000 /><value name="linux" title="Linux" /><value name="macosx" title="MacOSX� />
</attribute></conditions>
Content references (conrefs)
Standard DITA element attributeReferences another element of same typeOn output, content from referenced element substituted for the conref elementSimilar to FrameMaker �text insets�Analogous to referencing an image file
Content references in XMetaL
Content shown in conref is:Read-onlyUpdated when a document is opened
To manually refresh:Click Edit > Refresh All ReferencesOr press F11
Working with content references
Open a document containing a content referenceRight-click to switch between viewing local content and referenced content
Local content is highlighted in yellow
Reusable components
Reusable components:Managed snippets of XMLHave titles, short descriptions, and reusable-content.
One reusable component per fileClick Reuse > Create Reusable ComponentXMetaL only; not transportable
Reuse strategiesReuse Opportunity Solution
Multiple similar deliverables Flag some content as conditional
Piece of content used in many different contexts
Include it in different topics using content references
(Modular reuse)
Topic used in many different deliverables
Include it in different deliverables through DITA maps
(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)
1
Introduction to DITA and XMetaL
Simon BateScriptorium Publishing Services
2
Course Agenda
Overview of XMetaLElements and structured authoringGenerating output AttributesImagesTablesWriting topics
Sections and nested topicsCross-referencesMetadata and indexesTrack changesDITA mapsReusing content
3
Course purpose
Learn how to author content using XMetaL Author Enterprise EditionUnderstand DITAPut theory into practice, learn by doing
4
About DITA
Darwin Information Typing ArchitectureCreated at IBMNow developed and maintained by OASISStandard XML language
Cost-effective way to create, publish, reuse, and exchange structured content
5
Role of DITA Tools
An authoring tool is a user interface for creating DITA content
DITA documentation
DITA Language ReferencePurpose and content model for each elementHelp > DITA Specifications > DITA Language Reference
DITA Architectural SpecificationDescribes overall behavior of DITAVery technicalHelp > DITA Specifications > DITA Architectural Specification
6
Overview of XMetaL
7
8
XMetaL Author
Standard word-processing environmentMultiple undo (and redo)Spell checking & thesaurusChange tracking
Create and edit textFamiliar editing features to create content
9
XMetaL Author Interface: OverviewMenu
Structure View
Tool bar
Document Pane
View Mode buttons
Element List
Inserting symbols and special characters
Insert > Symbols
Insert > Special Characters
Or click View > Toolbars, Then toggle appropriate checkboxes
10
Typographical elements
BoldItalicUnderline
11
12
View modes
Four view modes for the document pane:NormalPage PreviewTags OnPlain Text
Controls in bottom left corner of the pane: Indicate the current viewSwitch between views
13
Normal view
Shows content No XML element tagsIndicated by this icon: Use most of the time when writing content
14
Tags On view
Shows content Shows XML element tagsIndicated by this icon: Allows precise insertionAllows tag deletion/unwrappingClick box to expand/collapse:Tip: CTRL+SHIFT toggles Tags On & Normal
15
Plain Text view
Edit all XML markup and contentIndicated by this icon: Does not check validityCan create invalid XML
16
Page Preview view
Shows a formatted preview Indicated by this icon: Verify the content is formatted correctlyXML document transformedOpens in browser or Acrobat
Tip:
Can�t see the menus?Open a DITA document
Want to see the structure view?View > Structure View
17
11/03/08 18
Workbook Exercise:Basic File Operations
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 carefulNo spacesNo special characters
20
Elements and Structured Authoring
21
Elements: Key terms
Element Element type (or name)Element contentsStart tagEnd tagAttribute
22
Structure and validity
XML must be:Well-formedValid
DITA content model defines validityHow to order elements Hierarchy of element typesAttributes
23
Validating documents
Click Tools > ValidateErrors most common in converted legacy documentsFix �missing required element� problems first
24
Structure and "Smart Insert"
When pasting XMetaL content:XMetaL inserts content at closest valid locationMay be far from the insertion pointMay not be pasted at all
When pasting Word or HTML content:XMetaL uses DITA elementsClosest match to paste and locationBest advice: watch when pasting
25
26
Identifying the current element
See context bar (at bottom of screen)Also shows ancestors' hierarchyBased on:
Cursor locationCurrently selected element
Here's a <li> within a <ul> within a <section>�
27
Be aware of what is selected
Identifying the current element
ENTER key
XMetaL inserts the most logical next element Often the same type as the current one
28
Insert menu
Allows you to insert elementsShows most available elementsContext free�Smart Insert�
Inserts an element in the next valid locationSometimes asks if you want to split the current element � usually this is what you want
29
30
Element List
View > Element ListLists available valid elementsDepends on cursor location
Insert newChange selected
Paragraph menu
Change paragraphs to notes and long quotationsSpecify note types:
dangertip
Apply and remove bullets and numbering
31
Format markup vs. Semantic markup
Separation of content from formatting
Format markup: how something should lookSemantic markup: what something means
Examples:<b> vs. <uicontrol><li> vs. <step>
32
Inserting domain elements
Domain elements cross topic typesInsert > * Element menus
ProgrammingSoftwareUser InterfaceUtilitiesOther
Domains in Element List
Domain elements are listed in Element ListTools > DITA Options Only affects the Element List
Not the Insert menu
34
Modifying elements
Change element typeRadio button in Insert element list
Expand and collapse content displaysDelete elements
35
Deleting elements
Easiest on Tags On view
To "unwrap" an element (leave content):Click just after the start tag, then press Backspace
To delete the element and content:Click a tag to select the entire element, then press Delete or Backspace
36
11/03/08 37
Workbook Exercise:Working with Elements
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
XHTMLPDFCHMRTFEclipse HelpJavaHelp
40
PDF options
XMetaL Enhanced PDFBest all-purpose PDF deliverable type
XMetaL Enhanced PDF via Acrobat DistillerUse if your documents have EPS graphics
41
Generating output
File > Generate Output for DITA Topic
Troubleshooting:File > View Output Log
42
11/03/08 43
Workbook Exercise:Generating Output
43
Attributes
44
Purpose of attributes
Provide additional informationwidth = �250 px�
Point to a file or URLhref = �http://www.microsoft.com�href = �images/red_button.gif�
Identify an elementid = �p_73412763�
Conditionalize an elementplatform = �macintosh�
45
Attribute Inspector
Click View > Attribute InspectorAllows you to examine and change values of XML attributesCursor position is important
46
Working with attributes
XMetaL creates element IDs automaticallySome dialog boxes set attributes
Insert ImageSet Conditional Text
Use Attribute Inspector
47
Attribute tooltips
Tip: Hover over a tag in Tags On view to see attributes
48
11/03/08 49
Workbook Exercise:Attributes
49
Images
50
Supported image formats
PNG, GIF, JPEGSVG (if an appropriate plug-in is installed)EPS
displays in XMetaL if preview information is available in the filerequires Acrobat Distiller to produce optimal PDF output
TIF, other formatsmay not display in all output formats
51
Working with images
Inserting imagesInsert > Image
Insert an image with a titleInsert > Figure with Title
Add a title to an existing imageSelect Image and wrap in figInsert > 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 editorSpecify �width� in pixels, inches, cm, etc.Specify �height�Least-supported: Specify �scale� by a percentage
53
11/03/08 54
Workbook Exercise:Images
54
Tables
55
Tables
Click Table > Insert TableChoose type:
Normal table = table with titleSimple table = informal table (no title)Step choices (task topics only) Properties (reference topics only)
Specify rows and columnsSpecify 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�t select the whole row.
58
11/03/08 59
Workbook Exercise:Tables
59
Writing topics
60
61
Topics
A Topic is a DITA unit of informationHas a title, short description, and content All topics have the same basic structure and capabilitiesLong enough to make sense on its own Short enough to provide essential info
62
Topic typesMain topic types:
Generic TopicConceptsTasksReference
DITA also includes:Composite or multiple topic typeGlossary entry (DITA 1.1)Specialization
63
Topics: Determining the topics you need
Identify a task to document.Identify the subtasks for the task.Identify the concepts you need to support the task and subtasks.Identify the supporting reference information.
XMetaL authoring templatesTemplates 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 topicsTitleShort 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 topic1-3 sentences, no more than 50 words
Body
65
66
Concept topics
Concept topics explain and teach. Help users build on their experience and knowledge. Read before using the product or completing a task.Can contain paragraphs, lists, tables, sections, images, etc.
67
Concept topics: examples
Concept topics can focus on specific types of information:
TechnologyUser concernsDecisionsBackgroundOverviewRelationshipsProcess overview
Sections and nested topics
68
Sections, topics, and headings
DITA is structuredNot like HTML or WordCannot put headings where you want
DITA requires more planning of your heading hierarchy
69
SectionsUse in Concept and Reference topicsCan have more than one sectionCan�t nest sectionsAll following paragraphs must be in section
70
71
Working with sections
Use Tags On view to see section boundariesMake sure section encloses all following content elements
72
Sections and subtopics
To nest information, either:Nest topics within a DITA mapInsert subtopics within the DITA topic
DITA maps are far preferredThink about reusability
11/03/08 73
Workbook Exercise:Creating Topics
73
74
Reference topics
Reference topics provide quick access to factsInfo users need to complete their tasksOften read when the info is neededLittle or no background or explanatory detailLinks to other closely related reference topics
Contents defined by your Style GuideGood use of specialization
Reference topics: examples
Documents the facts for categories such as:
device supportAPIsmessagesschemas
settingssymbolslanguage elementsand so on
75
Task topics
Task topics document proceduresAbout 70% of topics are tasksEach task topic presents information in a strict chronological sequence:
PrerequisitesContextSteps (required)ResultExamplePostrequisites
76
77
Task topics: Prerequisites
DITA element: <prereq>Things that users need to know or do before starting the task steps
Task topics: Context
DITA element: <context>Background information on the task
Typical task topic
<steps> element provides numbered steps
79
Sequence within a <step> element
<cmd> (required)Any number of the following:
<info> (tables, images, paragraphs, notes)<substeps > (2a, 2b, 2c� )<tutorialinfo> <stepxmp ><choicetable ><choices>
<stepresult>
80
Example of <steps>
81
82
Steps: Example in a step
DITA element: <stepxmp>Optional step elementIllustrates the successful completion of the current step
83
Steps: Step result
DITA element: <stepresult>Describes the result of the current stepOptional step elementExample:
When you depress the Lock button, all doors are locked automatically.
84
Steps: Substeps
DITA elements: <substeps>, <substep>Subdivides a major step in a sequence. Output is the equivalent of a nested ordered list within an ordered list. Can use all the elements valid for <step>, except for <choices> and <choicetable>.
Example: 3. Do the following:
a. Browse for the file. b. Type the file name.
85
Steps: Choices
DITA elements: <choices>, <choice>Decisions within a major step in a sequenceOutput is the equivalent of a nested unordered list within an ordered list. Can contain any general DITA elements
Example: 4. Select one of the following options:
Import all files Import selected files
86
Steps: Choice tables
DITA elements: <choicetable>, <chrow>, <choption>, <chdesc>Decisions within a major step in a sequence
Require a significant amount of informationWhere there are multiple options
Output is the equivalent of a tableCan contain any general DITA elementsExample:
type attribute for the <note> element
87
Steps: Choice table output
Option Description
Click in the same window
To open the perspective in the same window. When you open the window, it replaces the currently open window.
Click in a new window
To open the perspective in a new window. When you open the window, it opens in a new window and the currently open window remains open.
Specify how to open new perspectives:
Task with unordered steps
Bullets instead of numbers <steps-unordered> element
88
89
Task topics: Results
DITA element: <result>Illustrates the successful completion of the taskExample: The device is fully configured and ready for use.
90
Task topics: Example
DITA element: <example>Illustrates a successful completion of the task steps. <example> is a type of <section> element
Haven't introduced <section> yet.
91
Task topics: Postrequisites
DITA element: <postreq>Things that users need to know or do upon completing the task steps.
11/03/08 92
Workbook Exercise:Task Topics
92
Cross-references and links
93
Types of links
Inline links <xref>Cross-reference <xref href="#target"/>File reference <xref href="file.typ"/>Web link <xref href="http://..."/>
Related links <related-links>Links generated by relationship tables
94
Inserting links
Insert > Link > ...Cross-referenceFile referenceWeb link
All add <xref> elements
Related links added at end of topic
Refreshing References
To update content in cross-references: Click Edit > Refresh All ReferencesClose and reopen the document
96
11/03/08 97
Workbook Exercise:Cross-references and Links
97
Metadata and index elements
98
Metadata in DITA
Maintained in <prolog> elementExamples: author, publisher, copyright informationMetadata is usually company-specificClick Insert > Topic Metadata
This dialog can get you started, but best to create your own
99
Indexing
Use <indexterm>Can nest <indexterm> elementsCannot put in <title> elements
Place <indexterm> where appropriateDITA Open Toolkit will compile an index
100
Creating index entries
Click Insert > Index MarkerTip: Press Alt+Shift+XUse commas to create subentries
101
Editing index entries
Braces ({ and }) are XMetaLIndex 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 rangesSee/See alsoSort as
103
11/03/08 104
Workbook Exercise:Metadata and Index Elements
104
Track changes
105
Purpose:Communicate to reviewers about what�s newHave reviewers communicate about what they wantHelp you manage your writing process
XMetaL uses processing instructions to track changes
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
11/03/08 108
Workbook Exercise:Track Changes
108
DITA Maps
109
110
DITA maps
Organize DITA topics in a TOC-like structureReferences to DITA topicsAnalogous to a FrameMaker Book fileCan also contain topic metadata
Can have multiple maps for multiple deliverables.EG: data sheet vs concepts guide
111
Topics and mapsTopic
Unit of information that is meaningful when it stands alone
MapOrganizes topics into a coherent setTypically for different deliverables or media
Topics DITA Maps Deliverables
112
Working with maps
Map Editor displays maps in a GUIYou can:
Add and remove topicsChange topic orderNest topicsEdit with drag and drop or toolbar buttonsChange map properties
113
Insert a reference to an existing topic
Select the map entry under which you want to nest the topicClick Insert > Topic ReferenceBrowse for a topic
Tips for working with maps
Plan where to put your map and topic filesusually close to each other
Remember file and folder naming rules:no spaces, no special characters
Make sure you�re using files in the location you think you�re using
114
Insert and create a topic
Select the topic above where you want the new topicClick 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
117
Create a new map
Click (small) File > New Map.
or
Click (big) File > NewThen choose the DITA Map template
118
Insert a submap
Both maps must exist Click (small) Insert > Map Reference
119
Specify map properties
In the Map Editor, select the Properties button.In the Map Properties dialog, click the Special Attributes tabInteresting attributes include:
Navigation titleScopeInclude in TOCPrint
11/03/08 120
Workbook Exercise:Organizing Topics with Maps
120
121
Switch to XML view
Click (small) File > Switch to XML View of Map.
122
Switch to Map Editor
Select File > Switch to Map Editor
123
Different views for different tasksTask Map
editorXML View
Create the table of contents, a.k.a. the �hierarchical� part of the map
Browse topics by double-clicking
Edit relationship tables
Use conditional text to make parts of the map conditional
Troubleshoot
124
Relationship tables
Automatically generate �Related x� sectionsSpecial type of semantic table
Columns define information typesRows define relationships between topicsEach <topicref> in a cell will link to the other topic references in that rowCan control linking
125
Map metadata
Metadata in mapscan fine-tune linking in relationship tablescan be used instead of topic metadatais inherited from parent elements
126
Relationship Tables: XML View
127
Create a relationship table
Switch to XML viewInsert the relationship tableAdd the <topicref> elementsGenerate the mapReview the linksUpdate the relationship tableGenerate and reviewSwitch to Map Editor
128
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 otherlinking = �targetonly�
topicrefs can be targets, but cannot be linkslinking = �sourceonly�
topicrefs can be links, but cannot be targets
129
130
Add topicsHold 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.
11/03/08 131
Workbook Exercise:Relationship Tables
131
Glossaries
132
Glossaries
Writing glossary contentAssembling glossary content
133
Glossary content
Basic markup:<glossentry>
<glossterm></glossterm><glossdef></glossdef>
</glossentry>
One or more <glossentry> elements in a fileSpecialization 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 textModular reuse:
reusing topics in different mapscontent references (conref)
138
Conditional text
Single source fileContent for multiple deliverablesMarkup identifies different subsetsFor example,
Windows: "Press Ctrl+S"Macintosh: "Press Command+S"
139
What does conditional text markup look like?
No conditional text markup:
<p>Press Ctrl+S.</p>
Conditional text markup:
<p platform = "windows">Press Ctrl+S.</p>
attribute attribute value
Conditional text overview
Configure XMetaL with conditionsTypically: products, platforms, audiences
In XMetaL:Mark content as conditionalStyle conditional contentGenerate output
specify conditional content
..\XMetaL\Author\Conditional Text\configs\ct_config.xml.
141
Make content conditional
Select text or an element Click Reuse > Apply/Remove Conditions
142
Assigning conditional attributes
Windows only:<p platform="windows">Press Ctrl+S.</p>
Windows and Macintosh, but not Unix:<p platform="windows macintosh">Press Ctrl+S.</p>
All platforms:<p>Press Ctrl+S.</p>
143
What content can you make conditional?
DITA allows a high degree of granularitySingle words can be made conditional(But consider practicality)Not limited to text, other types of content
144
145
Elements that can be made conditional:
Yes:TextImagesCross-referencesIndex markersTablesRows in tablesContent within content referencesTopic references in DITA maps
No:Individual table cellsTable columnsRequired elements
Text within required elements is OK
<ph> element
If you make selected text conditional, XMetaL inserts <ph> tags so it can �hang� attributes on the <ph> element.
146
147
Style conditional text
Styles help keep track of conditional textXMetaL only, not in deliverablesReuse > Style Conditional Text
Generate conditional output
Choose what platforms, products, and audiences you want to include
148
How DITA handles multiple condition types
In output for this audience and product:
Does the element appear?
Notes
EuropeMacintosh
No* The element is for the right audience. The element is not for the right platform.
North AmericaWindows
No* The element is not for the right audience. The element is for the right platform.
Europe Windows and Macintosh
Yes The element is for the right audience. The element is for one of the right platforms.
For an element marked as audience = �Europe� and platform = �windows�
*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 "common to all"OR it matches at least one value that should be included.
150
151
Planning to use conditional text
Determine your team's needs in terms of content reuse:
What product variations are similar enough they could be documented through one set of source files?What audiences do you want to customize documentation for?Would it make sense to achieve reuse through conditional text, through content modularization, or both?
152
Configuring XMetaL conditions
Edit ct_config.xml<conditions> <attribute name="audience" title="Audience"> <value name="student" title="Student" />
<value name="teacher" title="Trainer" /> <value name=�self-study" title=�Self-Study" />
</attribute>
<attribute name="platform" title="Platform"> <value name="windowsxp" title="Windows XP� />
<value name="windows2000" title="Windows 2000 /><value name="linux" title="Linux" /><value name="macosx" title="MacOSX� />
</attribute></conditions>
153
Content references (conrefs)
Standard DITA element attributeReferences another element of same typeOn output, content from referenced element substituted for the conref elementSimilar to FrameMaker �text insets�Analogous to referencing an image file
154
Content references in XMetaL
Content shown in conref is:Read-onlyUpdated when a document is opened
To manually refresh:Click Edit > Refresh All ReferencesOr press F11
Working with content references
Open a document containing a content referenceRight-click to switch between viewing local content and referenced content
Local content is highlighted in yellow
155
Reusable components
Reusable components:Managed snippets of XMLHave titles, short descriptions, and reusable-content.
One reusable component per fileClick Reuse > Create Reusable ComponentXMetaL only; not transportable
156
Reuse strategiesReuse Opportunity Solution
Multiple similar deliverables Flag some content as conditional
Piece of content used in many different contexts
Include it in different topics using content references
(Modular reuse)
Topic used in many different deliverables
Include it in different deliverables through DITA maps
(Modular reuse)
157
11/03/08 158
Workbook Exercise:Reusing Content
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
