dita training handboook - sdigs.com · dita ov dita (darwin information, s dita is topic • makes...

27
DIT TA Tra ain ing g Ha and dboo ok

Upload: others

Post on 25-Mar-2020

16 views

Category:

Documents


2 download

TRANSCRIPT

Page 1: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

DITTA

Traainingg Haanddboook

Page 2: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

Contents

List of figures. ................................................................................................................................................ iii

List of tables ................................................................................................................................................... iv

Preface.................................................................................................................................................................................................... About this guide......................................................................................................................................................................................................................................................... Conventions.....................................................................................................................................................................................................................................................................

Chapter 1: Module 1. ......................................................................................................................................... 5 1.1 DITA overview .................................................................................................................................................. 5 1.2 Topic types. ..................................................................................................................................................... 5

1.2.1 Concept. .............................................................................................................................................. 5 1.2.2 Task ................................................................................................................................................... 5 1.2.3 Reference ........................................................................................................................................... 6

1.3 Folder structure. ............................................................................................................................................... 6 1.3.1 Naming convention. ............................................................................................................................. 7

1.4 DITA map structure. ......................................................................................................................................... 8 1.5 Tags (most often used) .................................................................................................................................... 9

1.5.1 Inline tags. ........................................................................................................................................... 9 1.5.2 Block elements. .................................................................................................................................. 10 1.5.3 Special tags. ........................................................................................................................................ 11

1.6 Tables and table formatting options. ................................................................................................................ 12 1.7 Setting up tools. .............................................................................................................................................. 14

1.7.1 Customizing Oxygen. .......................................................................................................................... 14 1.7.2 Setting up the stylesheet.................................................................................................................... 16

Chapter 2: Module 2. ...................................................................................................................................... 17 2.1 Reuse ............................................................................................................................................................. 17

2.1.1 Adding a cross reference. ................................................................................................................... 17 2.1.2 Adding a key reference....................................................................................................................... 18 2.1.3 Adding a content reference. .............................................................................................................. 20

2.2 Attributes ....................................................................................................................................................... 21 2.3 Filtering .......................................................................................................................................................... 22

2.3.1 Adding a filter. ................................................................................................................................... 22 2.3.2 Creating a ditaval file. ........................................................................................................................ 23 2.3.3 Using the ditaval file in the build ....................................................................................................... 24

2.4 Version control. .............................................................................................................................................. 26 2.5 Metadata ........................................................................................................................................................ 27

Appendix A: Where to get more information ................................................................................................ 28

Page 3: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

List of figures iii

List of figures

Figure 1: Standard concept topic. .............................................................................................................................. 5

Figure 2: Standard task topic. ................................................................................................................................... 6

Figure 3: Standard reference topic. ........................................................................................................................... 6

Figure 4: Folder structure ................................................................................................................................................. 7

Figure 5: Map open in map manager ................................................................................................................................ 8

Figure 6: Map open in author mode ................................................................................................................................. 9

Figure 7: Adding a table element ..................................................................................................................................... 12

Figure 8: Table wizard. .................................................................................................................................................... 12

Figure 9: Formatting a table. ........................................................................................................................................... 13

Figure 10: Table column width. ........................................................................................................................................ 13

Figure 11: Window layout of the Oxygen editor................................................................................................................. 14

Figure 12: Show View. ...................................................................................................................................................... 15

Figure 13: Oxygen Preferences window. ........................................................................................................................... 16

Figure 14: Adding a filter. ................................................................................................................................................ 23

Figure 15: Filter showing in Maps Manager ...................................................................................................................... 23

Figure 16: Filter showing in ditamap Author view ............................................................................................................. 23

Figure 17: Creating a ditaval file in Oxygen ..................................................................................................................... 24

Figure 18: Ditaval template location. ................................................................................................................................ 24

Figure 19: Ditaval file in folder structure .......................................................................................................................... 24

Figure 20: Accessing the Configure Transformation Scenario(s) window ........................................................................... 25

Figure 21: Adding the ditaval file to the scenario. ............................................................................................................. 26

Figure 22: Metadata in topics. .................................................................................................................................. 27

Page 4: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

List of tables

Table 1: Conventions....................................................................................................................................................................................................................................................................

Table 2: Inline tags .......................................................................................................................................................... 9

Table 3: Block elements .................................................................................................................................................. 10

Table 4: Special tags ........................................................................................................................................................ 11

Table 5: Attributes .......................................................................................................................................................... 21

Page 5: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

Ch

Mo

1.1

1.2

1.2.

1.2.

hapter 1

odule 1

DITA ovDITA (Darwininformation, s

DITA is topic

• makes un• helps colla• provides c

Topic tA topic is a u

Topics have e

NOTE

Some

.1 ConcepThe concept A descriptionEverything th

Figure 1: Sta

.2 Task A task topic isomething (a

1

verviewn Information Tsuch as for onl

oriented. The

its reusable aboration consistency

types nit of informat

elements that

E:

e elements are

pt topic type is th

n or explanatiohat does not fit

ndard concep

s a procedure lso see the Sty

w Typing Architeine help, docu

content is bui

ion that is mea

are required a

not allowed in

he most allowin of a topic that into a task to

pt topic

that has distinyle guide).

ecture) is a momentation, and

lt from small u

aningful when

t minimum and

n certain topic

ng of all topicsat goes beyonpic or referenc

nctive steps to

odular and exted training.

units that are se

it stand on its

d you can add

types, and not

s. Use the concd a simple glosce ends up a co

reach a goal. T

ensible XML-b

elf-contained.

own.

optional elem

t all elements c

cept topic to gssary definitiooncept.

The title shoul

based language

This approach

ments as requir

can be nested.

ive backgrounn. It answers th

d indicate this

e for topic-bas

h:

ed by your con

nd information he question, W

, for example C

Module 1 5

ed

ntent.

on somethingWhat is this?.

Configuring

.

Page 6: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.2.

1.3

Figure 2: Sta

.3 RefereThe topic coninformation yto be read on

Figure 3: Sta

Folder

Following are

• There is a• All DITA m• There is a

images an

andard task to

ence ntains referencyou would comnce, then it mo

andard referen

structu

e the rules to fo

an _images amaps are in thea folder for eacnd the files in r

opic

ce type informame back to seve

re likely fits int

nce topic

re

ollow when cre

and _reuse foe root directorh DITA map, w

reuse.

ation. The coneral times, for eto a concept to

eating or editin

older in each py for the produ

with the same

tent in this topexample a list aopic.

ng files belongi

product folder. uct. name, that con

pic is usually aand descriptio

ing to a DITA

ntains the dita

table or definon of command

map or project

files for the m

ition list. This ids. If the inform

t:

map. Only excep

Module 1 6

is the type of mation is only

ptions are

Page 7: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.3.

Figure 4: Fol

NOTE

The frefere

.1 Namin

Following are

• A well-for"_". The na

– Name

– Suffix • Use only l• The key, d• Make sure

NOTE

Using

Example

report

report

lder structure

E:

folder structureences. Use the

g conven

e the rules for n

med topic file ame has two p

describing the

_t, _c, or _r lowercase lettedescribed latere image names

E:

g spaces, punc

ts_creating

ts_overview

e

e of a project m svn structure

ntion

naming files:

name has a naarts:

e content

to identify theers, no punctuar, should matchs are self-expla

tuation and nu

g_t.dita

w_c.dita

must be identic as best practic

ame that descr

topic type of tation, and no nh the file nameanatory.

umbers in file n

cal on every wce.

ribes the conte

task, concept, numbers. e.

names will resu

riters system f

ent and any se

reference resp

ult in failure to

for the relative

eparation is do

pectively

build the outp

e paths to work

ne by using by

put.

Module 1 7

k in the

y underscores

Page 8: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.4

4 DITA m

The DITA ma

Figure 5: Ma

To link the to

There are som

• Stick to th• As a minim

– Notice– Bookli– Prefac

• The map • When sett

The cover paPackage Insta

report

map stru

ap collects and

p open in map

opics the href

me basic rules

he agreed convmum in the fro

es st section with

ce with the reqis arranged intting up a new

ge picks up eleallation and Us

ts_structur

ucture

d stores topics

p manager

f attribute of th

to adhere to:

vention of the ontmatter have

h: a TOC, Figuruired elementsto Chapters anmap the easie

ements from tsage Guideline

re_r.dita

in a structure.

he topicref

product's mape:

e list, and Tabs.

nd Appendicesst is to copy a

he bookmap. Tes in the styles

It is a collectio

f element is us

p structure.

le list.

s. working map,

The details areheet customiz

on of reference

sed.

and use it as a

e described in tation folder.

es.

a base.

the DITA Styleesheet Custom

Module 1 8

mization

Page 9: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.5

1.5.

NOTE

From

Figure 6: Ma

Tags (m

.1 Inline t

Table 2: Inlin

Tag

p

cite

cmdname

codeph

E:

the cover pag

p open in aut

most oft

tags

ne tags

ges we use the

hor mode

ten use

manwomanta

d)

Description

A paragraph

The <cite> ela book or art

The commancommand wh

The code phthe main flowfor emphasis

ablet cover

element (<p>)

ement is usedticle. It specific

nd name (<cmdhen it is part o

hrase (<codephw of text. The cs.

page as a defa

) is a block of t

when you neeally identifies t

dname>) elemof a software di

h>) element repcode phrase is

ault.

text containing

ed a bibliograpthe title of the

ment specifies tiscussion.

presents a snips displayed in a

g a single main

phic citation th resource.

the name of a

ppet of code wa monospaced

Module 1 9

n idea.

hat refers to

within font

Page 10: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

Module 1 10  

Tag Description

filepath The <filepath> element indicates the name and optionally the location of a referenced file by specifying the directory containing the file, and other directories that may precede it in the system hierarchy.

menuacascade

uicontrol

The user interface control (<uicontrol>) element is used to mark up names of buttons, entry fields, menu items, or other objects that allow the user to control the interface. Use the <uicontrol> element inside a <menucascade> element to identify a sequence of menu choices in a nested menu, such as File > New.

paramname When referencing the name of an application programming interface parameter within the text flow of your topic, use the parameter name (<parmname>) element to markup the parameter.

ph The phrase (<ph>) element is used to organize content for reuse or conditional processing (for example, when part of a paragraph applies to a particular audience).

sub A subscript (<sub>) indicates that text should be subscripted, or placed lower in relationship to the surrounding text.

sup systemoutput

The superscript (<sup>) element indicates that text should be superscripted, or vertically raised in relationship to the surrounding text.

The system output (<systemoutput>) element represents computer output or responses to a command or situation.

userinput The user input (<userinput>) element represens the text a user should input in response to a program or system prompt.

varname The variable name (<varname>) element defines a variable that must be supplied to a software application.

wintitle The window title <wintitle> element can be used to mark up names of windows or dialogs, or other user interface elements at the same level of grouping, including wizard titles, wizard page titles, and window pane titles.

1.5.2 Block elements

Table 3: Block elements

Tags Description

codeblock The <codeblock> element represents lines of program code. Content of this element has preserved line endings and is output in a monospaced font. Use this element for blocks of codes/commands that the user needs to type in. Used to show what to input.

Page 11: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

Module 1 11  

Tags Description

example

screen

The <example> element is a section with the specific role of containing examples that illustrate or support the current topic. The < example> element has the same content model as < section>. DITA uses < example> to contain both discussion and sample code or outputs. Hence, in a DITA topic, to represent programming code and results within the discussion in an example, use the < codeblock> and < systemoutput> elements within the example element. For lines of text, use the < lines> element. For pre-formatted text such as email headers, use the < pre> element.

The <example> element must be the last element in the body of the topic. The <screen> element contains or refers to a textual representation of a computer screen or user interface panel (window). Use this element for blocks of codes/ commands that are displayed by the system. Used to show the output.

stepxmp The step example <stepxmp> element is used to illustrate a step of a task. The example can be a couple of words, or an entire paragraph.

1.5.3 Special tags

Table 4: Special tags

Tag Description

fig The figure (<fig>) element is a display context (sometimes called an exhibit) with an optional title for a wide variety of content. A title is placed inside the figure element to provide a caption to describe the content. Use this element for adding images.

note A <note> element contains information, differentiated from the main text, which expands on or calls attention to a particular point. The type of the note can be set by the type attribute (for example, caution, danger, note, etc.). Always use a <p> element inside the note element.

ul In an unordered list (<ul>), the order of the list items is not significant. List items are typically styled on output with a "bullet" character, depending on nesting level.

A list (<li>) item is a single item in an ordered <ol> or unordered <ul> list.

ol An ordered list (<ol>) is a list of items sorted by sequence or order of importance.

dl A definition list (<dl>) is a list of terms and corresponding definitions. The term (<dt>) is flush left. The description or definition (<dd>) is usually either indented and on the same line to the right of the term.

In a definition list, each list item is defined by the definition list entry (<dlentry>) element. The definition list entry element includes a term <dt> and one or more definitions or descriptions <dd> of that term.

Page 12: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.6

Tag

draft-comme

Tables

Tables can be

Figure 7: Add

You can spec

Figure 8: Tab

ent

and tab

e added like ot

ding a table e

cify parameters

ble wizard

ble form

ther elements,

element

s of the table in

Description

The <draft-ccontents witha question othe source otime or dispo

matting

either manual

n the wizard, b

omment> elemhin the markedr make a commf the draft comosition attribut

options

lly, or by using

but these can b

ment allows simd-up content. Ument that you mment or the stes.

s

the table wiza

be changed lat

mple review anUse the <draft would like othstatus of the co

ard.

ter, as necessa

nd discussion ot-comment> elehers to review. omment, use th

ry.

Module 1 12

of topic ement to ask To indicate he author,

2

Page 13: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

All tables sho

Tables can be

• Add row/c• Insert an e• Remove r• Join or sp

Figure 9: For

The width of values. It is rewould take by30% of the ot

Figure 10: Ta

The table celthe content dto the followi

• apiname • codeph • cmdname• filepath • varname

For more info

ould have a title

e formatted us

column entry ow/column

plit cells horizon

rmatting a tab

the columns cecommended ty default, fillingther column, by

able column w

l auto wraps codoes not overflng elements:

e

ormation see th

e, which will sh

sing the toolba

ntally or vertic

ble

can be controllthat the width g the availabley setting one t

width

ontent, but canow the cell yo

he DITA Styles

how in the List

ar icons, or in x

ally

ed by droppin of the column space and havto 1.0* and the

n not break lonu can set the o

sheet Customiz

of Tables gen

xml mode. The

g the colspecs is specified prving an equal other to 0.3*.

ng words that outputclass att

zation Package

nerated for the

toolbar has op

s option down roportionally. T width. You can

do not containtribute to force

e guide in the

e map, and a he

ptions to:

(under the taThe value 1.0* n make one co

n a space charae-break. This fu

customization

eader row.

ble title) and sis the width th

olumn smaller, f

acter. To forceunctionality is

n package.

Module 1 13

setting the hat columns for example

e a linebreak so only available

3

o

Page 14: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.7

1.7.

Setting

.1 CustomThe Oxygen

Pink

Yellow

Blue

Green

Figure 11: Wi

To open add

g up too

mizing OXML editor wi

indow layout

itional window

ols

Oxygen ndow layout is

the map

an open

additiona

other vie

of the Oxygen

w elements use

s customizable

manager wind

dita file (with s

al views can be

ws minimized

n editor

the Window →

e, so it can be s

dow

several open fi

e displayed (at

on the side

→ Show View

set up in any w

les next to it)

ttributes are op

w option of the

way that is com

pen in this exa

e Menu bar.

mfortable for yo

mple)

Module 1 14

ou.

4

Page 15: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

Figure 12: Sh

Other import

Various optio

• how tags • enableme

how View

ant customiza

ons can be set

are displayed ent of spell che

ble settings ar

in the Preferen

in the author -eck - recomme

re in the Optio

nces. Just to m

- recommendended to have i

ons → Prefere

mention some o

ed to set to Fult on

ences option o

of the most im

l Tags for easi

of the Menu ba

portant:

iest reading (s

ar.

hown below)

Module 1 155

Page 16: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

1.7.

Figure 13: Ox

.2 Setting

IMPO

You m

xygen Prefere

g up the

ORTANT:

must be conne

ences window

styleshe

ected to the ne

w

eet

etwork to reach the SVN document repos

itory.

Module 1 166

Page 17: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

Ch

Mo

2.1

2.1.

hapter 2

odule 2

Reuse

One of the beintroduction wDITA Tricks fat the referen

Cross refere

Key referen

Content refe

.1 Adding

Before you Make sure th

Procedure

1. Right-clic

2

2

enefits of DITAwe will mostly for Dummies. Wnce location:

ence

nce

erence

g a cross

begin at the item to

k on the tags o

A is that eleme look at the hoWith the follow

Places a topic. If thhave a br

Places a gets resoFor a key

Displays on the soreused co

s referen

be referenced

of the item to b

nts that are rew to do it and

wing reuse type

reference link. he referenced roken link. With

reference link. olved at map ley reference a k

the whole refeource. Use this ontent.

nce

has an id.

be referenced

peatedly used not at the whyes you can eith

Recommende topic is removh a cross refer

Recommendeevel. So if the rekey or id mus

erenced conten for keywords

and copy, or u

d, can be referey. For a more dher place a link

ed to use withinved it will not gence an href

ed to use acroseferenced top

st be defined o

nt. For a conte that are in you

use ctrl-c after

enced from onedetailed descrik, or can displa

n topic. Do notgive an error anf is used to ref

ss topics and aic is removed t

on the referenc

nt reference yur reuse file an

selecting the t

M

e location. In thption on reusey the whole re

t use to refer fnd your built der.

at map level. Tthe map gives ced topic/part.

ou must have nd for small chu

tag.

Module 2 17

his e, refer to the eusable conten

rom outside document will

This reference you an error.

an id definedunks of

t

d

Page 18: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.1.

2. Right-clic

Results

This is how th

.2 Adding

About this t

There is moreinstead of Pa

Another meth

Procedure

1. If the topi

k the location

he finished link

g a key r

task

e than one measte as link, ch

hod is describe

c does not hav

to insert the re

k looks in auth

reference

thod to use keoose the Past

ed in this proce

ve a key define

eference to an

or mode:

e

ey references. Tte as link (key

edure. This me

ed, right-click t

d choose the P

The same metyref) option.

ethod can be u

the topic in the

Paste special

thod as in Add

used to use key

e map manage

→ Paste as li

ing a cross ref

y reference to

er, and choose

M

ink option.

ference on pag

link to topics.

Edit properti

Module 2 18

ge 17, but

es.

Page 19: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2. Set the ke

3. Move the

4. Choose th

ey to the same

cursor to whe

he correct key.

name as the t

re the link nee

topic, except th

eds to be insert

he topic type s

ted, and use th

suffix.

he link tool (eitther on the too

M

olbar or in DIT

Module 2 19

TA → Link).

Page 20: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.1.

Results

.3 Adding

About this t

Use content r

Procedure

1. Ensure th

2. Right-clic

3. At the loc

g a conte

task

reference for p

at the reusable

k on the tag of

ation, where y

ent refer

product name,

e content has

f the reusable

ou want the co

rence

reusable notes

an id.

content and co

ontent to appe

s, and other ch

opy, or use ctr

ear, right-click

hunks of text.

rl-c after select

and use Paste

ting the tag.

e Special → P

M

Paste as conte

Module 2 20

ent reference.

0

Page 21: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.2

Results The content a

NOTE

Contesure t

2 Attribu

Attributes ha

All elements,

• help ident• control th

Not all attribuvalues.

Table 5: Attr

Element

apiname

codeph

cmdname

filepath

varname

image

note

appears. Clicki

E:

ent referencedto check if the

utes

ve been used

and also maps

tifying the eleme behaviour of

utes are used o

ributes

A

o

sc

ty

ng on the refe

d material can o edit is approp

throughout th

s, have attribut

ment f the specific e

of course. The

Attribute

utputclass="fo

calefit="yes" O

ype

erence in autho

only be edited priate at everyw

e training, so t

tes that:

element

following table

orce-break"

R width OR he

or mode takes

at the source.where the cont

this is not new,

e contains the

eight can be se

you the sourc

. Please be cartent is used.

, but it is impo

most often us

Descrip

Contento fit avfunctiocontainuse thethe tagfirst co

et With scresizedspecific

DiffereThe detype toAlert te

e of the reuse.

reful when edit

ortant to under

sed attributes,

ption

nt in table cellsvailable space

on does not bren a space charae outputclass=g. Only workinglumn.

calefit="yes" sed to fit availablec width or heig

nt type of noteefault is note. Fo use see the mext section.

M

.

ting reused con

rstand the con

their elements

s is automatica in the cell. Theeak long wordsacter. To break

="force-break" ag on the eleme

et the image is e space. Altern

ght can be set

es result in diffFor informationmost up to date

Module 2 21

ntent. Make

cept.

s, and their

ally wrapped e auto wrap s that do not k a long word attribute on ents of the

automatically natively, for the image.

ferent output. n on which e Style Guide,

Page 22: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

Module 2 22  

Element Attribute Description

topicref processing-role="resource-only" Specifies whether the topic or map referenced should be processed normally or treated as a resource that is only included in order to resolve key or content references. Topics with this attribute don't get processed into the output.

various id This ID is the target for references.

various status="new" OR status="deleted" Can indicate new or deleted elements. See the Style Guide, Change tracking markup in the PDF and WebHelp output

2.3 Filtering

Filtering allows to get a variety of outputs from the same guide.

There are filters on various projects. Consult the lead writer or project manager for more information on the specific project. They can tell you what filters are used and why. You need to be aware how to build the correct output for the client.

The process to add a filter from scratch is:

1. Adding a filter on page 22 2. Creating a ditaval file on page 23 3. Using the ditaval file in the build on page 24

NOTE:

If the ditaval file is already created for the project, only the first procedure must be followed.

2.3.1 Adding a filter

About this task

Filters, or confitional formatting, can be added at map or topic level. A filter is an attribute that takes a arbitary value, which must be agreed with writers working on the same project. This attribute can be, but is not limited to:

• audience • product • platform • ...

As an example in the following task we will add a filter so that the Linux platform specific content will not show in the built document. Here, we will identify what we want to exclude in our Linux filter, but bear in mind that we might want the same content to appear in another build. So filtering is not only about excluding the content. It is more about specifiying which part of the content belongs to which build scenario.

Procedure

Identify the content you would like to filter.

In this example we will filter on map level so I open the ditamap and select the topic to place the filter on and add the linux value to the platform attribute.

Page 23: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.3.

Figure 14

N

Mpl

Oto

Results After saving t

Figure 15: Fil

Figure 16: Fil

What to do The filter is nditaval file on

.2 Creati

About this t

A special file project. Creatinclude or exc

NOTE

This pLead

4: Adding a filt

OTE:

ultiple filter valatform attr

n that note, doo make the nam

the map it will

lter showing i

lter showing i

next ow added, but

n page 23 and U

ng a dita

task

must be createted the ditavclude.

E:

procedure nee Writer or Proje

ter

alues can be adribute on the sa

o not uses spacme more reada

show on the to

n Maps Mana

in ditamap Au

t is currently juUsing the ditav

aval file

ed to use a filtval file on the

ed only to be foect Manager.

dded on the saame topic, we

ces in the filterable.

opic and a blu

ger

uthor view

ust sittinge theval file in the b

er. This only n ditamap lev

ollowed if the p

ame attribute. I eould only nee

r names as the

e icon appears

re. To create abuild on page 2

eed to be creavel of the folde

project does no

If we wanted ted to separate

e build will con

s next to it in t

a ditaval file24.

ated once and er structure. Th

ot already hav

o add both lie them with a s

sider them as

he Maps Mana

e and use it in

can be used fohe ditaval f

ve a ditaval

M

inux and nskspace.

two separate f

ager.

the build, see

or multiple mafile will tell the

file created. C

Module 2 23

k to the

filters. Use "_"

Creating a

ps in the same build what to

heck with the

3

e

Page 24: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.3.

Procedure

1. Created a

There is a

Figure 17

2. Choose th

Figure 18

This step

3. Modify th

In our exa

4. Save the d

Figure 19

.3 Using

About this t

We will not as

ditaval file

a template file

7: Creating a d

he ditaval f

8: Ditaval temp

will create a te

e template val

ample we add t

ditaval file on t

9: Ditaval file i

the dita

task

ssociate the di

e in Oxygen.

in Oxygen in F

ditaval file in O

ile template fro

plate location

emplate with s

ues according

the platform

the same level

n folder struc

val file in

itaval file a

File → New.

Oxygen

om the window

n

ome placehold

to the filter yo

m attribute wit

as your ditam

cture

n the bu

build scenario

w.

der values.

ou want to add

th the linux v

aps for this pr

ild

o.

d.

value to be ex

roject.

cluded.

MModule 2 244

Page 25: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

NOTE

If the steps

Procedure

1. Open the

Click DITA

Figure 20

2. Duplicate

3. Give the s

E:

project alread are not necce

Configure Tr

A Maps → Co

0: Accessing t

or create a ne

scenario a mea

dy has a ditavessary. Check w

ansformation

onfigure Trans

he Configure

ew build scenar

aningful name

val file, the scwith the Lead W

n Scenario(s) w

sformation Sc

Transformati

rio.

and add the a

cenario might Writer or Proje

window.

cenario(s) or s

ion Scenario(s

pproprite dit

be included inect Manager.

select the icon

s) window

taval file to th

the project. In

from the toolb

he Filters tab.

M

n this case the

bar.

Module 2 25

follwoing

5

Page 26: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.4

Figure 21

4. Save the s

The build

4 Versio

SVN is used f

• keep track• manage m• safely sto• reach the

When used ridifficult, but m

Folder structhe same levfolder struc

: Adding the d

scenario.

will be automa

on contr

for version con

k of all changemultiple peoplere everything i material from

ght, this can bmust be kept in

cture to stay avel as the svnture

ditaval file to

atically associa

ol

ntrol. This enab

es in files and pe working on thin one central anywhere whe

be a really helpn mind when c

at n

If the levecommit t

the scenario

ated with the m

bles us to:

projects he same projecrepository ere internet co

ful tool. It is escommitting to t

els in the struchem, they will

map. This can b

ct

onnection is av

ssential that evthe repository.

cture change, t not work for a

be chnaged at

vailable

veryone follows.

the relative linkanyone else.

t any time if ne

s the same pra

ks will not wor

M

eccessary.

actices. These

k for you. If yo

Module 2 26

are not very

u change and

6

Page 27: DITA Training Handboook - sdigs.com · DITA ov DITA (Darwin information, s DITA is topic • makes un • helps colla • provides c Topic t A topic is a u Topics have e NOTE Some

 

2.5

Update befo

Put Ignore oto be comm

Commit mes

5 Metada

Using (or not

The specific This section ispecific topic

This method

Figure 22: M

ore commit

on things nevitted

ssages

ata

t using) metad

topics we instas not visible in here. Standard

can be helpfu

etadata in top

Update yfind confyour pee

er If you havigonre lisnot alrea

Add a shthe projeyou or an

ata to track pr

alled in Settingn the build. If yod map-wide se

l if the edits ar

pics

your project belicts you must rs. Don't be sh

ve any files or st. For exampledy checked int

ort, but meaniect name and snyone else can

roject informat

g up the stylesou keep the toearch can then

e done by sev

efore committin resolve them y/lazy, do it!

folders that she, the temp andto svn - can be

ngful commit summarize whan understand w

tion is project s

heet on page 1opics cleaned u be used to fin

eral people or

ng, this way yo before commit

hould not be cod out folders oe ignored.

message on eat you did. The

what you mean

specific. The d

16 contain a seup after each rnd the edited t

in a very large

ou can see if thtting. This mig

ommitted you of the project. O

very commit. Ae message is tont a couple of m

ecision is with

ection where melease, you ca

topics.

e document or

M

here are any coght involve nee

can put them Only unversion

At minimum yoo be written inmonths later.

the lead write

metadata can bn indicate any

r document set

Module 2 27

onflicts. If you eding to talk to

on the svn ned files - files

ou should addn a way so that

er.

be entered. edits to the

t.

7

o