blob: 015673f647a20c1c087014a1e87a40e73f88d337 [file] [log] [blame]
kpriceef160682006-08-29 18:08:31 +00001<?xml version="1.0" encoding="utf-8"?>
kpriceb59c9f62008-04-02 21:24:37 +00002<!--Arbortext, Inc., 1988-2006, v.4002-->
4 "task.dtd">
kpriceef160682006-08-29 18:08:31 +00005<?Pub Inc?>
6<task id="txmlcat" xml:lang="en-us">
7<title>Adding entries to the XML Catalog</title>
9<searchtitle>Adding entries to the XML Catalog</searchtitle>
11<shortdesc>An XML Catalog entry contains two parts - a Key (which represents
kpriceb59c9f62008-04-02 21:24:37 +000012a DTD or XML schema) and a Location (similar to a URI, which contains information
13about a DTD or XML schema's location). You can place the Key in an XML file.
14When the XML processor encounters it, it will use the XML Catalog entry to
15find the location of the DTD or XML schema associated with the Key</shortdesc>
kpriceef160682006-08-29 18:08:31 +000016<prolog><metadata>
17<keywords><indexterm>XML catalog<indexterm>adding entries</indexterm></indexterm>
kpriceef160682006-08-29 18:08:31 +000018</keywords>
21<context><p>XML Catalog entries can be used in various situations. For example,
22you are working on an XML file on your main desktop computer and point its <codeph>schemaLocation</codeph> towards
23a schema called <codeph>c:\MySchema.xsd</codeph>. You then save it to your
24laptop computer so you can work on it later. When you open the file on your
25laptop, however, you encounter a problem - the XML editor cannot find the <codeph>MySchema.xsd</codeph> schema
26because it is actually installed on your D drive. You will have to edit the <codeph>schemaLocation</codeph> to
27point to <codeph>d:\MySchema.xsd</codeph>. When you have finished editing
28the XML file and are ready to publish it on the Web, you will need to edit
29the URI again so that it points to a resource that is accessible on the Web.
30By now, the problem is obvious. A URI used within an XML file is not as portable
31as you would like it to be. To avoid making frequent changes to your XML document,
32you can use the XML Catalog.</p><p>An XML Catalog entry is used by an XML
33processor when resolving entity references. You can provide rules to the catalog
34to specify how entities should be resolved. If you consider the preceding
35example, you could specify a rule that redirects an Internet resource reference
36(for example, <codeph>""</codeph>)
37so that it points to a resource on the developer's local machine (for example,
38 <codeph>"file:///C:/MySchema.xsd"</codeph>). Now, instead of frequently editing
kpriceb59c9f62008-04-02 21:24:37 +000039XML documents to update the URIs or locations (especially when there are many
40documents in your project), you only need to update a single rule in your
41XML Catalog.</p><p>The following instructions were written for the Resource
42perspective, but they will also work in many other perspectives.</p><p>To
43add an entry to the XML Catalog, follow these steps:</p></context>
kpriceef160682006-08-29 18:08:31 +000044<steps>
45<step><cmd>Open the XML file that you want to associate with a DTD or XML
47<step><cmd>Click <menucascade><uicontrol>Window</uicontrol><uicontrol>Preferences</uicontrol>
kpriceb59c9f62008-04-02 21:24:37 +000048</menucascade> and select <menucascade><uicontrol>XML</uicontrol><uicontrol>XML
49Catalog</uicontrol></menucascade>.</cmd><info>The <uicontrol>XML Catalog
50Entries</uicontrol> section contains a list of any user-defined and plug-in
51defined catalog entries. Select any entry to see information about it in the <uicontrol>Details</uicontrol> section.</info>
kpriceef160682006-08-29 18:08:31 +000052</step>
kpriceb59c9f62008-04-02 21:24:37 +000053<step><cmd>Click <uicontrol>Add</uicontrol> to create a new catalog entry.</cmd>
kpriceef160682006-08-29 18:08:31 +000054</step>
kpriceb59c9f62008-04-02 21:24:37 +000055<step><cmd>In the <uicontrol>Location</uicontrol> field, enter or browse for
56the location or URI of the DTD or XML schema file. This uses your computer's
57path style to describe the location of the file.</cmd></step>
58<step><cmd>Select a key type for the catalog entry from the <uicontrol>Key
59Type</uicontrol> drop down.</cmd><info>The values in this list will change
60depending on the type of file you specified in the <uicontrol>Location</uicontrol> field:<ul>
61<li>If you specified a DTD: select <uicontrol>Public ID</uicontrol>, <uicontrol>System
62ID</uicontrol>, or <uicontrol>URI</uicontrol> from the <uicontrol>Key Type</uicontrol> field.
63If you select <uicontrol>Public ID,</uicontrol> the value you enter in the <uicontrol>Key</uicontrol> field
kpriceef160682006-08-29 18:08:31 +000064should be the same as the Public ID in the XML file's DOCTYPE declaration.
65If you select <uicontrol>System ID</uicontrol>, the value you enter should
kpriceb59c9f62008-04-02 21:24:37 +000066correspond to the System ID in an XML file's DOCTYPE declaration. If you select <uicontrol>URI</uicontrol>,
67the value you enter must be a fully qualified URI.</li>
68<li>If you specified an XML schema: select either <uicontrol>Namespace Name</uicontrol> or
69 <uicontrol>Schema Location</uicontrol> from the <uicontrol>Key Type</uicontrol> field.
70If the schema defines a target namespace, it will automatically appear in
71the <uicontrol>Key</uicontrol> field. Otherwise, you can enter the schema
72location in the <uicontrol>Key</uicontrol> field.</li>
kpriceef160682006-08-29 18:08:31 +000074<step><cmd>Select the <uicontrol>Specify alternative Web address</uicontrol> check
75box if you want to be able to specify an alternate Web address for the resource.</cmd>
76<info>This Web address is used when an XML instance is generated from this
kpriceb59c9f62008-04-02 21:24:37 +000077catalog entry.<note>This option is only available if you select <uicontrol>Public
kpriceef160682006-08-29 18:08:31 +000078ID</uicontrol> (for a DTD) or <uicontrol>Namespace Name</uicontrol> (for
kpriceb59c9f62008-04-02 21:24:37 +000079a schema) in the <uicontrol>Key type</uicontrol> field.</note></info></step>
kpriceef160682006-08-29 18:08:31 +000080<step><cmd>If you want to refer to another catalog without importing it into
81the workbench, click <uicontrol>Next Catalog</uicontrol>. Type or browse for
82the XML catalog you want to refer to. </cmd></step>
83<step><cmd>When you are done creating catalog entries, click <uicontrol>OK</uicontrol> to
kpriceb59c9f62008-04-02 21:24:37 +000084close the Add XML Catalog Entry dialog. Click <uicontrol>OK</uicontrol> again
85to save your settings.</cmd></step>
kpriceef160682006-08-29 18:08:31 +000086<step><cmd>Make sure the XML file is in focus and click the <uicontrol>Reload
87dependencies</uicontrol> toolbar button. </cmd></step>
89<result>The XML file is now associated with the latest version of the XML
90schema or DTD.</result>
kpriceb59c9f62008-04-02 21:24:37 +000091<postreq><p>You can also export and import XML Catalog information:<?Pub Caret?> </p><p>To
92export, click <uicontrol>File > Export</uicontrol> and select <uicontrol>XML
93> XML Catalog</uicontrol>. You will be prompted to select a project and provide
94a file name to store your catalog entries in an .xmlcatalog file, which can
95be opened from the Navigator view. Since your catalog entries are stored in
96an .xmlcatalog file, you can check them in and out and share them like any
97other project resource.</p><p>To import, click <uicontrol>File > Import</uicontrol> and
98select <uicontrol>XML > XML Catalog</uicontrol>. Then specify the file that
99will be used to load the XML Catalog settings. When you import a .xmlcatalog
100file, any entries in it will be loaded into the XML Catalog (and any existing
101entries will be overwritten). </p></postreq>
kpriceef160682006-08-29 18:08:31 +0000102</taskbody>
kpriceb59c9f62008-04-02 21:24:37 +0000104<?Pub *0000006868?>