| 1 | <?xml version="1.0" encoding="UTF-8"?>
|
|---|
| 2 | <!--Arbortext, Inc., 1988-2010, v.4002-->
|
|---|
| 3 | <!DOCTYPE task PUBLIC "-//OASIS//DTD DITA Task//EN"
|
|---|
| 4 | "task.dtd">
|
|---|
| 5 | <task id="mapref" xml:lang="en-us">
|
|---|
| 6 | <title>Mapref</title>
|
|---|
| 7 | <shortdesc>Mapref refers to a special usage of the <tt><topicref></tt>
|
|---|
| 8 | element as a reference to another ditamap file. This allows you
|
|---|
| 9 | to manage the overall ditamap file more easily. A large ditamap
|
|---|
| 10 | file can thus be broken down into several ditamap files, making
|
|---|
| 11 | it easier for the user to manage the overall logical structure.
|
|---|
| 12 | This mechanism also increases the reusability of those ditamap files.</shortdesc>
|
|---|
| 13 | <taskbody>
|
|---|
| 14 | <context>You can create references to another ditamap file by setting
|
|---|
| 15 | the format attribute to "ditamap" as follows.<note>This usage is often
|
|---|
| 16 | referred to as <codeph>mapref</codeph>. A new <codeph>mapref</codeph> element
|
|---|
| 17 | is defined in DITA 1.2, which provides a shortcut for this function
|
|---|
| 18 | by defaulting the format attribute to "ditamap". However, any topicref
|
|---|
| 19 | or topicref specialization may do the same thing by setting the format
|
|---|
| 20 | attribute as described.</note></context>
|
|---|
| 21 | <steps>
|
|---|
| 22 | <step><cmd>Add a <tt><topicref></tt> element to your map.</cmd>
|
|---|
| 23 | </step>
|
|---|
| 24 | <step><cmd>Define the location of the target ditamap file in the href
|
|---|
| 25 | attribute. The href takes a standard URI format. Typically it is a
|
|---|
| 26 | relative path to the ditamap. </cmd></step>
|
|---|
| 27 | <step><cmd>Set format="ditamap".</cmd></step>
|
|---|
| 28 | <step importance="optional"><cmd>Add a navigation title in the navtitle
|
|---|
| 29 | attribute. </cmd><info>The navtitle attribute on a map reference is
|
|---|
| 30 | not used for anything during DITA-OT processing, but is helpful when
|
|---|
| 31 | authoring.</info></step>
|
|---|
| 32 | </steps>
|
|---|
| 33 | <example> <p>For example, if you want to create a reference
|
|---|
| 34 | to the <i>samples/mysamp.ditamap</i> file using <tt>sample
|
|---|
| 35 | ditamap</tt> as the navigation title, add the following codes
|
|---|
| 36 | into the <i>readme.ditamap</i> file.</p><p> <codeblock><topicref format="ditamap" href="samples/mysample.ditamap" navtitle="sample ditamap"> </codeblock>
|
|---|
| 37 | </p> <p>Now the complete content of the <i>readme.ditamap</i> file
|
|---|
| 38 | is shown as follows. <codeblock>
|
|---|
| 39 | <?xml version="1.0" encoding="utf-8"?>
|
|---|
| 40 | <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
|
|---|
| 41 | <map id="mainDITAreadme" title="DITA Readme map">
|
|---|
| 42 | <topicref collection-type="family" href="DITA-readme.xml" id="DITA-doc"
|
|---|
| 43 | locktitle="yes" navtitle="DITA-OT Introduction">
|
|---|
| 44 | <topicref href="DITA-changes.xml" navtitle="DITA release history"/>
|
|---|
| 45 | <topicref format="ditamap" href="samples/mysample.ditamap" navtitle="sample ditamap"/>
|
|---|
| 46 | </topicref>
|
|---|
| 47 | </map>
|
|---|
| 48 | </codeblock> </p> <p>Assume the file <i>samples/mysample.ditamap</i> is
|
|---|
| 49 | defined as follows:<codeblock>
|
|---|
| 50 | <?xml version="1.0" encoding="utf-8"?>
|
|---|
| 51 | <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
|
|---|
| 52 | <map id="samplemap" title="Sample Ditamap">
|
|---|
| 53 | <topicref href="..\DITA-relnotes.xml" navtitle="DITA OT Release notes"/>
|
|---|
| 54 | <topicref href="..\DITA-installation.xml" navtitle="Installation"/>
|
|---|
| 55 | </map>
|
|---|
| 56 | </codeblock><?Pub Caret 301?> </p><p>The <i>readme.ditamap</i> file
|
|---|
| 57 | can be equivalently expressed by the following map:</p><p>
|
|---|
| 58 | <codeblock>
|
|---|
| 59 | <?xml version="1.0" encoding="utf-8"?>
|
|---|
| 60 | <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
|
|---|
| 61 | <map id="mainDITAreadme" title="DITA Readme map">
|
|---|
| 62 | <topicref collection-type="family" href="DITA-readme.xml"
|
|---|
| 63 | id="DITA-doc" locktitle="yes" navtitle="DITA-OT Introduction">
|
|---|
| 64 | <topicref href="DITA-changes.xml" navtitle="DITA release history"/>
|
|---|
| 65 | <topicref href="DITA-relnotes.xml" navtitle="DITA OT Release notes"/>
|
|---|
| 66 | <topicref href="DITA-installation.xml" navtitle="Installation"/>
|
|---|
| 67 | </topicref>
|
|---|
| 68 | </map>
|
|---|
| 69 | </codeblock></p></example>
|
|---|
| 70 | </taskbody>
|
|---|
| 71 | </task>
|
|---|
| 72 | <?Pub *0000003985?>
|
|---|
