17. Extension Packages

17.1. Extension Package Format and Content
17.2. Extension Repository
17.3. Developing Extensions

TrEd extension packages are used to package related annotation modes (macros and Perl modules they use), stylesheets, resources (e.g. PML schemas), XSLT transformations, etc. to TrEd users. Extension pacakges are deployed using package repositories on the web. The users can install extensions from TrEd by adding the URL to the repository to a list of repositories using a Repository Manager accessible from the Extension Manager and selecting the extensions of their choice. Extensions can depend on other extensions and the TrEd installer attempts to resolve the dependencies automatically.

The following sections describe in detail the content and format of an extension package and the format of a web repository.

17.1. Extension Package Format and Content

An extension package is simply a ZIP file that among other files contains in the root directory a PML file named package.xml conforming to the PML schema tred_extension_schema.xml that can be found in the resources subdirectory of a TrEd installation. The information provided in the package.xml file is used by the Extension Manager to present the extension to the user. The package.xml file can look like this:

<?xml version="1.0" encoding="UTF-8"?>
<tred_extension xmlns="http://ufal.mff.cuni.cz/pdt/pml/">
    <schema href="tred_extension_schema.xml"/>
  <title>A Sample TrEd Extension</title>
  <copyright year="2008">Petr Pajas</copyright>
  <description>This is extension provides an example of how a TrEd extension might look like.</description>
    <extension name="pdt20" min_version="1.0" href="http://ufal.mff.cuni.cz/tred/extensions/core/pdt20"/>
    <extension name="padt" min_version="1.0" href="http://ufal.mff.cuni.cz/tred/extensions/core/padt"/>


An extension is uniquely identified by its short name (identifier), which in the above example is sample_extension. Extension creators should attempt to avoid name colisions by choosing dinstinctive names. To the users, the extension is presented by their long name, that can be a short descriptive phrase (A Sample TrEd Extension in the case above). Extensions are versioned so that TrEd can offer the user upgrades if newer version of an installed extension becomes available in some repository. The package.xml file should further contain a description element (which may contain a short paragraph of unformatted text) and copyright information. Finally, a list of other extensions required by this extension may be given (in our example they are extensions pdt20 and padt both in versions at least 1.0); optionally, an URL can be given to provide a direct link to the required extension for the case when the user does not have the corresponding repositories configured.

Beside the package.xml file, an extension can contain arbitrary files, some of which, however, have special meaning to TrEd:

  • If the extension contains a directory contrib, TrEd looks for all files named contrib.mac located either directly in the contrib directory or in its first level subdirectories and attempts to loads these files as files with macros. Also, an

    #include <contrib/filename>

    directive used in a macro file of any extension looks for contrib/filename in all (!) extensions. To avoid filename clashes, it is therefore recommended to put contrib.mac and all other macro files of an extension to a subdirectory (usually named after the extension) of contrib, e.g. to create the directory structure like this:



    #include <contrib/sample_extension/sample_macros2.mak>

    can be used to include the macro file sample_macros2.mak provided by this extension from a macro file of some other extension.

  • If the package contains a directory named libs, TrEd adds this directory to the Perl module search path (@INC).

  • If the package contains a directory named resources, TrEd adds this directory to its list of resource paths (see resourcePath configuration option).

  • If the package contains a directory named stylesheets, TrEd adds this directory to its list of directories to load stylesheets from. Each file in this directory should be a text file containing a TrEd stylesheet in the TrEd stylesheet syntax. The name of the stylesheet in TrEd is the same as the basename of the file. If a similarly named stylesheet is already loaded (e.g. from some directory appearing earlier in the stylesheet directory list), the stylesheet is ignored. If the stylesheet name contains non-ascii or non-alphanumeric characters, they must be http://search.cpan.org/dist/Treex-PML/lib/>URI-escaped. If the user modifies a stylesheet loaded from an extension, TrEd saves the modified version into the user's private stylesheet directory ~/tred.d/stylesheets, which always appears first in the stylesheet directory list, so the modified version has precedence.

  • If the package contains a directory named documentation and this directory contains an HTML or XHTML file named index.pm, TrEd adds a menu item HelpExtension manualsextension name that opens this file in the default browser. This index file can be just a table of contents, pointing to other files within the extension via relative URLs.

  • If the resource folder contains a PML file name pmlbackend_conf.inc with transformation rules for the PML_backend, the transformatino rules are prepended to the list of transformation rules contained in pmlbackend_conf.xml and are used as described in section Section 16.6.2, “Support for non-PML XML-based formats”.

17.2. Extension Repository

Extension repository is a local directory or a directory located on the web accessible by HTTP prococol that contains the following files:

  • a file named extensions.lst containing a list of short package names of extensions available in this repository. Each extension name must be given on a separate line.

  • for each package listed in extensions.lst, a ZIP file pkgname.zip where pkgname is the short name of the extension, containing the extension data (and most notably the file package.xml).

  • for each package listed in extensions.lst a subdirectory pkgname (where pkgname is the name of the extension) containing a file package.xml (described above) which should be exactly same as the one contained in the ZIP package of the extension.

When TrEd reads the content of a repository, it first fetches the file extensions.lst and for each entry listed there it requests the file pkgname/package.xml. If the user chooses to install or upgrade a given package, the ZIP file pkgname.zip is requested and extracted to a subdirectory .tred.d/extensions/pkgname/ in the user's home directory (Application Data on Windows).

17.3. Developing Extensions

The file devel/pack_extension.sh contains a Bash script that simplifies creating an extension package from a given directory, copying the result to a repository directory, and incrementing package versions. It takes two arguments: a path to a directory with the extension (containing the pacakge.xml file and other files pertaining by the extension) and a path to a directory containing a package repository. The script performs the following steps:

  • Check that there is a valid pacakge.xml file (validation requires the script pml_validate from the PML Toolkit).

    compress the the content of the extension directory into a ZIP archive

    check if a similarly named ZIP file is already contained in the repository:

    • If not, it creates an entry in extensions.lst in the repository, copies the ZIP file to the repository and creates there the corresponding subfolder with the package.xml file.

    • If yes, it compares the MD5 checksum of the newly created ZIP file with the one already in the repository. If the MD5s are equal, it does nothing. Otherwise the least significant part of the package version is incremented in the file package.xml in the extension directory, a new ZIP file is created with the updated package.xml and both the ZIP and the package.xml are copied to the repository directory.


To test a development version of an extension from a live working copy, one can e.g. go to the ~/.tred.d/extensions directory and replace the subdirectory corresponding to the (relevant part of the) extension with a symlink to the working copy. Using a symlink rather than a direct copy protects the actual working copy from being deleted by TrEd if Uninstall is performed on the extension from the Extension Manager (only the symlink gets deleted).