Editing TEI XML Documents in <oXygen/>

Abstract

This article is intended to prove how easy it is to create a TEI XML (Text Encoding Initiative) document and then convert it to the PDF or HTML format, all from within the <oXygen/> XML editor. We will use the TEI Lite DTD, the TEI XSL-FO stylesheets and the Apache's FOP, all of which are integrated into the <oXygen/> installation kit.

Creating an XML Document in <oXygen/> Using the TEI Lite DTD

From the "File" menu choose "New from Templates ...". The following window will be displayed, allowing you to choose from a list of built-in document templates as starting points for your TEI XML documents:

Document templates in <oXygen/>

Choose one of the TEI document templates from the list of built-in templates. If you select the TEI Lite template and click on the "OK" button <oXygen/> will automatically generate and open a skeleton document with a DTD declaration and minimum markup conforming to the declared DTD. The encoding is automatically set to "UTF-8".

Skeleton TEI document

If you wish to use a customized special-purpose TEI schema of type DTD, RELAX NG and W3C XML Schema (for example generated with the Roma program, http://tei.oucs.ox.ac.uk/Roma/, available on the TEI website, http://www.tei-c.org/Software/) you can manually modify the default document type declaration at the beginning of the document.

The encoding can be changed at any time by editing the XML prolog, for instance, changing to UTF-16:

<?xml version="1.0" encoding="UTF-16"?>

Editing the XML Document

The editor will scan the DTD file and will initialize the Code-Insight assistant. By pressing the "<" key, it is displayed a window containing all the elements that can be inserted at that point in the document. Notice that the window appears also when adding new attributes or when an attribute has default values you can choose from. In the first case the Code-Insight window is triggered by pressing the SPACE keyor the TAB key, in the later by pressing ' or " keys.

A simple TEI document can be:

]> Main title goes here Subtitle goes here syncRO soft Ltd. Filesize uncompressed: 10 Kbytes. XML TEI Lite online

syncRO soft Ltd. 170 Nicolae Titulescu Street Craiova 1100 support@oxygenxml.com

Freely available for non-commercial use provided that this header is included in its entirety with any copy distributed

Compiled from existing internal syncRO documents.

Paragraph, page divisions and punctuation have been checked before publication. Unless otherwise indicated (by a REND attribute) all EMPH elements should be rendered in italics, and all SOCALLED elements should be enclosed by quotation marks.

div sections bear IDs in the form Sn.

2003-05-25 syncRO soft staff edt (Editor) Created the initial version of the article 2003-05-26 syncRO soft staff pfr (Proofreader) check text 2003-05-27 syncRO soft staff cvt (Converter) convert to PDF using TEI XSL-FO stylesheets and Apache FOP Main title to be displayed on screen Subtitle to be displayed on screen syncRO soft May 27, 2003

Abstract

This template is intended to prove how easy it is to create a TEI XML (Text Encoding Initiative) document and then convert it to the PDF or HTML format, all from within the <oXygen/> XML editor. We can use the TEI Lite DTD, the TEI XSL-FO stylesheets and the Apache's FOP, all of which are integrated into the <oXygen/> installation kit.

Title of first section

First para

Second para

Third para

The encoding can be changed at any time by editing the XML prolog, for instance, changing to UTF-16:

<?xml version="1.0" encoding="UTF-16"?>

Title of second section

First para of second section

Second para of second section

Third para of second section

]]>

Transforming to PDF

Before proceeding to the FO transformation you need to check the validity of the document. For this, press the Validate Document button from the Validate toolbar, or use the shortcut of the Validate Document action, by default CTRL-SHIFT-V (COMMAND-SHIFT-V on Mac). The validity report will be displayed in the status bar. If there are errors, they will be listed in a special panel at the bottom of the <oXygen/> window.

Validation errors

In order to configure your XSL-FO transformation the following steps need to be taken:

Press the Configure Transformation Scenario button from the Transformation toolbar. This will open the Configure Transformation Scenario dialog where you can create a new transformation scenario or edit an existing one. Also you can use one of the predefined scenarios, for example the TEI PDF one which transforms a TEI XML document to PDF.

The XSL-FO transformation configuration dialog

On the XSLT tab of the Edit scenario dialog in the XSL URL field choose the tei.xsl file. You can find it by browsing to the folder ${frameworks}/tei/xml/teip4/stylesheet/fo/tei.xsl, where ${frameworks} is the frameworks subfolder of the <oXygen/> install folder. An XML FO document is generated when applying this stylesheet. Next, the FO processor can process it in order to generate output in the PDF format.

The XSLT configuration tab

On the FO Processor tab of the dialog make sure that the Perform FOP checkbox is selected.

The FO configuration tab

Make sure that the XSLT result as input radio button is selected.

Let the FO processor set to Built-in (Apache FOP).

Let the method set to pdf.

On the Output tab of the dialog choose the output file name and press the OK button.

The Output configuration tab

Press the Apply Transformation Scenario button from the Transformation toolbar or use CTRL-SHIFT-T (COMMAND-SHIFT-T on Mac) shortcut. This way the XSLT and FO processing is started. In the status bar is presented the current processing state. It will be displayed FO transformation successful when the FO processor ends. You can inspect the generated PDF file using the Acrobat Reader program.

Configuring an external FO processor, or other post processor.

The built-in FO Processor is based on the Apache project, and is under development. Problems may occur, depending on the complexity of the intermediate FO file.

To avoid this kind of difficulties it is possible to configure one or more external FO processors. (In other situations, you may need to run other post processors, not necessarily FOP.) Go to Options -> Preferences -> XML -> XSLT/FO/XQuery -> FO Processors to set up a post processor..

The external FO configuration dialog

By default, the list is empty. By pressing the New button it can be created a new FO entry. The entry consists of:

Name - This is the name that must be selected in the Processor combo box of the Edit scenario dialog when this processor is used in a transformation.

Description - A text description of the processor displayed in the FO Processors preferences panel.

Output encoding - The encoding of the output stream of the processor.

Error encoding - The encoding of the error stream of the processor.

Working directory - The start directory of the command that runs the FO processor.

Command line template - The command line is specifying the name of the FOP executable and the command line parameters. Try not to use environment variables in its expression, since those will not be expanded. Four editor variables can be used:

The FO method (the ${method} editor variable) - this being replaced by the editor with pdf, ps or txt;

The FO input file (the ${fo} editor variable) - this can be the edited file or the result of an XSLT transformation;

The file in which the result is stored (the ${out} editor variable).

The directory of the current oXygen project (the ${pd} editor variable).

Adding an external FO processor

Your editor may take as argument just one or two of the possible parameters. It is not required to use all the macros in the command line.