Invocation

The user interface to TEItools is a single script named sgml2any. It should be invoked via some other name like linuxdoc2tei or tei2tex, by the means of a symbolic link or just a copy. The syntax is asfollows:

scriptname source_file style_options

source_file is the name of the source SGML file to be processed.

Each style_option looks like

-style name or like -style name=value.

Each name modifies the output of TEItools in one way or another. The order of -style options is significant. Single -style might list several comma separated styles. More on styles below.

You will probably create your own extensions to the TEItools skeleton like I do. These can include:

• DTDs you use locally;
• Local styles;
• Local scripts and libraries.

To facilitate such local development, the TEItools home directory could have a site subdirectory - possibly symlinked to some directory outside TEItools tree for easy upgrades. It should have the same structure main TEItools tree have. Files are searched in site tree first and then in the main tree.

Front-ends and back-ends

sgml2any determines the frontend and backend to use just by its name: if it is started as tei2rtf, then the frontend is taken to be tei, and the backend is rtf.

Each frontend is placed in a subdirectory under $SGML_HOME. In turn, each backend lives in a subdirectory under the frontend's directory. The backend directory contains a CoST script named script plus any supplementary files it needs.The backend directory also contains a styles directory which in turn contains style files.

Each backend script processes document presentation independently, which distinguishes TEItools from DSSSL-based software. (Please, don't tell me I'm doing it in wrong way, you won't be first to do that, and even not in first dozen :-)). I'm trying to be consistent across scripts as far as it makes sense, so please report all divergences as bugs.

Style files are used by just appending them to the main script, so they can rename existing Tcl procedures and substitute their own equivalents. Styles for say tei to rtf conversion are looked up in $SGML_HOME/tei/rtf/styles directory.

If style has the name=val form, then a global Tcl variable TEItools_name_value will be set to val. It could then be checked from within the main scripts or styles.

If style has the name form, then a global Tcl variable TEItools_name_in_use will be set to some value. In this way styles could check for presence of other styles.

To understand the scripts, you have to know Tcl, CoST, and for RTF backend, RATFINK.

Localization

The TEItools are targeted to be easily internationalized. They works pretty well in Russian, since that's what I'm using daily. English, Russian, French, Finnish and Czech localization files are included in the distribution. You should clone one of them for creating new language support data.

Everything locale-dependent is in $SGML_HOME/lib/locale.LANG.tcl files. LANG is defined this way:

1. If top-level <tei.2> element carries lang attribute, its value is taken. Otherwise,
2. If SGML_LANG environment variable is defined, its value is taken. Otherwise,
3. If LANG environment variable is defined, its value is taken. Otherwise,
4. en is taken.

Note that LANG value is converted to lower case to form file name.

Locale files specify the following stuff.

First, there should be localize substitution[2], which defines some wordings in your native language, such as Table of contents etc. Second, there should be functions whose actions are localization-dependent. Currently, they are the following (parentheses show which backend uses the function).

openLang { lang } (LaTeX)

Appropriate \selectlanguage{} command. If your TeX installation doesn't use the babel package, return empty string. Example: \selectlanguage{english}.

closeLang{} (LaTeX)

Closing \selectlanguage{}.

tabTitle { number } (RTF)

Table caption. number gives table number. Example: "Table ${number}:"

figTitle { number } (RTF)

Figure caption. number gives figure number.

appendixPrefix { number } (RTF)

Appendix name letter generator. For example, if your appendices are numbered with "A", "B" and so on, then [appendixPrefix 0] should return "A" etc.

Styles

Note that each style applies to one backend only.

RTF specifics

The RTF backend now supports user-defined styles. For an example see $SGML_HOME/site/tei/rtf/styles/userstyle.

To make page references actual (e.g. in table of contents), load resulting RTF file into MS Word and press Ctrl-A F9 (select all and recalculate fields).