 User Manual: For epcEdit Release 1.2.1 | ||
|---|---|---|
| Prev | Chapter 17. DTDs and Catalogs | Next |
epcEdit comes with a number of popular pre-installed DTDs. However, you may want to create documents with other DTDs as well. This section describes the necessary steps for installing a new DTD that should be used by epcEdit.
Before you can use a new DTD in epcEdit, you have to store the DTD in a location where epcEdit can read the DTD an its associated files. We recommend to create a subdirectory for each DTD that you install on your system.
Create a new subdirectory for the DTD an all of its files in a suitable location. The epcEdit example directory can be used as the parent directory for the new DTD-specific directory, but any other directory can be used.
It would be a good idea to give the directory a name that corresponds to the DTD that you are installing.
Copy the DTD and its associated files (e.g. entity definitions, catalog files, etc) into the DTD subdirectory.
If you have downloaded the DTD from the internet or if you have received the DTD as an archive file (e.g. as a zip or tar archive), then you should unpack the archive into this directory.
For the DocBook XML DTD, you could create a directory called docbkx412. On a Unix system, you can use the following commands to create a directory and extract the files from the zip archive into this directory:
mkdir /usr/local/tksgml/examples/docbkx412 cd /usr/local/tksgml/examples/docbkx412 unzip ~/docbkx14.zip
Your new DTD may include a catalog file (usually named catalog) that contains information about the components of the DTD, their public identifiers, the entity sets, etc.
The DocBook XML DTD comes with a catalog file named docbook.cat. In order to use this catalog file, we must tell epcEdit that it should use this catalog for resolving public identifiers. There are three methods for making the catalog available to epcEdit:
By appending the catalog name to the environment variable SGML_CATALOG_FILES. This method is recommended if you are using different SGML/XML systems which honor this environment variable (such as SP/nsgmls and derived products) and you do not have a central system catalog.
By adding a reference to the catalog to the main system catalog. This is recommended if you have a main SGML catalog file and you want to make the DTD available to all SGML applications on your system.
By adding the catalog to the catalog list in the preferences dialog in epcEdit. This method has the advantage that you can safely experiment with new DTDs without influencing other SGML processing software.
In this example, we use the third approach and make the DTD available to epcEdit alone.
To add the catalog to epcEdit's list of catalog files, bring up the Preferences Dialog by selecting -> from the main menu, and click on the Catalogs tab. The following dialog will appear:
Click on the button to bring up a file selection dialog. In this dialog, choose the name of the catalog file that came with the DTD. In our example, this would be the file /usr/local/tksgml/examples/docbkx412/docbook.cat. Clicking the button in the file selection dialog will add the catalog file to the list.
Additionally, you may want to limit the use of the catalog docbook.cat to XML documents. Click on the button and select XML in the catalog usage dialog (see Figure 15-22 for details).
Finally, click on the button in the Preferences dialog to close the dialog and save your modifications.
epcEdit can now load documents that use the newly installed DTD.
If you want to create new documents with this DTD, one additional step is necessary: You should create a template that epcEdit will use for creating new documents.
If the new DTD came with an example document (or if you already have a document for the new DTD), the process of creating a new template is straight forward and simple:
Open the document for the new DTD in epcEdit by selecting -> and choosing the appropriate document file.
Select ->-> from the main menu. A file selection dialog will appear where you can specify the name of the document template.
Enter an appropriate file name (e.g. docbk41x for documents with the DocBook XML DTD) and click on the button to save the new template.
You can now create new documents by simply clicking on the template name in the new document dialog (see Figure 15-1).
If you do not have an example document for the new DTD, you will have to create a new template from scratch. Normally, you would use the template wizard for this task. Alternatively, you can simply create a new document (as describe in Section 3.2) and then derive the template from the document as described above. To create you fist DocBook document without a template, you would select to create a new XML document in the New file dialog and enter the following information:
Clicking on the button would then create a new DocBook document and you could save a template for this document as outlined above.
Note: Please refer to the following section for details about the system identifier and document portability.
The XML standard specifies that every valid XML document must contain a system identifier in its DOCTYPE statement. The system identifier gives the location of the DTD for your document. This means that the document references an external entity that resides either in the file system of your computer or somewhere on the net. This convention introduces two potential problems:
If the DTD is stored somewhere on the net, you will need an internet connection to access the DTD when epcEdit is loading or validating a document.
If the DTD is stored in your file system, the path name in the system identifier depends on where files are kept on your computer system. It might be relative to the location of your documents or it might be an absolute path denoting a fixed location on your hard disk. In both cases, the DTD must be stored in the same relative or absolute location of every computer that you want to exchange documents with.
We suggest to solve this issue by following these recommendations:
Whenever possible, provide both public and system identifiers for the DTD of your document. Since epcEdit creates new documents from templates, this information has to be entered only once for every type of document that you want to create.
Keep the system identifier relative to your document, either by only providing the file name of the DTD or by using a relative path. Use an URI with the http scheme for the system identifier if the DTD can be found on the net.
Use an catalog entry to tell epcEdit where to find the DTD. The exact form of this catalog entry depends on the availability of a public identifier for your DTD.
If a public identifier is available, then resolve that public identifier in a catalog file with an appropriate PUBLIC statement. Enclose this statement in OVERRIDE directives to tell epcEdit that the catalog information should override the system identifier in the DOCTYPE statement. In the example catalogs that come with epcEdit, we use the following statements for the DocBook DTD:
OVERRIDE YES
PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "docbookx.dtd"
OVERRIDE NO
This tells epcEdit to use the file docbookx.dtd in the same directory as the catalog file for resolving the public identifier -//OASIS//DTD DocBook XML V4.1.2//EN. The OVERRIDE YES statements tells epcEdit to use the catalog information for resolving a reference with a public identifier of -//OASIS//DTD DocBook XML V4.1.2//EN, even if a system identifier is provided. The OVERRIDE NO statement turns this feature off after the public identifier has been declared.
This example will make epcEdit always use the DTD from the directory that contains the catalog file, regardless of the system identifier provided in the DOCTYPE statement.
Use a reasonable default for the public identifier in your document. For example, use docbookx.dtd or dtd/docbookx.dtd as a default filename. If the original DTD is available on the net, then use an URL like http://www.oasis-open.org/docbook/xml/4.0/docbookx.dtd so that XML systems that have no support for catalog files will reference the original DTD on the web.
If you can not use a public identifier for your DTD, then provide a reasonable system identifier as described above and use a SYSTEM statement in one of your catalog files to map this system identifier to a system identifier in your file system. For example, if you would want to create DocBook documents that do not contain a public identifier for the DTD, you could put the following statement in a catalog file:
SYSTEM "docbookx.dtd" "/dtds/docbookx.dtd"
This would tell epcEdit to use the file /dtds/docbookx.dtd when looking for a system identifier docbookx.dtd. The exact form of the SYSTEM statement depends on the system identifier that you use in your documents and on the location of the DTD in your file system.
Be sure to enter the appropriate system identifier when you create a template for your new documents. epcEdit will not strip off the pathname of a system identifier that you provide in the corresponding dialog of the template wizard.
Tip: We recommend to avoid using absolute pathnames altogether. If you need to use a SYSTEM entry, then put a catalog file in the same directory as the DTD and add a SYSTEM directive like
SYSTEM "docbookx.dtd" "docbookx.dtd"
This seems pointless at a first glance, but it will make epcEdit look for the DTD in the same directory as the catalog file. Add this catalog to epcEdit's internal list of catalog files in the Catalogs tab of the Preferences dialog.