DITA for the ImpatientHussein ShafiePixware SARL91, rue Gambetta78120 - PDF document

DITA for the ImpatientHussein ShafieXMLmind Software35, rue Louis Leblanc78120 RambouilletFrancePhone: +33 (0)9 52 80 80 37xmleditor-support@xmlmind.comditac-support@xmlmind.comwww.xmlmind.com/xmleditor/www.xmlmind.com/ditac/October 15, 2020 DITA for the Impatient Chapter 1. IntroductionBy reading this short tutorial, you'll get acquainted with the DITA markup and after that, you'll be able toauthor your first DITA document(1) right away.This short tutorial will not discuss the DITA ``philosophy'' or the advantages of the DITA vocabulary overother XML vocabularies (e.g. DocBook).This article is published under the Creative Commons "Attribution-Share Alike" license. (1)Preferably using a DITA-aware XML editor such as XMLmind XML Editor. 1 DITA for the Impatient Chapter 2. About topics and mapsA DITA document is necessarily modular. The information unit used to compose a DITA document iscalled a topic. As its name suggests, a topic addresses a single subject.The overall contents of a DITA document are specified using a topic map (also simply called a map). Amap mainly contains a hierarchy of topic references.Figure 2-1. File layout of this tutorial &#xmap0; &#xtitl; 0.;&#x 000;&#x/tit;&#xle00;DITA for the impatient &#xtopi; 0.;&#x 000;ref href="introduction.dita"/ &#xtopi; 0.;&#x 000;ref href="topics_and_maps.dita"/ &#xtopi; 0.;&#x 000;ref href="..."/ ... onc;pt ;&#xid=";«ou;&#xt_to;&#xpics;&#x_and;&#x_map;&#xs"00; &#xtitl;◊&#x/tit;&#xle00; ... tutorial.ditamap introduction.dita topics_and_maps.dita &#xtopi; id;&#x="in;&#xtrod;&#xucti;&#xon"0; &#xtitl;◊&#x/tit;&#xle00; ... ... Remember•It is recommended to have a single topic per XML file.•The recommended filename extension for a topic file is ".dita".•The recommended filename extension for a map file is ".ditamap".•Topic and map files may be contained in different directories. You are free toorganize the contents of these directories as you wish. 3 DITA for the Impatient Chapter 3. The &#xtopi;ℵ elementIn this chapter,we'll first explain the structure of a &#xtopi;ℵ element;then we'll list the most useful “block elements” (paragraph, table, list, etc);then we'll list the most useful “inline elements” (bold, italic, etc);finally, we'll explain how to create internal and external links. Note that creating internal links inDITA, which is inherently modular, is slightly harder than in other, generally-monolithic, documenttypes. Therefore it is important to read this section carefully.1. The structure of the &#xtopi;ℵ element RememberA &#xtopi;ℵ element must always be given an ID. Use the @id attribute to specify it.The structure of the &#xtopi;ℵ element is very simple:1.A &#xtitl;◊ element.2.An optional &#xshor;&#xtdes;ℵ or «st;&#xract; element.The &#xshor;&#xtdes;ℵ element is longer and more descriptive than the &#xtitl;◊ element. However,it is recommended to keep it short, approximately one paragraph long, because the contents of thiselement are often used during navigation (e.g. to generate a detailed table of contents).The «st;&#xract; element is intended to contain more information than the &#xshor;&#xtdes;ℵ element.3.A ody; element(2).4.An optional &#xrela;&#xted-;&#xlink;&#xs000; element.This is a kind of ``See Also'' section containing a list of &#xlink; elements. Topics being generallyshort, this section stands out clearly after the body of a topic. That's why it is often preferred tospreading links inside the body of a topic.Example: 123456789101112 id="docbook_or_dita"&#xtopi;ℵ &#xtitl;◊DITA or DocBook?&#x/tit;&#xle00; &#xshor;&#xtdes;ℵBoth DITA and DocBook are both mature, feature rich, document types, so which one to choose?&#x/sho;&#xrtde;&#xsc00; ody; &#xp000;DocBook 5 is a mature document type. It is well-documented (DocBook: The Definitive Guide, DocBook XSL: The Complete Guide), featuring decent XSL stylesheets allowing conversion to a variety of formats, based on the best schema technologies: RELAX NG and Schematron.&#x/p00; (2)The ody; element is optional too. However creating a &#xtopi;ℵ element having no ody; child element is mainlya trick which is more simply implemented by adding a &#xtopi;hea;∠ to a map. 5 DITA for the Impatient 1314151617181920212223242526272829303132 &#xp000;DITA concepts (topics, maps, specialization, etc) have an immediate appeal to the technical writer, making this document type more attractive than DocBook. However the DocBook vocabulary is comprehensive and very well thought out. So choose DITA if its technical vocabulary is sufficiently expressive for your needs or if, anyway, you intend to specialize DITA.&#x/p00; &#x/bod;&#xy000; &#xrela;&#xted-;&#xlink;&#xs000; format="html" href="http://www.docbook.org/" scope="external"&#xlink; &#xlink;&#xtext;DocBook 5&#x/lin;&#xktex;&#xt000; &#x/lin;&#xk000; format="html" href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=dita" scope="external"&#xlink; &#xlink;&#xtext;DITA&#x/lin;&#xktex;&#xt000; &#x/lin;&#xk000; &#x/rel; ted;&#x-lin;&#xks00;&#x/top;&#xic00; The above example is rendered as follows:DITA or DocBook?Both DITA and DocBook are both mature, feature rich, document types, so which one to choose?DocBook 5 is a mature document type. It is well-documented (DocBook: The Definitive Guide, DocBookXSL: The Complete Guide), featuring decent XSL stylesheets allowing conversion to a variety of formats,based on the best schema technologies: RELAX NG and Schematron.DITA concepts (topics, maps, specialization, etc) have an immediate appeal to the technical writer,making this document type more attractive than DocBook. However the DocBook vocabulary iscomprehensive and very well thought out. So choose DITA if its technical vocabulary is sufficientlyexpressive for your needs or if, anyway, you intend to specialize DITA.Related information• DocBook 5• DITA2. The most commonly used “block elements”The most commonly used block elements are borrowed from HTML and as such, should be immediatelyfamiliar to the reader.Paragraphs and listsA paragraph is represented by the &#xp000; element.A preformatted paragraph is represented by the &#xpre0; element.An itemized list is represented by the &#xul00; element. As expected, it contains &#xli00; list item elements.An ordered list is represented by the &#xol00; element. 6 Chapter 3. The topic element DITA for the Impatient A variable list is represented by the l00; element. Unlike HTML's l00;, the t00; (term being defined)and the � (term definition) elements must be wrapped in a len;&#xtry0; element.Example: 123456789101112131415161718192021222324252627 &#xul00; &#xli00;First item. &#xp000;Continuation paragraph.&#x/p00; &#x/li0; &#xli00;Second item. This item contains an ordered list. &#xol00; &#xli00;First do this.&#x/li0; &#xli00;Then do that.&#x/li0; &#xli00;Finally do this.&#x/li0; &#x/ol0; &#x/li0; &#xli00;Third item. This item contains a variable list. l00; len;&#xtry0; t00;Term #1&#x/dt0; �Definition of term #1.&#x/dd0; &#x/dle;&#xntry; len;&#xtry0; t00;Term #2&#x/dt0; �Definition of term #2.&#x/dd0; &#x/dle;&#xntry; &#x/dl0; &#x/li0;&#x/ul0; The above example is rendered as follows:•First item.Continuation paragraph.•Second item. This item contains an ordered list.1.First do this.2.Then do that.3.Finally do this.•Third item. This item contains a variable list.Term #1Definition of term #1.Term #2Definition of term #2. 2. The most commonly used “block elements” 7 DITA for the Impatient SectionsDITA has no &#xh100;, &#xh200;, &#xh300;, etc, heading elements. Instead it has the &#xsect;&#xion0; element whichgenerally always has a &#xtitl;◊ child element. Note that &#xsect;&#xion0; elements cannot nest. Example: 123456 &#xsect;&#xion0; &#xtitl;◊The customary “hello word” program in Tcl/Tk&#x/tit;&#xle00; frame="all"&#xpre0;button .hello -text "Hello, World!" -command { exit } pack .hello&#x/pre;&#x/sec;&#xtion; The above example is rendered as follows:The customary “hello word” program in Tcl/Tk button .hello -text "Hello, World!" -command { exit }pack .helloFigures and examplesOf course, DITA has also figure, table and example elements.The xam;&#xple0; element is just a specialized kind of &#xsect;&#xion0;.The ig0; element generally has a &#xtitl;◊ and generally contains an &#ximag;◊ element.Like &#ximg0;, its HTML counterpart, the &#ximag;◊ “inline element” may be contained in any “blockelement”. The graphics file to be displayed is specified using the &#xhref; attribute. The &#ximag;◊ elementalso has @width, @height, @scale and @align attributes.Example: 12345678910 xam;&#xple0; &#xtitl;◊Converting a color image to black and white&#x/tit;&#xle00; &#xpre0;$ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gif&#x/pre; ig0; &#xtitl;◊The photo converted to black and white&#x/tit;&#xle00; href="bwphoto.gif" align="center"&#ximag;◊/ &#x/fig;&#x/exa;&#xmple; The above example is rendered as follows:Converting a color image to black and white $ convert -dither Floyd-Steinberg -monochrome photo.png bwphoto.gifFigure 3-1. The photo converted to black and white 8 Chapter 3. The topic element DITA for the Impatient TablesDITA has two kinds of table element: &#xsimp;&#xleta;le0; which is specific to DITA, and &#xtabl;◊ which isin fact a CALS table (also know as a DocBook table).&#xSimp;&#xleta;le0; example: 12345678910111213141516171819 relcolwidth="1* 2* 3*"&#xsimp;&#xleta;le0; &#xsthe;관 &#xsten;&#xtry0;A&#x/ste;&#xntry; &#xsten;&#xtry0;B&#x/ste;&#xntry; &#xsten;&#xtry0;C&#x/ste;&#xntry; &#x/sth; &#xstro;&#xw000; &#xsten;&#xtry0;A,1&#x/ste;&#xntry; &#xsten;&#xtry0;B,1&#x/ste;&#xntry; &#xsten;&#xtry0;C,1&#x/ste;&#xntry; &#x/str;&#xow00; &#xstro;&#xw000; &#xsten;&#xtry0;A,2&#x/ste;&#xntry; &#xsten;&#xtry0;B,2&#x/ste;&#xntry; &#xsten;&#xtry0;C,2&#x/ste;&#xntry; &#x/str;&#xow00;&#x/sim;&#xplet;«le; A &#xsimp;&#xleta;le0; element contains an optional &#xsthe;관 element, followed by one or more &#xstro;&#xw000;elements. Both row elements, &#xsthe;관 and &#xstro;&#xw000;, contain &#xsten;&#xtry0; cell elements. The@relcolwidth attribute may be used to specify the relative width of each column.The above example is rendered as follows: A B C A,1 B,1 C,1 A,2 B,2 C,2 Same as above example but using a CALS &#xtabl;◊ this time: 1234567891011121314 &#xtabl;◊ &#xtitl;◊Sample CALS table&#x/tit;&#xle00; cols="3"&#xtgro;&#xup00; colwidth="1*"ols;&#xpec0;/ colwidth="2*"ols;&#xpec0;/ colwidth="3*"ols;&#xpec0;/ &#xthea;∠ &#xrow0; align="center"ntr;&#xy000;A&#x/ent;&#xry00; align="center"ntr;&#xy000;B&#x/ent;&#xry00; align="center"ntr;&#xy000;C&#x/ent;&#xry00; &#x/row; 2. The most commonly used “block elements” 9 DITA for the Impatient 1516171819202122232425262728293031 &#x/the;관 &#xtbod;&#xy000; &#xrow0; ntr;&#xy000;A,1&#x/ent;&#xry00; ntr;&#xy000;B,1&#x/ent;&#xry00; ntr;&#xy000;C,1&#x/ent;&#xry00; &#x/row; &#xrow0; ntr;&#xy000;A,2&#x/ent;&#xry00; ntr;&#xy000;B,2&#x/ent;&#xry00; ntr;&#xy000;C,2&#x/ent;&#xry00; &#x/row; &#x/tbo; y00; &#x/tgr;&#xoup0;&#x/tab;&#xle00; CALS tables are quite complex and explaining how they can be used is out of the scope of this tutorial.Our recommendation is to use CALS tables rather than &#xsimp;&#xleta;le0;s only when you want a cell tospan more than one row and/or more than one column.The above example is rendered as follows:Table 3-1. Sample CALS table A B C A,1 B,1 C,1 A,2 B,2 C,2 3. The most commonly used “inline elements”The most generic inline elements are also borrowed from HTML: &#xi000; (italic), 뀀 (bold), &#xtt00; (teletypeor monospaced text), &#xsub0; (subscript), &#xsup0; (superscript).However like with any other document type, you should always try to use the most specific element foryour needs. Examples:•If you need to specify a filename, do not use &#xtt00;, instead use ile;&#xpath;.•If you need to specify a variable, do not use &#xi000;, instead use &#xvarn; me0;.•If you need to specify the name of a command, do not use 뀀, instead use mdn; me0;.DITA has dozens of such useful inline elements. In order to use them, we recommend authoring yourdocuments with a DITA-aware XML editor and browsing through the element names suggested by theeditor. Generally these names are very descriptive, so there is no real need to read the documentation. RememberUsing the most specific elements rather than the generic &#xi000;, 뀀, &#xtt00; elements, meansgetting nicer deliverables.Example: Let's suppose you want to refer to the "Open" item of the "File" menu. Donot type &#xtt00;&#xtt00;&#x/tt0; which would be rendered as: &#x/tt0;File-Open. Instead 10 Chapter 3. The topic element DITA for the Impatient List of Tables3-1.Sample CALS table ................................................................................................................... 10 iv DITA for the Impatient type &#xmenu;Êsc;균&#xuico;&#xntro;&#xl000;&#x/uic;&#xontr;&#xol00;&#xuico;&#xntro;&#xl000; ￿&#x/men;&#xucas;쫞uicontrol, which will be rendered as: File ® Open. Much nicer,isn't it?See &#xuico;&#xntro;&#xl000; and &#xmenu;Êsc;균.4. The &#xxref; and &#xlink; elementsDITA has two elements which allow specification of internal or external links: &#xxref; and &#xlink;.The &#xxref; “inline element” may be contained in any “block element”.The &#xlink; element may be contained only in a &#xrela;&#xted-;&#xlink;&#xs000; element.Both elements may contain text, though in the case of the &#xlink; element, this text must be wrapped in a&#xlink;&#xtext; child element.For both elements, the target of the link is specified by the value of the @href attribute, which is anabsolute or relative URL, possibly ending with a fragment.Examples: 12345678910111213 href="topic_structure.dita"&#xxref;/ href="http://www.xmlmind.com/xmleditor/" format="html" scope="external"&#xxref;XMLmind XML Editor&#x/xre;￿ href="samples/sample_topic.dita#docbook_or_dita"&#xlink;/ href="http://www.xmlmind.com/ditac/" format="html" scope="external"&#xlink; &#xlink;&#xtext;XMLmind DITA Converter&#x/lin;&#xktex;&#xt000;&#x/lin;&#xk000; External linksThe target of an external link is any location outside the overall DITA document. This location may be anabsolute or relative URL. This location is not intended to be transformed by the DITA processing software(e.g. DITA Open Toolkit or XMLmind DITA Converter). Remember•Always specify a text for an external link, as the DITA processing software has noway to automatically generate some text for such links.•Always specify the @format attribute of the link element. Example: given an URLsuch as "http://www.xmlmind.com/ditac/", the DITA processing software hasno way to guess that this corresponds to an HTML file.•Always specify attribute scope="external" for such links. By doing so, youinstruct the DITA processing software to use the target location as is in thedeliverable. 4. The xref and link elements 11 DITA for the Impatient Internal linksThe target of an internal link (&#xxref; or &#xlink; element) is a DITA element belonging to the sameDITA document. This target element may be found in the same XML file as the link element or, on thecontrary, in a different XML file. The later case is still considered to be an internal link because both thelink and its target belong to the same overall DITA document.Of course, in order to use a DITA element as the target of a link, this element must have an @id attribute.The value of the @href attribute of a link element is:"URL_of_the_target_DITA_file#qualified_ID_of_the_target_element", where:•URL_of_the_target_DITA_file may be omitted when both the link and its target are found inthe same XML file.•#qualified_ID_of_the_target_element may be omitted if you want to address the first topiccontained in an XML file.What is the qualified ID of the target element?•It's simply the value of the @id attribute for a topic element (of any kind: &#xtopi;ℵ, onc;pt0;,&#xrefe;&#xrenc;◊, etc).•It's the value of the @id attribute of the target element prefixed by"ID_of_the_topic_ancestor/" for any descendant element of a topic.Example: Let's suppose you want to add an &#xxref; element to topic1.dita: 1234567 id="t1"&#xtopi; 00; &#xtitl;◊Title of topic 1&#x/tit;&#xle00; ody; id="p1"&#xp 00;Paragraph inside topic 1.&#x/p00; &#xp000;More information in href="???"&#xxref;/.&#x/p00; &#x/bod;&#xy000;&#x/top;&#xic00; Let's suppose that you want to address elements contained in topic2.dita, this file being found in thesame directory as topic1.dita. 123456 id="t2"&#xtopi; 00; &#xtitl;◊Title of topic 2&#x/tit;&#xle00; ody; id="p2"&#xp 00;Paragraph inside topic 2.&#x/p00; &#x/bod;&#xy000;&#x/top;&#xic00; •If you want to address topic "t1", specify href="#t1".•If you want to address paragraph "p1", specify href="#t1/p1".•If you want to address topic "t2", specify href="topic2.dita#t2" or more simplyhref="topic2.dita".•If you want to address paragraph "p2", specify href="topic2.dita#t2/p2". Remember•There is generally no need to specify the text of internal links, as the DITAprocessing software can automatically generate this text. 12 Chapter 3. The topic element DITA for the Impatient Example: converting the following paragraph to XHTML &#xp000;More information in href="topic2.dita"&#xxref;/.&#x/p00;may result in something like: &#xp000;More information in href="page-23.html#t2"€Title of topic 2&#x/a00;.&#x/p00;This probably works fine for any element having a title: &#xtopi;ℵ, &#xsect;&#xion0;,&#xtabl;◊, ig0;, etc. However this cannot work for the other elements.For example, do not expect the DITA processing software to generate some text for: href="topic2.dita#t2/p2"&#xxref;/Instead explicitly specify some text: href="topic2.dita#t2/p2"&#xxref;this paragraph&#x/xre;￿•Link targets are tedious and error prone to specify by hand. Using a DITA-awareXML editor is therefore especially handy when it comes to inserting link elements.Figure 3-2. XMLmind XML Editor "Attributes Tool" is DITA-aware: see its auto-completion feature in action More information: XMLmind XML Editor - Online Help 4. The xref and link elements 13 DITA for the Impatient List of Figures2-1.File layout of this tutorial ........................................................................................................... 33-1.The photo converted to black and white ..................................................................................... 83-2.XMLmind XML Editor "Attributes Tool" is DITA-aware: see its auto-completion feature inaction .......................................................................................................................................... 13 iii DITA for the Impatient Chapter 4. Specialized topic typesThe &#xtopi;ℵ element is the most generic topic type. There are four more specialized topic types:onc;pt0;, &#xtask;, &#xrefe;&#xrenc;◊, &#xglos;&#xsent;&#xry00;. When appropriate, use a specialized topic typerather than a plain &#xtopi;ℵ.1. The onc;pt0; elementCreate a onc;pt0; element when you need to provide your reader with background information whichmust be absorbed in order to understand the rest of the document.Example: 123456789101112131415161718 id="what_is_a_cache"onc;pt0; &#xtitl;◊What is a cache?&#x/tit;&#xle00; &#xshor;&#xtdes;ℵEverything you'll ever need to know about &#xterm;cache&#x/ter;&#xm000;s.&#x/sho;&#xrtde;&#xsc00; onb;&#xody0; &#xp000;In computer science, a cache is a temporary storage area where frequently accessed data can be stored for rapid access.&#x/p00; &#x/con;ody; &#xrela;&#xted-;&#xlink;&#xs000; format="html" href="http://en.wikipedia.org/wiki/Cache" scope="external"&#xlink; &#xlink;&#xtext;Wikipedia definition of a cache&#x/lin;&#xktex;&#xt000; &#x/lin;&#xk000; &#x/rel; ted;&#x-lin;&#xks00;&#x/con;Îpt; Notice how the structure of a onc;pt0; element is similar to the structure of a &#xtopi;ℵ element.Moreover, a onb;&#xody0; element has almost the same content model as a ody; element.The above example is rendered as follows:What is a cache?Everything you'll ever need to know about caches.In computer science, a cache is a temporary storage area where frequently accessed data can be stored forrapid access.A cache hit occurs when the requested data can be found in a cache, while a cache miss occurs when itcannot.To be cost-effective and to enable efficient use of data, caches must be relatively small.Related information• Wikipedia definition of a cache 15 DITA for the Impatient 2. The &#xtask; elementCreate a &#xtask; element when you need to explain step by step which procedure is to be followed inorder to accomplish a given task.Example: 12345678910111213141516171819202122232425262728293031323334353637383940414243 id="install_emacs"&#xtask; &#xtitl;◊Installing GNU Emacs&#x/tit;&#xle00; &#xtask;ody; &#xprer;q00;Windows NT 4.0 or any subsequent version of Windows. 5Mb of free disk space.&#x/pre;&#xreq0; &#xstep;&#xs000; &#xstep; md0;Unzip the distribution anywhere.&#x/cmd; &#xinfo;We recommend to use the free, open source, format="html" href="http://www.info-zip.org/" scope="external"&#xxref;Info-ZIP&#x/xre;￿ utility to do so.&#x/inf;&#xo000; &#xstep;&#xxmp0;&#xscre;n00;C:\> unzip emacs-21.3-bin-i386.zip&#x/scr;în0;&#x/ste;&#xpxmp; &#xstep;&#xresu;&#xlt00;&#xp000;Doing this will create an ile;&#xpath;emacs-21.3&#x/fil;pat;&#xh000; directory.&#x/p00;&#x/ste;&#xpres;&#xult0; &#x/ste;&#xp000; &#xstep; md0;Go to the bin subdirectory.&#x/cmd; &#xstep;&#xxmp0;&#xscre;n00;C:\> cd emacs-21.3\bin&#x/scr;în0;&#x/ste;&#xpxmp; &#x/ste;&#xp000; &#xstep; md0;Run mdn; me0;addpm&#x/cmd;&#xname;.&#x/cmd; &#xstep;&#xxmp0;&#xscre;n00;C:\emacs-21.3\bin> addpm&#x/scr;în0;&#x/ste;&#xpxmp; &#xstep;&#xresu;&#xlt00;A confirmation dialog box is displayed.ig0; href="confirm_install_emacs.png"&#ximag;◊/ &#x/fig;&#x/ste;&#xpres;&#xult0; &#x/ste;&#xp000; &#xstep; md0;Click &#xuico;&#xntro;&#xl000;OK&#x/uic;&#xontr;&#xol00; to confirm.&#x/cmd; &#x/ste;&#xp000; &#x/ste;&#xps00; &#x/tas;&#xkbod;&#xy000;&#x/tas;&#xk000; Albeit being the most complex specialized topic type, the &#xtask; element is also the most useful one.Its &#xtask;ody; is mainly organized around the &#xstep;&#xs000; element. Other useful elements are &#xprer;q00; 16 Chapter 4. Specialized topic types DITA for the Impatient (pre-requisite section of a task), ont;xt0; (background information for the task), &#xresu;&#xlt00; (expectedoutcome of a task).The &#xstep; element has several useful child elements other than the required md0; element: &#xinfo;(additional information about the step), &#xstep;&#xxmp0; (example that illustrates a step), &#xsubs;&#xteps;,hoi;Îs0; (the user needs to choose one of several actions), &#xstep;&#xresu;&#xlt00; (expected outcome of astep).The above example is rendered as follows:Installing GNU EmacsBefore you beginWindows NT 4.0 or any subsequent version of Windows. 5Mb of free disk space.Procedure1.Unzip the distribution anywhere.We recommend to use the free, open source, Info-ZIP utility to do so. ￿C:\ unzip emacs-21.3-bin-i386.zipDoing this will create an emacs-21.3 directory.2.Go to the bin subdirectory. ￿C:\ cd emacs-21.3\bin3.Run addpm. ￿C:\emacs-21.3\bin addpmA confirmation dialog box is displayed. 4.Click OK to confirm.3. The &#xrefe;&#xrenc;◊ elementCreate a &#xrefe;&#xrenc;◊ element when you need to add an entry to a reference manual. The &#xrefe;&#xrenc;◊element is typically used to document a command or a function.Example: 12345 id="pwd_command"&#xrefe;&#xrenc;◊ &#xtitl;◊The mdn; me0;pwd&#x/cmd;&#xname; command&#x/tit;&#xle00; &#xrefb;&#xody0; &#xrefs;&#xyn00;mdn; me0;pwd&#x/cmd;&#xname;&#x/ref;&#xsyn0; 3. The reference element 17 DITA for the Impatient 6789101112131415161718192021 &#xsect;&#xion0;&#xtitl;◊DESCRIPTION&#x/tit;&#xle00;&#xp000;Print the full filename of the current working directory.&#x/p00;&#xnote;Your shell may have its own version of mdn; me0;pwd&#x/cmd;&#xname;, which usually supersedes the version described here.&#x/not;◊&#x/sec;&#xtion; &#xsect;&#xion0;&#xtitl;◊AUTHOR&#x/tit;&#xle00;&#xp000;Written by John Doe. &#x/p00;&#x/sec;&#xtion; &#x/ref;ody; &#xrela;&#xted-;&#xlink;&#xs000; format="html" href="http://www.manpagez.com/man/3/getcwd/" scope="external"&#xlink; &#xlink;&#xtext;mdn; me0;getcwd&#x/cmd;&#xname;(3)&#x/lin;&#xktex;&#xt000; &#x/lin;&#xk000; &#x/rel; ted;&#x-lin;&#xks00;&#x/ref;ren;츀 The &#xrefb;&#xody0; child element of a &#xrefe;&#xrenc;◊ can contain the following generic elements:&#xsect;&#xion0;s, xam;&#xple0;s, &#xsimp;&#xleta;le0;s and &#xtabl;◊s but also more specific elements: &#xrefs;&#xyn00;(contains the syntax of a command-line utility or the prototype of a function) and &#xprop;rti;s00; (aspecial kind of table having 3 columns: type, value and description).The above example is rendered as follows:The pwd commandpwdDESCRIPTIONPrint the full filename of the current working directory. NoteYour shell may have its own version of pwd, which usually supersedes the versiondescribed here.AUTHORWritten by John Doe.Related information• getcwd(3)4. The &#xglos;&#xsent;&#xry00; elementCreate a &#xglos;&#xsent;&#xry00; element when you need to add entry to a glossary.The following example shows three glossary entries having the following IDs: ajax, dhtml,javascript. 1 id="sample_glossary"&#xglos;&#xsgro;&#xup00; 18 Chapter 4. Specialized topic types DITA for the Impatient 23456789101112131415161718192021222324252627282930313233 &#xtitl;◊Sample glossary&#x/tit;&#xle00; id="ajax"&#xglos;&#xsent;&#xry00; &#xglos;&#xster;&#xm000;AJAX&#x/glo;&#xsste;&#xrm00; &#xglos;&#xsdef;뀀A&#x/b00;synchronous 뀀Ja&#x/b00;vaScript and 뀀X&#x/b00;ML. Web development techniques used on the client-side to create interactive web applications.&#x/glo;&#xssde;￿ &#x/glo;&#xssen;&#xtry0; id="dhtml"&#xglos;&#xsent;&#xry00; &#xglos;&#xster;&#xm000;DHTML&#x/glo;&#xsste;&#xrm00; &#xglos;&#xsdef;뀀D&#x/b00;ynamic 뀀HTML&#x/b00;. Web development techniques used on the client-side to create interactive web sites.&#x/glo;&#xssde;￿ &#x/glo;&#xssen;&#xtry0; id="javascript"&#xglos;&#xsent;&#xry00; &#xglos;&#xster;&#xm000;JavaScript&#x/glo;&#xsste;&#xrm00; &#xglos;&#xsdef;JavaScript is an object-oriented scripting language supported by all major web browsers. It allows the development of interactive web sites and web applications.&#x/glo;&#xssde;￿ &#xrela;&#xted-;&#xlink;&#xs000; format="html" href="https://developer.mozilla.org/en/JavaScript" scope="external"&#xlink; &#xlink;&#xtext;Mozilla's Official Documentation on JavaScript&#x/lin;&#xktex;&#xt000; &#x/lin;&#xk000; &#x/rel; ted;&#x-lin;&#xks00; &#x/glo;&#xssen;&#xtry0;&#x/glo;&#xssgr;&#xoup0; The &#xglos;&#xsent;&#xry00; element is the simplest specialized topic type. It contains a &#xglos;&#xster;&#xm000; childelement (the term being defined) followed by a &#xglos;&#xsdef; (the definition of the term) child element,optionally followed by the &#xrela;&#xted-;&#xlink;&#xs000; element common to all topic types.In the above example, the &#xglos;&#xsgro;&#xup00; element is used as a container for the three &#xglos;&#xsent;&#xry00;elements. Remember•It is not recommended to create XML files containing several topics because ifyou do so, first this makes it harder reusing your topics in different documents andsecond, this makes the topic map slightly harder to specify.However if you need to create multi-topic files, you'll have to use the ita;element as a wrapper for your topics.•A topic may contain other topics. The DITA grammar allows to add a topic childelement after the ody; or &#xrela;&#xted-;&#xlink;&#xs000; element (whichever is the lastchild) of the parent topic. 4. The glossentry element 19 DITA for the Impatient It is not recommended to use this nested topics facility which, in our opinion, isalmost never useful. The hierarchy of topics (that is, chapters containing sectionscontaining subsections, etc) is better expressed in a map using a hierarchy of&#xtopi;ref;s(3).The above example is rendered as follows:Sample glossaryAJAXAsynchronous JavaScript and XML. Web development techniques used on the client-side tocreate interactive web applications.DHTMLDynamic HTML. Web development techniques used on the client-side to create interactive websites.JavaScriptJavaScript is an object-oriented scripting language supported by all major web browsers. Itallows the development of interactive web sites and web applications.Related information• Mozilla's Official Documentation on JavaScript (3)More about topic maps later in this tutorial. 20 Chapter 4. Specialized topic types DITA for the Impatient Chapter 5. Topic maps1. The &#xmap0; elementA topic &#xmap0; mainly contains:•A &#xtitl;◊ child element.•A &#xtopi;met;€ element where you can specify the author of the document, the date of publication,etc.•A hierarchy of &#xtopi;ref; elements.The &#xhref; attribute of a &#xtopi;ref; element specifies the URL of a topic which is part of the DITAdocument. Example: href="samples/sample_glossary.dita"&#xtopi;ref;/If the target XML file contains several topics (not recommended), you'll have to use a fragment to specifythe ID of the referenced topic. href="samples/sample_glossary.dita#javascript&#xtopi;ref;"/A map contains a hierarchy of &#xtopi;ref; elements. What does this mean? 12345678 href="topic.dita"&#xtopi;ref; href="topic_structure.dita"&#xtopi;ref; href="samples/sample_topic.dita"&#xtopi;ref;/ &#x/top;&#xicre;￿ href="block_elements.dita"&#xtopi;ref;/ href="inline_elements.dita"&#xtopi;ref;/ href="link_elements.dita"&#xtopi;ref;/&#x/top;&#xicre;￿ In the case of the above example, this means two things:1.The overall DITA document contains this sequence of topics: topic.dita,topic_structure.dita, samples/sample_topic.dita, block_elements.dita,inline_elements.dita, link_elements.dita.2.Topics topic_structure.dita, block_elements.dita, inline_elements.dita,link_elements.dita are subsections of topic topic.dita. Topic samples/sample_topic.dita is a subsection of topic topic_structure.dita.If you instruct the DITA processing software to generate a Table of Contents for your document and/or to number the topics, the hierarchy of topics appears very clearly.What follows is the topic map actually used for this tutorial (contents of file tutorial.ditamap): 12345678 &#xmap0; &#xtitl;◊DITA for the Impatient&#x/tit;&#xle00; &#xtopi;met;€ uth;&#xor00;Hussein Shafie&#x/aut;&#xhor0; &#xpubl;&#xishe;&#xr000;Pixware&#x/pub;&#xlish;r00; rit;Úte;&#xs000; date="October 7, 2009"rea;&#xted0;/ 21 DITA for the Impatient 9101112131415161718192021222324252627282930 &#x/cri;&#xtdat;s00; &#x/top;&#xicme;&#xta00; href="introduction.dita"&#xtopi;ref;/ href="topics_and_maps.dita"&#xtopi;ref;/ href="topic.dita"&#xtopi;ref; href="topic_structure.dita"&#xtopi;ref; href="samples/sample_topic.dita" toc="no"&#xtopi;ref;/ &#x/top;&#xicre;￿ href="block_elements.dita"&#xtopi;ref;/ href="inline_elements.dita"&#xtopi;ref;/ href="link_elements.dita"&#xtopi;ref;/ &#x/top;&#xicre;￿ . . . navtitle="Topic maps"&#xtopi;hea;∠ href="map.dita"&#xtopi;ref;/ href="bookmap.dita"&#xtopi;ref;/ &#x/top;&#xiche;관 href="conclusion.dita"&#xtopi;ref;/&#x/map; The @toc attributeSpecifying attribute toc="no" for a &#xtopi;ref; element prevents it from appearing in the generatedTable of Contents. 123 href="topic_structure.dita"&#xtopi;ref; href="samples/sample_topic.dita" toc="no"&#xtopi;ref;/&#x/top;&#xicre;￿ The &#xtopi;hea;∠ elementThe &#xtopi;hea;∠ element provides an author with a simple way to group several topics in the sameHTML page and to give this HTML page a title(4). 1234 navtitle="Topic maps"&#xtopi;hea;∠ href="map.dita"&#xtopi;ref;/ href="bookmap.dita"&#xtopi;ref;/&#x/top;&#xiche;관 2. The ook;&#xmap0; elementA ook;&#xmap0; element is just a more elaborate form of &#xmap0;. We recommend using a ook;&#xmap0; foranything more complex than an article. (4)A less convenient alternative would be to use an actual &#xtopi;ℵ having no ody; at all, just a &#xtitl;◊. 22 Chapter 5. Topic maps DITA for the Impatient TipYou don't need to create a &#xmap0; for the screen media and a ook;&#xmap0; for the printmedia. If you follow the “one topic per XML file” rule, a single topic map (&#xmap0; orook;&#xmap0; depending on the complexity of the contents) is all you need.•A ook;&#xmap0; may have a ook;&#xtitl;◊ rather than a &#xtitl;◊.•Its metadata wrapper element, ook;&#xmeta;, may contain richer information than the &#xtopi;met;€element.•A bookmap may contain specializations of the &#xtopi;ref; element having stronger semantics:&#xpart;, hap;&#xter0;, ppe;&#xndix;.•The hierarchy of references to topic elements which makes up the body of the document may bepreceded by a ron;&#xtmat;&#xter0; element and followed by a ஬k;&#xmatt;r00; element.These wrapper elements can contain references to actual, hand-written, topics: bookabstract,&#xpref;고, ෭i;Êti;&#xon00;, olo;&#xphon;, etc.However the most common use of ron;&#xtmat;&#xter0; and ஬k;&#xmatt;r00; is to contain the following,empty placeholder elements: &#xtoc0;, igu;&#xreli;&#xst00;, &#xtabl;lis;&#xt000;, &#xinde;&#xxlis;&#xt000;. Theseplaceholders instructs the DITA processing software to automatically generate: a Table of Contents, aList of Figures, a List of Tables, an Index.What follows is a possible ook;&#xmap0; for this tutorial (contents of file tutorial-book.ditamap): 123456789101112131415161718192021222324252627 ook;&#xmap0; ook;&#xtitl;◊ &#xmain;ook;&#xtitl;◊DITA for the Impatient&#x/mai;&#xnboo;&#xktit;&#xle00; &#x/boo;&#xktit;&#xle00; ook;&#xmeta; uth;&#xorin;orm; tio;&#xn000; &#xpers;&#xonin;o00;...&#x/per;&#xsoni;&#xnfo0; &#xorga;&#xniza;&#xtion;&#xinfo;...&#x/org; niz; tio;&#xninf;&#xo000; &#x/aut;&#xhori;&#xnfor;&#xmati;&#xon00; rit;Úte;&#xs000; date="October 7, 2009"rea;&#xted0;/ &#x/cri;&#xtdat;s00; &#x/boo;&#xkmet;€ ron;&#xtmat;&#xter0; ook;&#xlist;&#xs000; &#xtoc/; igu;&#xreli;&#xst/0; &#xtabl;lis;&#xt/00; &#x/boo;&#xklis;&#xts00; &#x/fro;&#xntma;&#xtter; href="introduction.dita"hap;&#xter0;/ href="topics_and_maps.dita"hap;&#xter0;/ href="topic.dita"hap;&#xter0; href="topic_structure.dita"&#xtopi;ref; 2. The bookmap element 23 DITA for the Impatient 282930313233343536373839404142 href="samples/sample_topic.dita" toc="no"&#xtopi;ref;/ &#x/top;&#xicre;￿ href="block_elements.dita"&#xtopi;ref;/ href="inline_elements.dita"&#xtopi;ref;/ href="link_elements.dita"&#xtopi;ref;/ &#x/cha;&#xpter; . . . navtitle="Topic maps"hap;&#xter0; href="map.dita"&#xtopi;ref;/ href="bookmap.dita"&#xtopi;ref;/ &#x/cha;&#xpter; href="conclusion.dita"hap;&#xter0;/&#x/boo;&#xkmap; 24 Chapter 5. Topic maps DITA for the Impatient Chapter 6. ConclusionThis tutorial has just scratched the surface of DITA. We didn't discuss:•The &#xtrou;les;&#xhoot;&#xing0; topic.•A lot of useful elements such as: &#xscre;n00;, ode;&#xph00;, &#xnote;, n00; (footnote), &#xlq00; (longquote), &#xq000; (quote), etc.•The &#xrelt;«le; child element of topic maps which allows to link different topics without explicitlyadding a &#xrela;&#xted-;&#xlink;&#xs000; section to each of them.•Document meta-data: &#xtopi;met;€, &#xprol;&#xog00;, etc.•Conditional processing.•The conref transclusion mechanism which allows to reuse fine-grained content.However we believe that what you have learned here is sufficient to start authoring your first DITAdocument.Related information• Darwin Information Typing Architecture (DITA) Version 1.3 Part 2: Technical Content Edition (OASISspecification)• DITA Open Toolkit, the de facto reference DITA implementation• XMLmind DITA Converter, an alternative to using the DITA Open Toolkit 25 DITA for the Impatient Table of ContentsList of Figures ............................................................................................................................................ iiiList of Tables ............................................................................................................................................. ivChapter 1. Introduction ............................................................................................................................ 1Chapter 2. About topics and maps .......................................................................................................... 3Chapter 3. The topic element ................................................................................................................... 51. The structure of the topic element .................................................................................................. 52. The most commonly used “block elements” .................................................................................. 63. The most commonly used “inline elements” ................................................................................ 104. The xref and link elements ........................................................................................................... 11Chapter 4. Specialized topic types ......................................................................................................... 151. The concept element ..................................................................................................................... 152. The task element ........................................................................................................................... 163. The reference element ................................................................................................................... 174. The glossentry element ................................................................................................................. 18Chapter 5. Topic maps ............................................................................................................................ 211. The map element ........................................................................................................................... 212. The bookmap element ................................................................................................................... 22Chapter 6. Conclusion ............................................................................................................................. 25 i