 User Manual: For epcEdit Release 1.2.1 | ||
|---|---|---|
| Prev | Chapter 10. Templates | Next |
epcEdit can create templates for new documents by two methods:
By creating a template from scratch with the template wizard, or
By deriving a template from an existing document.
It is easier to derive a new template from an existing document, but this is only possible if you already have a document of this type. Well explain this in detail in Creating templates from documents and cover template creation with the template wizard first.
The following examples will illustrate how a new template is created with the template wizard. It shows how to create a new template for an already installed DTD, based on the following assumptions:
The document type is PAPER, i.e. the top-level element of every new document that is created with this template should be PAPER.
The DTD for the document is stored in the file /sgml/dtds/Paper.dtd and contains the content definition of the PAPER element.
A catalog entry of the form PUBLIC "-//EPC//DTD PAPER//EN" exists and points to the file Paper.dtd.
Since we will specify both public and system identifier in this example, the catalog entry is not really needed and used for the sake of completeness, only.
To start the template wizard, select ->->. The following dialog will appear:
Click the next button in this dialog to start defining your template.The following dialog will appear:
In the second screen of the wizard dialog, you can enter the document type for the new template. The document type is the name of the top-level element in your new document.
The name that you enter here will appear as follows in the documents that you create with the new template:
In SGML documents and valid XML documents, it will appear in the DOCTYPE statement at the beginning of your document in the general form <!DOCTYPE name.... In addition, it will be the name of the initial top-level element that epcEdit will insert for you when you create a new document with this template.
Please note that your DTD must contain the definition of the top-level element.
In wellformed XML documents (i.e. in XML documents without a DTD), this name will be used for creating the top-level element in a new, otherwise empty document that you create with this template.
In the example above, we have entered a DOCTYPE name of PAPER for the new document so that epcEdit will insert the top-level element when we create a new document.
In the next steps, we will add more information to the template and tell epcEdit more about the type of documents that we want to create with this template. For now, we just move on to the next screen of the template wizard by pressing the button. The following dialog will appear:
In this dialog, you have to select one of the following options:
SGML specifies a valid SGML document. In order to create such documents, you need to have access to a DTD that contains a declaration for the document type that you have entered in the previous dialog.
XML is similar to SGML: epcEdit will need to access a DTD that defines the possible content of the document element.
DTDless XML is for XML documents that do not use a DTD.
In the following steps, we will show the creation of a template for valid XML documents. If you want to create a template for wellformed XML document, the dialogs for declaring the public and system identifiers for the DTD are skipped.
After you have selected the appropriate option in the wizard dialog, you can continue with the next screens of the template wizard by pressing the button. The following dialog will appear:
The characters in the XML document can be encoded in different formats. XML uses the Unicode (UTF-8 or UTF-16) character set by default, but other encodings can be used if they are declared in the XML declaration. at the beginning of the document.
In this screen of the template wizard, you can specify the encoding for the documents created with the template. Encodings can only be specified for XML documents; this screen of the template wizard will not appear if you are creating a template for an SGML document.
Choose an encoding from the drop-down list in the dialog of select <none> to omit the encoding specification in the XML declaration.
XML systems will assume that your document has been encoded with Unicode (UTF-8 or UTF-16) characters if no other encoding has been explicitly specified. epcEdit will store XML documents in the UTF-8 encoding if no other encoding has been specified in the XML declaration.
After selecting the document encoding, continue with the next screens of the template wizard by pressing the button. The following dialog will appear:
For valid XML and SGML documents, it is necessary to provide the document type definition (DTD) for the new documents. epcEdit will need to analyze the DTD in order to ensure the validity of the documents that will be created.
The DTD can be specified by a system ID (which is a file name or a URL) or by a public ID which is resolved by the system catalog. This dialog is for entering the system ID; you can skip this dialog if you are creating a template for SGML documents and the DTD should be specified by a public identifier (which can be entered on the next screen).
In this dialog, you can enter the system ID for the DTD to be used by documents created with the new template. Instead of entering the filename by hand, you can click on the button for selecting a file.
Please note that you do not always need to enter a system ID if you want to access the DTD by using a public identifier. More specifically, you can
Enter only a system ID that specifies the filename containing the DTD. epcEdit will use the DTD in the file specified by the system ID. This approach is possible for valid XML and SGML documents, but it can introduce system dependent information into your documents.
Leave the system ID entry blank and specify a public ID in the following dialog. epcEdit will resolve the public ID by accessing the system catalog. This is the recommended practice for SGML documents. Valid XML documents need to provide a system identifier, so omitting this information is not possible if you are creating a template for valid XML documents.
Provide a system ID in this dialog and specify a public ID in the next dialog. In this case, the system ID will override the public ID unless an OVERRIDE YES statement occurs in your catalog files. For valid XML documents, it is recommended to provide both public and system identifiers. To minimize system dependencies in your documents, you should specify a minimal filename for the system ID and provide an explicit file name for the public identifier in a catalog with an OVERRIDE YES statement if you are using DTDs that reside in the file system of your computer.
For SGML documents only, you can omit both system and public ID. In this case, the system catalogs will be consulted to determine which DTD to use for the given document type. Please note that this approach is discouraged because not all SGML systems support catalog lookup for the DTD.
After you have entered the appropriate value in the wizard dialog, you can continue with the next screens of the template wizard by pressing the button. The following dialog will appear:
Instead of specifying the filename of the DTD, a public ID can be used. Public identifiers are resolved by consulting the system catalogs which leads to enhanced portability of SGML documents. The catalogs used by epcEdit are in the format defined by SGML Open Technical Resolution TR9401:1997.
The advantage of using the system catalogs is that no pathname (or filename) needs to be stored inside the document which would require the same DTD to be stored in the same location on all computer systems that want to exchange documents. By using a public identifier and system catalogs, the storage locations are referenced by a public ID and the catalog defines the location from which the DTD can be retrieved by associating the public identifier with a system identifier.
In this dialog, you can enter the public ID for the DTD to be used. Instead of entering the public ID by hand, you can click on the button for selecting an entry from your catalog files.
If you press the button in the template wizard, a list with all available public identifiers will appear where you can choose the desired identifier:
Building the list of available public identifiers may take a few seconds, depending on the number and the size of SGML catalogs on your system.
After you have entered the appropriate value in the wizard dialog, you can continue with the next screens of the template wizard by pressing the button. The following dialog will appear:
For some purposes, it may be necessary to augment the document prolog with additional declarations, e.g. for specifying parameter entities.
If your documents require such additional declarations, you may enter them in this dialog. Anything that you enter in this dialog will be placed verbatim in a markup declaration immediately following the document type statement.
In most cases, you will not have to enter anything in this dialog. However, you should be aware that anything that you enter here will be included in the document prolog and may have significant influence on the way your document is processed. It's probably the wisest to treat this dialog as a kind of expert mode feature and not to tinker with it unless you know what you are doing.
The template wizard has now collected all necessary information for a new template. In the next step, it will try to use the template to create a new document and to verify that all information that has been entered is correct.
Continue with the next screens of the template wizard by pressing the button.
After the template wizard has verified the contents of the new template by creating a new document with this information, it will ask you for a location where the template should be stored:
epcEdit will look for template files in the locations that are specified by the settings in the Preferences dialog. These locations are shown in the list at the bottom of the dialog. Choosing one of these locations will set the default directory in the file selection dialog for saving the template.
If you press the button, a file selection window will appear where you can enter the name of the template file. When you later ask epcEdit to create a new document, it will display the names of all template files to choose from.
After you have saved the new template, the template wizard will display its final dialog to inform you that a new template has been created:
The final dialog of the template wizard is for information purposes only.
It informs you that a new template has been created and can be used for the creation of new documents. Click on the button to terminate the template wizard.
If the template wizard fails to create a new document with the information from the template, it will display a list of error messages that describe the cause of the failure. The dialog will look similar to the one below:
In this case, you will have to correct the information in one or more of the previous dialogs. You can go back through the previous steps by pressing the button. The template wizard will not loose any information from previous or later dialogs when you move back and forth between the wizard dialogs with the and buttons.
Instead of using the template wizard, a new template can be created from an existing document. This is convenient if you already have an example document of a certain type and want to create new documents with the same document type.
For example, you may have the IEEE Standard DTD installed on your system and some documents that are using this DTD exist. To create new documents that conform to the IEEE DTD, you will need to create a document template for this document type. Instead of starting the template wizard, you can simply load one of the existing IEEE documents and derive a new template from this document. This template can then be used for creating new IEEE documents.
To create a new template from an existing document, follow these steps:
Select -> from the main menu and open a document of the document type in question.
Select ->-> from the main menu.
Enter an appropriate name in the file selection dialog that appears and click on the button. The new template will be saved under this name in the template directory.
Once a new template has been derived from a document, it can be used to create new documents of the same document type as the original document.
Note: When a template is created from an existing document, the template will contain the complete document prolog of this document. All declarations in the original document (e.g. local entity declarations) will be part of the template and will appear in the prolog of new documents that were created with this template.
If you create a new template from an existing document, the current style sheet settings for this document are stored in the new template.