TLex / tlTerm / tlDatabase Documentation

• FAQ: TLex/tlTerm/tlDatabase Frequently Asked Questions; Tips & Tricks; Undocumented
• TLex/tlTerm/tlDatabase Best Practices
• Lua Scripting Documentation and Sample Scripts

See also the TLex User Guide (or tlDatabase User Guide) for primary documentation.

FAQ: TLex/tlTerm/tlDatabase Frequently Asked Questions; Tips & Tricks; Undocumented

Listed here are answers to common queries, as well as some potentially useful features that haven't quite yet made "full-fledged feature" status and/or have otherwise not yet been documented elsewhere, as well as other useful "tips & tricks" for TLex, tlTerm and tlDatabase.

Yes.

Yes.

Yes, all of our software products do.

As of the end of 2010, all of our software still runs on Windows 2000, Windows XP, Windows Vista and Windows 7 (as well as Windows 2003 and 2008). (As of 2011, we intend to start phasing out support for Windows 2000, as well as service pack levels of XP SP2 or earlier.)

Yes; as of early 2010, there are native Mac versions of these applications.

Prior to this, virtualisation was also a solution: TLex and tlTerm will also work on the Mac if using Parallels. TLex and tlTerm have also been reported to more or less work in the CrossOver environment, although some configuration is needed - one of our users has kindly posted instructions online: Getting TshwaneLex working in CrossOver.

In early 2009, we began switching to a "new, improved Document Object Model" ("DOM" = the way your document is represented internally in TLex). This is a significant improvement to the "internals" of our software that enables our users to have much more power and flexibility in terms of how they can structure their data (particularly regarding "XML inline elements / PCDATA").

(If you don't understand this or are otherwise unsure, please contact us.)

Most old-DOM TLex documents can be upgraded completely transparently to the new DOM.

However, in a small number of cases, certain complex old-DOM documents can not be trivially migrated without a little re-modelling work on the data.

Thus, in order to give those customers time to make the change, we have implemented a dual-release system where we provide both old-DOM and new-DOM versions in parallel:

If your version number's SECOND DIGIT is a ZERO, then you are using an "old DOM" release, e.g.: "7.0.0.270"
If your version number's SECOND DIGIT is a ONE, then you are using a "new DOM" release, e.g.: "7.1.0.270"

The fourth digit corresponds to the particular release date. Thus "7.0.0.270" and "7.1.0.270" would be built and released simultaneously.

Note that you CAN install BOTH old-DOM and new-DOM versions of the software on the same computer at the same time. (They will share the same activation information / 'license'.)

This temporary dual-release system may be confusing, but we have chosen to do this as the best option for our customers, as it ensures that no customer will be forced to interrupt their current workflow (i.e. if you're on the old model, you can stay on the old model for now, while new customers, or customers for whom transitioning is easy, will be able to start immediately on the new DOM if desired).

To upgrade a document to the new DOM, first make an extra backup of your .tldict TLex file (or .tterm file for tlTerm). Then, simply open your document in a new-DOM ".1" release, and it will perform any necessary conversion when it opens the document. There are three possibilities:

Possibility 1, No Changes Required: If your document is simple enough (as will be the case with most of our users), then NO CONVERSION MESSAGE will appear, and the document will open immediately. If this happens, congratulations, you are now on the "new DOM" and can simply continue working :) No document reviewing is required.

Possibility 2, Changes Required, Simple Case:: If you see the following message, it means that TLex needs to convert the data:

Document uses legacy Document Object Model (DOM), and needs to be converted to the new, improved DOM. You should make a backup of your data before proceeding."

If this happens, proceed, and then review how your dictionary looks. If it looks good to you, congratulations, you are now on the "new DOM" and can simply continue working.

Do not be alarmed if you see this dialog, the majority of upgrade cases where you see this dialog, the document can be upgraded without problems.

Possibility 3, Changes Required, Non-Trivial Case: Same message as 'possibility 2'; however, if you spot problems in the 'formatted output' while reviewing your dictionary, then contact us to assist with the upgrade process (or continue working on old-DOM). (This scenario only occurs in certain relatively obscure situations involving relative mixed ordering of element PCDATA and attributes in the Styles system - unfortunately it was not technically feasible to prevent.)

Please note that while you can always upgrade an old-DOM document to a new-DOM document, once you've saved it you cannot convert the new-DOM document to an old-DOM document. Thus always make a backup copy of the file before attempting to upgrade, and make sure the document 'looks OK' before proceeding in new-DOM.

Though we officially announced the end of old-DOM TLex Suite for version 2013, as of 14 July 2016, we have continued to do parallel releases of old-DOM (7.0, 8.0, 9.0 etc.) and new-DOM (7.1, 8.1, 9.1 etc.) TLex Suite. Old-DOM TLex Suite may be discontinued at any time henceforth (date to be determined).

NB, users requiring old-DOM will NOT be "stuck" at that point - you will be able to continue to use the last-released old-DOM installer, but after the phase-out date, we will no longer publish updates for old-DOM TLex Suite, so for new features and fixes you should try upgrade to new-DOM. Please contact us if you need assistance upgrading to the new-DOM version.

Version	Old DOM	New DOM	Releases
TLex Suite 2016 (v9)		9.1	To be determined
TLex Suite 2013 (v8)	8.0	8.1	Dual-release
TLex Suite 2012 (v7)	7.0	7.1	Dual-release
TLex Suite 2011 (v6)	N/A	6.1	Dual-release
TLex Suite 2010 (v5)	5.0	5.1	Dual-release
TshwaneLex Suite 4	4.0	4.1	Dual-release
TshwaneLex Suite 3	3.0		Old-DOM only
TshwaneLex 2	2.0		Old-DOM only

We recommend starting new projects on the new DOM (".1" releases) immediately.

Generally, these are already "new DOM", so not to worry.

If one regularly imports CSV documents with given columns, defaults for the corresponding attributes can be configured by creating a text file in the TLex/tlTerm application folder (typically something like "c:\Program Files\TLexSuite") called "ImportCSVDefaults.txt". The contents of this text file are simply what you would see in the right-side column of the 'Import CSV' dialog box, e.g.:

Lemma::LemmaSign
Lemma::PartOfSpeech
Lemma::Sense::TE::TE

A blank row corresponds to a "Nothing". If this text file is present, then when the 'Import CSV' dialog is opened, it will automatically attempt to fill in the right-side column with the fields read from the text file (provided those fields exist in the DTD; if not a "Nothing" will be added instead).

[Version 2010 (v5)] This can be simply resized with the mouse.

[TLex 4] As of TLex Suite 4, one can change the width of the Lemma List or Term List dynamically in TLex or tlTerm using the keyboard shortcuts Ctrl+Alt+Shift+Right and Ctrl+Alt+Shift+Left.

[New from 2006-11-15] For some projects the lemma list width may seem a bit on the small side. The width can be configured by creating a DWORD registry key called "EntryListWidth" under "HKEY_CURRENT_USER/Software/TshwaneDJe/(ApplicationName)/UserInterface". This specifies the width as a percentage of the width of the application window. The default is around 11%.

Under "HKEY_CURRENT_USER/Software/TshwaneDJe/(ApplicationName)/App", create a DWORD registry key called "NoSplash" and set the value to 1.

[Releases later than 29 Nov 2010] Go to 'Tools/Options', 'Properties', search for '/SectionSearch/MaxResultsToDisplay' and change as desired.

[Releases prior to 29 Nov 2010] Under "HKEY_CURRENT_USER/Software/TshwaneDJe/(ApplicationName)/Settings" (create if necessary), create a DWORD registry key called "MaxSearchResults" and set the value to the desired maximum number of search results.

[New from 2006-11-16] Create "HKEY_CURRENT_USER/Software/TshwaneDJe/(ApplicationName)/Settings". Underneath this, there are two possible settings:

TildeStyle (DWORD)
     0: Underline (default)
     1: Bold
     2: Italics
     3: No styling
TildeMethod (DWORD)
     Set this to 1 for alternate tilde expansion strategy for when first letter is uppercase, e.g. lemma "university ... U~ of Cape Town"
[OLD METHOD - Use the new Tilde expansion Lua script method instead]
TildeLuaScript (STRING)
     Specifies a filename for an optional Lua script to be invoked to handle the tilde replacement behaviour. When set, this supercedes the TildeMethod. If the filename is relative (as opposed to absolute), it is looked for relative to the application executable path. The script must define a "main" function that takes four parameters: function main(sString,sStyle,sReplacement,bExpand) - e.g. ("~ the line","%u","draw",true). The sStyle parameter is thus the markup specified by the TildeStyle setting above, while bExpand specifies whether the 'Expand tildes' Format (F4) option is enabled. Note that TLex must be restarted whenever you update this script, as it loads the file once at application startup for performance reasons.

It is now possible to assign a Lua script that will be invoked in place of the default built-in tilde replacement behaviour.
The script must define an "ExpandTilde" function that takes four parameters: function ExpandTilde(sString,sStyle,sReplacement,bExpand) - e.g. ("~ the line","%u","draw",true). The sStyle parameter is thus the markup specified by the TildeStyle setting above, while bExpand specifies whether the 'Expand tildes' Format (F4) option is enabled.
The script must be set on a per dictionary basis. To set the script perform the following steps:

• Select "Properties" from the "Dictionary" menu.
• Click on the "Properties [Advanced] tab.
• Locate the item labelled "Lua/ExpandTilde", if no such item exists then you will need to update to a new version of TLex (recommended) or you will need to use the old tilde expansion method in the section above (not recommended).
• Double click on the item labelled "Lua/ExpandTilde".
• Paste or enter the contents of the script you wish to use, when you are done select "OK".
• The script is now applied, please be aware that this script is saved with the dictionary and will therefore also be applied for all other users of the dictionary as well.

Under "HKEY_CURRENT_USER/Software/TshwaneDJe/(ApplicationName)/PerLexicon/(ProjectKey)/SectionID(Num)/", the following settings apply:

• Disable large headword in Preview

  ShowHeadwordPreview (DWORD): [New from 2007-06] If 0, the large headword displayed at the top of the Preview is disabled.

• Limit number of entries shown in Preview

  MaxPreviewEntries (DWORD): [New from 2007-06] Limits the maximum number of entries following the selected one that are displayed

1. [Optional] Try to get your styles 'more or less correct' in TLex already - this will minimize the amount of work that needs to be done later in InDesign.
2. [Optional] If you have multiple stylesets, select the desired styleset with Ctrl+P in TLex.
3. Export RTF from TLex/tlTerm ('File/Export/RTF (Rich Text Format)').
4. Create 'new' document in InDesign, with desired or estimated projected number of pages, and desired number of columns.
5. Select the 'File/Place' command, and select the RTF file that was exported from TLex/tlTerm.
6. Hold in Shift and click in the top left of the first column. The entire document should now be imported.

Once in InDesign via RTF, each field (information type, i.e. element/attribute) has an associated 'style' which may be manipulated centrally in InDesign.

1. Open the TLex file and do 'File/Export XML (Formatted)' (NB: It must be the 'Formatted' XML export option).
2. Open InDesign and create a new blank document with the desired layout, number of pages, columns and so forth.
3. Select 'File/Import XML' in InDesign, and select the XML file that was exported from TLex (the default import settings should be fine). The InDesign 'Structure' view should appear, showing the XML entry content, with 'root' at the top.
4. Drag the 'root' node with the mouse and onto the top left of the document. The first page of text should then display in the document, with a small square in the lower right of the page/column, with a '+' in it.
5. Ctrl+Click on the '+'
6. Hold in Shift and click in the top left of the second page, to 'place' the next page of text. This should cause pages 2 and onwards to be shown. (If you don't hold in Shift, only page 2 will be placed.)
7. Create some InDesign styles, as desired, based on the desired visual appearance of various fields.
8. Click in the Structure view , then click the tiny drop-down arrow in the 'Tags' overlay window, and select 'Map Tags to Styles'. Here you can map each of your InDesign styles (visual appearance) onto the corresponding XML data fields from TLex.
9. In theory, the InDesign styles and tag mapping should only have to be done once; whenever there is newer data available from TLex, it can be re-imported onto the Structure root node in InDesign.

• 'Word Boundary' Syntax

  Use "\b" to find word boundaries; "\<" and "\>" for left/right word boundaries. (NOTE: For TLex/tlTerm releases prior to June 2007, use [[:<:]] and [[:>:]] for left/right word boundaries.)

• Find all examples (or combinations) in which the "~" was not used

  Do a field-specific (e.g. "Example::Example") regular expression search for "^[^~]+$".

• Find all definitions (or examples etc.) which end with a fullstop

  Do a field-specific (e.g. "Definition::Definition") regular expression search for "\.$".

• Find all definitions (or examples etc.) which do not end with a fullstop

  Do a field-specific (e.g. "Definition::Definition") regular expression search for "[^\.]$".

• Find all definitions (or examples etc.) which begin with an uppercase letter (or with a lowercase letter)

  Do a field-specific (e.g. "Definition::Definition") case-sensitive regular expression search for "^[A-Z]" (or "^[a-z]" for lowercase letters).

• Find all single-word (i.e. non-multi-word) headwords/terms which begin with an uppercase letter

  Do a case-sensitive regular expression search for "^[A-Z][^ ]*$".
  
  => A mistake people sometimes make, particularly inexperienced users, is to enter headwords or terms starting with a capital letter, e.g. "Computer" instead of "computer"; this search can help automatically find such cases, while ignoring multi-word terms that should be uppercase, e.g. "World Wide Web".

• Find all entries beginning with a certain letter or range of letters

  See the section below titled "Exporting all Entries Beginning with a Certain Letter (e.g. 'A'), or a Range of Letters (e.g. 'Q to Z')"

Our regular expressions use the Perl syntax: Regular Expression Syntax Reference.

There are at least two methods:

(1) In the DTD editor, configure the attribute value to be 'required'. Then do an "Error check" (or use the "Required attribute" F5 Filter).

(2) Do a field-specific F3 search for the regular expression "^$".

1. Select the first desired entry
2. Select 'Edit/Tag entry'
3. Select the last desired entry
4. Select 'Edit/Tag range'
5. Select 'Edit/Filter tagged'

Then when exporting, select the 'Use filters' option.

[TLex 2] To find or export all entries beginning with a certain letter or letters, one can use a field-specific regular expression search, combined with a search filter, as explained in the following steps:

1. Go to "Search (F3)"
2. Make sure "regular expression" is ticked
3. Make sure "Whole word only" and "Case sensitive" are not ticked
4. Click "Fields <" to open the field list
5. Click "Clear all" at the bottom of the field list
6. Tick "Lemma::LemmaSign" in the field list
7. Enter "^a" into the search box (replace "a" with the desired starting letter). For a range of letters such as 'q to z', use the search query "^[q-z]". (NOTE: If you enter "^a" and it changes into a single character, turn off "replace-as-you-type" under the "Tools" menu.)
8. Click "Search"
9. Click "As Filter" ("Filter +" in version 4) in the search results (this will apply the current search results as a 'filter')

Now export as usual (e.g. to RTF), making sure to select the "Use filters" option.

(For languages with prefixes, e.g. if a "-" precedes roots/stems in the headword, the regular expressions "^-?a" and "^-?[q-z]" can be used respectively.)

Apply the desired filter(s) under "Filter (F5)", and select "File/Save a copy/TshwaneLex file". Select "Use filters", and if desired, "Include incomplete articles".

This can also be used to clear a side of the dictionary, by applying a filter on that side that leaves no entries remaining (e.g. 'subtract all entries with a lemma sign').

NB: One thing to watch out for when exporting a filtered subset in this way, is that cross-references to articles that are not also included by the filter will be removed from the exported data.

See previous question.

If one wants to retain certain settings from the original database, such as the user logons, see previous question.

If one only wants to use the core TLex DTD and styles, but lose e.g. the user logons, one can use "DTD Templates", explained in the User Guide.

Open "Edit/Search and replace". Under "Fields", do 'Clear all' and tick only the 'Incomplete' attribute. Do a find of "0" and replace with "1" (enter these without quotes).

Open "Edit/Search and replace". Under "Fields", do 'Clear all' and tick only the 'Incomplete' attribute. Do a find of "1" and replace with "0" (enter these without quotes).

This can be achieved using the CSV import and using the values '0' or '1' (to clear or set the incomplete status, respectively) for the incomplete attribute. Be sure to uncheck 'Mark imported entries as incomplete'.

The quickest method [TLex 3] is to go to "Format (F4)" and select the 'modified date' (typically named "Modified") attribute under "Sort by". The most recent work will now be at the bottom of the Lemma List or Term List. Once done, you can select the "-" option from the "Sort by" list to go back to normal.

Note that this can be combined with "Filter (F5)"; for example, you could filter on a particular username to see all the latest work of that user only.

Go to 'Search (F3)', tick 'Regular expression' and enter '\w+'. The number of words will be the first number after "Matches found".

Clicking on the number of results will display the word count on a per-field basis.

Go to "Search (F3)". Click "Fields <" to display the fields list, click 'Clear all' and tick only the 'Modified' attribute on the lemma/entry element (this means "restrict the search to the 'last modified date' field"). Enter a date into the search box in YYYY-MM-DD format (e.g. "2008-03-20", without quotes) and click 'Search'.

You can also easily search for work from an entire month by searching for that month specified in YYYY-MM format, e.g. "2008-03".

To find work from multiple days, you can tick 'Regular expression' and then separate them with the "|" (vertical line, meaning 'or' in regular expression syntax) character, e.g. you could search for "2008-03-20|2008-03-21|2008-03-22". More advanced regular expressions could be used to construct fancier queries.

Note that this can be combined with "Filter (F5)"; for example, you could first filter on a particular username to see the work of that user only.

'Inline elements' refers to when an element is used inside the text of a field, i.e. when another field type occurs somewhere within the text of a single "Attributes (F1)" box. Take the following simple example Dutch - French dictionary article:

aanbouwmeubel meuble [m.] assemblé par éléments

The gender "m." of "meuble" is indicated in italics with square brackets within the actual translation "meuble assemblé par éléments". Using an inline element, the gender information may be specially tagged as such, e.g. with its own "gender" element, using XML syntax inside the translation equivalent field, like so:

meuble <gender>m.</gender> assemblé par éléments

Here "gender" is an element defined in the DTD. It thus has its own style in TLex, allowing it to automatically always appear with its own particular distinctive font/colour/formatting as well as automatic punctuation such as the square brackets around it.

The sample "English - French Inline Element Sample.tldict" that comes with TLex demonstrates this usage of inline elements.

Inline Elements Background:

In XML, only "PCDATA" can contain inline elements - regular attributes may not. This is because for an inline tag to be understood, the text that it occurs in must be 'parsed' (i.e. basically 'processed'), and ordinary attribute values are not parsed - only the PCDATA section of an element is parsed (PCDATA actually stands for "Parsed Character Data"). The PCDATA of an element is basically everything that falls between the opening tag of an element and its corresponding closing tag:

<Element ...>THIS IS PCDATA</Element>

Ordinarily, by default, a translation equivalent in TLex is stored as a regular attribute of an element, which will be exported as XML that looks like the following:

<TE TE="meuble assemblé par éléments"></TE>

If the "TE" attribute above is instead marked as being used for the PCDATA of the TE element in the DTD Editor, then it will be exported as XML that looks like the following (note the translation equivalent is now in the PCDATA section of the element):

<TE>meuble assemblé par éléments</TE>

This then allows inline elements to be used, e.g. the following is valid XML:

<TE>meuble <gender>m.</gender> assemblé par éléments</TE>

Using inline elements within a regular attribute, however, is invalid XML:

<TE TE="meuble <gender>m.</gender> assemblé par éléments"></TE>

Inline elements may also be used for basic formatting, such as bold and italics, instead of the TLex "%" markup characters:

<TE>here is some <b>bold</b> text</TE>

Advantages of Inline Elements:

In the above example of the "gender" element, using an inline element effectively allows "knowledge" of what the "m." means to be encoded into the data, rather than just "dumb" text. This has advantages, e.g. in the TLex Electronic Dictionary module, if the end-user clicks on a gender label, a grammar window explaining the gender system could be displayed. A smarter search index could also be generated, allowing the end-user to search for "meuble assemblé", since the search system could 'know' that the gender label is not strictly part of the translation.

Inline Cross-references [TLex 3]

Another advantage of inline elements in TLex is that they allow for the creation of inline cross-references - i.e. cross-references somewhere within the text of a field. This can be configured in the DTD Editor, in the "Attributes" section (using the 'XRef target' and 'XRef display' checkboxes). The 'XRef target' attribute is used to specify the actual cross-reference, while the optional 'XRef display' attribute, if filled in, indicates some substitution text to appear in place of the cross-referenced headword (if you need to display something different). (If both of these two settings are used, they must be ticked for different attributes (or PCDATA) within the same element.)

The 'XRef target' attribute type may be used on either PCDATA (for inline cross-references - this will likely usually be the case) or normal attributes. In the following example it is used in PCDATA:

<reftype>See</reftype> <ref>bunny</ref>

If "ref" has a PCDATA with 'XRef target' selected, then TLex will try to resolve "bunny" as a cross-reference and make a hyperlink. It doesn't have to be PCDATA, it could be a regular attribute; you could thus also do something like:

<reftype>See</reftype> <ref target="bunny" />

The 'XRef display' is for cases where the text that is displayed in the Preview should be different from the actual cross-reference target. For example, if we create a "ref::display" attribute and check the 'XRef display' option for it, we could do the following:

Check <ref display="Google">http://google.com/</ref> for more info.

or non-PCDATA equivalent:

Check <ref display="Google" target="http://google.com/"> for more info.

The output will then display "Check Google for more info", but if you click on "Google" the actual link will be "http://google.com/". Apart from hyperlinks to websites, this also has lexicographic applications (the inline cross-references sample in TLex demonstrates this).

'XRef target' is required to be ticked if you want to use inline cross-references, but 'XRef display' is optional. If you use it though, it must be on the same element as the 'XRef target' it corresponds to. This can also be used on either PCDATA or normal attributes.

Note that inline cross-references are not "smart cross-references", although will display as a hyperlink if the cross-reference target is found. It is suggested to use normal smart cross-references instead of inline cross-references unless you have a definite need to e.g. have complex sentences with cross-references appearing anywhere inside a sentence.

By default the cross-reference type is displayed with the same style as the cross-reference headword, e.g.:

hound SEE dog

It is sometimes desirable to use a different style for the cross-reference type, e.g.:

hound SEE dog

This can be achieved to some extent by using markup tags in the 'display labels' under "Dictionary/Edit cross-reference types", e.g.:

%bSEE%b

In this example, the bold tags 'cancel out' the surrounding bold from the overall style of the entire cross-reference. In future, we intend to add more advanced controls for the appearance of cross-references.

Releases of TLex later than July 2007 include the ability to do closed list item validation for inline elements. A PCDATA section can be specified to be of 'closed list' type in the DTD editor, and if its value isn't in the selected list, it will be highlighted as red in the Preview (likewise for attributes written inline). For example, if you have in an etymology field:

From <lang>Old French</lang> <originword>entreprendre</originword>

then the part inside the "lang" tags may be checked against values in a closed list, such as a list of valid origin languages; thus if you make a typo:

From <lang>Old Frenhc</lang> <originword>entreprendre</originword>

the language name will be highlighted in red, immediately tipping the user off that there is a mistake.

[New from 2007-03-22; TLex 2] Special "tag" shortcut keys can be created under "Tools/Options/Keyboard shortcuts (macros)" that make tagging data with inline elements under "Attributes (F1)" far more convenient and user-friendly than typing out tags manually. This involves creating a shortcut key with the following format for "Text to insert when shortcut is pressed":

$TAG$:tagname

For example:

$TAG$:gender

Pressing this shortcut key in an "Attributes (F1)" box will then automatically 'intelligently' output either an opening "<gender>" or closing "</gender>" tag as appropriate, or if some text is selected, surround the selected text with a pair of opening and closing tags.

It may be useful sometimes to refer to a certain entry while working on another, so that both are on the screen simultaneously.

This can be achieved easily by selecting the desired entry (or entries) to view, selecting 'Edit/Tag entry' (Ctrl+F2), and enabling 'Edit/Show tagged always'. Once done, you can select 'Edit/Clear all tags'.

Older versions, or alternative method:

This can be done by selecting the entry you want to "pin", selecting "Edit/Tag entry", then enabling "Edit/Show tagged always", which will effectively "pin" tagged entries in the Preview.

Another trick here, or if you're using an older version of TLex without the 'tags' functionality, is to use "Search (F3)" to get the first entry into the search results window, then select and work on the other entry.

The most common cause of this is having the same dictionary file open more than once simultaneously (e.g. in two separate TLex windows). Failing that, it may be that the file is marked as 'read-only'.

This was caused by a bug in Windows Vista. A workaround has been implemented in newer versions of TLex - if you are experiencing this, use "Help/Check for updates" to update your software.

The idea behind 'templates' is to pre-create entire element tree sub-structures and then enter these 'in one go' in the Tree View. Templates are not yet directly supported in TLex/tlTerm, but are planned for a future release. In the meantime, for many applications, there are 'work-arounds' - tips that allow one to achieve a similar effect in certain cases. One, for 'lemma templates' as a whole, is to create a few 'dummy' entries, perhaps sorted to the top of the dictionary always, and use the "Lemma/Duplicate article" (Ctrl+Shift+U) menu command in TLex (or "Entry/Duplicate entry" in tlTerm) when you wish to create an instance of the 'template'. A similar technique can be used for sub-element trees within an entry, by using the Tree View 'copy' and 'paste' commands (Ctrl+C and Ctrl+V respectively) to duplicate Tree View structures from a 'template' source. Another possibility in some cases is to use the DTD child relation constraints, e.g. specifying a "one or more" relation will cause the child element to automatically be created when one of its parent elements are created. Finally, for advanced users, the built-in Lua scripting could be used.

Data in XML form can be imported into TLex or tlTerm via the "File/Import/XML" menu option.

It is best to import data into a 'clean/empty' document, i.e. to select the XML import command when no database is open in TLex/tlTerm.

Note that after importing XML, there would usually be no TLex/tlTerm styles, thus all imported entries will usually be displayed in a default text style in black on a white background. You can use the "Format/Styles" menu option as usual to add styles once you are satisfied with the import.

TLex has one or two basic 'expectations' of how the data should be structured in order to import the data in a meaningful way (i.e. in a way that allows TLex to 'understand' what some of the key fields are, such as the headword). The following is an example of roughly the simplest XML document that can be thrown at the importer:

<Dictionary>
<Language>
<Entry LemmaSign="cow">
</Entry>
</Language>
</Dictionary>

Note that the element for a 'dictionary entry' appears at the third depth level in the document, and should contain an attribute called "LemmaSign" that contains the headword; this allows TLex to recognise which attribute it should use as the headword for purposes of sorting, indexing in the Lemma List, and so on. (If the headword is in a different element or attribute, it will still be imported - TLex will just not 'know' to use that field for the Lemma List and so on.)

The names of the elements above ("Dictionary", "Language" and "Entry") can be anything, although their structure is important (i.e. second-level element represents each 'section' or 'side' of a dictionary within TLex, and third level represents the list of entries within that section).

Note that you do not necessarily need a DTD attached to the data - if importing XML data with no DTD, TLex will attempt to construct a DTD based on the elements/attributes it encounters. For well-structured data, this can work well.

Here is a slightly more complex example (note "TE" stands for "Translation Equivalent" for, in this case, bilingual English - Afrikaans data):

<Dictionary>
<Language>
<Entry LemmaSign="dog">
<Plural>dogs</Plural>
<Sense>
<TE TE="hond" />
<Definition Definition="A domestic mammal that barks" />
</Sense>
</Entry>
<Entry LemmaSign="cat">
<Sense>
<TE TE="kat" />
</Sense>
</Entry>
</Language>
</Dictionary>

The entries do not need to be correctly sorted within the XML (e.g. "dog" then "cat" above) - TLex will automatically resort them according to the default configured 'sort method' (which can also be changed at any time later on).

'Merge' XML Import

If you want to import entries into an existing database, the most important thing is to 'tell' the importer which 'side' (section/language) of a dictionary to import sets of entries into. This is done by filling in the language "Name" attribute with the exact same name configured for a language side/section under "Dictionary/Properties". This is shown in the following example:

<Dictionary>
<Language Name="English">
<Entry LemmaSign="dog">
<Sense><TE TE="inja" /></Sense>
</Entry>
</Language>
<Language Name="Zulu">
<Entry LemmaSign="inja">
<Sense><TE TE="dog" /></Sense>
</Entry>
</Language>
</Dictionary>

To do the 'merge' import, one then just selects "File/Import/XML" while the desired database is open.

NB: It is a good idea to always do a 'File/Create a backup' before doing a 'merge import'.

Click on the "Pronunciation" link near the bottom of the TshwaneLex page to hear an audio recording. (Note how the "sh" is not pronounced as in English, but more resembling an ordinary English "s".)

'Tshwane' is the African name for the city in which the company and its software were originally created, namely Pretoria, while 'Lex' refers to 'lexicon' (or alternatively 'lexicography'). For further background, see the Wikipedia entries on Tshwane and Pretoria.

TLex/tlTerm/tlDatabase Best Practices

• A common mistake is to export your data to an 'output' format such as Microsoft Word, and then start editing the data externally, e.g. within Microsoft Word. Do not do work on your data in Microsoft Word. If you are proofreading data that has been exported to MS Word (or any other printable / formatted output, such as InDesign), only mark the required changes, and implement those changes in TLex/tlTerm/tlDatabase directly. You can then re-export to MS Word easily. The latest version of your data should always be in TLex/tlTerm/tlDatabase. In general, it is easy to go from TLex/tlTerm/tlDatabase to MS Word / InDesign etc., but is very difficult to take any data or changes from MS Word back into TLex/tlTerm/tlDatabase. Because Word is an unstructured editing format and the tlDatabase product family are structured editing formats, there is no easy, generic way to get work done in Word into TLex/tlTerm/tlDatabase. (If you have made a mistake like this, contact us for possible assistance with data conversion to get the data back into TLex and/or XML - we are very experienced in dealing with these kinds of problems.)

• 'Ordinary' users / lexicographers / terminology practitioners / data enterers should be restricted from being allowed to edit the DTD using the User Management system; changes to the DTD should be coordinated and centralised through managers and/or IT administrators who are technically clued up enough to solve problems using the DTD in the correct way. Users who don't fully understand the DTD often create bad 'ad hoc' solutions to specific problems; these can cause many other problems down the line.

• For projects involving more than one person, enable User Management and give each user their own logon to the database - there are numerous significant advantages to using this.

• Keep your software up to date! Use the "Help/Check for updates" menu option to check if there are updates available.

• Always follow sensible backup procedures; see the User Guide for more guidance on this topic.