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.
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/">
<head>
<schema href="tred_extension_schema.xml"/>
</head>
<pkgname>sample_extension</pkgname>
<title>A Sample TrEd Extension</title>
<version>3.1</version>
<copyright year="2008">Petr Pajas</copyright>
<description>This is extension provides an example of how a TrEd extension might look like.</description>
<require>
<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"/>
</require>
</tred_extension>
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:
contrib/
contrib/sample_extension/
contrib/sample_extension/contrib.mac
contrib/sample_extension/sample_macros1.mak
contrib/sample_extension/sample_macros2.mak
Then
#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
→ →
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”.
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.zippkgname 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 pkgnamepkgnamepackage.xml
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.xmlpkgname.zip.tred.d/extensions/
in the user's home directory (pkgname/Application Data on Windows).
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).