Syntext Serna+DITA Tutorial

The PDF version of this tutorial is available at: http://www.syntext.com/products/serna/doc/dita-tutorial/dita-serna-tutorial.pdf

Table of Contents

1. Introduction

2. DITA Authoring Tips

Creating DITA Topics

Creating "Color Temperature" Concept
Creating "Drawing a Rainbow" Task

Creating DITA Map

Inserting Topic References in Map
Inserting References to Newly-Created Documents in Map
Editing Topic References in Map
Resolving Topic References in Map

Making References and Links

Making Local Xref in "Drawing a Rainbow" Task
Making External Xref in "Drawing a Rainbow" Task
Making External Related Link in "Drawing a Rainbow" Task

Content Referencing

Making Local Conref in "Warm Colors" Concept
Making External Conref in "Cool Colors" Concept

3. Publishing DITA Documents

A. DITA XSLT Parameter Sets

List of Tables

A.1. DITA Topics XSLT Parameter Sets
A.2. DITA Maps XSLT Parameter Sets

Chapter 1. Introduction

This tutorial helps you get handy with DITA authoring in Serna. You'll learn to create topics and integrate them into a map, make links, and reuse content by means of content references. In the tutorial, you will also find information about publishing DITA documents and about available views of DITA documents in Serna. For general things, such as element insertion, cursor placement, selection, navigation, etc, refer to the Syntext Serna Basics Tutorial.

To read this tutorial, you are supposed to have a general understanding of basic DITA concepts. For the introduction to DITA, see http://en.wikipedia.org/wiki/DITA.

All versions of Serna support DITA. However, the DITA usability tools, which facilitate the insertion of common DITA constructs, are available in the Enterprise edition and the trial version of Serna only.

Chapter 2. DITA Authoring Tips

Table of Contents

Creating DITA Topics

Creating "Color Temperature" Concept
Creating "Drawing a Rainbow" Task

Creating DITA Map

Inserting Topic References in Map
Inserting References to Newly-Created Documents in Map
Editing Topic References in Map
Resolving Topic References in Map

Making References and Links

Making Local Xref in "Drawing a Rainbow" Task
Making External Xref in "Drawing a Rainbow" Task
Making External Related Link in "Drawing a Rainbow" Task

Content Referencing

Making Local Conref in "Warm Colors" Concept
Making External Conref in "Cool Colors" Concept

Creating DITA Topics

Abstract

DITA documents can be of different types, e.g. concept, task, reference, etc. In this section, we'll create a concept and a task, and we'll use these topics later in the tutorial when we deal with a DITA map, linking and content referencing.

Creating "Color Temperature" Concept

Let's create a "Color Temperature" concept:

Choose Document->New Document to call the New Document Dialog.
Select DITA 1.1 -> Concept .
In the File Name field, specify the path to the new file color-temperature.xml: D:/dita-examples/color-temperature.xml.

Note

You can use the Browse... button to specify the new file location.
Click OK.
A new document color-temperature.xml will be created. Put the cursor inside the p element.
Type about the concept of color temperature:
```
Colors are said to be warm or cool.
```
Change the title from "Concept" to "Color Temperature".
Save color-temperature.xml.

Creating "Drawing a Rainbow" Task

Let's create a "Drawing a Rainbow" task:

Choose Document->New Document to call the New Document Dialog.
Select DITA 1.1 -> Task .
In the File Name field, specify the path to the new file draw-rainbow.xml: D:/dita-examples/draw-rainbow.xml.

Note

You can use the Browse... button to specify the new file location.
Click OK.
A new document draw-rainbow.xml will be created.

Make 7 steps and type inside the cmd elements:

Draw a red arc.
Draw an orange arc.
Draw a yellow arc.
Draw a green arc.
Draw a blue arc.
Draw an indigo arc.
Draw a violet arc.

Change the title from "Task" to "Drawing a Rainbow".
Save draw-rainbow.xml.

Creating DITA Map

A DITA map lets you organize topics for a particular output. You can aggregate any of the existing topics by means of topic references (topicrefs) and set relationships between them.

Now that we have a concept and a task, let's create a map:

Choose Document->New Document to call the New Document Dialog.
Select DITA 1.1 -> Map .
In the File Name field, specify the path to the new file colors.ditamap: D:/dita-examples/colors.ditamap.

Note

You can use the Browse... button to specify the new file location.
Click OK.
A new DITA map document will be created.
Select the "DITA Map" text of the title and change it to "Colors".
Now the title says "Colors".

Inserting Topic References in Map

Let's insert references to the "Color Temperature" and "Drawing a Rainbow" topics:

Click the Insert Topic Reference button to call the Insert Topic Reference Dialog.
In the Insert Topic Reference Dialog, do the following:
1. Select the file color-temperature.xml and the target "Color Temperature" concept.
2. From the Type drop-down list, select "concept" to display the type of the referenced topic.
3. Click the Insert button.
4. Select the file draw-rainbow.xml and the target "Drawing a Rainbow" task.
5. From the Type drop-down list, select "task" to display the type of the referenced topic.
6. Click the Insert button.
7. Click the Close button.
The topic references (topicrefs) have been inserted. The titles are extracted from the referenced topics and you see the links to the documents. Also, the types of the topics are shown: a concept and a task.
Save colors.ditamap.

Inserting References to Newly-Created Documents in Map

Above, we inserted references to existing topics. It is also possible to create new DITA documents and simultaneously insert references to these newly created documents in DITA Map.

Let's insert two more references to documents which do not exist yet: "Warm Colors" Concept and "Cool Colors" Concept.

Inserting Reference to Newly-Created "Warm Colors" Concept in Map

Let's nest the reference to a newly-created "Warm Colors" concept in the "Color Temperature" topic reference:

Put the cursor in the "Color Temperature" topic reference.
Click the Insert New DITA Document Reference button to call the Insert New DITA Document Reference Dialog.
Set properties for the new DITA topic:

In the Insert New DITA Document Reference Dialog, do the following:
1. From the Template drop-down list, select Concept.
2. In the Title field, type: "Warm Colors"". Note that the Id field gets filled in automatically: warm-colors.
3. In the File field, specify the path to the new file warm-colors.xml: D:/dita-examples/warm-colors.xml.
  
  Note
  
  You can use the Browse... button to specify the new file location.
Check the Open after insert checkbox.
Click the Insert button.
The topic reference (topicref) to the "Warm Colors" concept has been nested.
A new document warm-colors.xml has been created and opened. The concept already has the title "Warm Colors" and the ID warm-colors.
Put the cursor inside the p element.

Type about the concept of warm colors:

Such energetic colors as red, orange and yellow are associated with
sunlight. That's why they are often called "warm colors".

You should get a "Warm Colors" concept like this:
Save warm-colors.xml.
Save colors.ditamap.

Inserting Reference to Newly-Created "Cool Colors" Concept in Map

Let's nest the reference to a newly-created "Cool Colors" concept in the "Color Temperature" topic reference:

Put the cursor after the "Warm Colors" topic reference. It is convenient to click this position in the ContentMap.
Click the Insert New DITA Document Reference button to call the Insert New DITA Document Reference Dialog.
Set properties for the new DITA topic:

In the Insert New DITA Document Reference Dialog, do the following:
1. From the Template drop-down list, select Concept.
2. In the Title field, type: "Cool Colors"". Note that the Id field gets filled in automatically: cool-colors.
3. In the File field, specify the path to the new file cool-colors.xml: D:/dita-examples/cool-colors.xml.
  
  Note
  
  You can use the Browse... button to specify the new file location.
Check the Open after insert checkbox.
Click the Insert button.
The topic reference (topicref) to the "Cool Colors" concept has been nested.
A new document cool-colors.xml has been created and opened. The concept already has the title "Cool Colors" and the ID cool-colors.
Put the cursor inside the p element.

Type about the concept of cool colors:

Such soothing colors as green, blue and violet are associated with winter,
rain and ocean. That's why they are often called "cool colors".

You should get a "Cool Colors" concept like this:
Save cool-colors.xml.
Save colors.ditamap.

Editing Topic References in Map

Let's display the type of the "Warm Colors" topic:

Click the "Warm Colors" topic reference.
Click the Insert Topic Reference button .
In the Change Topic Reference Dialog, select "concept" from the Type drop-down list.
Click the Change button. Click Close.
Now the type of the "Warm Colors" topic is shown.
Save colors.ditamap.

Let's specify the collection type of the referenced concepts to describe the relationship between them:

Click the "Color Temperature" topic reference.
Click the Insert Topic Reference button .
In the Change Topic Reference Dialog, select "family" from the Collection Type drop-down list.
Click the Change button. Click Close.
Now the "family" collection type of the concepts is specified.
Save colors.ditamap.

Resolving Topic References in Map

Let's switch to the map view that displays resolved topic references:

From the XSLT Parameter Set drop-down list, select Show Resolved .
Now the map displays the content of the referenced topics.

Tip

You can't edit the content of topics right in the map. Double-click a topic in the map to open it as a separate document.

Note

For a summary of XSLT Parameter Sets for DITA, see Appendix A, DITA XSLT Parameter Sets.

Making References and Links

Abstract

In this section we'll learn to make different types of links to targets with IDs: local and external xref and related links.

Making Local Xref in "Drawing a Rainbow" Task

Let's insert a local xref in the "Drawing a Rainbow" task:

Open draw-rainbow.xml.
Add the ID attribute to the first step element "Draw a red arc.".
After the steps element, insert the postreq element and type inside it:
```
You can remember the colors as ROY G BIV.
```
Let's make the letter "R" a local xref to the first step "Draw a red arc." Place the cursor before the letter "R".
Choose DITA->Insert Local Xref.
In the Insert Local Xref Dialog, select the target step. Check the Close on Insert checkbox. Click the Insert button.
A local xref to the first step "Draw a red arc." has been inserted.
Now cut the letter "R" and paste it in the xref.
Save draw-rainbow.xml.

Making External Xref in "Drawing a Rainbow" Task

Let's insert an external xref in the "Drawing a Rainbow" task:

Open draw-rainbow.xml.
In the first step after the cmd, insert info-> note-> p elements.

Type inside the p:
```
Red is a warm color. For details, see .
```
Choose DITA->Insert External Xref.
In the Insert External Xref Dialog, select the file warm-colors.xml and the target "Warm Colors" concept. Click the Insert button.
The external xref to warm-colors.xml has been inserted.
Save draw-rainbow.xml

Making External Related Link in "Drawing a Rainbow" Task

Let's insert an external related link in the "Drawing a Rainbow" Task:

Open draw-rainbow.xml.
Choose DITA->Insert External Related Link.
In the Insert External Related Link Dialog, select the file color-temperature.xml and the target "Color Temperature" concept. Click the Insert button.
The external related link to the concept of color temperature has been inserted.
Save draw-rainbow.xml.

Content Referencing

Abstract

In this section we'll learn to work with local and external content references (conrefs) that provide a powerful mechanism for content reuse. Conref is an attribute of an element that pulls the content into the element from another element of the same type. Any element with an ID can be reused by means of a conref.

When you need to insert a conref, Serna creates an element automatically together with the conref attribute that pulls the content into the element.

Making Local Conref in "Warm Colors" Concept

Let's create a local content reference in the "Warm Colors" concept:

Open warm-colors.xml.
After the p element, insert a note with a p.

Type inside the p:

The irony is that the hottest bodies radiate with a cool color
while the less hot bodies radiate with a warm color.

Add the ID attribute to the note.
Put the cursor after the note.
Choose DITA->Insert Local Conref.
In the Insert Local Conref Dialog, select the target note. Click the Insert button.
The local content reference has been inserted.

Type more text in the original note:

For example, a red dwarf star has a relatively low surface temperature,
while a blue giant star has the warmest surface.

and see the changes applied to the local conref.

Save warm-colors.xml.

Making External Conref in "Cool Colors" Concept

Let's create an external content reference in the "Cool Colors" concept:

Open cool-colors.xml.
Put the cursor after the p element.
Choose DITA->Insert External Conref.
In the Insert External Conref Dialog, do the following:
1. Select the file warm-colors.xml.
2. Select the target note.
3. Click the Insert button.
The external content reference has been inserted and resolved.

Tip

Despite the fact that external conrefs can be resolved, their content can't be changed. However, you can edit the conref attribute itself: right-click the element and select Element Attributes from the context menu. In the Element Attributes Dialog, you can change the value of the conref attribute (change the path to the target element).
Save cool-colors.xml.

Making Conrefs Explicit

Open cool-colors.xml where we inserted a note as an external conref.

The default document view profile displays resolved content references, so the note inserted by means of a conref looks like an ordinary note in the editing window.

To make the conref distinguishable in the editing window, switch to another document view profile:

From the XSLT Parameter Set drop-down list, select Edit Conrefs .
The external conref is highlighted with blue and you see the path to the original note.

Tip

Despite the fact that external conrefs can be resolved, their content can't be changed. However, you can edit the conref attribute itself: right-click the element and select Element Attributes from the context menu. In the Element Attributes Dialog, you can change the value of the conref attribute (change the path to the target element).

Note

For a summary of XSLT Parameter Sets for DITA, see Appendix A, DITA XSLT Parameter Sets.

Chapter 3. Publishing DITA Documents

DITA documents can be published to HTML and PDF format.

DITA documents are published with DITA Open Toolkit V1.4 that requires installation of Java not older than J2SE v 1.4.2_08:

Installing Java on Windows:

Download J2SE v 1.4.2_08 JRE at http://java.sun.com/products/archive/j2se/1.4.2_08/index.html.
Install J2SE v 1.4.2_08 JRE.
Set the environment variable for JAVA_HOME.
1. From the Start Menu, select Start->Settings->Control Panel.
2. Double-click System to open the System Properties window.
3. On the Advanced tab, click Environment Variables .
4. Click New under the System variables section.
5. Type JAVA_HOME in the Variable name field.
6. Type <JAVA_INSTALL_PATH>\j2re1.4.2_08 in the Variable value field.
7. Click OK.
Note

The instructions are given for Classic Start menu and Classic View of Control Panel.

Installing Java on Linux:

Download J2SE v 1.4.2_08 JRE at http://java.sun.com/products/archive/j2se/1.4.2_08/index.html.
Install J2SE v 1.4.2_08 JRE.
Set the environment variable for JAVA_HOME.

Let's publish colors.ditamap:

Open the document in Serna.
Click the Publish button on the toolbar (or press Ctrl-P, or choose Document->Publish).
In the Publish Dialog:
- From the Publishing output drop-down list, select HTML DITA Map.
- Click Generate and wait until the script ends.
- Click View and the generated HTML DITA Map file will be opened in your browser.
  
  Click the link "Cool Colors".
- The file will be opened.

Appendix A. DITA XSLT Parameter Sets

We touched upon XSLT Parameter Sets in the section called “Resolving Topic References in Map”and the section called “Making Conrefs Explicit”, where we switched between the sets to change the view of a document.

This appendix deals with specifics of DITA XSLT Parameter Sets only. For general information about what an XSLT Parameter Set is, how to switch between sets, edit and save them, please see the Syntext Serna Basics Tutorial, Chapter 4. XSLT Parameter Sets.

The following table provides a summary of XSLT Parameter Sets available for all DITA topics, i.e. Topic, Concept, Task, Reference, Composite and Glossary.

Table A.1. DITA Topics XSLT Parameter Sets

XSLT Parameter Set	Effect
Default View	Resolves `conref`s; Displays `prolog`s.
Hide Prolog	Hides `prolog`s.
Edit Conrefs	Displays unresolved `conref`s highlighted with blue; Displays the path to the target element (the value of the `conref` attribute).

The following table provides a summary of XSLT Parameter Sets available for DITA maps, i.e. Map and Bookmap.

Table A.2. DITA Maps XSLT Parameter Sets

XSLT Parameter Set	Effect
Default View	Displays titles extracted from referenced topics and links to topics (unresolved `topicref`s); Resolves `conref`s.
Show Descriptions	Displays the `shortdesc` information of referenced topics.
Show Resolved	Resolves `topicref`s showing the content of referenced topics.
Edit Conrefs	Displays unresolved `conref`s highlighted with blue; Displays the path to the target element (the value of the `conref` attribute).