<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY void "">
]>
<?xml-stylesheet href="docbook-css-0.4/driver.css" type="text/css"?>
<article lang="en">
  <articleinfo>
    <title>TrEd User's Manual</title>
    <author>
      <firstname>Petr</firstname>
      <surname>Pajas</surname>
      <affiliation>
	<address format="linespecific"><email>pajas@ufal.mff.cuni.cz</email></address>
      </affiliation>
    </author>
  </articleinfo>
  <section id="intro">
    <title>Introduction</title> <para><application>TrEd</application> is a fully customizable and
      programmable graphical editor and viewer of tree-like structures
      such as dependency trees.  Among other projects, it was used as
      the main annotation tool for syntactical and tectogrammatical
      annotations of 
      <ulink url="http://ufal.mff.cuni.cz/pdt/index.html">The Prague Dependency Treebank</ulink>, as well as for
      decision-tree based morphological annotation of
      <ulink url="http://ufal.mff.cuni.cz/padt/">The Prague Arabic Dependency Treebank</ulink>.
    </para>
    <para>
      TrEd's default behavior can be customized
      (extended or narrowed)
      using so called <firstterm>annotation modes</firstterm> (previously called <firstterm>binding contexts</firstterm>)
      that can provide different interfaces
      for different types of data or annotation.
      An annotation mode usually consists of a set of macros
      (subroutines programmed in Perl)
      that can be bound to keyboard shortcuts, menus, toolbars,
      or certain automatically triggered events.
      TrEd comes with an extensive library of pre-defined macros, which greatly
      simplifies writing new annotation modes.
    </para>
    <para>
      The visual representation of trees in TrEd 
      can be customized independently on the annotation mode by 
      user-defined stylesheets.
    </para>
    <para>
      TrEd supports various input and output formats. Some of them
      are of general nature (e.g. a XML-based format
      called <link linkend="pmlbackend">PML</link>
      or a simple
      text-based format called <ulink url="http://ufal.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html">FS-format</ulink>
      developed by Michal Kren),
      while other are bound to a particular project. Support for new
      formats can be added by writing a custom I/O _backend (a Perl
      module able to convert data from their format-specific
      representation into the internal representation used by TrEd,
      and save them back in the original format)
      or by providing a pair of XSLT (1.0) stylesheets
      that convert a given XML-based format
      to PML and back.
    </para>
    <para>Annotation modes, libraries of macros, styles, 
      I/O transformations, resources (such as dictionaries, PML schemas, etc.), example
      data, etc. can be easily distributed to TrEd users
      as so called <link linkend="extension_package">Extension Packages</link>
      that are easy to create, deploy, install, and update.
    </para>
    <para>There is also a non-graphical (off-line) variant of TrEd,
      usefull for batch processing of tree-like data. It is called
      <command>btred</command> &#8212;
      <quote>Batch-mode Tree Editor</quote> and allows users to apply
      TrEd macros on trees without having to enter the graphical
      interface.  This tool is further acompanied by another tool,
      named <command>ntred</command>. NTrEd allows for parallelizing
      btred processing over a cluster of networked machines.  In
      combination with TrEd, it can also be used as an extremely
      powerful search engine over large base of data.
    </para>
    <figure float="0">
      <title>TrEd's main window with two views highly customized for
	visual comparison of trees of the Prague Dependency Treebank
	project.
      </title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="pics/treddiff.png" format="PNG" role="html"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/treddiff.eps" format="EPS" role="latex" width="13cm"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/treddiff" format="linespecific"/>
	</imageobject>
	<textobject>
	  <phrase>Screenshot</phrase>
	</textobject>
      </mediaobject>
    </figure>
    <para>
      <application>TrEd</application> runs on the following platforms (see <xref linkend="installation"/> for details):
    </para>
    <orderedlist continuation="restarts" inheritnum="ignore">
      <listitem>
	<para><productname class="trade">Windows 2000/XP/Vista</productname></para></listitem>
      <listitem>
	<para><productname class="trade">Linux</productname></para></listitem>
      <listitem>
	<para>
	    <productname class="trade">MacOS X</productname> (X11),
	    <productname class="trade">BSD</productname>,
	    <productname class="trade">UNIX</productname>,
	    <productname class="trade">Solaris</productname> and other UNIX-based systems
									     </para>
    </listitem>
    </orderedlist>
  </section>
  <section id="installation">
    <title>Installation and start up instructions</title>    
    <para>
      On all supported platforms, <application>TrEd</application> requires a Perl language
      interpreter, the Perl-Tk module (a GUI library for Perl), and
      depending on the I/O _backends used also various XML related
      modules. Installation of all these tools differs on Unix-like
      and Windows platforms.
    </para>
    <para>
      To install TrEd on your system follow the instructions specific
      for your platform below:
    </para>
    <section id="install-windows">
      <title>Windows</title>
      <section>
	<title>Step 1: installation of <application>Strawberry Perl for Windows</application></title>
      <para>
	<application>TrEd</application> for Windows requires
	<ulink url="http://strawberryperl.com/">Strawberry Perl</ulink>.
	It can be installed separately before the installation of <application>TrEd</application> or during the installation of <application>TrEd</application>.
	Packages with Strawberry Perl included are also available on the <application>TrEd</application>'s home page. These installation wizards 
	can download and set up Strawberry Perl, if it is not already installed on the system.
      </para>
      <para>
	  Active Perl is no longer supported. If you already have Active Perl installed, you have to install Strawberry Perl 
	  and choose proper custom Perl directory during the installation 
	  (by default, Strawberry Perl executable is installed to C:\strawberry\perl\bin).
	</para>
      </section>
      <section>
	<title>Step 2: installation of <application>TrEd</application></title>
	<para>
	  Download one of the versions of
	  TrEd installer for Windows from <ulink url="http://ufal.mff.cuni.cz/tred/">the project's
	  homepage</ulink>.  These packages contains
	  <application>TrEd</application> as well as all required Perl
	  modules. You can choose from 3 packages -- one with Strawberry Perl included, one without Strawberry Perl
	and one portable version of TrEd with portable Strawberry Perl included.
	</para>
	<para>
	  The portable version can be extracted to any location on your hard drive by <ulink url="http://www.7-zip.org/">7-zip</ulink>.
	To install non-portable TrEd, just follow the instructions of the installers.
	</para>
	<warning>
	<para>
	  It is not recommended to run TrEd with the CygWin distribution
	  of Perl (but you can install
	  Strawberry Perl, even if you already have a Perl installation
	  in CygWin). If you really must try running TrEd in CygWin,
	  follow the instructions for setup on <link linkend="install-unix">UNIX-like systems</link> (but you have been warned).
	</para>
      </warning>
      </section>
    </section>
    <section id="install-unix">
      <title>Linux, MacOS X, and other UNIX-like systems</title>
      <para>
	Almost every today's <application>UNIX/Linux</application> system contains a
	<application>Perl</application> installation,
	so we expect that you already have a working <application>Perl</application> setup (version &gt;= 5.8.3 is required
	but at least 5.8.8 is recommended). 
      </para>
      <para>
	<application>TrEd</application> further requires at least the following Perl
	modules and their dependencies:
	<itemizedlist>
	  <listitem><simpara><literal>File-Temp</literal></simpara></listitem>
	  <listitem><simpara><literal>File-Which</literal></simpara></listitem>
	  <listitem><simpara><literal>File-Spec</literal></simpara></listitem>
	  <listitem><simpara><literal>Text-Iconv</literal></simpara></listitem>
	  <listitem><simpara><literal>Tie-IxHash</literal></simpara></listitem>
	  <listitem><simpara><literal>Tk</literal> (for GUI)</simpara></listitem>
	  <listitem><simpara><literal>Compress-Zlib</literal> (for printing to PDF)</simpara></listitem>
	  <listitem><simpara><literal>XML-LibXML</literal> (requires <ulink url="http://xmlsoft.org">libxml2</ulink>)</simpara></listitem>
	  <listitem><simpara><literal>XML-Simple</literal></simpara></listitem>	  
	  <listitem><simpara><literal>XML-Writer</literal></simpara></listitem>
	  <listitem><simpara><literal>Archive-Zip</literal></simpara></listitem>
	</itemizedlist>
      </para>
      <para>
	TrEd along with all the required Perl modules and libraries can be installed
	in one step using an installer script <ulink url="http://ufal.mff.cuni.cz/tred/install_tred.bash"><literal>install_tred.bash</literal></ulink>, as follows:
	<programlisting format="linespecific">$ <userinput>wget <ulink url="http://ufal.mff.cuni.cz/tred/install_tred.bash">http://ufal.mff.cuni.cz/tred/install_tred.bash</ulink></userinput>
$ <userinput>bash install_tred.bash --tred-dir ~/tred</userinput>
</programlisting>
	 This installs TrEd under <filename>~/tred</filename> and all missing modules and libraries
	 under <filename>~/tred/dependencies</filename>. TrEd should be started using a wrapper script
	 <filename>~/tred/bin/start_tred</filename> which configures correct library paths.
      </para>
      <para>The installation script offers several options that allow custom choice of installation paths
      and also supports installation of development versions of TrEd from SVN.
      Use 
      <programlisting format="linespecific">$ <userinput>bash install_tred.bash --help</userinput></programlisting>
      for more information.
	<!--
	<note role="PDT20">
	  <para>
	    If you have the <productname class="trade">Prague
	      Dependency Treebank 2.0</productname> CD-ROM, you may
	    start the installation of these modules directly from
	    the CD-ROM by running <command>./install</command> in
	    the <filename>tools/tred/packages_unix</filename>
	    directory. In this case you may skip steps
	    1. and 2.
	  </para>
	</note>
	-->
      </para>
	  <para>
	    Check your installation with:
	    <programlisting format="linespecific">$ <userinput>~/tred/bin/start_tred -v</userinput>
TrEd 1.3587 2008-10-01 14:16:32Z
Perl: 5.008008
Platform: linux
Tk: 804.028
</programlisting>
	    If you get a similar output, you have successfully installed <application>TrEd</application> 
	    on your system. You can add <filename>~/tred/bin</filename> to your PATH or symlink all <filename>~/tred/bin/start_*</filename> scripts to some
	    directory in your PATH, e.g. <filename>~/bin</filename>.
	  </para>
<!--
      <orderedlist continuation="restarts" inheritnum="ignore">
	<listitem>
	  <para>
	    Fetch the  <ulink url="http://ufal.mff.cuni.cz/~pajas/tred/tred-dep-unix.tar.gz">tred-dep-unix.tar.gz</ulink>
	    package</para>
	</listitem>
	<listitem>
	  <para>
	    Unzip the package with
	    <programlisting format="linespecific">$ <userinput>tar xzvf tred-dep-unix.tar.gz</userinput></programlisting>
	  </para>
	  <para>
	    Change to the <literal>tred-dep-unix</literal> directory:
	    <programlisting format="linespecific">$ <userinput>cd tred-dep-unix</userinput></programlisting>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    If you have a root account on the machine, switch to it, e.g.
	    by issuing
	    <programlisting format="linespecific">$ <userinput>su root</userinput>
Password:
</programlisting>

	    If not, you may continue, but read carefully the following
	    step.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Run the module installation script (you'll need a
	    functional C compiler, <literal>make</literal>, etc., e.g. tools
	    available on most Linux/UNIX setups):

	    <programlisting format="linespecific">$ <userinput>./install</userinput></programlisting>


	    This scripts compiles and installs all required modules to the
	    directory prefix where the Perl installation resides. If
	    you'd like to use a different prefix (e.g. because you
	    don't have root permissions on the box), use
	    
	    <programlisting format="linespecific">$ <userinput>./install -&void;-prefix=<replaceable>directory-prefix</replaceable></userinput></programlisting>

	    and ensure the environment variable settings suggested by
	    the installation script at the end of the installation.
	    You can review all options of the installation script with
	    <command>./install -&void;-help</command>.
	  </para>
	</listitem>
 	<listitem>
 	  <para>
	    The last few steps describe the installation of
	    <application>TrEd</application> itself.
	    Start by fetching the latest <application>TrEd</application>
	    distribution package <ulink url="http://ufal.mff.cuni.cz/~pajas/tred/tred-current.tar.gz">tred-current.tar.gz</ulink>,
	    unpack the package it using
	    <programlisting format="linespecific">$ <userinput>tar xzvf tred-current.tar.gz</userinput></programlisting>
	    and copy the resulting <filename>tred</filename> directory
	    to a suitable locatoin on your system, e.g. with
	    <programlisting format="linespecific">$ <userinput>cp -R tred /opt</userinput></programlisting>
	    or 
	    <programlisting format="linespecific">$ <userinput>cp -R tred /home/<replaceable>yourname</replaceable></userinput></programlisting>
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Create symlinks to <command>tred</command>,
	    <command>btred</command>, and <command>ntred</command>
	    executables from the destination directory you have chosen to
	    some directory in your path, e.g.
	    <programlisting format="linespecific">$ <userinput>ln -s <replaceable>/opt/tred</replaceable>/*tred <replaceable>/usr/local/bin</replaceable> </userinput></programlisting>
 	  </para>
	</listitem>
	<listitem>
	  <para>
	    Check your installation with:
	    <programlisting format="linespecific">$ <userinput>tred -v</userinput>
TrEd 1.3587 2008-10-01 14:16:32Z
Perl: 5.008008
Platform: linux
Tk: 804.028
</programlisting>
	    If you get a similar output, you have successfully installed <application>TrEd</application> 
	    on your system.
	  </para>
	</listitem>
      </orderedlist>
	  -->
	    <!--
	    <note role="PDT20">
	      <para>
		If you have the <productname class="trade">Prague
		  Dependency Treebank 2.0</productname> CD-ROM, you'll find the
		unpacked installation package in the directory
		<filename>tools/tred/tred</filename>
		on the CD-ROM.
	      </para>
	    </note>
	    -->
	  <note>
 	    <para>
	      Unfortunatelly, another commonly used package contains
	      an executable named <command>tred</command>, namely the
	      <application>GraphViz</application> package by AT&amp;T.
	      This tool requires standard input, so if you attempt to start TrEd using
	      the command <command>tred</command> and it just hangs, 
	      you may be running the <application>GraphViz</application>
	      tool, not the tree editor TrEd.
 	    </para>
 	  </note>
	  <!--
	  <note>
	    <para>If the <command>tred</command>
	      executable fails to start at all, try changing the first line
	      (<command>#!/usr/bin/env perl</command>) so
	      that it points directly to your Perl executable. 
	      If you find <application>TrEd</application> halting immediately,
	      complaining about not finding <filename>Tk.pm</filename> or some
	      other Perl module, make sure that the installation went fluently.
	      You may also try to setup the environment variable <varname>PERLLIB</varname>
	      to point to the directory/directories where the modules
	      were installed.
	    </para>
	  </note>
	  -->
    </section>
  </section>
  <section id="terminology">
    <title>Basic concepts and terminology</title>
    <para>In this section we list and describe several concepts often used in this
      manual without a further reference.</para>
    <variablelist>
      <varlistentry>
	<term>file</term>
	<listitem>
	  <para>Files is a collections of trees (possibly acompanied with some
	    meta data common to all trees). Although the in-memory
	    representation of a file has always the same form,
	    its <quote>physical representation</quote>  (called
	    <firstterm>format</firstterm>) may vary. 
	    The part of <application>TrEd</application> program
	    responsible for reading and writing files in a specific
	    format is called a <firstterm>I/O _backend</firstterm>.
	    Depending on a format, files may differ in some features.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>tree</term>
	<listitem>
	  <para>
	    A tree in this context is a rooted oriented cycle-free graph of nodes.
	    In other words: it is a finite ordered set of objects called nodes (sometimes, but
	    not in this manual, also called <firstterm>verteces</firstterm>),  
	    each of the nodes but one is connected to another node
	    called its <firstterm>parent</firstterm>-node. This connection
	    is called an <firstterm>edge</firstterm>. Such a structure is then called a tree if edges
	    never form a cycle, i.e.
	    by following an edge-path (e.g. a sequence of adjacent edges
	    leading from a node to its parent-node) we
	    never return to the node where we
	    started. There is exactly one node without a parent-node,
	    called the <firstterm>root</firstterm> of the tree.
	    Every edge-path in the tree leads to this node.
	    If <replaceable>A</replaceable> is a parent-node of
	    <replaceable>B</replaceable>, then 
	    <replaceable>B</replaceable> is a <firstterm>child-node</firstterm>
	    of <replaceable>A</replaceable>. Nodes having the same
	    node as their parent-node are called <firstterm>siblings</firstterm>.
	    In <application>TrEd</application>'s internal
	    representation of a tree, there are the following additional
	    links between nodes:
	    <itemizedlist>
	      <listitem>
		<para>
		  a link from a parent-node to one of its child-nodes (usually but not necessarily this is the
		  first of its child-nodes in the linear ordering
		  of the tree). This child-node is called the
		  <firstterm>first-son</firstterm> of the parent-node.</para>
	      </listitem>
	      <listitem>
		<para>
		  First son is linked with its next sibling (if any),
		  called its right-sibling node (or <firstterm>lbrother</firstterm>).
		  This sibling is again connected to another
		  sibling, etc, so that all siblings are connected and
		  this connection contains no cycle.
		  Hence child-nodes of each node form a (possibly empty) chain
		  originating on the first-son and connecting all its
		  siblings one after another. The last sibling in the chain
		  is called the <firstterm>last-sibling</firstterm> or
		  <firstterm>last-son</firstterm>.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  For easier tree traversal, nodes in
		  <application>TrEd</application>
		  also contain link representing a reversed version of the
		  previous <quote>right-sibling</quote> relation,
		  called left-sibling (or <firstterm>lbrother</firstterm>).
		  So, if a node <replaceable>A</replaceable> is the
		  right-sibling of <replaceable>B</replaceable>, then
		  <replaceable>B</replaceable> is the
		  left-sibling of <replaceable>A</replaceable>.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>node</term>
	<listitem>
	  <para>
	    We have already describe a node as an object occuring in a tree and
	    possibly connected to other nodes in the tree. Apart from that,
	    every node may be associated with some data represented in form of
	    an <firstterm>attribute-value structure</firstterm> (AVS or
	    feature-structure if you like). Each members of this structure
	    (also called an attribute) has a name and value. Each name
	    may occure in AVS only once. The names of node's attributes and types
	    of their values are file-specific (or in some cases I/O-backend
	    specific). Generally, a value of an
	    attribute may be of one of the following types (it must be noted that
	    not all of the types are supported by the I/O backends equally):
	    <itemizedlist>
	      <listitem>
		<para>string</para></listitem>
	      <listitem>
		<para>enumerated type (a string value from a pre-defined
		  list)</para></listitem>
	      <listitem>
		<para><quote>flat</quote> list of values of one of the above types,
		  i.e. a string of <literal>|</literal>-separated items.
		  This type is used e.g. by FS-backend. 
		</para>
	      </listitem>
	      <listitem>
		<para>constant (usually not very useful, but sometimes handy)</para>
	      </listitem>
	      <listitem>
		<para>attribute-value stucture (implemented as a Perl hash reference,
		  fully supported by PML-backend and
		  partially emulated by FS-backend)</para>
	      </listitem>
	      <listitem>
		<para>ordered list of values of any type except list
		  (implemented as a Perl array reference of the
		  <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm">Treex::PML::List</ulink></literal> class). Currently
		  only supported by PML-backend.
		</para>
	      </listitem>
	      <listitem>
		<para>unordered list of values of any type except list
		  (implemented and supported likewise).
		</para>
	      </listitem>
	      <listitem>
		<para>alternative of values of any type except alternative
		  (implemented as a Perl array reference of the
		  <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm">Treex::PML::Alt</ulink></literal> class).
		  Alternative is very similar to unordered list but as long
		  as it has only one single value,
		  it is represented by that value (rather
		  than a <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm">Treex::PML::Alt</ulink></literal> array reference containing that value).
		  Alternatives are currently supported by PML-backend.
		</para>
	      </listitem>
	    </itemizedlist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>active (or current) node</term>
	<listitem>
	  <para>
	    The <firstterm>active node</firstterm> plays a similar role to that
	    of a cursor in a text editor. Each view remembers its active node.
	    In general, if we refer to the active or current node, we usually
	    mean the active node of the active view. In the default setup, the
	    active node is by default visually differentiated from other nodes
	    by its red color (other nodes are displayed as yellow or black).
	    However, it must be noted that a stylesheet can (and often does)
	    change the coloring of the tree, including definin its own way
	    to distinguish the active node.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>file list</term>
	<listitem>
	  <para>Files in <application>TrEd</application> are further
	    organized into collections called
	    <firstterm>file lists</firstterm>.
	    A file list is basically a list of filenames of files
	    belonging to the collection.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>view</term>
	<listitem>
	  <para>
	    A view is the part of <application>TrEd</application> window where
	    a tree is displayed. <application>TrEd</application> allows for
	    multiple views (created by splitting a view in half either along
	    the horizontal or vertical axis). Always, one of the views is
	    focused. This view is called the <firstterm>active view</firstterm>
	    (also the current view). All commands related to a file, tree and
	    node usually only apply to the active view (or more specifically,
	    to the objects it displays). The active view is visually
	    distinguishable from the other views by its thick black border.
	    Optionally, inactive views may also be stippled (see <xref linkend="stippleinactivewindows"/>). Views can display trees from one file but also from several
	    unrelated files. It is also possible to display a single tree in
	    several views simultaneously. Each view is associated with a
	    file list and a in-memory representation of a single 
	    file from that file list (in case of the active
	    view called the <firstterm>current file list</firstterm>
	    and the <firstterm>current file</firstterm>).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>value line</term>
	<listitem>
	  <para>This term refers to the text
	  field 
	  that appears 
	  above all tree views in the main window of TrEd,
	  just below toolbars.
	  Its content is controlled by stylesheets
	  and hooks.
	  It is typically used to display 
	  textual representation of the tree
	  in the current view, e.g. a sentence.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>status line</term>
	<listitem>
	  <para>Status line is a text
	  field that appears 
	  at the bottom of the main window of TrEd.
	  It is content is controlled by hooks and is typically used to display 
	  additional information about the
	  active node in the current view computed using by macros,
	  etc.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>macro</term>
	<listitem>
	  <para><application>TrEd</application> by default offers only a small
	    set of fundamental and generic tree-editing commands.
	    Commands specific to certain purpose or data are typically
	    implemented as user-defined macros. A <firstterm>macro</firstterm> is
	    a small program (more specifically a Perl subroutine), typically
	    associated with a keyboard shortcut or a menu item.
	    See <xref linkend="macros"/> for details.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>hook</term>
	<listitem>
	  <para>
	    <firstterm>Hooks</firstterm> are similar to macros but
	    they are called indirectly by <application>TrEd</application> 
	    rather directly by the user, although they also 
	    in a way response to a particular
	    event or action performed by the user. For example, every time
	    the user performs an action resulting in
	    a file being opened, <application>TrEd</application>
	    tries to locate and call a user-defined function
	    named <link linkend="file_opened_hook"><literal>file_opened_hook</literal></link>
	    in the current annotation mode (described below).
	    See <xref linkend="hooks"/> for details.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>annotation mode (also called binding context)</term>
	<listitem>
	  <para>
	    Macros serving similar purpose and often related to
	    some specific data may be organized to sets
	    called <firstterm>annotation mode</firstterm>.
	    Each view is associated with a annotation mode (called the
	    <firstterm>current mode</firstterm>) and
	    the user may easilly switch from one mode to another.
	    If the user presses a keyboard shortcut,
	    <application>TrEd</application> tries to find
	    a binding for that shortcut in the current
	    annotation mode. If it fails, tries the same
	    with a default annotation mode called <literal>TredMacro</literal>.
	    Similar lookup applies when the user performs an
	    action which requires a <firstterm>hook</firstterm>
	    to be called.
	    See <xref linkend="contexts"/> for details.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry id="minor_mode">
	<term>minor mode</term>
	<listitem>
	  <para>
	    The concept of minor modes is borrowed from <ulink url="http://www.gnu.org/software/emacs/">GNU Emacs</ulink>
	    editor. 
	    Minor modes use hooks to provide additional
	    functionality that is independent of the current
	    annotation mode. 
	    Different minor modes can be used for different views.
	    Currently TrEd ships with
	    the following minor modes:
	    <variablelist>
	      <varlistentry>
		<term>neigh_sent</term>
		<listitem>
		  <para>shows 
		  in the text view above the tree
		  the information from
		  a configurable number of preceding and following trees,
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>neigh_trees</term>
		<listitem>
		  <para>
		    shows the active tree
		    and a configurable number of
		    neighboring trees on the left and right.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>move</term>
		<listitem>
		  <para>allows the user to manually adjust
		  position of nodes in the view by dragging
		  the nodes and pressing
		  Shift or Control before drop to move
		  the current node or the whole subtree to the 
		  position of the drop.
		  </para>
		</listitem>
	      </varlistentry>
	      <varlistentry>
		<term>reslt</term>
		<listitem>
		  <para>is a helper minor mode used by
		  tree query macros to colour nodes that match
		  the query.
		  </para>
		</listitem>
	      </varlistentry>
	    </variablelist>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>stylesheet</term>
	<listitem>
	  <para>
	    A stylesheet is a set of rules (called
	    <firstterm>patterns</firstterm>) modifying the default appearance
	    of trees in a view. Each view initially uses a stylesheet provided
	    by the data file (which may be empty), but the user may instruct
	    the view to use another stylesheet. The same tree may be viewed
	    simultaneously in different views with completely different
	    stylesheets. If a very 
	    complex visual presentation is required, stylesheet rules may be accompanied by
	    some further presentational code defined in a
	    <link linkend="node_style_hook"><literal>node_style_hook</literal></link>.
	    For more information see <xref linkend="stylesheets"/>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry id="extension_package">
	<term>extension (or extension package)</term>
	<listitem>
	  <para>An <firstterm>extension package</firstterm>
	  is a special type of a ZIP file 
	  recognized by TrEd,
	  which provides some additional functionality to 
	  TrEd.
	  It can be installed directly from TrEd
	  using the <link linkend="extension_manager">Extension Manager</link>
	  by the individual users
	  and usually contains 
	  macros (annotation modes),
	  resource files,
	  file lists of sample data, configurations of I/O backends,
	  stylesheets etc.
	  related to some specific
	  annotation project.
	  The format of an extension package
	  is described in Section <xref linkend="extension_packages"/>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>I/O backend</term>
	<listitem>
	  <para>
	    <firstterm>I/O backend</firstterm> is a module
	    of <application>TrEd</application> responsible for
	    reading and writing files in some particular data format.
	    Thus, adding support for a new data format only requires
	    writing a corresponding I/O backend.
	    Different data formats not only represent the data (trees, nodes,
	    meta data) differently, but often differ in the ability
	    to interchange data with other I/O backends because of
	    the nature of the data. For example, while some I/O backends
	    are rather generic, other are tightly bound to the actual
	    content of the data (hence loading a file using one I/O backend and
	    saving it in another may not work as expected in all cases). 
	    Nonetheless, most of the
	    I/O backends used in <application>TrEd</application>
	    are able to read the data and save them back without
	    any loss of information. Detailed discussion of
	    I/O backends can be found in <xref linkend="backends"/>.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section id="overview">
    <title>Overview of <application>TrEd's</application> user
    interface</title>
    <mediaobject>
      <imageobject>
	<imagedata fileref="pics/tred_overview.png" format="PNG" role="html"/>
      </imageobject>
      <imageobject>
	<imagedata fileref="pics/tred_overview.eps" format="EPS" role="latex"/>
      </imageobject>
      <imageobject>
	  <imagedata fileref="pics/tred_overview" format="linespecific"/>
      </imageobject>
      <textobject>
	<phrase>overview</phrase>
      </textobject>
    </mediaobject>
    <para>
      The picture above shows the <application>TrEd</application>'s
      main window. The most importatnt elements of the user interface
      are marked by numbers in the picture and briefly introducted
      below:
      <orderedlist>
	<listitem>
	  <para>
	    This part of the window contains one or more views.
	    Each view displays one tree. The black border
	    distinguishes the active view (there is only one view
	    pictured here).
	  </para>
	</listitem>
	<listitem>
	  <para>
	    This part of the window displays additional textual
	    information associated with the tree displayed in the
	    active view (e.g. the <quote>sentence</quote> represented by the tree),
	    and optionally some surrounding context.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Status line. It displays various information provided by
	    the current annotation mode.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Current annotation mode. You can change the context by clicking on this
	    menu button and selecting a different one from the list.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Current stylesheet. It can be changed in the similar way as the
	    context.
	  </para>
	</listitem>
	<listitem>
	  <para>Click here to edit the current stylesheet.</para>
	</listitem>
	<listitem>
	  <para>
	    Click here to get the list of all <quote>sentences</quote>
	    associated with trees in the current file. Above this
	    button, you also see the index of the current tree in the
	    current file.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    Toolbar buttons provide shortcuts for the following
	    actions:
	    Open file, Save file, Reload file,
	    Previous File (in file list),
	    Next File (in file list),
	    Print,
	    Undo, Redo, Find, Find Next, Find Previous,
	    Previous Tree,
	    Next Tree, 
	    Split View Vertically,
	    Split View Horizontally,
	    Remove Current View.
	    The last button with the icon of a lock,
	    ties all views so that if one moves to
	    the next/previons tree or file in the current view, the
	    same operation is automatically performed in all other
	    views.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    This button displays a menu of available <link linkend="minor_mode">Minor modes</link>
	    and the label on the right shows which minor modes are active.
	    If a minor mode is configurable,
	    double-clicking on the label opens a configuration dialog.
	  </para>
	</listitem>
	<listitem>
	  <para>
	    The scale slider allows to zoom the tree in the current
	    view in or out. Clicking on the slider with the right
	    button returns the slider to the center position of 100%
	    scale.
	  </para>
	</listitem>
      </orderedlist>
    </para>
  </section>
  <section id="menu">
    <title>Menu commands</title>    
    <para>
      The following paragraphs describe menu commands.
    </para>
    <!--
    <para>
      Each submenu in
      <application>TrEd</application> has as its first item a tear-off
      line (<guimenuitem>- - - - -</guimenuitem>)
      which can be used to tear the menu off and place it as a
      separate window anywhere on your desktop.
    </para>
    -->
    <section id="file">
      <title><guimenu>File</guimenu></title>
      
	<section>
	  <title><guimenuitem>Open ...</guimenuitem></title>
	  <para>
	      Opens an existing file that the user chooses in the
	      <guilabel>Open</guilabel> dialog box.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Open URL ...</guimenuitem></title>
	  <para>
	      Displays a dialog window with an entry into which the
	      user can enter a URL or a
	      filename. <application>TrEd</application> can
	      downloading and open files at least using <literal>http</literal>, <literal>ftp</literal>, and <literal>file</literal> protocols. Network
	      protocols (<literal>http</literal> and
	      <literal>ftp</literal>) are read-only.  On UNIX systems,
	      <application>TrEd</application> also supports the SSH
	      protocol with URLs of the form
	      <literal>ssh://<optional><replaceable>user@</replaceable></optional><replaceable>host</replaceable>/<replaceable>remote-filename</replaceable></literal>.
	    </para><note>
	      <para>
		Since the current implementation of SSH remote file transfer
		requires several subsequent login sessions each time a
		remote file is accessed, it is highly recommended that a
		password-less access (e.g. using Kerberos or SSH keys)
		is set up before remote files are opened in TrEd using
		the SSH protocol.</para>
	    </note><para>Additionally to the
	      protocols already mentioned, TrEd supports a special
	      protocol indicated by the URL prefix <literal>ntred://</literal> used for
	      communication with BTrEd servers. This protocol allows
	      to inspect and change trees stored in memory of BTrEd
	      servers.
	    </para>
	</section>
	<section>
	  <title><guisubmenu>Recent</guisubmenu></title>
	  <para>A submenu containing a list of recently open files;
	  selecting a menu entry opens the file in the current view.</para>
	</section>
	<section>
	  <title><guisubmenu>Kept in Memory</guisubmenu></title>
	  <para>A submenu containing a list of open files or files 
	  that TrEd holds in memory. Selecting a menu entry opens the file
	  in the current view.</para>
	</section>
	<section>
	  <title><guisubmenu>File Lists</guisubmenu></title>
	  <para>This submenu gathers all operations available for working with file lists,
	  see <xref linkend="filelists"/>.
	  </para>
	  <section>
	    <title>Select File List ...</title>
	    <para>
	      Displays a list box where all file lists currently known to
	      <application>TrEd</application> are listed. The user may switch
	      to another file list by choosing the corresponding item.
	      If the file list was not accessed during the session,
	      the first file on the list is opened and displayed.
	      Otherwise, the file last accessed on that list
	      is re-opened and displayed.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Next in File List</guimenuitem></title>
	    <para>
	      Opens the next file of the current file list in the current view, if any.
	      Unless displayed in some other view, the active file is closed
	      (the user may be asked to save possible changes).
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Previous in File List</guimenuitem></title>
	    <para>
	      Opens the previous file of the current file list in the current view, if any.
	      Unless displayed in some other view, the active file is closed
	      (the user may be asked to save possible changes).
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Go to File List Index</guimenuitem></title>
	    <para>
	      Asks the user to enter a number <replaceable>N</replaceable> and
	      then opens <replaceable>N</replaceable>th file in the current file list.
	    </para>
	  </section>
	  <section>
	    <title>New File List ...</title>
	    <para>
	      Create a new empty file list.
	      Files (or node addresses)
	      can be added to the new file list in several ways,
	      e.g.
	      using
	      <menuchoice>
		<guimenu>File</guimenu>
		<guimenuitem>Bookmarks</guimenuitem>
		<guimenuitem>Add Bookmark to File List</guimenuitem>
	      </menuchoice>
	      or
	      <menuchoice>
		<guimenu>File</guimenu>
		<guimenuitem>File Lists</guimenuitem>
		<guimenuitem>Manage File Lists...</guimenuitem>
	      </menuchoice>.
	    </para>
	  </section>
	  <section>
	    <title>Remove File Lists ...</title>
	    <para>Allows the user to select one or more user-defined
	    file lists and remove them.  If the file-list file is
	    located in the <filename>.tred.d/filelists/</filename>
	    directory in user's home, this action also physically removes
	    the file-list file on the disk.
	    File lists located elsewhere are kept untouched and TrEd just 
	    removes them from its memory and configuration.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Manage File Lists ...</guimenuitem></title>
	    <para>Opens a <guilabel>File List</guilabel> dialog window
	    which allows the user to manage lists, e.g. load them,
	    create them, or add new files to them.  See more
	    detail in <xref linkend="filelists"/>.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Add Files To Default File List</guimenuitem></title>
	    <para>If this option is on, all opened files are added to
	    the file list <literal>Default</literal>. This allows the
	    user to easily go back and forth recently opened using
	    <menuchoice>
	      <guimenu>File</guimenu>
	      <guimenu>File Lists</guimenu>
	      <guimenuitem>Previous in File List</guimenuitem>
	      </menuchoice> and
	      <menuchoice>
		<guimenu>File</guimenu>
		<guimenuitem>Next in File List</guimenuitem>
	      </menuchoice>.
	    </para>
	  </section>
	</section>
	<section>
      <title><guimenu>Bookmarks</guimenu></title>
      <para>
	This submenu allows the user to manage bookmarks. Bookmarks are filenames
	with tree-number and node position attached. The list
	of user's bookmarks is maintained in a special file list named <literal>Bookmarks</literal>. 
      </para>
      <section>
	<title><guimenuitem>Place of Last Action</guimenuitem></title>
	<para>
	This opens the file, tree, and exact node where the user made a last modification to the data.
	This is extra position is stored in
	TrEd's configuration file and does not appear among bookmarks.
	</para>
      </section>
      <section>
	<title><guimenuitem>Add Bookmark</guimenuitem></title>
	<para>Creates a new bookmark for the current file, tree, and node
	by adding an entry to the <literal>Bookmarks</literal> file list.
	</para>
      </section>
      <section>
	<title><guimenuitem>Add Bookmark to List</guimenuitem></title>
	<para>Adds the current file, tree, and node address
	to as a new entry in a file list selected by user.
      </para>
      </section>
      <section>
	<title><guisubmenu>Go to Bookmark</guisubmenu></title>
	<para>
	  Displays a sub-menu where the user can open
	  any bookmarked address by selecting the corresponding item.
	</para>
      </section>
	</section>
    <section>
	  <title><guimenuitem>New</guimenuitem></title>
	  <section>
	    <title><guimenuitem>From Template</guimenuitem></title>
	    <para>
	      Allows the user to create a new empty file based
	      on an pre-defined template. File templates can
	      be provided by extensions.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Based on Existing File</guimenuitem></title>
	    <para>
	      Lets the user choose an existing file and
	      creates a new empty file with the same schema or attribute set as
	      the file chosen by user.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Based on Current File</guimenuitem></title>
	    <para>
	      Creates a new empty file with the same schema or attribute set as
	      the currently open file.
	      The command does nothing if no file is open.
	    </para>
	  </section>
	</section>
	<section>
	  <title><guimenuitem>Close</guimenuitem></title>
	  <para>Closes current file. If the file is modified but not
	      saved, the user is allowed to save it.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Close in Window</guimenuitem></title>
	  <para>Closes the view on the file in the current
	      window. All other views on the file remain untouched.
	      If no other view on the file exists, the file is closed.
	      If the file is modified but not saved, the user is allowed
	      to save it.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Close and Remove From File List</guimenuitem></title>
	  <para>Closes the current file and removes it from
	      the current file list. If the file is modified but not saved, the user is allowed
	      to save it.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Save</guimenuitem></title>
	  <para>
	      Saves the active file to the disk.  The previous version
	      of the file on the disk is renamed by appending `~' to
	      the filename (according to the well-known UNIX convention for
	      naming of backup files).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Save As ...</guimenuitem></title>
	    <para>This command first asks the user to choose a desired
	      output format, then opens the standard file dialog where
	      new name and location of the file can be specified, and
	      finally runs the <guimenuitem>Save</guimenuitem>
	      command.
	    </para>
	</section>
	<section id="print_command">
	  <title><guimenuitem>Print ...</guimenuitem></title>
	  <para>
	      Opens the Print Dialog. See <xref linkend="printing"/> for
	      a detailed information.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Quit</guimenuitem></title>
	  <para>Quit TrEd.  The the user is allowed to save all open
	      files containing unsaved changes.
	    </para>
	</section>
    </section>
    <section id="node">
      <title><guimenu>Node</guimenu></title>
      <section>
	<title>Navigation commands</title>
	<para>
	  These commands focus the
	  <guimenuitem>Next</guimenuitem> or
	  <guimenuitem>Previous</guimenuitem> node in depth-first order,
	  navidate vertically 
	  <guimenuitem>Up Level</guimenuitem> or
	  <guimenuitem>Down Level</guimenuitem>,
	  horizontally among siblings
	  (<guimenuitem>Left Sibling</guimenuitem> or <guimenuitem>Right Sibling</guimenuitem>),
	  horizontally within the whole level
	  (<guimenuitem>Left on Level</guimenuitem> or
	  <guimenuitem>Right on Level</guimenuitem>),
	  and along the linear ordering of the tree
	  (<guimenuitem>Next in Order</guimenuitem>,
	  <guimenuitem>Previous in Order</guimenuitem>,
	  <guimenuitem>First in Order</guimenuitem>,
	  <guimenuitem>Last in Order</guimenuitem>).
	</para>
      </section>
      <section>
	  <title><guimenuitem>Edit Node Attributes...</guimenuitem></title>
	  <para>
	      Displays the node attribute editor, described in detail in
	      <xref linkend="editnode"/>.
	    </para>
	</section>
      	<section>
	  <title><guimenuitem>New Node</guimenuitem></title>
	  <para>Creates a new node and connects it as a child of the
	      active node. Initially, all attributes of the new node are empty.</para>
	</section>
	<section>
	  <title><guimenuitem>Remove Active Node</guimenuitem></title>
	  <para>Passes all children of the active node to its parent and
	      deletes the active node. This command is ignored if the active node is
	      the root of the tree.</para>
	</section>
	<section>
	  <title><guimenuitem>Make Current Node the Root</guimenuitem></title>
	  <para>Makes the the current node a new root of the current tree and
	     the current root its new child.
	     This operation goes in three steps:
	     first the current subtree (i.e. the current node with all its descendants) is disconnected
	     from the tree. The rest of the tree is then
	     replaced by the subtree (i.e. the current node
	     becomes the new root and the original root and its subtree is not attached to the file).
	     Finally, the original root and its subtree is attached
	     to the tree as the child of the current node.</para>
	</section>
	<section id="find">
	  <title><guimenuitem>Find ...</guimenuitem></title>
	  <para>
	      This command displays a dialog box in which the user may
	      specify a search criterion for a node search. The
	      criterion is based on regular expressions, wild-card
	      patterns or literal strings matches for attribute
	      values. In the dialog, every permittable node attribute
	      has an editable entry where the user specifies search
	      criterion for the particular attribute.  The user may
	      choose the type of the search criterions to be a <ulink url="regexps.html">regular expressions</ulink>,
	      exhaustive regular expressions (when the whole value
	      must match), wild-card pattern (where <literal>?</literal> matches any character and
	      <literal>*</literal> matches any number
	      of any characters) or a literal string. The type of the
	      criterion is selected in the <guilabel>Search method</guilabel> option-menu and
	      applies to all entries.
	    </para><para>
	      In the <guilabel>Search file list</guilabel> option-menu, 
	      the user may choose a file list to search through. By
	      default, this menu displays entry <guilabel>[Current file only]</guilabel>,
	      which is a virtual file list containing just the current file.
	    </para><para>
	      When user presses <guibutton>Find</guibutton> button, <application>TrEd</application> searches for the
	      first matching node in the selected file list. A node
	      matches the criterion if and only if every attribute of
	      the node matches the criterion in the corresponding
	      entry (empty criterions always match).  If a matching
	      node is found, the search stops and the matching node is
	      displayed and made active.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Find Next ...</guimenuitem></title>
	  <para>
	      Finds a next node matching criteria specified in the
	      previous use of the <guimenuitem>Find
	      ...</guimenuitem> command.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Find Previous ...</guimenuitem></title>
	  <para>
	      Finds a preceding node matching the criterion specified
	      in a previous use of the <guimenuitem>Find ...</guimenuitem> command.
	    </para>
	</section>
      
    </section>
    <section id="tree">
  <title><guimenu>Tree</guimenu></title>
      <para>This menu gathers commands related to trees.</para>
<section>
	  <title><guisubmenu>Previous Tree</guisubmenu></title>
	  <para>View the previous tree in the current file.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Next Tree</guimenuitem></title>
	  <para>View the next tree in the current file.</para>
	</section>
	<section>
	  <title><guimenuitem>Go To Tree Number</guimenuitem></title>
	  <para>View the <replaceable>N</replaceable>-th tree in the file (the user is asked to enter the number <replaceable>N</replaceable>).</para>
	</section>
	<section>
	  <title><guimenuitem>Insert New Tree</guimenuitem></title>
	  <para>Inserts a new tree <emphasis>before</emphasis> the current
	      tree. The new tree consists of a root node only. Initially, attributes of
	      this node are empty.</para>
	</section>
	<section>
	  <title><guimenuitem>Insert New Tree After</guimenuitem></title>
	  <para>Inserts a new tree <emphasis>after</emphasis> the current
	      tree. The new tree consists of a root node only. Initially, attributes of
	      this node are empty.</para>
	</section>
	<section>
	  <title><guimenuitem>Remove Whole Current Tree</guimenuitem></title>
	  <para>
	      Removes the current tree from the file and displays the
	      following tree (or the preceding tree, in case the
	      current tree was the last one in the file). The memory
	      representation of the removed tree is destroyed.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Move Current Tree Backward</guimenuitem></title>
	  <para>
	      Swap the current tree and the preceding tree (if any).
	    </para>
	</section>
<section>
	  <title><guimenuitem>Move Current Tree Forward</guimenuitem></title>
	  <para>
	      Swap the current tree and the following tree (if any).
	    </para>
	</section>
	<section id="copytrees_command">
	  <title><guimenu>Copy Trees</guimenu></title>
	  <para>
	      Displays a dialog allowing user to copy trees from the
	      current file into another file currently opened in TrEd.
	      The trees are selected by a comma separated list of
	      ranges. The format of the list is the same as in the
	      <link linkend="print_command">Print dialog</link>.
	    </para>
	</section>
	
    </section>
    <section id="view">
      <title><guimenu>View</guimenu></title>
	<section id="list_of_sentences">
	  <title><guimenuitem>List of sentences ...</guimenuitem></title>
	  <para>
	      Display a window containing a list of
	      <quote>sentences</quote> of all trees in a current
	      file. These <quote>sentences</quote> are computed in the
	      same way as the content of the text line above the tree,
	      e.g.  using a <link linkend="get_value_line_hook"><literal>get_value_line_hook</literal></link>
	      or the <literal>text:</literal> stylesheet pattern (see
	      <xref linkend="stylesheets"/>), or as a concatenation of
	      special attribute values (i.e. attributes declared
	      as <literal>@V</literal> in the FS
	      format).
	      In the list, buttons <inlinemediaobject><imageobject><imagedata fileref="pics/1rightarrow.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/1rightarrow.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/1rightarrow" format="linespecific"/></imageobject>
		<textobject><phrase>right-arrow</phrase></textobject>
</inlinemediaobject>
	      display the corresponding sentence in the current TrEd view.
	      Buttons <inlinemediaobject><imageobject><imagedata fileref="pics/gray_belly3.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/gray_belly3.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/gray_belly3" format="linespecific"/></imageobject>
		<textobject><phrase>gray-belly</phrase></textobject>
</inlinemediaobject>
	      are used to select sentences. Selected sentences may be later inserted to tree
	      selection fields, e.g. in the <link linkend="print_command">Print dialog</link> and
	      in the <link linkend="copytrees_command">Copy trees
	      dialog</link>, by pressing the button <inlinemediaobject><imageobject><imagedata fileref="pics/1leftarrow.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow" format="linespecific"/></imageobject>
		<textobject>
		  <phrase>with an arrow</phrase>
		</textobject>
	      </inlinemediaobject>.
	    </para><para>
	      All or selected sentences can also be exported as a HTML
	      page. The generated page can optionally contain images
	      of the trees associated with the selected sentences.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Guess Suitable Mode</guimenuitem></title>
	  <para>Runs the <link linkend="guess_context_hook">guess_context_hook</link> in order to
	  determine and select a suitable annotation mode for the
	  current file. Note that this is done automatically run when
	  a file is opened; this command is useful when
	  the user wants to return to the ``default'' annotation mode.
	  </para>
	</section>
<section>
	  <title><guimenuitem>Select Mode ...</guimenuitem></title>
	  <para>
	      Open a dialog window where the user can select an annotation mode. annotation modes are groups of user defined
	      macro-bindings, usually identified with macro
	      packages. See also <xref linkend="macros"/>.  The
	      current annotation mode can also be selected from the first list
	      in the top right corner of the main window, but this
	      makes changing annotation modes fully keyboard accessible.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Select Stylesheet ...</guimenuitem></title>
	  <para>
	      Open a dialog window where the user can select a display
	      stylesheet. See <xref linkend="stylesheets"/>.  A
	      stylesheet can also be selected from the second list in
	      the top right corner of the main window, but this
	      menu makes changing stylesheets fully keyboard accessible.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Toggle Minor Modes</guimenuitem></title>
	  <para>Allows the user to enable or disable minor modes.</para>
	</section>
	<section id="orientation">
	  <title><guimenuitem>Orientation</guimenuitem></title>
	  <para>
	      In this menu you can choose between
	      <guimenuitem>Default</guimenuitem>,
	      <guimenuitem>Horizontal</guimenuitem>, and
	      <guimenuitem>Vertical</guimenuitem> 
	      <link linkend="vertical-mode">orientation of the tree</link>.
	      If <guimenuitem>Default</guimenuitem> is selected,
	      then the orientation is selected automatically 
	      according to the setting of
	      <literal>#{vertical}</literal> (which defaults to 0 - horizontal mode)
	      stylesheet instruction. Otherwise horizonal or vertical orientation is forced, disregarding any current stylesheet
	      setting.
	      The default value is controlled by the
	      <link linkend="displaymode">DisplayMode</link>
	      configuration option.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Close Current View</guimenuitem></title>
	  <para>
	      Closes the focused view if more than one views are present.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Split View Horizontally</guimenuitem></title>
	  <para>
	      Create and focus a new view by splitting the current
	      view horizontally. Sizes of the new and old view may be
	      adjusted by dragging the bar between them. The user may
	      focus a view by clicking into it.  Most keyboard
	      shorcuts as well as menu and button commands only apply
	      to the focused view. The focused view is distinguished
	      from other views by black border drawn around it (both
	      color and width of this border may be customized, see
	      <link linkend="highlightwindowcolor"><varname>HighlightWindowColor</varname></link>
	      and <link linkend="highlightwindowwidth"><varname>HighlightWindowWidth</varname></link>
	      configuration options described below).  Inactive views
	      may be further distiguished using a stipple pattern (see
	      <link linkend="stippleinactivewindows">StippleInactiveWindows</link>
	      configuration option).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Split View Vertically</guimenuitem></title>
	  <para>
	      Create and focus a new view by splitting the current
	      view vertically. Sizes of the new and old view may be
	      adjusted by dragging the bar between them.  See also
	      little more detailed description of <guimenuitem>Split view horizontally</guimenuitem>
	      above.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Focus Next View</guimenuitem></title>
	  <para>If TrEd window is splitinto several views, focus the
	  next view.</para>
	</section>
		<section>
	  <title><guimenuitem>Focus Previous View</guimenuitem></title>
	  <para>If TrEd window is splitinto several views, focus the
	  previous view.</para>
	</section>
	<section id="side_panel">
	  <title><guimenuitem>Side Panel</guimenuitem></title>
	  <para>Toggle side panel visibility. The side panel is a
	    panel on the left side of TrEd window offering sever
	    useful widgets, that can be turned on or off individually.
	    The widgets include a read-only view of the attributes of the
	    currently selected node, the current file list, a
	    file-system browser and a list of named macros.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>List of available macros...</guimenuitem></title>
	  <para>
	      Display a window listing all user-defined
	      menus and keyboard shortcuts (macros) in a selected annotation mode.
	      User may run a macro
	      by double-clicking on a corresponding item in the list, or
	      by pressing the <guibutton>Run and Close</guibutton>
	      button. In the latter case, the window is closed. 
              There are several other buttons in the window.
	      The first button,
	      <guilabel>Include anonymous macros</guilabel>, controls
	      whether macros available only via keyboard shortcut are displayed,
              the second button, <guilabel>See Perl names</guilabel>,
	      toggles displaying of a column containing raw Perl name of macros,
	      and another two
	      buttons (<guilabel>Sort by name</guilabel> and <guilabel>Sort by
	      keyboard shortcuts</guilabel>) control the order in which
	      macros are listed. Finally, the button <guibutton>Export as HTML</guibutton>
	      creates a handy reference page from the listing in form of a HTML document.
	    </para>
	</section>
      
    </section>
    <section>
      <title><guimenu>Macros</guimenu></title>
      <para>This menu allows to run, examine and reload
      pre-defined annoation macros (see <xref linkend="macros"/>).
      </para>
      <section>
	  <title><guimenuitem>List of available macros...</guimenuitem></title>
	  <para>
	      Display a window listing all user-defined
	      menus and keyboard shortcuts (macros) in a selected annotation mode.
	      User may run a macro
	      by double-clicking on a corresponding item in the list, or
	      by pressing the <guibutton>Run and Close</guibutton>
	      button. In the latter case, the window is closed. 
              There are several other buttons in the window.
	      The first button,
	      <guilabel>Include anonymous macros</guilabel>, controls
	      whether macros available only via keyboard shortcut are displayed,
              the second button, <guilabel>See Perl names</guilabel>,
	      toggles displaying of a column containing raw Perl name of macros,
	      and another two
	      buttons (<guilabel>Sort by name</guilabel> and <guilabel>Sort by
	      keyboard shortcuts</guilabel>) control the order in which
	      macros are listed. Finally, the button <guibutton>Export as HTML</guibutton>
	      creates a handy reference page from the listing in form of a HTML document.
	    </para>
	</section>
      <section id="current-context-menu">
      <title><guimenu>Current Mode</guimenu></title>
      <para>
	This menu shows <link linkend="macros">macros</link> available in the current
	annotation mode. Any macro can be invoked by selecting the corresponding item.
      </para>
      </section>
      <section id="usercommands">
      <title><guimenu>All Modes</guimenu></title>
      <para>
	This menu gathers
	all available <link linkend="macros">macros</link>,
	and is organized into submenus by annotation modes.
	Any macro can be invoked by selecting the corresponding item.
	Note that calling a macro from an annotation
	mode that was not intended to be used for working
	of the current type of file
	can be dangerous!
      </para>
      <para>
	Here we give only a brief
	description of the few macros defined by default in the
	default
	<application>TredMacro</application> annotation mode 
	in <filename>tredlib/tred.mac</filename>.
	Although they are general purpose macros, they 
	should be used wisely, since some of them they allow almost
	arbitrary (and possibly unintended) modification of the tree structure.
      </para>
      <note>
	<para>
	  Only a few of built-in commands in TrEd are
	  associated with a keyboard shortcut (other than the standard
	  menu navigation using <keycode>Alt</keycode> and the
	  underlined letter). The aim is to give the users maximum
	  freedom of choice of available shortcuts for their own
	  macro commands.
	</para>
      </note>      
	<section>
	  <title><guimenuitem>Save File</guimenuitem>
	  (<keycap>F2</keycap>)</title> 
	  <para>Provides a keyboard shortcut for the Save command.</para>
	</section>
	<section>
	  <title><guimenuitem>Save and Go to Previous File</guimenuitem>
	  (<keycap>F11</keycap>)</title> 
	  <para>Save the current file and open the previous file on the
	      current file list.</para>
	</section>
	<section>
	  <title><guimenuitem>Save and Go to Next File</guimenuitem>
	  (<keycap>F12</keycap>)</title> 
	  <para>Save the current file and open the next file on the
	      current file list.</para>
	</section>
	<section>
	  <title><guimenuitem>Go to Previous File</guimenuitem>
	  (<keycap>Shift+F11</keycap>)</title> 
	  <para>Close the current file and open the previous file on the current
	      file list. If the current file contains unsaved changes,
	      the user is allowed to save them.</para>
	</section>
	<section>
	  <title><guimenuitem>Go to Next File</guimenuitem>
	  (<keycap>Shift+F12</keycap>)</title> 
	  <para>Close the current file and open the next file on the current
	      file list. If the current file contains unsaved changes,
	      the user is allowed to save them.</para>
	</section>
	<section>
	  <title><guimenuitem>Find</guimenuitem>
	  (<keycap>F3</keycap>)</title>
	  <para>
	      Invoke <menuchoice>
		<guimenu>Node</guimenu>
		<guimenuitem>Find ...</guimenuitem>
	      </menuchoice>.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Find Next</guimenuitem>
	  (<keycap>F4</keycap>)</title>
	  <para>
	      Invoke <menuchoice>
		<guimenu>Node</guimenu>
		<guimenuitem>Find Next</guimenuitem>
	      </menuchoice>.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Copy Values</guimenuitem>
	  (<keycap>F5</keycap>)</title> 
	  <para>
	      Copies all values of the active node to an internal
	      clipboard. These values may be pasted to any other node using
	      the <guimenuitem>Paste Values</guimenuitem> command.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Paste Values</guimenuitem>
	  (<keycap>F8</keycap>)</title>
	  <para>
	      Assignes the active nodes attribute values stored in an internal
	      clipboard during the last call of the <guimenuitem>Copy Values</guimenuitem> command.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Cut Subtree</guimenuitem> (<keycombo action="simul"><keycap>Ctrl</keycap><keycap>Insert</keycap></keycombo>)</title>
	  <para>Cuts off a subtree of the active node and stores
	      it in an iternal clipboard. The cut subtree may be attached later
	      to another node using the <guimenuitem>Paste Subtree</guimenuitem>
	      command.
	      </para>
	</section>
	<section>
	  <title><guimenuitem>Paste Subtree</guimenuitem>
	    (<keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>Insert</keycap></keycombo>)</title>
	  <para>
	      Ataches a previously cut subtree to the active node.      
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Delete Node</guimenuitem>
	  (<keycap>F8</keycap>)</title> 
	  <para>
	      Deletes active node. The node must be a leaf and must
	      not be the root of the tree, otherwise this command is
	      ignored.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to first tree</guimenuitem>
	    (<keycap>Home</keycap> or
	    <keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>&lt;</keycap></keycombo>)</title> 
	  <para>
	      Displays the first tree in the file.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to first tree</guimenuitem>
	    (<keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>Home</keycap></keycombo>)</title> 
	  <para>
	      Like <guimenuitem>Go to first tree</guimenuitem>,
	      only applies to all views, if <inlinemediaobject>
		<imageobject>
		  <imagedata fileref="pics/lock.png" format="PNG" role="html"/>
		</imageobject>
		<imageobject>
		  <imagedata fileref="pics/lock.eps" format="EPS" role="latex"/>
		</imageobject><imageobject>
		  <imagedata fileref="pics/lock" format="linespecific"/>
		</imageobject>
		<textobject><phrase>lock</phrase></textobject>
	      </inlinemediaobject>
	      is pressed.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to last tree</guimenuitem>
	    (<keycap>End</keycap> or
	    <keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>&gt;</keycap></keycombo>)</title>  
	  <para>
	      Displays the last tree in the file.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to to last tree (tied)</guimenuitem>
	    (<keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>End</keycap></keycombo>)</title>  
	  <para>
	      Like <guimenuitem>Go to last tree</guimenuitem>,
	      only applies to all views, if <inlinemediaobject>
		<imageobject>
		  <imagedata fileref="pics/lock.png" format="PNG" role="html"/>
		</imageobject>
		<imageobject>
		  <imagedata fileref="pics/lock.eps" format="EPS" role="latex"/>
		</imageobject><imageobject>
		  <imagedata fileref="pics/lock" format="linespecific"/>
		</imageobject>
		<textobject><phrase>lock</phrase></textobject>
	      </inlinemediaobject>
	      is pressed.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to...</guimenuitem> (<keycombo action="simul">
	      <keycap>Alt</keycap>
	      <keycap>g</keycap></keycombo>)</title> 
	  <para>
	      Promts the user to enter an ordinal number of a tree in
	      the file and displays that tree.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Go to...(tied)</guimenuitem> (<keycombo action="simul">
	      <keycap>Alt</keycap>
	      <keycap>Shift</keycap>
	      <keycap>G</keycap></keycombo>)</title> 
	  <para>
	      Promts the user to enter an ordinal number of a tree in
	      the file and displays that tree (depending
	      on the status of the button 
	      <inlinemediaobject>
		<imageobject>
		  <imagedata fileref="pics/lock.png" format="PNG" role="html"/>
		</imageobject>
		<imageobject>
		  <imagedata fileref="pics/lock.eps" format="EPS" role="latex"/>
		</imageobject><imageobject>
		  <imagedata fileref="pics/lock" format="linespecific"/>
		</imageobject>
		<textobject><phrase>lock</phrase></textobject>
	      </inlinemediaobject>
	      either in the current view only or in all views).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>New Node (r-brother)</guimenuitem>
	  (<keycap>F7</keycap>)</title> 
	  <para>
	      Creates a new node as a right sibling of the active node
	      (this command is ignored if the active node is the root node).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>New Node (son)</guimenuitem> (<keycombo action="simul">
	      <keycap>Shift</keycap>
	      <keycap>F7</keycap></keycombo>)</title>
	  <para>
	      Creates a new child-node of the active node.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Perl-Search</guimenuitem> (<keycombo action="simul">
	      <keycap>Alt</keycap>
	      <keycap>H</keycap></keycombo>)</title>
	  <para>
	      When invoked, a dialog with an editor for a Perl code
	      snippet is displayed. The Perl code entered by user is
	      then evaluated for every node of the tree in their
	      natural ordering starting from the current node.  The
	      evaluation stops at first node for which the Perl code
	      returns true (i.e. a defined non-zero value) and this
	      node is activated.
	    </para><para>
	      The Perl code conforms to the very same rules as a
	      macro, i.e. in brief, the variables <literal>$this</literal> and <literal>$root</literal> refer to the active node
	      and root of the tree respectively.  If <literal>$n</literal> refers to some node, then
	      <literal>$n-&gt;{attr}</literal> is
	      value of <literal>attr</literal>
	      attribute for the node <literal>$n</literal>.  The parent-node of
	      <literal>$n</literal> is accessed via <literal>$n-&gt;parent</literal>, child-nodes of
	      <literal>$n</literal> as <literal>$n-&gt;childnodes</literal> (returns a
	      list), etc. Macros from the current annotation mode may be
	      called as Perl subroutines. See <xref linkend="macros"/>
	      for details.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Perl-Search Next</guimenuitem> (<keycombo action="simul">
	      <keycap>Alt</keycap>
	      <keycap>Shift</keycap>
	      <keycap>H</keycap></keycombo>)</title>
	  <para>
	      Searches the next node satisfying the Perl-expression
	      specified in a previous usage of the command
	      <guimenuitem>Perl-Search</guimenuitem>.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Swap nodes (values only)</guimenuitem>
	      (<keycombo action="simul">
	      <keycap>Ctrl</keycap>
	      <keycap>PageUp</keycap></keycombo>)</title> 
	  <para>
	      Makes the active node exchange its attributes with its
	      parent-node which effectively swaps the two nodes.
	    </para>
	</section>
	    </section>
          
    
    </section>
    <section>
      <title><guimenu>Setup</guimenu></title>
      <para>This menu gathers tasks related to TrEd configuration and setup.</para>
      <section id="extension_manager">
	<title>Manage Extensions...</title>
	<para>This menu command starts a extension manager
	in a separate window
	(<xref linkend="fig_extension_repo"/>).
	The extension manager can be used
	to enable, disable, or upgrade currently installed extensions,
	to install new extensions from <link linkend="extension_repo">web repositories</link>
	and to manage a list of repositories.
	</para>
	<figure id="fig_extension_repo" float="0">
	  <title>Extension Manager</title>
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="pics/extension_manager.png" format="PNG"/>
	    </imageobject>
	    <textobject>
	      <phrase>screenshot</phrase>
	    </textobject>
	  </mediaobject>
	</figure>
      </section>
	<section>
	  <title><guimenuitem>Edit Stylesheet ...</guimenuitem></title>
	  <para>
	      Open a dialog box with a stylesheet editor for the
	      currently selected stylesheet. A styleseet defines which
	      attributes should be displayed and defines the tree's
	      overall appearance. See <xref linkend="stylesheets"/>
	      for more detail.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Reload Stylesheets ...</guimenuitem></title>
	  <para>
	      Reloads display stylesheets
	      This command is useful
	      if you have changed the stylesheets in a text
	      editor or in an another running instance of
	      <application>TrEd</application>.
	      For more information about stylesheets,
	      see <xref linkend="stylesheets"/>.
	    </para>
	</section>
  <section>
	  <title><guimenuitem>Edit Config File ...</guimenuitem></title>
	  <para>
	      Opens the configuration file in a simple text editor
	      (see <xref linkend="configuration"/> for the details
	      about configuration options).  To apply the new
	      configuration, save the configuration file to disk and
	      leave the editor press the <guibutton>Save and Apply</guibutton> button. To
	      apply changes without saving them, press <guibutton>Apply</guibutton>. The <guibutton>Close</guibutton> button closes the
	      editor without making any changes to the present
	      configuration. A search entry on the bottom of the
	      dialog window can be used for fast case-insensitive
	      searches. While searching, use <keysym>F3</keysym> key to highlight
	      next match.
	    </para><para>
	      When editing the configuration file, make sure
	      you only define each configuration option once, since
	      TrEd doesn't give you any warning about duplicated
	      configuration entries. If an option occurs in the
	      configuration file more than once, the latter occurrence
	      has precedence.
	    </para><note>
	      <para>
		Some configuration options even if applied take effect only
		after restarting <application>TrEd</application>.
	      </para>
	    </note>
	</section>
	<section>
	  <title><guimenuitem>Reload Config File ...</guimenuitem></title>
	  <para>
	      Use this command to reload the configuration file from
	      disk and apply the new options. This command is useful
	      if you have changed the configuration file in a text
	      editor or in an another running instance of
	      <application>TrEd</application>. As above, note that
	      some configuration changes still take effect only after
	      restarting <application>TrEd</application>.
	    </para>
	</section>
	<section>
	  <title><guisubmenu>Appearance</guisubmenu></title>
	  <section>
	  <title><guimenuitem>Show Hidden Nodes</guimenuitem></title>
	  <para>
	      Toggle visibility the ``hidden'' nodes and subtrees of
	      the tree.  If this item is checked, TrEd displays nodes
	      that would otherwise been hidden. A node can be hidden
	      if the stylesheet specifies a style pattern <link linkend="style-instructions"><literal>#{Node-hide:1}</literal></link>
	      for it, or if it belongs to the subtree of a node with
	      value <literal>hide</literal> or <literal>1</literal>
	      in a special hiding FS-attribute (see <ulink url="http://quest.ms.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html">FS-format description</ulink> for details).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Stipple Inactive Views</guimenuitem></title>
	  <para>If this item is checked, inactive views are covered
	      with a semi-transparent stipple pattern. This may
	      improve orientation if working with more than one view,
	      but also slightly reduces the clarity of trees displayed
	      in the inactive views.
	      (See also <link linkend="stippleinactivewindows">StippleInactiveWindows</link>
	      configuration option).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Clear Text Background</guimenuitem></title>
	  <para>If this item is checked, rectangles
	      in the background color are drawn under each individual
              node label so that text
	      overlapping edges and other graphical elements is legible.
	      (See also <link linkend="cleartextbackground">ClearTextBackground</link>
	      configuration option).
	    </para>
	</section>
	<section>
  <title><guimenuitem>Draw Boxes Around Labels</guimenuitem></title>
	  <para>If this item is checked, square boxes are drawn
	      around groups of node labels.</para>
	</section>
	<section>
	  <title>
	    <guimenuitem>Draw Boxes Around Edge Labels</guimenuitem></title>
	  <para>If this item is checked, square boxes are drawn
	      around groups of edge attributes.</para>
	</section>
	<section>
	  <title><guimenuitem>Highlight Attributes</guimenuitem></title>
	  <para>
	      Toggle highlighting certain attributes with
	      user-definable set of colors. See <xref linkend="configuration"/> for details on customizing
	      colors and <ulink url="http://quest.ms.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html">FS-format
	      description</ulink> to learn about how to specify which
	      attributes are highlighted. In general, it is better to
	      avoid this approach of changing tree appearance in favor
	      of stylesheets (see <xref linkend="stylesheets"/>).
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Preserve Attributes on Reload</guimenuitem></title>
	  <para>
	    If this option is checked, all changes in the 
	    <guilabel>&lt;From File&gt;</guilabel> stylesheet
	    are preserved even if the file is reloaded.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Sort Attributes in Dialogs</guimenuitem></title>
	  <para>
	      Toggle sorting attributes by name in all dialog windows
	      displaying any form of a list of attributes. 
	      By default, sorting is turned on. If turned off,
	      depending on the format, attributes may be displayed in
	      order of their declaration in the file or schema. When this option
	      is on, sorting of attributes may be further altered by
	      the <link linkend="sort_attrs_hook"><literal>sort_attrs_hook</literal></link>.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Sort Attribute Values in Dialogs</guimenuitem></title>
	  <para>
	      Toggle sorting of attribute values in all dialog windows
	      displaying a choice of attribute values.
	      By default, sorting is turned on. If turned off,
	      depending on the format, values may be displayed in
	      order of their declaration in the file or schema. When this option
	      is on, sorting of attribute value choices may be further altered by
	      the <link linkend="sort_attrs_hook"><literal>sort_attr_values_hook</literal></link>.
	    </para>
	</section>

	</section>
	<section>
	  <title><guisubmenu>Files in Memory</guisubmenu></title>
	<section>
	  <title><guimenuitem>Keep This File in Memory Until Explicitly Closed</guimenuitem></title>
	  <para>If checked, TrEd will keep the current file in  memory until the
	  file is explicitly closed by the user using 
	  <menuchoice><guimenu>File</guimenu>
	  <guimenuitem>Close</guimenuitem>
	  </menuchoice> or a similar command;
	  in particular, the file will be kept in memory
	  even if another file is opened 
	  in the last view using the file.
	  Files kept in memory can be accessed in
	  <menuchoice><guimenu>File</guimenu>
	  <guisubmenu>Kept in Memory</guisubmenu>
	  </menuchoice>.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Keep All Files in Memory Until Explicitly Closed</guimenuitem></title>
	  <para>If checked, TrEd will keep all files in  memory until they are
	  explicitly closed by the user using 
	  <menuchoice><guimenu>File</guimenu>
	  <guimenuitem>Close</guimenuitem>
	  </menuchoice> or a similar command;
	  in particular, a file will be kept in memory
	  even if another file is opened
	  in the last view using the file.
	  Files kept in memory can be accessed in
	  <menuchoice><guimenu>File</guimenu>
	  <guisubmenu>Kept in Memory</guisubmenu>
	  </menuchoice>.
	  </para>
	</section>
	</section>
    </section>
    <section>
      <title><guimenu>Help</guimenu></title>
	<section>
	  <title><guimenuitem>User's Manual</guimenuitem></title>
	  <para>
	    Displays TrEd documentation (this document) in the
	    default browser.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>TrEd Home Page</guimenuitem></title>
	  <para>
	    Displays TrEd internet homepage in the default browser.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Extension Manuals</guimenuitem></title>
	  <para>
	    Displays a submenu where the documentation to installed
	    extensions can be accessed. Unfortunatelly, some
	    extensions come with no documentation.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Library Manuals</guimenuitem></title>
	  <para>
	    Displays a submenu where the documentation to 
	    various Perl libraries used by TrEd
	    can be accessed, including
	    the TrEd macro API library (<xref linkend="defaultmacros"/>).
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Command-Line Tools</guimenuitem></title>
	  <para>
	    Displays a submenu where the documentation to 
	    TrEd command-line tools (including TrEd command-line options) can be accessed.
	  </para>
	</section>
	<section>
	  <title><guimenuitem>Keybindings</guimenuitem></title>
	  <section>
	    <title><guimenuitem>Examine bindings</guimenuitem></title>
	    <para>Displays a window where the user may safely test keyboard bindings.
	    Every time a keyboard short-cut is pressed in the dialog, TrEd looks up
	    if some macro is associated with the short-cut and displayes
	    the result. No macros acrually executed.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Table of Macros in Current Mode</guimenuitem></title>
	    <para>Opens the default web browser with a HTML table of macros and key bindings
	    available in the current annotation mode. The page can be printed out and used as a cheet sheet.
	    </para>
	  </section>
	  <section>
	    <title><guimenuitem>Table of Macros in Current Mode + TredMacro</guimenuitem></title>
	    <para>Opens the default web browser with a HTML table of macros and key bindings
	    available in the current annotation mode and the TredMacro annotation mode. The page can be printed out and used as a cheet sheet.
	    </para>
	  </section>
	</section>
	<section>
	  <title><guimenuitem>About</guimenuitem></title>
	  <para>
	      Displays the <guimenuitem>About</guimenuitem> dialog
	      where the information about version, current file name
	      and format, number of trees, and more is given.
	    </para>
	</section>
	<section>
	  <title><guimenuitem>Debugging messages</guimenuitem></title>
	  <para>In this submenu the user may turn on and off various sets of 
	      debugging messages printed by <application>TrEd</application> on
	      the standard or error output (e.g. in a terminal window).
	      The following sets of debugging messages are defined:
	      <guilabel>tred</guilabel> (messages produced by
	      <application>TrEd</application>'s GUI),
	      <guilabel>macro</guilabel>
	      (messages issued by TrEd when a macro is evaluated),
	      <guilabel>hooks</guilabel>
	      (messages issued by TrEd when a hook is evaluated),
	      <guilabel>keyboard</guilabel>
	      (messages produced by TrEd when a keyboard short-cut is pressed),
	      <guilabel>backend</guilabel>
	      (messages produced by I/O backends),
	      <guilabel>view</guilabel>
	      (messages produced by the displaying engine and errors
	      raised during style-sheet evaluation).
	    </para>
	</section>
    </section>
  </section>
  <section id="toolbar">
    <title>Toolbar</title>
    <para>
      Most of the toolbar buttons only provide mouse-oriented
      shortcuts for standard menu-commands. 
    </para>
    <variablelist>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/fileopen.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/fileopen.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/fileopen" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>file-open</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>File</guimenu>
	      <guimenuitem>Open ...</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/filesave.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/filesave.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/filesave" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>file-save</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>File</guimenu>
	      <guimenuitem>Save</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/reload.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/reload.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/reload" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>reload</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>Reload the current file from disk. Current annotation mode and stylesheet are preserved.</para>
	  <note>
	    <para>	    
	      Note for macro developers: during this action,
	      neither annotation mode guessing, nor <link linkend="file_opened_hook">file_opened_hook</link>
	      nor <link linkend="file_resumed_hook">file_resumed_hook</link> are
	      called, but <link linkend="file_reloaded_hook">file_reloaded_hook</link>
	      is called instead (in case of success).
	    </para>
	  </note>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/start.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/start.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/start" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>start</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>File</guimenu>
	      <guisubmenu>File Lists</guisubmenu>
	      <guimenuitem>Previous in File List</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/finish.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/finish.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/finish" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>end</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	      <guimenu>File</guimenu>
	      <guisubmenu>File Lists</guisubmenu>
	      <guimenuitem>Next in File List</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/fileprint.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/fileprint.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/fileprint" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>print</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>File</guimenu>
	      <guimenuitem>Print ...</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/undo.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/undo.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/undo" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>undo</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>Undo last operation on the current
	    tree. (See also <link linkend="maxundo">MaxUndo</link>
	    configuration option.)</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/redo.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/redo.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/redo" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>redo</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>Redo last undone operation on the current tree.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/find.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/find.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/find" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>find</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>Node</guimenu>
	      <guimenuitem>Find ...</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag+.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag+.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag+" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>find-next</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>Node</guimenu>
	      <guimenuitem>Find Next</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag-.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag-.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/viewmag-" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>find-prev</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	    <menuchoice>
	      <guimenu>Node</guimenu>
	      <guimenuitem>Find Previous</guimenuitem>
	    </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/1leftarrow.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/1leftarrow.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/1leftarrow" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>left-arrow</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>Tree</guimenu>
	    <guimenuitem>Previous Tree</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/1rightarrow.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/1rightarrow.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/1rightarrow" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>right-arrow</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>Tree</guimenu>
	    <guimenuitem>Next Tree</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/view_top_bottom.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_top_bottom.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_top_bottom" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>split-h</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>View</guimenu>
	    <guimenuitem>Split View Horizontally</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/view_left_right.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_left_right.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_left_right" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>split-v</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>View</guimenu>
	    <guimenuitem>Split View Vertically</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/view_remove.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_remove.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/view_remove" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>remove-view</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>View</guimenu>
	    <guimenuitem>Close Current View</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/lock.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/lock.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/lock" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>lock</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>This button has two states. If pressed,
	    all displayed views are tied together, so that
	    pressing <inlinemediaobject><imageobject><imagedata fileref="pics/1leftarrow.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow" format="linespecific"/></imageobject><textobject><phrase>left-arrow</phrase></textobject></inlinemediaobject> or
	    <inlinemediaobject><imageobject><imagedata fileref="pics/1rightarrow.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/1rightarrow.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/1rightarrow" format="linespecific"/></imageobject><textobject><phrase>right-arrow</phrase></textobject></inlinemediaobject> buttons
	    as well as invoking
	    <menuchoice><guimenu>Tree</guimenu><guisubmenu>Previous Tree</guisubmenu></menuchoice> or
	    <menuchoice><guimenu>Tree</guimenu><guisubmenu>Next Tree</guisubmenu></menuchoice>
	    applies to all displayed views.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/wizard.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/wizard.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/wizard" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>check</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>Setup</guimenu>
	    <guimenuitem>Edit Stylesheet...</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  <inlinemediaobject>
	    <imageobject>
	      <imagedata fileref="pics/contents.png" format="PNG" role="html"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/contents.eps" format="EPS" role="latex"/>
	    </imageobject>
	    <imageobject>
	      <imagedata fileref="pics/contents" format="linespecific"/>
	    </imageobject>
	    <textobject><phrase>contents</phrase></textobject>
	  </inlinemediaobject>
	</term>
	<listitem>
	  <para>
	  <menuchoice>
	    <guimenu>View</guimenu>
	    <guimenuitem>List of Sentences...</guimenuitem>
	  </menuchoice>
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
  </section>
  <section id="mouse-and-keyboard">
    <title>Basic tree editing using mouse and keyboard</title>
    <para>
      <application>TrEd</application> can be
      controlled both using keyboard and mouse. Most keyboard short-cuts relate
      to the <firstterm>active node</firstterm>, which
      plays a similar role to that of a cursor in a text
      editor. Almost all of the basic tree editing operations (such as navigation
      the active node along the tree, cut-paste operations on the
      tree, editing node content, etc.) can be achieved both
      using keyboard and mouse bindings. Custom bindings and commands
      may be added using macros (see <xref linkend="macros"/>).
      Here is a brief overview of the basic editing operations:
    </para>
    <section>
    <title>Mouse Control</title>
    <itemizedlist>
      <listitem>
	  <para>Clicking left or right mouse button on a node activates it.</para></listitem>
      <listitem>
	  <para>Double clicking left mouse button on a node invokes
	    <menuchoice>
	    <guimenu>Node</guimenu>
	    <guimenuitem>Edit Node Attribues...</guimenuitem></menuchoice> command.</para></listitem>
	<listitem>
	  <para>Double clicking left mouse button on the text of 
	    a node's attribute opens a prompt for editing the value of
	    this attribute.
	  </para>
      </listitem>
      <listitem>
	  <para>
	    Dragging a node with left mouse button and dropping
	    it on another node cuts the dragged node and its subtree
	    and pastes it on the target node.	
	  </para>
      </listitem>
      <listitem>
	  <para>
	    Dragging and dropping a node with right mouse button has the same
	    effect as above, but this time, if the tree is too large to fit the window, the
	    window scrolls forward the direction of dragging so that when
	    the dragged node reaches an edge of the window it meets
	    the edge of the tree in that direction at the same time.
	  </para>
      </listitem>
      <listitem>
	  <para>
	    Pressing the middle button and moving the mouse pointer while
	    the button is pressed has the
	    same <quote>scrolling effect</quote> described above, but without
	    actually dragging any node.
	  </para>
	</listitem>
      </itemizedlist>
    </section>
    <section>
      <title>Keyboard Shortcuts</title>
      <para>Cursor keys may be used
	to activate another node in the structure. Use
	<keycap>left</keycap>/<keycap>right</keycap> to activate the
	nearest left/right brother-node of the active node and
	<keycap>up</keycap>/<keycap>down</keycap> to activate the active
	node's ancestor (parent)/its leftmost son.  
      </para>
      <para>
	Use <keycombo action="simul"> <keycap>Shift</keycap>
	  <keycap>left</keycap> </keycombo>/<keycombo action="simul">
	  <keycap>Shift</keycap> <keycap>right</keycap> </keycombo> to
	  activate the nearest node on the left/right of the active
	  node within the active node's level.
      </para>
      <para>
	Use <keycombo action="simul"> <keycap>Shift</keycap>
	  <keycap>up</keycap> </keycombo>/<keycombo action="simul">
	  <keycap>Shift</keycap> <keycap>down</keycap> </keycombo> to
	activate the previous or next node in the linear ordering of
	the tree.
      </para>
      <para>
	<keycap>Tab</keycap> and
	<keycombo action="simul">
	  <keycap>Shift</keycap>
	  <keycap>Tab</keycap>
	</keycombo> keys activate the
	next/previous node on the way along the tree structure.
      </para>
      <para>
      <keycap>Enter</keycap> runs the <menuchoice>
	  <guimenu>Node</guimenu>
	  <guimenuitem>Edit Node Attributes...</guimenuitem></menuchoice> command.
    </para>
    <para>
      Note that certain annotation modes define shortcuts
      which can be used to edit the tree structure with keyboard only,
      see <link linkend="current-context-menu">
      <menuchoice>
	<guimenu>Macros</guimenu>
	<guisubmenu>Current Mode</guisubmenu>
      </menuchoice>
      </link> and
      <link linkend="usercommands">
      <menuchoice>
	<guimenu>Macros</guimenu>
	<guisubmenu>All Modes</guisubmenu>
	<guimenuitem>TredMacro</guimenuitem>
      </menuchoice></link>.
      </para>
    </section>
  </section>
  <section id="editnode">
    <title>Editing node attributes</title>
    <para>
      Double-clicking any attribute value displayed in the tree shows
      a simple value editor, where the value of the attribute can be
      changed (note however that some annotation modes disable editing certain
      or all attributes - in that case, the value editor presentes the
      attribute value as read-only).
    </para>
    <para>
      Usually not all attributes are displayed in the tree.  In that
      case it is necessary to use the <guilabel>Edit
      Node</guilabel> dialog, which can be invoked either by
      double-clicking on the desired node in the tree, by activating the
      node and pressing <keycap>Enter</keycap>, or by
      activating the node and selecting <menuchoice>
	<guimenu>Node</guimenu>
	<guimenuitem>Edit Node Attributes...</guimenuitem>
      </menuchoice> from the menu.
    </para>
    <para>
      The <guilabel>Edit Node</guilabel> dialog shows all attributes
      defined for the type of the node or for the file and their
      corresponding values at the selected node.
      Depending on the type of the file, the dialog may have one
      of two possible interfaces, here refered to as the
      <firstterm>old interface</firstterm>
      (see <xref linkend="fig-old-editnode"/>)
      and the <firstterm>new interface</firstterm>
      (see <xref linkend="fig-new-editnode"/>).
    </para>
    <section id="old_editnode_interface">
      <title>Old interface</title>
    <para>
      Displays the 
      dialog box <guilabel>Edit Node</guilabel>,
      listing all attributes defined for the type of the node or
      for the file and their corresponding values at the active node.
      Depending on the type of the file, the dialog may have one
      of two possible interfaces, here refered to as the
      <firstterm>old interface</firstterm>
      (see <xref linkend="fig-old-editnode"/>)
      and the <firstterm>new interface</firstterm>
      (see <xref linkend="fig-new-editnode"/>).
    </para>
    <para>
      The old interface supports attributes of the following
      types: strings,
      <literal>|</literal>-separated lists of strings,
      enumerated values, and <literal>|</literal>-separated
      lists of enumerated values. In the old interface,
      only plain string values can be edited directly.
      Any other attribute value can be edited in a dedicated
      sub-dialog, which appears after clicking on the button
      labeled <guibutton>...</guibutton> beside them.
    </para>
    <figure id="fig-old-editnode" float="0">
      <title>The old interface</title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="pics/edit_node_dialog_old.png" format="PNG" role="html"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/edit_node_dialog_old.eps" format="EPS" role="latex"/>
	</imageobject><textobject><phrase>edit node dialog</phrase></textobject>
      </mediaobject>
    </figure>
    </section>
    <section id="new_editnode_interface">
      <title>New interface</title>
    <para>The new interface (now default for PML-based files
      and files in FS format) offers support for
      string attributes, enumerated attributes,
      constant attributes,
      <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm">Treex::PML::List</ulink></literal>
      lists of values of an arbitrary type, <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm">Treex::PML::Alt</ulink></literal>
      alternatives of values, and <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm">Treex::PML::Seq</ulink></literal> sequences of named elements), and, 
      most importantly,  for 
      <firstterm>hierarchical attributes</firstterm> (<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Struct.pm">Treex::PML::Struct</ulink></literal>
      and <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Container.pm">Treex::PML::Container</ulink></literal>).
      Alternatives consisting of <literal>|</literal>-separated lists of strings used by FS format files are supported too.

    </para>
      <para>Colors are used to visually differentiate items and buttons
	of various data types. Specifically, required
	attributes are listed in blue, other attributes are brown. 
	Pale yellow background is used for
	structures and containers, pink for lists, green for
	alternatives, and blue for sequences.
	Orange color is used for 
	<literal>|</literal>-separated alternatives.
      </para>
    <figure id="fig-new-editnode" float="0">
      <title>The new interface</title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="pics/edit_node_dialog.png" format="PNG" role="html"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/edit_node_dialog.eps" format="EPS" role="latex"/>
	</imageobject><textobject><phrase>edit node dialog</phrase></textobject>
      </mediaobject>
    </figure>
    <para>In this interface, the hierarchy
      of attributes is presented as a collapsible tree.
      The leafs of the tree represent the editable
      (string or enumerated) values.
      </para>
      <para>
	Enumerated values
      can be selected from a combo-box with a search-as-you-type
      functionality. Lists, alternatives, sequences and/or their members have additional
      buttons beside their tree-entry for adding
      new members, removing members, and altering the order of members,
      as listed in <xref linkend="tab-editnode"/>.
    </para>
    <table id="tab-editnode">
      <title>Buttons in the new <guilabel>Edit Node</guilabel>
	interface</title>
      <tgroup cols="3">
	<thead>
	  <row>
	    <entry>Button</entry>
	    <entry>Keyboard shortcut</entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_plus.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_plus.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>+</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>+</keysym>
	      </keycombo>
	    </entry>
	    <entry>add a new member to a list</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_minus.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_minus.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>-</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>-</keysym>
	      </keycombo>
	    </entry>
	    <entry>remove the current member from a list</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_up.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_up.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>up</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>up</keysym>
	      </keycombo>
	    </entry>
	    <entry>move the current member up in an ordered list</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_down.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_down.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>down</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>down</keysym>
	      </keycombo>
	    </entry>
	    <entry>move the current member down in an ordered list</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_star.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_star.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>*</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>*</keysym>
	      </keycombo>
	    </entry>
	    <entry>add an alternative value</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_cross.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_cross.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>x</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>/</keysym>
	      </keycombo>
	    </entry>
	    <entry>remove the current alternative value</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_hash.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_hash.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>#</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>#</keysym>
	      </keycombo>
	    </entry>
	    <entry>create/delete a structure</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_plus_blue.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_plus_blue.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>+</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>+</keysym>
	      </keycombo>
	    </entry>
	    <entry>add a new element to a sequence (a menu pops up to select name)</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_minus_blue.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_minus_blue.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>-</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>-</keysym>
	      </keycombo>
	    </entry>
	    <entry>remove the current element from a sequence</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_up_blue.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_up_blue.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>up</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>up</keysym>
	      </keycombo>
	    </entry>
	    <entry>move the current element up in a sequence</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_down_blue.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_down_blue.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>down</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>down</keysym>
	      </keycombo>
	    </entry>
	    <entry>move the current element down in a sequence</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_star_orange.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_star_orange.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>*</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>*</keysym>
	      </keycombo>
	    </entry>
	      <entry>add an alternative value to a <literal>|</literal>-separated FS-alternative</entry>
	  </row>
	  <row>
	    <entry>
	      <mediaobject>
		<imageobject><imagedata fileref="pics/edit_node_cross_orange.png" format="PNG" role="html"/></imageobject>
		<imageobject><imagedata fileref="pics/edit_node_cross_orange.eps" format="EPS" role="latex"/></imageobject>
		<textobject>
		  <phrase><literal>x</literal></phrase></textobject>
	      </mediaobject>
	    </entry>
	    <entry><keycombo action="simul">
		<keysym>Ctrl</keysym>
		<keysym>/</keysym>
	      </keycombo>
	    </entry>
	      <entry>remove the current value from a <literal>|</literal>-separated FS-alternative</entry>
	  </row>
	</tbody>
      </tgroup>
    </table>
    </section>
  </section>
  <section id="vertical-mode">
    <title>Tree Orientation</title>
    <para>
      TrEd supports two modes for displaying trees:
      <firstterm>horizontal</firstterm>
      and 
      <firstterm>vertical</firstterm>. Switching between
      these modes can be achieved
      either by
      <link linkend="orientation">
      <menuchoice>
	<guimenu>View</guimenu>
	<guisubmenu>Orientation</guisubmenu>
      </menuchoice></link>,
      or by using the <literal>rootstyle:</literal>
      instruction <literal>#{vertical}</literal>
      in the <link linkend="stylesheets">stylesheet</link>.
    </para>
    <para>
      In this manual, we
      usually only refer to the default mode, which is also called
      <firstterm>horizontal mode</firstterm>. In this mode
      the parent nodes apear above the childnodes and the horizontal
      position of nodes reflects the global ordering of nodes
      or, for <link linkend="balancetree">balanced</link> trees,
      the ordering of siblings with parents placed in between them.
      In the horizontal mode, node labels are placed below the nodes
      and edge labels are placed on the flowline between the
      node and its parent.
    </para>
    <para>
      In the <firstterm>vertical mode</firstterm>, however, each node
      is displayed on the left of its descendants and the global
      ordering of the tree or siblings is reflected on the vertical
      position of the node, the first node in the ordering being the
      top-most.
      In other words, if
      displayed without labels, the tree in vertical mode would appear
      mirrored and rotated counterclockwise by 90 degrees
      compared to the horizontal mode.
    </para>
    <para>
      The labels in vertical mode are displayed differently
      than in the horizontal mode. The first label, either node or
      edge, is displayed next to the node.  All other labels, again
      node or edge, are displayed on the right of the first displayed
      label in the order in which they are defined in the stylesheet,
      but are aligned in a tabular way so that the horizontal position
      of the corresponding labels is the same for all nodes.
      Each node and its labels thus appears on a line.
      The line corresponding to the current node
      is highlighted (see <link linkend="horizstripe">HorizStripe</link>
      and <link linkend="stripecolor">StripeColor</link> configuration
      options).
    </para>
    <para>The difference is best visible on <xref linkend="horiz-vert-mode"/>,
      which shows a simple tree with two sibling node below the root
      using the following stylesheet:
      <programlisting>
<command>style:</command> #{EdgeLabel-dodrawbox:yes}
<command>node:</command> #{red}n-1
<command>node:</command> n-2
<command>edge:</command> #{blue}e-1
<command>node:</command> n-3
<command>edge:</command> #{blue}e-2</programlisting>
    </para>
    <para>
      When the vertical mode is active, key bindings for the arrow keys
      have a modified semantics. The <keysym>Left</keysym> key
      behaves as <keysym>Up</keysym>,
      the <keysym>Right</keysym> key behaves as <keysym>Down</keysym>,
      <keysym>Up</keysym> behaves like <keysym>Left</keysym>
      and
      <keysym>Down</keysym> behaves like <keysym>Right</keysym>.
      This change also applies to all
      <link linkend="bindings">user defined combinations</link>
      with any other modifiers,
      but does not affect the combinations with 
      <keysym>Shift</keysym>, so that in particular
      <keycombo action="simul">
	<keysym>Shift</keysym>
	<keysym>Up</keysym>
      </keycombo> and
      <keycombo action="simul">
	<keysym>Shift</keysym>
	<keysym>Down</keysym>
      </keycombo>
      select the previous/next node in the linear order,
      i.e. the node displayed on the previous/next line.
    </para>
    <figure id="horiz-vert-mode">
      <title>A tree displayed first in the horizontal mode then in the vertical mode</title>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="pics/horiz_mode.png" format="PNG" role="html"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/horiz_mode.eps" format="EPS" role="latex" width="6cm"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/horiz_mode" format="linespecific"/>
	</imageobject>
	<textobject><phrase>horizontal mode</phrase></textobject>
      </mediaobject>
      <mediaobject>
	<imageobject>
	  <imagedata fileref="pics/vert_mode.png" format="PNG" role="html"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/vert_mode.eps" format="EPS" role="latex" width="6cm"/>
	</imageobject>
	<imageobject>
	  <imagedata fileref="pics/vert_mode" format="linespecific"/>
	</imageobject>
	<textobject><phrase>vertontal mode</phrase></textobject>
      </mediaobject>
    </figure>
  </section>
  <section id="stylesheets">
    <title>Customizing Tree Appearance: Stylesheets</title>
    <section id="stylesheets_intro">
      <title>Introduction to stylesheets</title>
    <para>
      In <application>TrEd</application>, the way a
      tree is displayed is controlled by so called <firstterm>display
      stylesheets</firstterm>.  Display stylesheets define what text
      will be rendered as node and edge labels and how, the way tree edges
      are to be drawn (much more can be achieved than just straight lines
      connecting a node and its parent node), the shape of the nodes,
      coloring of various visual elements,
      the text to be displayed as a tool-tip (<firstterm>hint</firstterm>)
      when mouse pointer hovers over a node, and also the
      content of text window displayed above the tree.
      All these properties of the visual representation of the tree
      are specified using so called styling <firstterm>patterns</firstterm>.
    </para>
    <para>
      TrEd maintains a list of stylesheets from which stylesheets can
      selected and swithched between.  The easiest way to select a
      stylesheet is to click on the stylesheet menu-button shown on
      the picture <xref linkend="fig_patternset"/> below. This button
      can be found on the right side of the toolbar next to the
      <inlinemediaobject><imageobject><imagedata fileref="pics/wizard.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/wizard.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/wizard" format="linespecific"/></imageobject><textobject><phrase>wizard</phrase></textobject></inlinemediaobject> button.
      Another way to select a stylesheet is using 
      <menuchoice>
	<guimenu>View</guimenu>
	<guimenuitem>Select Stylesheet...</guimenuitem>
      </menuchoice>.
    </para>

    <figure float="0" id="fig_patternset">
      <title>Switching between stylesheets</title>
      <mediaobject><imageobject><imagedata fileref="pics/patternset.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/patternset.eps" format="EPS" role="latex" width="13cm"/></imageobject><imageobject><imagedata fileref="pics/patternset" format="linespecific"/></imageobject><textobject><phrase>stylesheet-menu</phrase></textobject></mediaobject>
    </figure>

    <para>
      The stylesheet currently selected on the picture and named
      <guilabel>&lt;From File&gt;</guilabel> is always
      present. This is a rather virtual stylesheet whose content is
      always the styling patterns specified in the currently displayed
      file (some - but not all - file formats such as FS allow storing
      stylesheet information). These file-specific stylesheets are
      rather hard to maintain especially when one is working with
      hunderds of files. It is thus much more convenient to create a
      named stylesheet that can be used for any file at any time.
    </para>
    <para>
      To create a new named stylesheet (based on the current pattern
      settings), select an item labeled <guilabel>&lt;New From
      Current&gt;</guilabel> from the stylesheet list and fill a name
      into the displayed dialog entry. The new stylesheet
      immediatelly appears as the selected item in the list.
    </para>
    <warning>
      <para>
	Although the API for stylesheets is case sensitive, for compatibility with
	Microsoft Windows, there must not be two
	stylesheets whose names differ only in case.
      </para>
    </warning>
    <para>
      While a file-specific stylesheet is stored directly in the FS
      file, named stylesheets are all saved in
      similarly named files in <filename>.tred.d/stylesheets/</filename> in user's home
      directory.  Stylesheet files are updated every time a named stylesheet
      is added removed or edited. Currently selected named stylesheet
      can be completely removed from the list by selecting <guilabel>&lt;Delete Current&gt;</guilabel> item from the
      pattern-set list.
    </para>
    <para>
      Selected stylesheet can be edited in a stylesheet editor which
      appears when <inlinemediaobject><imageobject><imagedata fileref="pics/wizard.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/wizard.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/wizard" format="linespecific"/></imageobject><textobject><phrase>wizard</phrase></textobject></inlinemediaobject> button is pressed or <menuchoice>
      <guimenu>Setup</guimenu> <guimenuitem>Edit Stylesheet...</guimenuitem></menuchoice>
      menu command issued.
    </para>
    <figure float="0">
      <title>Stylesheet editor</title>
      <mediaobject><imageobject><imagedata fileref="pics/customatt.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/customatt.eps" format="EPS" role="latex" width="13cm"/></imageobject><imageobject><imagedata fileref="pics/customatt" format="linespecific"/></imageobject><textobject><phrase>stylesheet editor</phrase></textobject></mediaobject>
    </figure>
    <para>
      The dialog window contains two main elemens: a list of node
      attributes and an editor of stylesheet paterns. Double-clicking
      an attribute in the list inserts an attribute reference at the
      current cursor position in the pattern editor.
    </para>
    </section>
    <section id="pattern_syntax">
      <title>Stylesheet syntax: the styling patterns</title>
      <para>
	A stylesheet consists of one or more styling patterns. A
	styling pattern begins with a pattern prefix which must occur
	at the very beginning of a line (no whitespace allowed) and is
	followed by a comma. After the comma follows a body of the
	pattern.
      </para>
      <para>
	TrEd recognizes the following pattern prefixes (described in
	detail below): <literal>node</literal>,
	<literal>edge</literal>, <literal>style</literal>, <literal>text</literal> and <literal>rootstyle</literal>.
	If any other prefix is used, TrEd ignores the pattern.
      </para>
      <variablelist>
	<varlistentry>
	  <term><literal>node:</literal></term>
	  <listitem>
	    <para>
	      defines a line of text to be
	      displayed under each node of the tree. A stylesheet may
	      contain one or more <literal>node:</literal> patterns,
	      in which case the lines are displayed in the tree one
	      under another in the order as they appear in the
	      stylesheet.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>edge:</literal></term>
	  <listitem>
	  <para>
	    defines a line of text displayed across (or beside)
	    the edge connecting each node with its parent. Of course, this
	    label is not rendered for the root node.
	      Likewise <literal>node:</literal> patterns, several
	    <literal>edge:</literal> patterns may be specified.
	      Note however that <literal>edge:</literal> patterns
	      make the tree look quite wide and it is usually better
	    to avoid them.
	  </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>style:</literal></term>
	  <listitem>
	    <para>defines a pattern affecting the visual
	      representation of various components of a tree. <literal>style:</literal> patterns do not result
	      in any text visible on the screen but may contain
	      special tree styling instructions described below. These
	      instructions may dynamically alter the appearance (such
	      as coloring, line thickness, etc) of the nodes, edges
	      and text labels.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>text:</literal></term>
	  <listitem>
	    <para>defines a portion of the text representing each node
	      in the text window above the tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>rootstyle:</literal></term>
	  <listitem>
	    <para>defines a pattern which behaves quite the same as a
	      <literal>style:</literal> pattern but is
	      only interpolated once (for the root node), applies to
	      every node of the tree, but the styling instructions
	      defined in this pattern have lower precedence than those
	      of <literal>style:</literal> patterns.
	      Beside the use for setting default style values for all nodes,
	      there are some style instructions with global effect 
	      which can only be used in the
	      <literal>rootstyle:</literal> pattern.
	      See <xref linkend="rootstyle-instructions"/>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>hint:</literal></term>
	  <listitem>
	    <para>
	      defines the content of a tool-tip shown when mouse pointer
	      lingers over a node.  No styling instructions are
	      allowed in the <literal>hint:</literal> patterns.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>
	Pattern body consists of a text which is interpreted as follows:
      </para>
    <variablelist>
      <varlistentry>
	<term><literal>&lt;?<replaceable>code</replaceable>?&gt;</literal></term>
	<listitem>
	  <para>
	    Perl-code expansion. This sequence may encapsulate any Perl code. The code
	    is interpreted in the time of evaluation of the pattern
	    (i.e. just before the line is actually to be displayed)
	    and the result returned by the code replaces
	    the code sequence in the pattern.
	  </para>
	  <para>
	    Note that the returned value may contain other special
	    sequences, but can't contain another <literal>&lt;?<replaceable>...</replaceable>?&gt;</literal>
	    sequences.
	  </para>
	  <para>
	    The <replaceable>code</replaceable> is subject to very
	      similar rules as macros in TrEd (see <xref linkend="macros"/>). One may refer to any attribute
	      value of the node currently being styled as either
	      <literal>$${<replaceable>attr</replaceable>}</literal>
	      or <literal>$this-&gt;attr('<replaceable>attr</replaceable>')</literal>.
	      The current node object itself can be refered to as <literal>$this</literal> (so e.g. <literal>$this-&gt;parent</literal> gives access
	      to its parent).  Regardless
	      of what annotation mode is currently selected, the code occuring
	      in the styling patterns is always evaluated within the
	      <literal>TredMacro</literal> namespace.
	      In order to call a user-defined macro from another
	      namespace, it is therefore necessary to use a complete
	      namespace (package name) prefix. So, a call to a macro
	      named <literal>bar</literal> from a
	      package (annotation mode) <literal>Foo</literal>
	      should look like <literal>Foo::bar(<replaceable>arguments...</replaceable>)</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>${<replaceable>attr</replaceable>}</literal></term>
	<listitem>
	  <para>
	      Attribute reference. Any occurence of this substring is
	      replaced by current node's value of attribute named
	      <replaceable>attr</replaceable>.  Using attribute
	      references only makes sense in the
	      <literal>node:</literal>, <literal>edge:</literal>,
	      <literal>text:</literal> and <literal>hint:</literal>
	      patterns. In the labels rendered from
	      <literal>node:</literal>, <literal>edge:</literal>
	      patterns, this reference is actually linked with the
	      corresponding node's attribute, so double-clicking on the
	      displayed value in the tree shows a dialog where the
	      attribute value can be edited.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>${<replaceable>attr</replaceable>=<replaceable>value</replaceable>}</literal></term>
	<listitem>
	  <para>
	      This is a special form of an attribute reference, which
	      is only useful in <literal>node:</literal>,
	      <literal>edge:</literal> patterns.  It always renders as
	      <replaceable>value</replaceable>, but still retains the
	      reference to the attribute
	      <replaceable>attr</replaceable> of the corresponding
	      node, so that double-clicking on the displayed
	      <replaceable>value</replaceable> in the tree shows a
	      dialog where the attribute
	      <replaceable>attr</replaceable> can be edited.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>#{<replaceable>color</replaceable>}</literal></term>
	<listitem>
	  <para>
	    This sequence of characters may be used to change the
	    color of any possible following text generated by the
	    pattern. The <replaceable>color</replaceable> may be
	    either an english name of a color,
	    such as <literal>black</literal>, <literal>red</literal> or
	    <literal>darkblue</literal>, or one of
	      user defined colors <literal>custom<replaceable>XXX</replaceable></literal>
	    (that can be defined in the configuration file using 
	    <literal>CustomColor<replaceable>XXX</replaceable></literal>
	    configuration option), or
	    an RGB value specified as
	    <literal>#<replaceable>RRGGBB</replaceable></literal>,
	    where <replaceable>RR</replaceable>,
	    <replaceable>GG</replaceable>,
	    <replaceable>BB</replaceable> are hexadecimal numbers
	      from 00 to FF representing respectively the red, green, and blue
	    components of the color.
	  </para>
	</listitem>
	</varlistentry>
	<varlistentry>
	<term><literal>#{<replaceable>object</replaceable>-<replaceable>feature</replaceable>:<replaceable>value</replaceable>}</literal></term>
	<listitem>
	  <para>
	    These instructions may affect appearence of
	    all elements of the tree. They should be used within
	    <literal>style</literal>
	    and <literal>rootstyle</literal> labeled patterns only, but
	    may be created dynamically utilizing the <literal>&lt;?
	    ... ?&gt;</literal> perl-code evaluation.
	  </para>
	  <para>See <xref linkend="style-instructions"/> for
	    list of <replaceable>objects</replaceable>,
	    their <replaceable>features</replaceable> and
	    possible <replaceable>values</replaceable>.
	  </para>
	</listitem>
      </varlistentry>
	<varlistentry>
	  <term>any other text</term>
	  <listitem>
	    <para>
	      Any other text occuring within a
	      <literal>node:</literal>, <literal>edge:</literal>,
	      <literal>text:</literal>, or <literal>hint:</literal>
	      pattern is render as is (using the default font and
	      the default or previously selected color and styling).
	      Plain text occuring in a 
	      <literal>style:</literal> or
	      <literal>rootstyle:</literal>
	      pattern is ignored (note however that this may change
	      in the future versions).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term>white space</term>
	  <listitem>
	    <para>Leading and trailing white space of a pattern is
	    ignored. To all other occurences of white-space the above
	    rule for any other text applies.
	    </para>
	  </listitem>
	</varlistentry>
    </variablelist>
    <table id="rootstyle-instructions">
      <title>Rootstyle instructions</title>
	<tgroup cols="2">
	  <colspec colnum="1" align="left"/>
	  <colspec colnum="2" align="justify"/>
	  <thead>
	  <row>
	    <entry><replaceable>name</replaceable></entry>
	    <entry>Description</entry>
	  </row>
	</thead>
	<tbody>
	    <row>
	    <entry><literal>balance</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="balancetree">BalanceTree</link>
		  configuration option.
		  Use either <literal>#{balance}</literal> or
		  <literal>#{balance:1}</literal> for
		  balanced trees horizontally compressed,
		  <literal>#{balance:spread}</literal>
		  for non-compressed balanced trees or
		  <literal>#{balance:0}</literal> for ordered trees. 
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>baseXPos</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="basexpos">BaseXPos</link>
		  configuration option.
		  Usage: <literal>#{baseXPos:<replaceable>value</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>baseYPos</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="baseypos">BaseYPos</link>
		  configuration option.
		  Usage: <literal>#{baseYPos:<replaceable>value</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>nodeXSkip</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="nodexskip">NodeXSkip</link>
		  configuration option.
		  Usage: <literal>#{nodeXSkip:<replaceable>value</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>nodeYSkip</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="nodeyskip">NodeYSkip</link>
		  configuration option.
		  Usage: <literal>#{nodeYSkip:<replaceable>value</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>lineSpacing</literal></entry>
	    <entry>
		<para>
		  Coeficient for line spacing in text labels.
		  The value can be float.
		  Default coeficient is 1 (single line spacing).
		  This style has the same effect as the
		  <link linkend="basexpos">LineSpacing</link>
		  configuration option.
		  Usage: <literal>#{lineSpacing:<replaceable>value</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>skipHiddenParents</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="skiphiddenparents">SkipHiddenParents</link>
		  configuration option.
		  Usage: <literal>#{skipHiddenParents}</literal>
		  or <literal>#{skipHiddenParents:1}</literal> to turn
		  on, or <literal>#{skipHiddenParents:0}</literal>
		  to turn off.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>skipHiddenLevels</literal></entry>
	    <entry>
		<para>
		  Has the same effect as the
		  <link linkend="skiphiddenparents">SkipHiddenLevels</link>
		  configuration option.
		  Usage: <literal>#{skipHiddenLevels}</literal>
		  or <literal>#{skipHiddenLevels:1}</literal> to turn
		  on, or <literal>#{skipHiddenLevels:0}</literal>
		  to turn off.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>vertical</literal></entry>
	    <entry>
		<para>
		  Turns on the <link linkend="vertical-mode">vertical mode</link>.
		  Use <literal>#{vertical}</literal> or
		  <literal>#{vertical:1}</literal> to set the option
		  on, <literal>#{vertical:0}</literal> or none
		  to set it off.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>labelsep</literal></entry>
	    <entry>
		<para>
		  <link linkend="vertical-mode">Vertical
		  mode</link> only. The distance
		  between a node and the label next to it.
		  Usage: <literal>#{labelsep:<replaceable>integer</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>columnsep</literal></entry>
	    <entry>
		<para>
		  <link linkend="vertical-mode">Vertical
		  mode</link> only. The distance
		  between two columns of labels.
		  Usage: <literal>#{columnsep:<replaceable>integer</replaceable>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	      <entry><literal>columnsep[<replaceable>i</replaceable>]</literal></entry>
	    <entry>
		<para>
		  <link linkend="vertical-mode">Vertical
		  mode</link> only. The distance
		  before the <replaceable>i</replaceable>-th column
		  of labels. Usage: <literal>#{columnsep[<replaceable>i</replaceable>]:<literal>integer</literal>}</literal>.
		</para>
	      </entry>
	    </row>
	    <row>
	    <entry><literal>stackOrder</literal></entry>
	    <entry>
		<para>
		  A comma separated list of item tags 
		  defining a z-axis
		  ordering of canvas items (lowest first).
		  The default stackOrder is:
		  line, node, textbox, edgetextbox, textbg, text,
		  plaintext.
		</para>
	      </entry>
	    </row>
	  <row>
	    <entry><literal>NodeLabel-valign</literal></entry>
	    <entry><para>This instruction takes one of the following
		values: <quote><literal>top</literal></quote>,
		<quote><literal>center</literal></quote>,
		and <quote><literal>bottom</literal></quote>. 
		This feature specifies which side of the group of
		node labels should be placed towards the node. 
		If <quote><literal>top</literal></quote> is selected
		(which is the default value), node labels appear
		below the node. If
		<quote><literal>bottom</literal></quote>
		is selected, node labels are displayed
		above the node.	If the value of
		<quote><literal>center</literal></quote>
		is used, node labels are displayed
		across the node.	
	      </para></entry>
          </row>
	  </tbody>
	</tgroup>
      </table>
    <table id="style-instructions">
      <title>Style instructions</title>
	<tgroup cols="2">
	  <colspec colnum="1" align="left"/>
	  <colspec colnum="2" align="justify"/>
	  <thead>
	  <row>
	    <entry><replaceable>object</replaceable>-<replaceable>feature</replaceable></entry>
	    <entry>Description and a list of possible values</entry>
	  </row>
	</thead>
	<tbody>
	    <row>
	    <entry><literal>Node-hide</literal></entry>
	    <entry>
	      <para>Nodes for which this feature is non-zero are not
		  displayed at all. The following
		  <literal>rootstyle</literal> options
		  control how child nodes of hidden nodes are displayed:
		  <link linkend="skiphiddenparents"><literal>skipHiddenParents</literal></link>
		  and <link linkend="skiphiddenlevels"><literal>skipHiddenLevels</literal></link>.
	      </para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-shape</literal></entry>
	    <entry>
	      <para>The shape of the point representing the node in
		the tree. Possible values are <literal>oval</literal>,
		<literal>rectangle</literal>, and
		<literal>polygon</literal>
		(see also <literal>Node-polygon</literal> below).
	      </para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-polygon</literal></entry>
	    <entry><para>
		Specifies the relative coordinates for three or
		more points that define a closed polygon. The
		first and last points may be the same;  whether they are
		or not, TrEd will draw the polygon as a closed polygon.
	      </para></entry>
	  </row>
	  <row>
	    <entry><literal>Node-width</literal></entry>
	    <entry>
	      <para>Width of an oval- or rectangle-shaped node.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-height</literal></entry>
	    <entry>
	      <para>Height of an oval- or rectangle-shaped node.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-currentwidth</literal></entry>
	    <entry>
	      <para>Width of an oval- or rectangle-shaped node
	      when current.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-currentheight</literal></entry>
	    <entry>
	      <para>Height of the node an oval- or
	      rectangle-shaped node when current.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-addwidth</literal></entry>
	    <entry>
	      <para>Increase width of an oval- or rectangle-shaped node
	      by a given amount.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-addheight</literal></entry>
	    <entry>
	      <para>Increase height of an oval- or rectangle-shaped
	      node by a given
	      amount.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Node-rellevel</literal></entry> <entry><para> Allows altering
		the default vertical position of a subtree. 
		The values are multiples of one default level height.
		Positive values move the subtree down, while negative values
		move the subtree up. </para></entry>
	  </row>
	  <row>
	    <entry><literal>Node-level</literal></entry> <entry>
	      <para>
		Very similar to <literal>Node-rellevel</literal>
		above, except that this option affects one node only 
		rather than the whole subtree.
	      </para>
	    </entry>
	  </row>
	  <row>
	    <entry><literal>Node-addbeforeskip</literal></entry>
            <entry><para>Additional horizontal space before node
		in pixels</para></entry>
	  </row>
	  <row>
	    <entry><literal>Node-addafterskip</literal></entry>
	    <entry><para>Additional horizontal space after node
		in pixels</para></entry>
          </row>
	  <row>
	    <entry><literal>Node-disableedgelabelspace</literal></entry>
	    <entry><para>If set the value is <quote><literal>yes</literal></quote>
		no additional horizontal skip for
		edge labels is added during
		positioning the node.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Node-textalign</literal></entry>
	    <entry>
		<para>Alignment of the node labels:
		  <literal>right</literal>,
		  <literal>center</literal>, or 
		  <literal>left</literal>.</para>
	    </entry>
          </row>
	  <row>
	      <entry><literal>Node-textalign[<replaceable>i</replaceable>]</literal></entry>
	    <entry>
		<para>Alignment of the <replaceable>i</replaceable>-th
		  node label: <literal>right</literal>,
		  <literal>center</literal>, or 
		  <literal>left</literal>.</para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>NodeLabel-skipempty</literal></entry>
	    <entry><para>This option controls whether an empty node
	    label should be skipped to make the nearest preceding and
	    following non-empty labels vertically adjacent. This produces
	    considerably more compact trees.
	  </para>
	    </entry>
	  </row>
	  <row>
	    <entry><literal>NodeLabel-valign</literal></entry>
	    <entry><para>This instruction
		may be used only within <literal>rootstyle</literal>
		patterns, see the table above.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>NodeLabel-halign</literal></entry>
	    <entry><para>One of the following values
		may be used: <quote><literal>left</literal></quote>,
		<quote><literal>center</literal></quote>,
		and <quote><literal>right</literal></quote>. 
		This feature specifies which side of the group of
		node labels should be placed towards the node. 
		E.g, if <quote><literal>right</literal></quote> is selected
		(which is the default value), node labels appear
		left of the node.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>NodeLabel-yadj</literal></entry>
	    <entry><para>Adjust vertical position of node labels
		by extra amount of pixels.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>NodeLabel-dodrawbox</literal></entry>
	    <entry><para>If <menuchoice>
		  <guimenu>Setup</guimenu>
		  <guisubmenu>Appearance</guisubmenu>
		  <guimenuitem>Draw Boxes Around Labels</guimenuitem>
		</menuchoice>
		is not selected and this instruction
		is set to
		<quote><literal>yes</literal></quote> for a given node ,
		box is still drawn around the node's labels.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>NodeLabel-nodrawbox</literal></entry>
	    <entry><para>
		If <menuchoice>
		  <guimenu>Setup</guimenu>
		  <guisubmenu>Appearance</guisubmenu>
		  <guimenuitem>Draw Boxes Around Labels</guimenuitem>
		</menuchoice>
		is selected and this instruction
		 is set to
		<quote><literal>yes</literal></quote> for a given node,
		no box is drawn around the node's labels.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>EdgeLabel-yadj</literal></entry>
	    <entry><para>Adjust vertical position of edge labels
		by extra amount of pixels.
		The horizontal position is adjusted automatically.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>EdgeLabel-coords</literal></entry> 
	    <entry><para> This option
		can be used to specify custom (non-standard) positioning
		of the edge label by specifying the exact point to which
		the edge label is anchored.  The format of this option is
		similar to <literal>Line-coords</literal>, except that
		only one pair of coordinates (X,Y) is allowed. See <link linkend="Line-coords">Line-coords</link> for more
		information.
	      </para>
	    </entry>
	  </row>
	  <row>
	    <entry><literal>EdgeLabel-halign</literal></entry>
	    <entry><para>One of 
		the values <quote><literal>right</literal></quote>,
		<quote><literal>center</literal></quote>,
		and <quote><literal>left</literal></quote>
		may be used to specify which side of the edge label
		should be oriented towards the edge.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>EdgeLabel-valign</literal></entry>
	    <entry><para>One of 
		the values <quote><literal>top</literal></quote>,
		<quote><literal>center</literal></quote>,
		and <quote><literal>bottom</literal></quote>
		may be used to specify which side of the edge label
		should be oriented towards the edge.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>EdgeLabel-dodrawbox</literal></entry>
	    <entry><para>If <menuchoice>
		  <guimenu>Setup</guimenu>
		  <guisubmenu>Appearance</guisubmenu>
		  <guimenuitem>Draw Boxes Around Edge Labels</guimenuitem>
		</menuchoice>
		  is not selected and this instruction
		is set to
		<quote><literal>yes</literal></quote> for a given node ,
		box is still drawn around the node's edge labels.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>EdgeLabel-nodrawbox</literal></entry>
	    <entry><para>If <menuchoice>
		  <guimenu>Setup</guimenu>
		  <guisubmenu>Appearance</guisubmenu>
		  <guimenuitem>Draw Boxes Around Edge Labels</guimenuitem>
		</menuchoice>
		is selected and this instruction
		is set to
		<quote><literal>yes</literal></quote> for a given node,
		no box is drawn around the node's edge labels.</para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-dash</literal></entry>
	    <entry><para>Dash pattern for the outline
	      of the point representing the node of the tree.
	      A dash pattern is either a sequence of arbitrary
		of the following characters <quote>.,-_</quote>
		where space can be used
		to enlarge the space between other line elements, and can
		not occur as the first position in the string, or
		a comma-separated list of integer numbers
		specifying the lengths of dashes and spaces between them. 
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-activedash</literal></entry>
	    <entry><para>Dash pattern for the outline
	      of the point when mouse is over the point. See
	      description of <literal>Oval-dash</literal>
		for more information on dash patterns.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-dashoffset</literal></entry>
	    <entry><para>The starting offset (in pixels)
		into the pattern provided by the
		<literal>Oval-dash</literal> instruction.		
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-fill</literal></entry>
	    <entry><para>The color that fills the
		node.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-activefill</literal></entry>
	    <entry><para>The color to fill the node
	      when mouse is over it.</para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-outline</literal></entry>
	    <entry><para>The color of the outline
		of the node.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-activeoutline</literal></entry>
	    <entry><para>The color of the outline
		of the node when mouse is over it.
	      </para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Oval-width</literal></entry>
	    <entry><para>Width of the outline
		of the node.</para></entry>
          </row>
	  <row>
	    <entry><literal>Oval-activewidth</literal></entry>
	    <entry><para>Width of the outline
		of the node when mouse is over it.</para></entry>
          </row>
	  <row id="Line-coords">
	    <entry><literal>Line-coords</literal></entry>
	    <entry><para>
		This, very complex, option allows to setup
		one or more lines leading from the node. Unless this
		option is set, only a line (edge) starting at the
		node and leading to its parent is drawn.
	      </para>
	      <para>
		This option may consist of one or more 
		tuples of coordinates separated with
		<literal>&amp;</literal>
		of the form <literal>x1, y1..., xn, yn</literal>,
		where
		x1 through yn give the coordinates for a
		series of two or more points that describe a series of
		connected line segments.
	      </para>
	      <para>
		The coordinates may be either absolute or relative to
		the node, its parent, or if necessary to any node in
		the tree. In fact, 
		each corrdinate can be specified as an
		arithmetic expressions 
		involving the operations 
		<literal>+</literal>, <literal>-</literal>,
		<literal>*</literal>, <literal>/</literal>,
                <literal>%</literal> (modulus),
		functions 
		<literal>abs()</literal>,
		<literal>sgn()</literal>, and
		<literal>sqrt()</literal>, and
		the ternary operator
		<literal>condition ? exp-if-true : exp-if-else</literal>
		where condition can be a boolean expression
		involving 
		<literal>&amp;&amp;</literal> as conjunction, <literal>||</literal>
		as disjunction,
		and <literal>==</literal>, <literal>&lt;</literal>
		<literal>&gt;</literal>,
		<literal>&lt;=</literal>, and
		<literal>&gt;=</literal> as numeric comparison operators. Use the letter
		<literal>n</literal> to refer to the coordinate of the
		current node on the current axes and the letter
		<literal>p</literal> to refer to the coordinate of the
		parent node of the current node.  Use
		<literal>xn</literal> and <literal>yn</literal>, or
		<literal>xp</literal> and <literal>yp</literal> to
		refer to a coordinate of the current node or its
		parent (resp.) on an explicit axis.
		</para>
	      <para>		
		Coordinates of other nodes may be queried
		using the following constructions:
		<variablelist>
		  <varlistentry>
		    <term>Simple search</term>
		    <listitem>
		      <para>
			The construction of the form
			<literal>x[attribute_name = value]</literal>
			or
			<literal>y[attribute_name = value]</literal>
			may be used to query x-coordinate
			or y-coordinate (respectively)
			of the first node whose attribute
			<literal>attribute_name</literal>
			has the given <literal>value</literal>.
		      </para>
		    </listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Simple perl search</term>
		    <listitem>
		      <para>
			The construction of the form
			<literal>x[? code ?]</literal>
			or
			<literal>y[? code ?]</literal>
			may be used to query a
			coordinate 			
			of the first node for which the
			given Perl code returns non-zero
			defined value. Within the code,
			use 
			<literal>$this</literal> to refer
			to the current node and
			<literal>$node</literal>
			to the node being tested.
		      </para>
		    </listitem>
		  </varlistentry>
		  <varlistentry>
		    <term>Custom perl search</term>
		    <listitem>
		      <para>
			Sometimes it is not necessary to
			go through the whole tree to find the desired
			node. In such a case, the user may provide
			a code that finds the node
			and returns it.
			This type of query has the form
			<literal>x[! code !]</literal> or
			<literal>y[! code !]</literal>,
			where <literal>code</literal>
			is the user's custom node search algorithm
			written in Perl.
			Within the code, use 
			<literal>$this</literal> to refer
			to the current node.
		      </para>
		    </listitem>
		  </varlistentry>
		</variablelist>
	      </para>
	    </entry>
          </row>
	  <row>
	    <entry><literal>Line-arrow</literal></entry>
	    <entry><para>One of the values
		<quote><literal>first</literal></quote>,
		<quote><literal>both</literal></quote>,
		<quote><literal>last</literal></quote>,
		may be used to make arrow to be drawn
		on one or both sides of the edge connecting
		the given node with its parent.
		If multiple lines pertain to a node,
		values for individual lines should be separated by
		<literal>&amp;</literal>
		  in the same order in which lines are specified in <literal>Line-coords</literal>.
	      </para>
	    </entry>
          </row>
	  <row id="Line-tag">
	    <entry><literal>Line-tag</literal></entry>
	    <entry><para>Values are arbitrary strings
		  that will be passed to <literal>line_click_hook</literal>
		  if the line is clicked.
		If multiple lines pertain to a node,
		values for individual lines should be separated by
		<literal>&amp;</literal>
		  in the same order in which lines are specified in <literal>Line-coords</literal>.
		  The individual tag values must not contain
		  <literal>&amp;</literal>.

              </para>
	    </entry>
	  </row>
	  <row id="Line-hint">
	    <entry><literal>Line-hint</literal></entry>
	    <entry><para>Values are arbitrary strings
		  that will be shown when the user hovers mouse pointer
		  over the line.
		  If multiple lines pertain to a node,
		  values for individual lines should be separated by
		  <literal>&amp;</literal>
		  in the same order in which lines are specified in <literal>Line-coords</literal>.
		  For this reason the text for no line must not contain
		  <literal>&amp;</literal>.
              </para>
	    </entry>
	  </row>
	  <row>
	    <entry><literal>Line-smooth</literal></entry>
	    <entry><para>Values are 1 or 0.
              It indicates whether or not the line should be drawn as a curve.  If
              so, the line is rendered as a set of parabolic splines: one spline
              is drawn for the first and second line segments, one for the second
              and third, and so on.  Straight-line segments can be generated
              within a curve by duplicating the end-points of the desired line
              segment.
		If multiple lines pertain to a node,
		values for individual lines should be separated by
		<literal>&amp;</literal>
		  in the same order in which lines are specified in <literal>Line-coords</literal>.
              </para>
	    </entry>
	  </row>
	  <row>
	    <entry><literal>Line-decoration</literal></entry>
	    <entry><para> This option can be use to define various
	    line decorations to be drawn along individual lines
	    specified in <literal>Line-coords</literal>.  A decoration is
	    basically an item of the <ulink url="http://search.cpan.org/~SREZIC/Tk/pod/Canvas.pod">Tk::Canvas</ulink>
	    widget. This option can specify the shape type, relative
	    coordinates, size, and other properties of an decoration
	    item and the way in which the item is to be copied along
	    the line path.
	    </para><para>The
	    value consists of a <literal>&amp;</literal>-separated sequence of
	    decoration specifications for the individual lines (in the same order in
	    which lines are specified in
	    <literal>Line-coords</literal>).
	     </para>
	     <para>Each line can have multiple decorations;
	       individual decoration definitions are separated by <literal>|</literal>.
	       A decoration is defined by a semi-colon-separated list
	       of <literal><replaceable>option</replaceable>=<replaceable>value</replaceable></literal> pairs.
	     </para>
	     <para>
	       The following options are allowed in a decoration definition:
	     </para>
	       <variablelist>
		 <varlistentry>
		   <term>shape</term>
		   <listitem><para>One of
		   <literal>line</literal>,
		   <literal>text</literal>, 
		   <literal>rectangle</literal>,
		   <literal>polygon</literal>,
		   <literal>oval</literal>,
		   <literal>arc</literal>,
		   <literal>image</literal>.
		   </para></listitem>
		 </varlistentry>
		 <varlistentry>
		   <term>coords</term>
		   <listitem><para>A comma-separated list
		   of coordinates relative to
		   the current point on the line.
		   The shapes
		   <literal>text</literal> and
		   <literal>image</literal>
		   require one pair of coordinates,
		   <literal>oval</literal>,
		   <literal>arc</literal>, and
		   <literal>rectangle</literal>
		   require two pairs of coordinates,
		   <literal>line</literal> requires
		   at least two pairs of coordinates and
		   <literal>polygon</literal>
		   requires at least three pairs
		   of coordinates.
		   </para></listitem>
		 </varlistentry>
		 <varlistentry>
		   <term>step</term>
		   <listitem><para>Distance
		   between two adjacent instances of
		   decoration on the line.
		   The value can be a percent
		   string from 0% to 100%
		   defines the distance in percents
		   of the length of the line path
		   or an absolute distance (integer)
		   from the start of the line along the line path. 
		   </para></listitem>
		 </varlistentry>
		 <varlistentry>
		   <term>start</term>
		   <listitem><para>A distance (relative or absolute - see <literal>step</literal>)
		   from the start-point of the line in which
		   the first decoration should be drawn.
		 </para>
		 </listitem>
		 </varlistentry>
		 <varlistentry>
		   <term>stop</term>
		   <listitem><para>A distance (relative or absolute - see <literal>step</literal>)
		   from the end-point of the line beyond which
		   no further decoration should be drawn.
		 </para>
		 </listitem>
		 </varlistentry>
		 <varlistentry>
		   <term>force</term>
		   <listitem><para>If used,
		   it must provide a distance
		   in which a decoration is drawn
		   in case that the distance
		   defined using <literal>stop</literal>
		   precedes the distance defined using
		   <literal>start</literal>.
		   </para></listitem>
		 </varlistentry>	       
		 <varlistentry>
		   <term>repeat</term>
		   <listitem><para>Defines maximum number of decorations to
		   be drawn along the line path.</para></listitem>
		 </varlistentry>	       
		 <varlistentry>
		   <term>rotate</term>
		   <listitem><para>If set to a true value, 
		   the coordinates specified with
		   <literal>coords</literal> will
		   be rotated around the
		   current point on the line
		   so as to preserve
		   the same angle to the tangent
		   of the line as the initial coordinates
		   have to the axis X.
		  </para></listitem>
		 </varlistentry>	       
		 <varlistentry>
		   <term>tag</term>
		   <listitem><para>A comma-separated
		   list of tags to associate with
		   the decoration objects.</para></listitem>
		 </varlistentry>	       
		 <varlistentry>
		   <term><replaceable>other</replaceable></term>
		   <listitem><para>Any 
		   option 
		   such as <literal>fill, dash, outline,width</literal>
		   supported by the
		   given Tk::Canvas item-type (shape) 
		   can be passed
		   here.
		   Please consult <ulink url="http://search.cpan.org/~SREZIC/Tk/pod/Canvas.pod">Tk::Canvas#OVERVIEW_OF_ITEM_TYPES</ulink> documentation for a complete list.
		    The options must be passed without the leading dashes.
		   </para></listitem>
		 </varlistentry>	       
	       </variablelist>
	    </entry>
	  </row>

	  <row>
	    <entry><literal>Line-</literal><replaceable>feature</replaceable></entry>
	    <entry><para>Features
		<literal>dash</literal>,
		<literal>activedash</literal>,
		<literal>fill</literal>,
		<literal>activefill</literal>,
		<literal>width</literal>, and
		<literal>activewidth</literal>
		may be used to style the edge. Their values and
		meaning is similar to those of <literal>Oval</literal>,
		as described above.
		If multiple lines pertain to a node,
		values for individual lines should be separated by
		<literal>&amp;</literal>
		  in the same order in which lines are specified in <literal>Line-coords</literal>.
	      </para></entry>
          </row>
	  <row id="Textposition-fill">
	    <entry><literal>Text<replaceable>&lt;position&gt;</replaceable>-fill</literal></entry>
	    <entry><para>
		This feature may be used to set the color of a certain
		text object. The object is determined by its
		<replaceable>position</replaceable> which may have one
		of the following forms:
		<literal>[<replaceable>attribute-name</replaceable>]</literal>,
		<literal>[<replaceable>attribute-name</replaceable>][<replaceable>n</replaceable>]</literal>,
		or
		<literal>[<replaceable>attribute-name</replaceable>][<replaceable>n</replaceable>][<replaceable>m</replaceable>]</literal>,
		where <replaceable>attribute-name</replaceable>
		is name of an attribute,
		<replaceable>n</replaceable> is the ordinal number of
		pattern which is the source of the text object
		and <replaceable>m</replaceable> is ordinal number
		of the attribute reference (<literal>${<replaceable>attribute-name</replaceable>}</literal>) within that pattern.
	      </para></entry>
          </row>
	  <row>
	    <entry><literal>Text<replaceable>&lt;position&gt;</replaceable>-activefill</literal></entry>
	    <entry><para>This feature may be used to set the color of a certain
		text object when mouse is over it.
		The syntax of <replaceable>position</replaceable>
		is as above.
	      </para></entry>
          </row>
	  <row id="TextBg">
	    <entry><literal>TextBg<replaceable>&lt;position&gt;</replaceable>-<replaceable>feature</replaceable></literal></entry>
	    <entry><para>This instruction may be used to set features
		of an underlying rectangle of certain
		text object.
		The syntax of <replaceable>position</replaceable>
		is as above, except that only the first
		two forms are accepted, because text objects
		appearing on one line have common underlying rectangle.
		The following features are supported:
		<literal>dash</literal>,
		<literal>activedash</literal>,
		<literal>dashoffset</literal>,
		<literal>fill</literal>,
		<literal>activefill</literal>,
		<literal>outline</literal>,
		<literal>activeoutline</literal>,
		<literal>width</literal>, and
		<literal>activewidth</literal>.
	      </para></entry>
          </row>
	  <row id="TextBox">
	    <entry><literal>TextBox-<replaceable>feature</replaceable></literal></entry>
	    <entry><para>This instruction may be used to set features
		of the frame drawn around the group of node labels.
		The following features are supported:
		<literal>dash</literal>,
		<literal>activedash</literal>,
		<literal>dashoffset</literal>,
		<literal>fill</literal>,
		<literal>activefill</literal>,
		<literal>outline</literal>,
		<literal>activeoutline</literal>,
		<literal>width</literal>, and
		<literal>activewidth</literal>.
	      </para>
	    </entry>
          </row>
	  <row id="EdgeTextBox">
	    <entry><literal>EdgeTextBox-<replaceable>feature</replaceable></literal></entry>
	    <entry><para>This instruction may be used to set features
		of the frame drawn around the group of node's edge
		labels. The list of supported features is the same as
		that of <literal>TextBox</literal>.
	      </para>
	    </entry>
          </row>
	</tbody>
      </tgroup>
    </table>
    </section>
  </section>
  <section id="printing">
    <title>Printing Trees</title>
    <para>
      <application>TrEd</application> is
      able to render trees to PostScript,
      Encapsulated PostScript (EPS), and Portable
      Document Format (PDF). 
      Should the trees contain non-latin
      (iso-8859-1, iso-8859-2, windows-1250, etc.) characters,
      such as Arabic, the PDF might be the only option,
      because of its support for TrueType fonts.
    </para>
    <para>
      If <ulink url="http://www.imagemagick.org">ImageMagick</ulink>
      toolkit is installed, TrEd can also automatically convert the
      result into one of many bitmap image formats supported by this
      toolkit.</para>
    <para>  While PostScript is the default printing format on
      most Unix/Linux systems (and can be printed using the standard
      <command>lpr</command> command), Windows users
      may use for example <ulink url="http://www.adobe.com/products/acrobat/readermain.html">Adobe
      Acrobat Reader</ulink> to preview and print trees rendered into
      PDF. There are also some free PostScript interpreters for
      Windows (see <ulink url="http://www.cs.wisc.edu/~ghost/">GhostView</ulink>).
    </para>
    <figure float="0">
      <title>Print dialog
      </title>
      <mediaobject><imageobject><imagedata fileref="pics/tredprint.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/tredprint.eps" format="EPS" role="latex" width="13cm"/></imageobject><imageobject><imagedata fileref="pics/tredprint" format="linespecific"/></imageobject><textobject><phrase>print dialog</phrase></textobject></mediaobject>
    </figure>
    <para>
      Encapsulated PostScript files (<literal>EPS</literal>) are especially useful for
      preparation of other printed materials e.g. <application>PDF</application> of <application>LaTeX</application> documents. Compared to
      bitmapped images, EPS images have the advantage of being
      scalable.  Most office suits (such as Microsoft Office and
      OpenOffice.org) have at least limited support for EPS.  Similar
      results can be obtained by using <application>PDF</application>
      with <literal>BBox</literal> media size.
    </para>
    <note>
      <para>
	TrEd's ability to render PostScript
	and EPS is limitted to Eastern European character sets.
	For other charsets and unicode (especially when TrEd
	runs on a unicode aware versions of
	<literal>Perl</literal> and <literal>Tk</literal>,
	i.e. at least <literal>Perl 5.8</literal> and
	<literal>Tk804</literal>), PDF print format is recommended.
      </para>
    </note>
    <para>
      Printing into PDF requires a TrueType font containing at
      least the glyphs used in the tree.  For most languages,
      the usual fonts such as Arial
      (<literal>arial.ttf</literal>), Times New Roman
      (<literal>times.ttf</literal>) or Bitstream Vera
      (<literal>vera.ttf</literal>) are sufficient while other
      languages, such as Arabic, require a fully featured
      Unicode font such as <literal>Arial Unicode MS</literal>.
      The TrueType font can be specified either directly
      from the Print dialog or by setting <link linkend="ttfont"><literal>TTFont</literal></link>
      configuration option. If <literal>TTFont</literal>
      is not given, it defaults to <literal>Arial</literal>. 
      TrEd searches for TrueType fonts in directories listed in
      <link linkend="ttfontpath"><literal>TTFontPath</literal></link>
      configuration option. If this option is not explicitly
      specified, TrEd uses directories listed in 
      fontconfig library configuration file
      <literal>/etc/fonts/fonts.conf</literal> on Unix
      and Windows system font directory on Windows.
      If no usable font is found, PDF printing is disabled.
    </para>
    <para>
      For PostScript printing, <application>TrEd</application>
      uses a Type1 font.  The file containing the font may be
      specified using the <link linkend="psfontfile"><literal>PsFontFile</literal></link>
      (and optionally <link linkend="psfontafmfile"><literal>PsFontAFMFile</literal></link>)
      configuration option.
    </para>
    <itemizedlist>
      <listitem>
	<para>
	  In the <guilabel>Print</guilabel> dialog you can specify a printing command to
	  be used or (if <guilabel>Print to file</guilabel> is checked) a filename of the
	  destination file.
	</para>
      </listitem>
      <listitem>
	<para>
	  You can also specify a media-type (paper format)
	  in the <guilabel>Media</guilabel> roll-out menu, page
	  width and height (in case of <literal>User</literal>
	  media-type), and horizontal and vertical margins.
	  If the printed tree exceeds specified page
	  boundaries, it is automatically shrunk and
	  (unless <guilabel>Disable landscape rotation of wide
	    trees</guilabel> is selected) rotated to fit on the
	  page. See <link linkend="psmedia"><literal>PSMedia</literal></link>
	  configuration option for a list of supported media
	  formats.
	</para>
      </listitem>
      <listitem>
	<para>
	  The output format is specified by
	  selecting one of <guilabel>Create PostScript</guilabel>,
	  <guilabel>Create EPS</guilabel>, <guilabel>Create
	    PDF</guilabel> and  <guilabel>Convert according to
	    ImageMagick</guilabel> buttons.
	</para>
      </listitem>
      <listitem>
	<para>If <ulink url="http://www.imagemagick.org">ImageMagick</ulink>
	  utilities are installed on the system,
	  then automatic conversion to one of many image formats
	  is supported. To use it, first check the
	  <guilabel>Convert according to file
	    extension</guilabel> button, then select a desired
	  pixel resolution for conversion to bitmap, and finally
	  edit the output filename extension to that of the
	  desired output file-format such as
	  <filename>.png</filename> or
	  <filename>.jpg</filename>.  When converting
	  to a bitmap, <guilabel>Resolution</guilabel> may be specified to
	  adjust the mapping between PostScript coordinate
	  system units (given in 1/72 inch) to raster pixels.
	</para>
      </listitem>
      <listitem>
	<para>
	  If you also want the <quote>sentence</quote> of the tree
	  (i.e. the usual annotation mode of the text window above the tree)
	  to be printed under the tree, check the <guilabel>Print sentence</guilabel> button.
	</para>
      </listitem>
      <listitem>
	<para>
	  It is possible to print more than one tree (each tree then
	  appears either on a separate page or in a separate file).
	  To do so, a comma-separated list of tree numbers or ranges
	  of tree numbers that correspond to the desired trees in the
	  active file, must be entered into the <guilabel>Page range</guilabel> field.  The
	  <inlinemediaobject><imageobject><imagedata fileref="pics/1leftarrow.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/1leftarrow" format="linespecific"/></imageobject><textobject><phrase>left-arrow</phrase></textobject></inlinemediaobject>
	  button is be used to automatically insert a page range
	  corresponding to sentences selected via <link linkend="list_of_sentences"><menuchoice>
	  <guimenu>View</guimenu> <guimenuitem>List of Sentences...</guimenuitem>
	  </menuchoice></link>. A different selection based on
	  <quote>sentences</quote> can be made by pressing the button
	  <inlinemediaobject><imageobject><imagedata fileref="pics/contents.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/contents.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/contents" format="linespecific"/></imageobject><textobject><phrase>contents</phrase></textobject></inlinemediaobject>.
	</para>
      </listitem>
      <listitem>
	<para id="page_range">
	  If entered manually, the page range must be specified
	  according to the following rules: Trees in the file are
	  numbered starting from 1. Ranges are pairs of numbers of the
	  form <quote><literal>3-20</literal></quote>
	  (which in this case covers all trees starting from the tree
	  no. 3 to no. 20).  If the first number in the range is
	  omitted, 1 is assumed. If the second number in the range is
	  ommited, the number of the last tree in the active file is
	  assumed.  The order of the tree numbers given in the list is
	  strictly reflected in the output file, which also means that
	  ceratin tree can be printed more than once.
	  <note>
	    <title>Example:</title>
	    <para>
	      To print trees from 1 to 5, then trees no. 7, 11, 12 and 5
	      again, use e.g. one of the following lists:
	      <simplelist type="vert">
		<member><literal>1-5,7,11,12,5</literal></member>
		<member><literal>1-5,7,11-12,5</literal></member>
		<member><literal>-5,7,11-12,5</literal></member>
	      </simplelist>
	    </para>
	  </note>
	</para>
      </listitem>
    </itemizedlist>
    <note>
      <para>
	Printing trees can also be automated by writing a suitable
	macro. For this purpose, TrEd API offers the function
	<literal>Print</literal> (see <xref linkend="defaultmacros"/>). This function however requires
	TrEd GUI, i.e. it cannot be run in <command>btred</command>.
      </para>
      <example>
	<title>Printing trees from a user-defined macro</title>
	<programlisting format="linespecific">
	  <![CDATA[
# bind key p to CreateImages menu Create bitmap images of all trees
sub CreateImages {
   GotoTree(1);
   my $tree_no = 1;
   my $name = FileName();
   $name =~ s/\..*//; # strip filename suffix
   do {{
      TredMacro::Print(
	 -toFile => 1,
	 -format => 'ImageMagick',
	 -imageMagickResolution => 90,
	 -colors => 1,
	 -sentenceInfo => 1,
	 -filename => "${name}_${tree_no}.png"
       );
      $tree_no++;
   }} while NextTree();
}	  
]]>
	</programlisting>
      </example>
    </note>
  </section>
  

  <section id="filelists">
    <title>Using File Lists</title>
    <para>
      file list is simply a named list of file-name patterns or actual
      file names (possibly with extra suffixes attached to them
      specifying certain tree or node by its position in the
      file - see the file-name handling conventions described in <xref linkend="commandline"/>). file lists can be created, modified, saved or deleted in
      a file list editor accessible via <menuchoice>
      <guimenu>File</guimenu> <guisubmenu>File Lists</guisubmenu> <guimenuitem>Manage File Lists...</guimenuitem> </menuchoice>
      menu-command.
    </para>
    <para>
      file lists can serve several purposes, the most common of which
      are searching and comfortable editing series of files.  Each
      view is associated with a file list. For the active view, we
      call that file list the current file list. Name of the
      current-file list is displayed at the title of the main
      <application>TrEd</application>'s window.  If
      current file list contains more than one file, the commands
      <menuchoice> <guimenu>File</guimenu> <guisubmenu>File Lists</guisubmenu>  <guimenuitem>Previous in File List</guimenuitem> </menuchoice> (or
      <inlinemediaobject><imageobject><imagedata fileref="pics/start.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/start.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/start" format="linespecific"/></imageobject><textobject><phrase>start</phrase></textobject></inlinemediaobject>
      button) and <menuchoice> <guimenu>File</guimenu><guisubmenu>File Lists</guisubmenu> <guimenuitem>Next
      in File List</guimenuitem>
    </menuchoice>
      (or <inlinemediaobject><imageobject><imagedata fileref="pics/finish.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/finish.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/finish" format="linespecific"/></imageobject><textobject><phrase>end</phrase></textobject></inlinemediaobject> button)
      can be used to open previous and next file in the file list, respectively.
    </para>
    <figure float="0">
      <title>Creating file lists</title>
      <mediaobject><imageobject><imagedata fileref="pics/filelist.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/filelist.eps" format="EPS" role="latex" width="13cm"/></imageobject><imageobject><imagedata fileref="pics/filelist" format="linespecific"/></imageobject><textobject><phrase>file list</phrase></textobject></mediaobject>
    </figure>
    <para>
      The following file lists are created and managed automatically
      by <application>TrEd</application>:
    </para>
    <variablelist>
      <varlistentry>
	<term><literal>Default</literal></term>
	<listitem>
	  <para>
	    This file list contains files opened with <menuchoice>
	    <guimenu>File</guimenu> <guimenuitem>Open ...</guimenuitem> </menuchoice> during the current session
	    up to the moment.
	  </para>
	</listitem>	
      </varlistentry>
      <varlistentry>
	<term><literal>CmdLine-<replaceable>n</replaceable></literal></term>
	<listitem>
	  <para>
	    This file list contains files specified either directly on
	    the command line or in file(s) following the command-line
	    option <parameter>-l</parameter>. <replaceable>n</replaceable> is
	    an integer number starting from 1 (files from the
	    <replaceable>n</replaceable>-th file specified in
	    <parameter>-l</parameter> appear in the file list
	    <literal>CmdLine-<replaceable>n</replaceable></literal>).
	  </para>
	</listitem>	
      </varlistentry>
      <varlistentry>
	<term><literal>Bookmarks</literal></term>
	<listitem>
	  <para>
	    The <literal>Bookmarks</literal> file list
	    conains all bookmarks.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
    <para>
      To create a user-defined file list, open the <guilabel>File List</guilabel> dialog, Type a name
      of the file list into the <guilabel>File lists</guilabel> field
      (on the top right side), press <keycap>Enter</keycap> and
      confirm the creation by pressing the
      <guibutton>Create</guibutton> button in the
      confirmation dialog which pops up.
      Alternativelly, press the <guibutton>New</guibutton> button,
      fill the name of the new file list to the entry in the displayed
      dialog and press <guibutton>OK</guibutton>.
    </para>
    <para>
      To modify an existing file list, first choose it from the menu
      that appears when the button on the right of the <guilabel>File
      lists</guilabel> entry is pressed.  To add some files to the
      chosen file list, first browse the files in the list on the left
      of the <guilabel>File List</guilabel> dialog. Then select the
      desired files in this list and finally press the
      <guibutton>Add--&gt;</guibutton>.  If the selection contains a
      directory, user is prompted for a wild-card pattern and all
      files from the directory matching the pattern are added to the
      file list. This is a very convenient way for adding all files in
      a directory. This has also the advantage that any change made in
      the content of the directory automatically leads to the
      corresponding effect in the file list.
    </para>
    <para>
      To remove files from the file list, select the files and
      press the <guibutton>Remove</guibutton> button.
    </para>
    <para>
      To make certain file list the current file list for <application>TrEd</application> double-click on any file in
      the file list or just select the file and press <guibutton>Show in TrEd</guibutton>. The selected file is
      opened and the file list is made current.
    </para>
    <note>
      <para>It is possible to switch between several file lists
	without entering the file list editor, simply by selecting other file list using
	<menuchoice>
	  <guimenu>File</guimenu>
	  <guisubmenu>File Lists</guisubmenu>
	  <guimenuitem>Select File List...</guimenuitem>
	</menuchoice>.
      </para>
    </note>
    <para>
      The button <guibutton>Save</guibutton> is used
      to save the chosen file list to a file, so that it can be either
      automatically or manually opened in the next <application>TrEd</application>'s session. Note that the
      <literal>Bookmark</literal> file list is saved
      automatically at the end of every
      <application>TrEd</application> session.
    </para>
    <para>
      The button <guibutton>Delete</guibutton> makes
      <application>TrEd</application> forget about the selected
      file list.  Note that deleting a file list does not delete the
      file it was previously saved to.
    </para>
    <para>The <guibutton>Load</guibutton> button can
      be used to load a previously saved file list. Note that all
      saved file lists that are known to <application>TrEd</application> at the end of a session are
      automatically loaded at the start of the next <application>TrEd</application>'s session.
    </para>
    <para>
      The button <guilabel>Close</guilabel> closes the
      <guilabel>File List</guilabel> dialog window.
    </para>
  </section>
  <section id="configuration">
    <title>Configuration and customization</title>
    <para>
      The configuration and customization of <application>TrEd</application> is possible through modifying
      its configuration file. At the start of a session, <application>TrEd</application> searches for its
      configuration file on several places and uses the first
      configuraton file found:
    </para>
    <orderedlist continuation="restarts" inheritnum="ignore">
      <listitem>
	<para>
	  First <application>TrEd</application> looks for a file given with a command-line parameter
	  <parameter>-c</parameter> (see <xref linkend="commandline"/> for details).
	</para>
      </listitem>
      <listitem><para>    
	If the <varname>HOME</varname> system variable is set (on UNIX/Linux this
	  variable points to user's home directory) <application>TrEd</application> searches for
	<filename>.tredrc</filename> (mind the dot
	  here) file in that directory. On Windows,
	  <application>TrEd</application> uses the <filename>Application Data</filename> folder in user's profile.
      </para>
      </listitem>
      <listitem><para>
	  If the <varname>TREDHOME</varname> system variable is set <application>TrEd</application> searches for
	<filename>tredrc</filename> file in that directory. 	
      </para></listitem>
      <listitem><para>
	  <application>TrEd</application> looks for a <filename>tredrc</filename> file in 
	  the directory where the program file of <application>TrEd</application> itself is located.
      </para></listitem>
      <listitem>
	<para>
	  <application>TrEd</application> looks for a
	  <filename>tredrc</filename> file in directories
	  <filename>../lib/tred</filename>, <filename>../lib/tredlib</filename> and
	  <filename>./tredlib/tredrc</filename> respectively, relative to the
	  directory of the program file of <application>TrEd</application>.
	</para>
      </listitem>
      <listitem><para>
	  <application>TrEd</application> looks for a <filename>tredrc</filename> file in 
	  the <filename>/usr/share/config/</filename> directory.
	</para></listitem>
    </orderedlist>
    <para>
      If none of these files is found, default values for configuration
      options are used.
    </para>
    <para>
      <application>TrEd</application>'s configuration
      file is a plain text file with a very simple structure. It can
      be edited either in an external text editor (like <application>vi</application>, <application>Emacs</application> or <application>Notepad</application>) or directly from TrEd in
      a built-in editor (<menuchoice> <guimenu>Setup</guimenu> <guimenuitem>Edit Config File...</guimenuitem></menuchoice>). In both cases
      there is a way to update the options used by a running session
      of <application>TrEd</application>: </para>
    <itemizedlist>
      <listitem><para>Use <menuchoice> <guimenu>Setup</guimenu> <guimenuitem>Reload Config File</guimenuitem></menuchoice>
	    menu command to make TrEd re-read the configuration file
	    from disk.</para></listitem> <listitem><para> In the
	    <application>TrEd</application>'s built-in
	    configuration editor use the <guibutton>Save and Apply</guibutton> button to apply
	  changes and save them or <guibutton>Apply</guibutton> button to apply changes
	  withought saving them. In the latter case, all changes only apply for the 
	  current session and the configuration file is
	  untouched. As the built-in editor re-reads the configuration
	  file every time, all such changes are lost when the editor
	  is closed (although they still apply).
	  The first command also quits the configuration editor.
	</para>
      </listitem>
    </itemizedlist>
    <note>
      <para>
	Some configuration options only take effect after restarting
	<application>TrEd</application>.
      </para>
    </note>
    <para>Each line in the configuration file
      has the following simple form:</para>
    <literallayout class="normal" format="linespecific"><replaceable>option_name</replaceable> = <replaceable>value</replaceable></literallayout>
    <para>
      There may be any amount of white-space between the option name
      and value but they must be both on the same line. Any characters
      folowing a semi-colon (<literal>;</literal>) to
      the end of line are treated as a comment and hence ignored.
      It is possible to quote any value using either quotes or
      double-quotes, so that white-space and semi-colons are preserved
      correctly. All option names are case-insensitive. 
    </para>
    <para>
      Available configuration options may be divided into several categories:
    </para>
    <section>
    <title>Colors</title>
      <variablelist>
	<varlistentry id="backgroundcolor">
	  <term><literal>BackgroundColor</literal></term>
	  <listitem>
	    <para>Background color of the tree-view canvas.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="backgroundimage">
	  <term><literal>BackgroundImage</literal></term>
	  <listitem>
	    <para>This option allows specifying a background image
	      for the canvas on which trees are displayed. 
	      At present, only GIF, XBM, XPM, BMP, JPEG, PNG and
	      PPM/PGM files are supported.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="backgroundimagex">
	  <term><literal>BackgroundImageX</literal></term>
	  <listitem>
	    <para>Horizontal offset of the background image.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="backgroundimagey">
	  <term><literal>BackgroundImageY</literal></term>
	  <listitem>
	    <para>Vertical offset of the background image.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="highlightwindowcolor">
	  <term><literal>HighlightWindowColor</literal></term>
	  <listitem>
	    <para>Color of the frame drawn around the focused view.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="currentnodecolor">
	  <term><literal>CurrentNodeColor</literal></term>
	  <listitem>
	    <para>Color to draw the active node. Default is red.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nearestnodecolor">
	  <term><literal>NearestNodeColor</literal></term>
	  <listitem>
	    <para>Color to highlight the nearest node to indicate the
	      destination of a possible drop when dragging a node.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="bwprintnodecolor">
	  <term><literal>BWPrintNodeColor</literal></term>
	  <listitem>
	    <para>Color used to fill nodes when printing in
	      black-and-white. Defaults to <literal>white</literal>,
	      which results in nodes with only black outline. 
	      If set to <literal>black</literal>, nodes are printed
	      as all-black objects without a visible outline.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="textcolor">
	  <term><literal>TextColor</literal></term>
	  <listitem>
	    <para>Color used to display text of normal tree attributes.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="usefscolors">
	  <term><literal>UseFSColors</literal></term>
	  <listitem>
	    <para>Enable node-label coloring according to FS-format specific color flags: Shadow, Hilite and XHilite.
	      Defaults to 0 TrEd revisions &gt;= 1.3271.
	      See <ulink url="http://quest.ms.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html">FS-format
	      description</ulink> to learn about how to specify which attributes
	      are shadowed, highlighted and extra-highlighted. 
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="textcolorshadow">
	  <term><literal>TextColorShadow</literal></term>
	  <listitem>
	    <para>Color used to display text of shadowed tree attributes (only used if <literal>UseFSColors=1</literal>).</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="textcolorhilite">
	  <term><literal>TextColorHilite</literal></term>
	  <listitem>
	    <para>Color used to display text of highlighted tree
	      attributes (only used if <literal>UseFSColors=1</literal>).</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="textcolorxhilite">
	  <term><literal>TextColorXHilite</literal></term>
	  <listitem>
	    <para>Color used to display text of extra-highlighted tree
	      attributes.
	      (only used if <literal>UseFSColors=1</literal>)
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="customcolor">
	  <term><literal>CustomColor<replaceable>name</replaceable></literal></term>
	  <listitem>
	    <para>
	      Defines a custom color named
	      <replaceable>name</replaceable>, 
	      which may be refered to in a stylesheet pattern with
	      <literal>#{custom<replaceable>name</replaceable>}</literal>
	      or queried in a macro with
	      <literal>CustomColor("<replaceable>name</replaceable>")</literal>.
	      For more information see <xref linkend="stylesheets"/>.
	      See also the <link linkend="allowcustomcolors"><literal>AllowCustomColors</literal></link>
	      option which can be used to enable or disable the actual
	      use of the custom colors.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="activetextcolor">
	  <term><literal>ActiveTextColor</literal></term>
	  <listitem>
	    <para>
	      Color used to flash the text of an attribute under the mouse-pointer.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="boxcolor">
	  <term><literal>BoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      labels if the <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw Boxes Around Edges</guimenuitem>
	      </menuchoice> item is checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="currentboxcolor">
	  <term><literal>CurrentBoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      the active node's labels if the <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw Boxes Around Labels</guimenuitem></menuchoice> item is checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hiddenboxcolor">
	  <term><literal>HiddenBoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      a hidden node's labels if the <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw Boxes Around Labels</guimenuitem></menuchoice> and 
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Show Hidden Nodes</guimenuitem></menuchoice>
	      items are checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="edgeboxcolor">
	  <term><literal>EdgeBoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      edge labels if the <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw Boxes Around Edge Labels</guimenuitem>
	      </menuchoice> item is checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="edgecurrentboxcolor">
	  <term><literal>EdgeCurrentBoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      the edge label of the active node ( if the <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw Boxes Around Edge Labels</guimenuitem></menuchoice> item is checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="edgehiddenboxcolor">
	  <term><literal>EdgeHiddenBoxColor</literal></term>
	  <listitem>
	    <para>
	      Background color of a border drawn around the text of
	      a hidden node's edge labels if the <menuchoice>
		<guimenu>View</guimenu>
		<guimenuitem>Draw boxes around edge labels</guimenuitem></menuchoice> and 
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Show Hidden
		</guimenuitem></menuchoice>
	      items are checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="linecolor">
	  <term><literal>LineColor</literal></term>
	  <listitem>
	    <para>Color used to draw the lines connecting dependent nodes in a
	      tree.
	      Default is black.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hiddenlinecolor">
	  <term><literal>HiddenLineColor</literal></term>
	  <listitem>
	    <para>Color used to draw the lines connecting hidden
	      nodes with their parents. Default is gray.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="dashhiddenlines">
	  <term><literal>dashHiddenLines</literal></term>
	  <listitem>
	    <para>Controls is lines connecting hidden nodes with
             their parents are dashed or solid. Allowed values are 0
             (solid) or 1 (dashed). Default is 0.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="linearrow">
	  <term><literal>LineArrow</literal></term>
	  <listitem>
	    <para>One of the values
	      <quote><literal>first</literal></quote>,
	      <quote><literal>both</literal></quote>,
	      <quote><literal>last</literal></quote>,
	      may be used to make arrows to be drawn by default
	      on one or both sides of the edge connecting
	      the given node with its parent.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodecolor">
	  <term><literal>NodeColor</literal></term>
	  <listitem>
	    <para>Color used to fill an ordinary node of the tree.
	      Default is yellow.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodeoutlinecolor">
	  <term><literal>NodeOutlineColor</literal></term>
	  <listitem>
	    <para>Color used to draw the outline of an ordinary node.
	      Default is black.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hiddennodecolor">
	  <term><literal>HiddenNodeColor</literal></term>
	  <listitem>
	    <para>Color used to draw nodes marked as hidden, if shown. Default
	      is black.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>Other options affecting tree appearence</title>
      <variablelist>
	<varlistentry id="balancetree">
	  <term><literal>BalanceTree</literal></term>
	  <listitem>
	    <para>If this option is set to 1 or 'spread', the tree will be
	      auto-balanced, disregarding a node-ordering
	      attribute. The value 'spread' indicates,
	      that the balanced tree should be spread so that
	      the projections of the leaf nodes to the
	      lowest level of the tree do not overlap;
	      that is, there must be a partition of the canvas
	      into vertical stripes such that each stripe
	      contains exactly one leaf node along with all its
	      node labels (and the stripes do not overlap).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="displaymode">
	  <term><literal>DisplayMode</literal></term>
	  <listitem>
	    <para>If this option is set to 1, the tree will be
	      always displayed in the <link linkend="vertical-mode">vertical mode</link>, if set to -1,
	      the tree will be always displayed in the horizontal
	      mode. In either case, the setting of 
	      rootstyle <literal>#{vertical}</literal> instruction in
	      the current stylesheet is ignored.
	      Defaults to 0 (obey stylesheet).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="skiphiddenlevels">
	  <term><literal>SkipHiddenLevels</literal></term>
	  <listitem>
	    <para>If the <link linkend="get_nodelist_hook"><literal>get_nodelist_hook</literal></link>
	      provides an incomplete list of nodes of the tree 
	      or if some nodes are hidden using <link linkend="style-instructions"><literal>Node-hide</literal></link>, there
	      may be nodes whose parent-node is not on the list.
	      If this option is set to <literal>1</literal>,
	      any such a orphan node <quote>skip levels</quote> and appears
	      as if it was child-node of its nearest ancestor-node that belongs
	      to the list. This option implies
	      <link linkend="skiphiddenparents"><literal>SkipHiddenParents</literal></link>.
	      (Note that this only affects the way a tree is drawn,
	      it does not relate in any way to tree-navigation and
	      tree-traversal functions).
	      Default is <literal>0</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="skiphiddenparents">
	  <term><literal>SkipHiddenParents</literal></term>
	  <listitem>
	    <para>If the <link linkend="get_nodelist_hook"><literal>get_nodelist_hook</literal></link>
	      provides an incomplete list of nodes of the tree or if some nodes are hidden using <link linkend="style-instructions"><literal>Node-hide</literal></link>, there
	      may be nodes whose parent-node is not on the list.
	      If this option is set to <literal>1</literal>,
	      then any lines that would connect such an orphan node with its parent
	      are instead connected to the nearest ancestor of the node that
	      belongs to the list. The orphan node however remains on its
	      level in the tree (see also <link linkend="skiphiddenlevels"><literal>SkipHiddenLevels</literal></link>).
	      (Note that this only affects the way a tree is drawn,
	      it does not relate in any way to tree-navigation and
	      tree-traversal functions).
	      Default is <literal>0</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="highlightwindowwidth">
	  <term><literal>HighlightWindowWidth</literal></term>
	  <listitem>
	    <para>Width of the frame drawn around the focused view.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="linewidth">
	  <term><literal>LineWidth</literal></term>
	  <listitem>
	    <para>Width of the lines connecting dependent nodes in a tree.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodewidth">
	  <term><literal>NodeWidth</literal></term>
	  <listitem>
	    <para>
	      The horizontal diameter of the ellipsis representing a node in
	      a tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodeheight">
	  <term><literal>NodeHeight</literal></term>
	  <listitem>
	    <para>
	      The vertical diameter of the ellipsis representing a node in
	      a tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="currentnodewidth">
	  <term><literal>CurrentNodeWidth</literal></term>
	  <listitem>
	    <para>
	      The horizontal diameter of the ellipsis representing the active node in
	      a tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="currentnodeheight">
	  <term><literal>CurrentNodeHeight</literal></term>
	  <listitem>
	    <para>
	      The vertical diameter of the ellipsis representing the active node in
	      a tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodexskip">
	  <term><literal>NodeXSkip</literal></term>
	  <listitem>
	    <para>The minimal horizontal distance between two nodes in a
	      tree.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nodeyskip">
	  <term><literal>NodeYSkip</literal></term>
	  <listitem>
	    <para>The minimal vertical distance between two nodes in a
	      tree.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="xmargin">
	  <term><literal>XMargin</literal></term>
	  <listitem>
	    <para>Horizontal amount of space left around borders of the box
	      surrounding the text of displayed attributes of a node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="ymargin">
	  <term><literal>YMargin</literal></term>
	  <listitem>
	    <para>Horizontal amount of space left around borders of the box
	      surrounding the text of displayed attributes of a node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="basexpos">
	  <term><literal>BaseXPos</literal></term>
	  <listitem>
	    <para>
	      The horizontal distance of the tree root (zero's node)
	      from the right of the tree view.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="baseypos">
	  <term><literal>BaseYPos</literal></term>
	  <listitem>
	    <para>
	      The vertical distance of the tree root (zero's node)
	      from the top of the tree view.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="linespacing">
	  <term><literal>LineSpacing</literal></term>
	  <listitem>
	    <para>
	      Coeficient for line spacing in text labels.
	      The value can be float.
	      Default coeficient is 1 (single line spacing).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="drawboxes">
	  <term><literal>DrawBoxes</literal></term>
	  <listitem>
	    <para>
	      If this option is set, <application>TrEd</application> starts with the 
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>DrawBoxes</guimenuitem></menuchoice> menu item checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="drawedgeboxes">
	  <term><literal>DrawEdgeBoxes</literal></term>
	  <listitem>
	    <para>
	      If this option is set, 
	      <application>TrEd</application> starts with the 
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Draw boxes around edge labels</guimenuitem>
	      </menuchoice> menu item checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="edgelabelskipabove">
	  <term><literal>EdgeLabelSkipAbove</literal></term>
	  <listitem>
	    <para>
	      Extra space left above every edge label.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="edgelabelskipbelow">
	  <term><literal>EdgeLabelSkipBelow</literal></term>
	  <listitem>
	    <para>
	      Extra space left below every edge label.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="useadditionaledgelabelskip">
	  <term><literal>UseAdditionalEdgeLabelSkip</literal></term>
	  <listitem>
	    <para>
	      This options controls whether the algorighm
	      computing the tree-layout in TrEd should try to
	      add a reasonable horizontal skip for the edge labels,
	      to avoid their overlapping. Note that
	      even with this option on, the algorithm cannot
	      reliably ensure that. Defaults to 1.
	    </para>
	  </listitem>
	</varlistentry>
	<!--
	<varlistentry id="highlightattributes">
	  <term><literal>HighlightAttributes</literal></term>
	  <listitem>
	    <para>
	      obsolete
	    </para>
	  </listitem>
	</varlistentry>
	-->
	<varlistentry id="cleartextbackground">
	  <term><literal>ClearTextBackground</literal></term>
	  <listitem>
	    <para>
	      Choose if invisible rectangles should be drawn beneath
	      text labels to clear the background for the text.
	      Possible values are <literal>0</literal> and <literal>1</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="allowcustomcolors">
	  <term><literal>AllowCustomColors</literal></term>
	  <listitem>
	    <para>
	      This option takes one of the values <literal>0</literal>
	      and <literal>1</literal>.
	      If set to <literal>0</literal>, all references to
	      custom colors in attribute patterns are ignored. 
	      It is also the default value.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="showhidden">
	  <term><literal>ShowHidden</literal></term>
	  <listitem>
	    <para>
	      If this option is set, <application>TrEd</application> starts with the 
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guimenu>Appearance</guimenu>
		<guimenuitem>Show Hidden Nodes</guimenuitem>
	      </menuchoice> menu item checked.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hintwait">
	  <term><literal>HintWait</literal></term>
	  <listitem>
	    <para>
	      This option controls time interval
	      that mouse pointer needs to linger over a node 
	      before the hint for the node is displayed. 
	      The value is to be given in
	      milliseconds.  See <xref linkend="stylesheets"/> for more
	      information about defining the content of the hints.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="toolbarhintwait">
	  <term><literal>ToolbarHintWait</literal></term>
	  <listitem>
	    <para>
	      This option controls time interval
	      that mouse pointer needs to linger over a TrEd toolbar
	      button (or other widget with a tool-tip)
	      before a tool-tip is displayed. 
	      The value is to be given in
	      milliseconds.  See <xref linkend="stylesheets"/> for more
	      information about defining the content of the hints.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="searchmethod">
	  <term><literal>SearchMethod</literal></term>
	  <listitem>
	    <para>
	      This option lets you define the default method used when
	      searching with the <menuchoice>
		<guimenu>Node</guimenu>
		<guimenuitem>Find</guimenuitem>
	      </menuchoice> command. The default value is
	      <literal>Exhaustive regular expression</literal>
	      but user may use any of the following values (actually
	      only the first letter suffices):
	      <simplelist type="vert">
		<member><literal>Regular Expression</literal></member>
		<member><literal>Wildcards</literal></member>
		<member><literal>Literal</literal></member>
		<member><literal>Exhaustive regular expression</literal></member>
	      </simplelist>
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="macrolistorder">
	  <term><literal>MacroListOrder</literal></term>
	  <listitem>
	    <para>This option defines the default ordering of macros
	      when <menuchoice>
		<guimenu>Macros</guimenu>
		<guimenuitem>List of Macros...</guimenuitem>
	      </menuchoice>
	      menu command is used. Possible values are letters
	      <literal>M</literal> (sort by macro menu label)
	      and <literal>K</literal> (sort by keyboard shortcuts
	      assigned to macros). Default value is <literal>M</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="maxdisplayedvalues">
	  <term><literal>MaxDisplayedValues</literal></term>
	  <listitem>
	    <para>
	      This option may be used to tell
	      <application>TrEd</application>
	      how many fields should fit in one screen of a
	      list when a dialog
	      displaying possible (or already assigned)
	      values for a certain attribute is displayed.
	      (The greater the number is, the taller
	      the dialog grows).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="maxdisplayedattributes">
	  <term><literal>MaxDisplayedAttributes</literal></term>
	  <listitem>
	    <para>
	      This option may be used to tell
	      <application>TrEd</application>
	      how many fields should fit in one screen of the
	      <guilabel>Edit Node ...</guilabel>
	      and
	      <guilabel>Find Node by Attributes</guilabel>
	      dialog windows. (The greater the number, the taller
	      the dialogs).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vertstripe">
	  <term><literal>VertStripe</literal></term>
	  <listitem>
	    <para>
	      If set to <literal>1</literal>, a vertical
	      stripe is displayed across the screen at the position
	      of the current node. This helps identifying the current
	      node and its horizontal position among other nodes.
	      This option does not apply to the <link linkend="vertical-mode">vertical mode</link>.
	      Defaults to <literal>0</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="horizstripe">
	  <term><literal>HorizStripe</literal></term>
	  <listitem>
	    <para>
	      This option only applies to the  <link linkend="vertical-mode">vertical mode</link>.
	      If set to <literal>1</literal> (default), the line corresponding
	      to the current node is highlighted with a horizontal stripe.
	      This helps identifying the current node among other nodes.
	      Set this option to <literal>0</literal> to disable the stripe.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="stripecolor">
	  <term><literal>StripeColor</literal></term>
	  <listitem>
	    <para>
	      The color of a stripe highlighting the current node.
	      See <link linkend="horizstripe">HorizStripe</link> and
	      <link linkend="vertstripe">VertStripe</link> options for
	      more information.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="columnsep">
	  <term><literal>ColumnSep</literal></term>
	  <listitem>
	    <para>
	      Default distance between two columns of labels
	      in <link linkend="vertical-mode">Vertical mode</link>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="labelsep">
	  <term><literal>LabelSep</literal></term>
	  <listitem>
	    <para>
	      Default distance between a node and the label next to it
	      in <link linkend="vertical-mode">Vertical mode</link>.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>GUI options</title>
      <variablelist>
	<varlistentry id="appname">
	  <term><literal>AppName</literal></term>
	  <listitem>
	    <para>The window title for the <application>TrEd</application>'s main window.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="appicon">
	  <term><literal>AppIcon</literal></term>
	  <listitem>
	    <para><application>TrEd</application>'s desktop and window
	      icon (in <literal>XPM</literal> format).</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="showsidepanel">
	  <term><literal>ShowSidePanel</literal></term>
	  <listitem>
	    <para>If true, TrEd starts with side panel displayed.
	    Note: the option is saved by TrEd on exit.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="stippleinactivewindows">
	  <term><literal>StippleInactiveWindows</literal></term>
	  <listitem>
	    <para>
	      If set to <literal>1</literal>, inactive views are
	      covered with a semi-transparent stipple pattern. This
	      may improve orientation if working with more than one
	      view, but also slightly reduces the clarity of trees
	      displayed in the inactive views. This option can also be
	      controlled in run-time using
	      <menuchoice>
		<guimenu>Setup</guimenu>
		<guisubmenu>Appearance</guisubmenu>
		<guimenuitem>Stipple Inactive Views</guimenuitem>
	      </menuchoice>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlineheight">
	  <term><literal>VLineHeight</literal></term>
	  <listitem>
	    <para>Initial height for the value line in lines. Default
	    value is 2.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinealign">
	  <term><literal>VLineAlign</literal></term>
	  <listitem>
	    <para>Specifies alignment for value line. Possible values
	      are <literal>left</literal>, <literal>center</literal>, and <literal>right</literal>.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinewrap">
	  <term><literal>VLineWrap</literal></term>
	  <listitem>
	    <para>Specifies value line wrapping. Possible values
	      are <literal>node</literal> (no wrapping),
	      <literal>char</literal> (allow wrapping on any character
	      boundary),
	      and <literal>word</literal> (allow wrapping on word boundary).</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinereverselines">
	  <term><literal>VLineReverseLines</literal></term>
	  <listitem>
	    <para>Draw wrapped value lines in reverse order (bottom-up).</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlineforeground">
	  <term><literal>VLineForeground</literal></term>
	  <listitem>
	    <para>
	      Foreground color of the value line.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinebackground">
	  <term><literal>VLineBackground</literal></term>
	  <listitem>
	    <para>
	      Background color of the value line.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinefocusforeground">
	  <term><literal>VLineFocusForeground</literal></term>
	  <listitem>
	    <para>
	      Foreground color of the highlighted value corresponding to the
	      active node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="vlinefocusbackground">
	  <term><literal>VLineFocusBackground</literal></term>
	  <listitem>
	    <para>
	      Background color of the highlighted value corresponding to the
	      active node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hintbackground">
	  <term><literal>HintBackground</literal></term>
	  <listitem>
	    <para>
	      Background color of the hints shown when mouse
	      lingers over a node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hintforeground">
	  <term><literal>HintForeground</literal></term>
	  <listitem>
	    <para>
	      Text color of the hints shown when mouse 
	      lingers over a node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="toolbarhintbackground">
	  <term><literal>ToolbarHintBackground</literal></term>
	  <listitem>
	    <para>
	      Background color of the tool-tips shown when mouse
	      lingers over a tool-bar button or one of
	      several other widgets.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="toolbarhintforeground">
	  <term><literal>ToolbarHintForeground</literal></term>
	  <listitem>
	    <para>
	      Text color of the tool-tips shown when mouse 
	      lingers over a tool-bar button or one of
	      several other widgets.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="buttonsrelief">
	  <term><literal>ButtonsRelief</literal></term>
	  <listitem>
	    <para>
	      Style of the relief of the GUI buttons. 
	      Possible values for this option are:
	      raised, sunken, flat, ridge, solid, and groove.
	      Default is 'raised'.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="buttonsborder">
	  <term><literal>ButtonsBorder</literal></term>
	  <listitem>
	    <para>
	      Width of the borders of GUI buttons. Default is 2.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="menubarrelief">
	  <term><literal>MenubarRelief</literal></term>
	  <listitem>
	    <para>
	      Style of the relief of the GUI menu-bar. Same values as for
	      ButtonsRelief option are possible. Default is 'raised'.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="maxmenulines">
	  <term><literal>MaxMenuLines</literal></term>
	  <listitem>
	    <para>Maximal number of User-menu lines. If more lines in the menu
	      should appear, a submenu is created as a last item, in which the
	      menu continues.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="sortattributes">
	  <term><literal>SortAttributes</literal></term>
	  <listitem>
	    <para>If <literal>1</literal>, all lists where attribute names
	      are displayed are sorted
	      alphabetically (or according to the
	      <link linkend="sort_attrs_hook"><literal>sort_attrs_hook</literal></link>).
	      Otherwise the order of declaration in the particular PML schema or FS format
	      header is preserved.
	      Default value for this option is <literal>1</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="sortattributevalues">
	  <term><literal>SortAttributeValues</literal></term>
	  <listitem>
	    <para>If <literal>1</literal>, all lists where a choice of attribute values
	      is displayed are sorted
	      alphabetically (or according to the
	      <link linkend="sort_attrs_hook"><literal>sort_attr_values_hook</literal></link>).
	      Otherwise the order of declaration in the particular PML schema or FS format
	      is preserved.
	      Default value for this option is <literal>1</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<!--
	<varlistentry id="createmacromenu">
	  <term><literal>CreateMacroMenu</literal></term>
	  <listitem>
	    <para>
	      If this option is <literal>1</literal>, <application>TrEd</application> creates a special menu
	      <guimenu>Key-macros</guimenu> where all defined macros which are assigned
	      a key are presented also as menu functions.
	    </para>
	  </listitem>
	</varlistentry>
	-->
	<varlistentry id="strictmotif">
	  <term><literal>StrictMotif</literal></term>
	  <listitem>
	    <para>
	      If this option is <literal>1</literal>, strict motifish look and feel is
	      used in TrEd's GUI.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="iconpath">
	  <term><literal>IconPath</literal></term>
	  <listitem>
	    <para>
	      Colon-separated (on Windows comma-separated) 
	      list of paths for tred to look for icons.
	      Only XPM and PNG icons are supported
	      (it is not recommended to use
	      PNG icons on X11 with present versions of Tk804,
	      due to a severe bug causing occasional crashes).
	      Relative paths relate to 
	      <literal><replaceable>libDir</replaceable>/icons</literal>
	      directory.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="lastaction">
	  <term><literal>LastAction</literal></term>
	  <listitem>
	    <para>
	      This option, automatically updated on exit, contains an
	      URL and position of a last action on a tree.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="geometry">
	  <term><literal>Geometry</literal></term>
	  <listitem>
	    <para>
	      TrEd's main window geometry 
	      (<literal>HxW[+-]x[+-]y</literal>,
	      where <literal>H</literal> is window's height,
	      <literal>W</literal> is window's width,
	      <literal>x</literal> is window's horizontal
	      position from the left if positive and
	      from the right if negative, 
	      and <literal>y</literal>
	      is window's vertical
	      position from the top of the screen if positive and
	      from the bottom of the screen if negative).
	      This option is automatically updated every time
	      TrEd's main window is closed.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>Fonts</title>
      <variablelist>
	<varlistentry id="font">
	  <term><literal>Font</literal></term>
	  <listitem>
	    <para>
	      Font used to display the text of attributes and also in
	      several other places of GUI where the text of attributes is
	      displayed or edited. There are two possible formats of values
	      for this option:
	      <orderedlist continuation="restarts" inheritnum="ignore">
		<listitem><para>Font attribute-oriented format, which is a 
		    comma-separated list of pairs of the form
		    <literal>font-attribute:value</literal>. The attributes are:
		    <literal>family, size, weight, slant, underline,
		      overstrike</literal>. Family is a font-family name like
		    <literal>Arial, Helvetica</literal> or <literal>Times New Roman</literal>.
		    Size is a number providing the font-size in points
		    (i.e. not pixels!). Possible values for <literal>bold</literal>
		    are <literal>normal</literal> and <literal>bold</literal>, possible
		    values for <literal>slant</literal> are <literal>roman</literal> and
		    <literal>italics</literal>. The <literal>underline</literal> and 
		    <literal>overstrike</literal> attributes take just boolean
		    values of <literal>1</literal> and <literal>0</literal>.
		    If a font, that would match the specified attributes 	    
		    exactly, is not found, the most similar font is used.
		  </para>
		  <note>
		    <title>Example</title>		 
		    <literallayout class="normal" format="linespecific">Font = family:Arial,size:10,weight:bold</literallayout>
		  </note>
		</listitem>
		<listitem><para>On XFT enabled Tk/X11, it is also
		    possible to use font patterns as specified by the
		    <ulink url="http://freedesktop.org/software/fontconfig">fontconfig</ulink>
		    library. These font patterns take the form:
<literallayout format="linespecific" class="normal">&lt;families&gt;-&lt;point sizes&gt;:&lt;name1&gt;=&lt;values1&gt;:&lt;name2&gt;=&lt;values2&gt;...</literallayout>
	      Where <replaceable>names</replaceable> and 
	      <replaceable>values</replaceable>
	      refer to the folowing table:
		  </para>
		    <informaltable>
		      <tgroup cols="3">
			<thead>
			  <row>
			    <entry>Name of a property</entry>
			    <entry>Value type</entry>
			    <entry>Description</entry>
			  </row>
			</thead>
			<tbody>
			  <row><entry><literal>family</literal></entry><entry>String</entry><entry><para>Font family name</para></entry></row>
			  <row><entry><literal>style</literal></entry><entry>String</entry><entry><para>Font style. Overrides weight and slant</para></entry></row>
			  <row><entry><literal>slant</literal></entry><entry>Int</entry><entry><para>Italic, oblique or roman</para></entry></row>
			  <row><entry><literal>weight</literal></entry><entry>Int</entry><entry><para>Light, medium, demibold, bold or black</para></entry></row>
			  <row><entry><literal>size</literal></entry><entry>Double</entry><entry><para>Point size</para></entry></row>
			  <row><entry><literal>aspect</literal></entry><entry>Double</entry><entry><para>Stretches glyphs horizontally before hinting</para></entry></row>
			  <row><entry><literal>pixelsize</literal></entry><entry>Double</entry><entry><para>Pixel size</para></entry></row>
			  <row><entry><literal>spacing</literal></entry><entry>Int</entry><entry><para>Proportional, monospace or charcell</para></entry></row>
			  <row><entry><literal>foundry</literal></entry><entry>String</entry><entry><para>Font foundry name</para></entry></row>
			  <row><entry><literal>antialias</literal></entry><entry>Bool</entry><entry><para>Whether glyphs can be antialiased</para></entry></row>
			  <row><entry><literal>hinting</literal></entry><entry>Bool</entry><entry><para>Whether the rasterizer should use hinting</para></entry></row>
			  <row><entry><literal>verticallayout</literal></entry><entry>Bool</entry><entry><para>Use vertical layout</para></entry></row>
			  <row><entry><literal>autohint</literal></entry><entry>Bool</entry><entry><para>Use autohinter instead of normal hinter</para></entry></row>
			  <row><entry><literal>globaladvance</literal></entry><entry>Bool</entry><entry><para>Use font global advance data</para></entry></row>
			  <row><entry><literal>file</literal></entry><entry>String</entry><entry><para>The filename holding the font</para></entry></row>
			  <row><entry><literal>index</literal></entry><entry>Int</entry><entry><para>The index of the font within the file</para></entry></row>
			  <row><entry><literal>ftface</literal></entry><entry>FT_Face</entry><entry><para>Use the specified FreeType face object</para></entry></row>
			  <row><entry><literal>rasterizer</literal></entry><entry>String</entry><entry><para>Which rasterizer is in use</para></entry></row>
			  <row><entry><literal>outline</literal></entry><entry>Bool</entry><entry><para>Whether the glyphs are outlines</para></entry></row>
			  <row><entry><literal>scalable</literal></entry><entry>Bool</entry><entry><para>Whether glyphs can be scaled</para></entry></row>
			  <row><entry><literal>scale</literal></entry><entry>Double</entry><entry><para>Scale factor for point-&gt;pixel conversions</para></entry></row>
  <row><entry><literal>dpi</literal></entry><entry>Double</entry><entry><para>Target dots per inch</para></entry></row>
			  <row><entry><literal>rgba</literal></entry><entry>Int</entry><entry><para>unknown, rgb, bgr, vrgb, vbgr, none - subpixel geometry</para></entry></row>
			  <row><entry><literal>minspace</literal></entry><entry>Bool</entry><entry><para>Eliminate leading from line spacing</para></entry></row>
			  <row><entry><literal>charset</literal></entry><entry>CharSet</entry><entry><para>Unicode chars encoded by the font</para></entry></row>
			  <row><entry><literal>lang</literal></entry><entry>String</entry><entry><para>List of RFC-3066-style languages this font supports</para></entry></row>
			</tbody>

		      </tgroup>
		    </informaltable>
		  <note>
		    <title>Example</title>		 
		    <literallayout class="normal" format="linespecific">Font = {Lucida Grande}-12:bold:slant=italic:antialias=0</literallayout>
		  </note>	  
		</listitem>
		<listitem><para>OBSOLETE: Standard X font-spec, with possible wildcards, e.g.:
		<literal>-*-helvetica-medium-r-normal-*-12-*-*-*-*-*-iso8859-2</literal>
		</para></listitem>
	      </orderedlist>	
	    </para>
	  </listitem>
	</varlistentry>      
	<varlistentry id="vlinefont">
	  <term><literal>VLineFont</literal></term>
	  <listitem>
	    <para>
	      Font used for displaying the text in the value line above
	      tree. The same formats as for Font are allowed for this
	      option. If not specified, Font is used. 
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="guifont">
	  <term><literal>GUIFont</literal></term>
	  <listitem>
	    <para>
	      General font used in the GUI (buttons, menus, etc.)
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="guifont_small">
	  <term><literal>GUIFont_small</literal></term>
	  <listitem>
	    <para>
	      Small font used for small elements in the GUI (toolbar, annotation mode and stylesheet menu)
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="guifont_other">
	  <term><literal>GUIFont_<replaceable>type</replaceable></literal></term>
	  <listitem>
	    <para>
	      These options can be used to change other fonts used for formatted text in the GUI 
	      (e.g. in the extension manager
	      or stylesheet pattern help). Types are:
	      <simplelist type="horiz">
		<member>heading</member>
		<member>fixed</member>
		<member>default</member>
		<member>bold</member>
		<member>italic</member>
		<member>small_bold</member>
	      </simplelist>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>Printing options</title>
      <variablelist>
	<varlistentry id="defaultprintcommand">
	  <term><literal>DefaultPrintCommand</literal></term>
	  <listitem>
	    <para>
	      Command used to pass the resulting PostScript to
	      the print spool. Default value is <command>lpr</command>
	      in UNIX systems and <command>prfile32.exe /-</command>
	      on Windows (<literal>prfile32.exe</literal> is a
	      freeware Windows printing utility available at <ulink url="http://www.lerup.com/printfile/">http://www.lerup.com/printfile/</ulink>).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="ttfont">
	  <term><literal>TTFont</literal></term>
	  <listitem>
	    <para>
	      Name of the TrueType font to be used
	      when printing into Portable Document Format (PDF).
	      Defaults to <literal>Arial</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="ttfontpath">
	  <term><literal>TTFontPath</literal></term>
	  <listitem>
	    <para>
	      A comma-separated list of directories to look into
	      for TrueType fonts.
	      If this option is not explicitly
	      specified, TrEd uses directories listed in 
	      fontconfig library configuration file
	      <literal>/etc/fonts/fonts.conf</literal> on Unix
	      and Windows system font directory on Windows.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="psfontfile">
	  <term><literal>PsFontFile</literal></term>
	  <listitem>
	    <para>
	      A pfa-file with a Type1 PostScript font to be used for
	      PostScript or EPS generation.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="psfontafmfile">
	  <term><literal>PsFontAFMFile</literal></term>
	  <listitem>
	    <para>
	      An afm-file containing the Type1 font metrics to be used for
	      PostScript or EPS generation. It is not necessary to 
	      specify this option if the metrics file name
	      can be derived from the <link linkend="psfontfile"><literal>PsFontFile</literal></link>
	      by substitution the extension for <literal>.afm</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="printcolors">
	  <term><literal>PrintColors</literal></term>
	  <listitem>
	    <para>
	      If <literal>0</literal>, <application>TrEd</application> prints in black and white.
	      If <literal>1</literal>, <application>TrEd</application> uses the same colors for printing
	      as it does for displaying the tree on the screen.
	      This option may be overriden by the <guilabel>Use Colors</guilabel>
	      check-box in the <guilabel>Print</guilabel> dialog.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="psfontsize">
	  <term><literal>PsFontSize</literal></term>
	  <listitem>
	    <para>Size of the Postscript font to be substituted 
	      by the font given in PsFontFile in the final PosctScript.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="prtfmtwidth">
	  <term><literal>PrtFmtWidth</literal></term>
	  <listitem>
	    <para>
	      Width of the paper used for printing. Append one of the
	      characters <literal>i,c,m</literal> to the number to destinguish the
	      dimension (inches, centimeters, milimeters
	      respectively).
	      This option only applies if <link linkend="psmedia"><literal>PSMedia</literal></link>
	      is set to <literal>User</literal> (see below).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="prtfmtheight">
	  <term><literal>PrtFmtHeight</literal></term>
	  <listitem>
	    <para>Width of the paper used for printing. Same format as
	    PrtFmtWidth.
	      This option only applies if <link linkend="psmedia"><literal>PSMedia</literal></link>
	      is set to <literal>User</literal> (see below).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="psmedia">
	  <term><literal>PSMedia</literal></term>
	  <listitem>
	    <para>A PostScript or PDF document media-type used to
	      calculate page width and height. The default value is
	      <literal>A4</literal>. If this option is set to
	      <literal>BBox</literal>, then the generated page has the
	      dimensions of a minimal bounding box around the tree.
	      If this options set to <literal>User</literal>, then
	      the values of <literal>PrtFmtHeight</literal>
	      and <literal>PrtFmtWidth</literal> described above
	      are used. The supported media types beside
	      <literal>User</literal>
	      and <literal>BBox</literal> are:
	      <literal>Letter, LetterSmall, Legal, Statement, Tabloid, Ledger,
	Folio, Quarto, 7x9, 9x11, 9x12, 10x13, 10x14,
	Executive, A0, A1, A2, A3, A4, A4Small, A5, A6, A7, A8, A9,
	A10, B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10, ISOB0,
	ISOB1, ISOB2, ISOB3, ISOB4, ISOB5, ISOB6, ISOB7, ISOB8, ISOB9,
	ISOB10, C0, C1, C2, C3, C4, C5, C6, C7</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="psfile">
	  <term><literal>PSFile</literal></term>
	  <listitem>
	    <para>
	      The default name of the output file when printed to file.
	      This name may be modified in the <guilabel>Print</guilabel> dialog.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="maximizeprintsize">
	  <term><literal>MaximizePrintSize</literal></term>
	  <listitem>
	    <para>
	      If this option is on (i.e. <literal>1</literal>), <application>TrEd</application> tryes to draw the
	      tree as big as to fill the whole paper. Default is <literal>0</literal> here.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="prthmargin">
	  <term><literal>PrtHMargin</literal></term>
	  <listitem>
	    <para>
	      Specifies the default 
	      horizontal print margin. Default is <literal>2c</literal>
	      (c = centimeters).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="prtvmargin">
	  <term><literal>PrtVMargin</literal></term>
	  <listitem>
	    <para>
	      Specifies the default 
	      vertical print margin.
	      Default is <literal>3c</literal>
	      (c = centimeters).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="imagemagickconvert">
	  <term><literal>ImageMagickConvert</literal></term>
	  <listitem>
	    <para>
	      Path to ImageMagick's <command>convert</command> command
	      which is used to convert resulting EPS to various image
	      formats. The default value is <literal>convert</literal>
	      which means TrEd expects the command to be installed in
	      some directory in <varname>PATH</varname>.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>I/O related options</title>
      <variablelist>
	<varlistentry id="iobackends">
	  <term><literal>IOBackends</literal></term>
	  <listitem>
	    <para>This option can be used to provide additional
	      (user-defined) I/O backends (see <xref linkend="backends"/>). It consists of a comma separated
	      list of Perl module names implementing the
	      backends. <application>TrEd</application> will try to
	      open a file using the backends defined here before trying
	      any of default I/O backends.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="resourcepath">
	  <term><literal>ResourcePath</literal></term>
	  <listitem>
	    <para>This option can contain a (colon-separated on UNIX,
	      comma-separated on Windows) list of directories
	      where <application>TrEd</application>, its
	      I/O backends, and macros should look for additional resources
	      they might need (such as DTDs, XML/PML schemata, XSLT stylesheets, etc.). By default, this option is set to 
	      <literal>resources</literal> subdirectory of the
	      TrEd installation directory and
	      the subdirectory <literal>.tred.d</literal>
	      of the user's home directory.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="autosave">
	  <term><literal>AutoSave</literal></term>
	  <listitem>
	    <para>
	      Time interval in minutes in which TrEd creates
              auto-save file. AutoSave=0 disables auto-saving.
	      Defaults to 5.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="lockfiles">
	  <term><literal>LockFiles</literal></term>
	  <listitem>
	    <para>
	      When a file is open, TrEd creates
	      a lock file to prevent other TrEd instances
	      accessing the same file.
	      If set to 0, this option disables this behaviour.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="reloadpreservespatterns">
	  <term><literal>ReloadPreservesPatterns</literal></term>
	  <listitem>
	    <para>
	      This option may be set to 0 to force the Reload function
	      to use the file's attribute pattern setting rather than
	      preserving the current one.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="defaultfileencoding">
	  <term><literal>defaultFileEncoding</literal></term>
	  <listitem>
	    <para>
	      The encoding used for files opened in TrEd.
	      If TrEd runs on <literal>Perl 5.8</literal> or higher
	      with <literal>Tk804</literal> or higher with Unicode
	      support, arbitrary encoding supported by Perl can be
	      used. In all other cases, only 8-bit encodings are
	      supported and it is necessary to setup the display font
	      for correct displaying.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="defaultdisplayencoding">
	  <term><literal>defaultDisplayEncoding</literal></term>
	  <listitem>
	    <para>This option may be used in TrEd running on
	      non-unicode aware <literal>Perl</literal> and
	      <literal>Tk</literal> (see above) if the file encoding
	      differs from the encoding used by the display font. In
	      such case, TrEd supports conversions between
	      <literal>iso-8859-2</literal> and
	      <literal>windows-1250</literal> for Eastern European languages
	      and
	      <literal>iso-8859-6</literal> and
	      <literal>windows-1256</literal> for Arabic.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="openfilenamecommand">
	  <term><literal>OpenFileNameCommand</literal></term>
	  <listitem>
	    <para>This option may be used 
	      to provide a custom command for displaying Open File dialogs.
	      In the command specification,
	      <literal>%t</literal> is replaced with
	      the dialog title, 
	      <literal>%m</literal> with a list of file-types (patterns),
	      <literal>%t</literal> with the initial filename
	      (only for save dialogs, see the 
	      <link linkend="savefilenamecommand">SaveFileNameCommand</link>
	      option below), and
	      <literal>%d</literal> with the initial directory.
	      For example, setting this option to 
	      <literal>kdialog --title %t --getopenfilename %d %m</literal>
	      in a KDE 3.3.x environment makes TrEd use
	      the default KDE Open File dialog.
	      This option is unused by default.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="savefilenamecommand">
	  <term><literal>SaveFileNameCommand</literal></term>
	  <listitem>
	    <para>This option may be used 
	      to provide a custom command for displaying Save File dialogs.
	      See the <link linkend="openfilenamecommand">SaveFileNameCommand</link> option above
	      for more detail. For example, setting this option to 
	      <literal>kdialog --title %t --getopenfilename %d%f %m</literal>
	      in a KDE 3.3.x environment makes TrEd use
	      the default KDE Open File dialog.
	      This option is unused by default.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="sgmls">
	  <term><literal>sgmls</literal></term>
	  <listitem>
	    <para>This option may be used to point
	      <application>TrEd</application> to the
	      <command>nsgmls</command>
	      SGML parser.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="sgmlsopts">
	  <term><literal>SgmlsOpts</literal></term>
	  <listitem>
	    <para>
	      This option may be used to provide additional parameters
	      to the SGML parser declared in <link linkend="sgmls">Sgmls</link> option. By default,
	      this option is set to <literal>-i preserve.gen.entities</literal>.
	      These parameters forces James Clark's
	      <command>nsgmls</command> parser to include a part of
	      CSTS DTD where all global entities are re-declared in such a
	      way that they expand to themselves literally and thus
	      are preserved (as if no expansion was done).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="cstsparsercommand">
	  <term><literal>CstsParserCommand</literal></term>
	  <listitem>
	    <para>
	      This option may be used to customize the command used by
	      CSTS backend to invoke SGML parser. The default value is
	      <literal>%s %o %d %f</literal>. In this string,
	      the <literal>%s</literal> substring is replaced
	      with the value of <link linkend="sgmls"><literal>Sgmls</literal></link> option,
	      <literal>%o</literal> is replaced with the value of
	      <link linkend="sgmlsopts"><literal>SgmlsOpts</literal></link> option, 
	      <literal>%d</literal> is replaced with the value of
	      <link linkend="cstsdoctype"><literal>CSTSDoctype</literal></link> option, and
	      <literal>%f</literal> is replaced with the filename.
	      The only requirement is that this command returns
	      a valid representation of the CSTS file in <ulink url="http://xml.coverpages.org/WG8-n931a.html#n931-esis">ESIS</ulink>
	      format on standard output.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="cstsparserzcommand">
	  <term><literal>CstsParserZCommand</literal></term>
	  <listitem>
	    <para>
	      This option may be used to customize the command used by
	      CSTS backend to invoke SGML parser for files compressed
	      with GNU GZip. The default value is <literal>%z &lt; %f |
	      %s %o %d -</literal>.  In this string, the
	      <literal>%z</literal> substring is replaced with the
	      value of <link linkend="zcat"><literal>zcat</literal></link> option.  See <link linkend="cstsparsercommand"><literal>CstsParserCommand</literal></link>
	      for more.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="cstsdoctype">
	  <term><literal>CSTSDoctype</literal></term>
	  <listitem>
	    <para>
	      This option should point to a file containing CSTS
	      doctype declaration combining both the SGML subset
	      declaration as well as the CSTS DTD. This file
	      is included in the distribution of TrEd and is by default stored
	      in TrEd's library directory as
	      <filename>csts.doctype</filename>.
	      Setting this option overrides this default.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="gzip">
	  <term><literal>gzip</literal></term>
	  <listitem>
	    <para>This option may be used to point
	      <application>TrEd</application> to a
	      GNU <command>gzip</command>
	      command, which is used for transparent
	      saving files commpressed by GNU <command>gzip</command>.
	      The default value is <literal>/bin/gzip -c</literal>
	      if <filename>/bin/gzip</filename> exists and is
	      executable. Otherwise the value is undefined and
	      <application>TrEd</application> does not support
	      transparent saving GNU-zipped files.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="gzipopts">
	  <term><literal>gzipopts</literal></term>
	  <listitem>
	    <para>This option may provide additional
	      command-line arguments for the <command>gzip</command> command.
	    </para>
	  </listitem>	  
	</varlistentry>
	<varlistentry id="zcat">
	  <term><literal>zcat</literal></term>
	  <listitem>
	    <para>This option may be used to point
	      <application>TrEd</application> to a
	      GNU <command>zcat</command>	      
	      command, which is used for transparent opening
	      files commpressed by GNU <command>gzip</command>.
	      (These files are recognized by the
	      <filename>.gz</filename>
	      suffix.) The default value is <literal>/bin/zcat</literal>
	      if <filename>/bin/zcat</filename> exists and is
	      executable. Otherwise the value of
	      <literal>gzip</literal> option is used.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="zcatopts">
	  <term><literal>zcatopts</literal></term>
	  <listitem>
	    <para>This option may provide additional
	      command-line arguments for the <command>zcat</command> command.
	    </para>
	  </listitem>	  
	</varlistentry>
	<varlistentry id="ssh">
	  <term><literal>ssh</literal></term>
	  <listitem>
	    <para>This option can be used to point
	      <application>TrEd</application> to
	      <command>ssh</command> command,
	      which (depending on setup) may be used 
	      for transparent secure remote file-transfer.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="sshopts">
	  <term><literal>sshopts</literal></term>
	  <listitem>
	    <para>This option may provide additional
	      command-line arguments for the <command>ssh</command> command.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="curl">
	  <term><literal>curl</literal></term>
	  <listitem>
	    <para>This option can be used to point
	      <application>TrEd</application> to
	      the program <command>curl</command>,
	      which (depending on setup) may be used for transparent file-transfer over
	      ftp and http.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="curlopts">
	  <term><literal>curlopts</literal></term>
	  <listitem>
	    <para>This option may provide additional
	      command-line arguments for the <command>curl</command> command.
	    </para>
	  </listitem>
	</varlistentry>
	
	<varlistentry id="kioclient">
	  <term><literal>kioclient</literal></term>
	  <listitem>
	    <para>This option can be used to point
	      <application>TrEd</application> to
	      the program <command>kioclient</command>
	      (part of recent KDE distribution)
	      which (depending on setup) may be used for transparent file-transfer over
	      <literal>ftp://</literal>, <literal>http://</literal>,
	      <literal>fish://</literal> (ssh),
	      and various other protocols.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="kioclientopts">
	  <term><literal>kioclientopts</literal></term>
	  <listitem>
	    <para>This option may provide additional
	      command-line arguments for the <command>kioclient</command> command.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="nolockprotocols">
	  <term><literal>NoLockProtocols</literal></term>
	  <listitem>
	    <para>This option may provide <ulink url="regexps.html">regular expression</ulink>
	      matching protocols for which lock-files should never be
	      created. By default, its value is set to
	      <literal>^(https?|zip|tar)$</literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="rejectprotocols">
	  <term><literal>RejectProtocols</literal></term>
	  <listitem>
	    <para>This option may provide <ulink url="regexps.html">regular expression</ulink>
	      matching protocols from which <application>TrEd</application>
	      should never attempted to fetch files. .
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      
    </section>
    <section>
      <title>Miscelaneous options</title>
      <variablelist>
	<varlistentry id="htmlbrowser">
	  <term><literal>HTMLBrowser</literal></term>
	  <listitem>
	    <para>
	      Preferred HTML browser to open TrEd User's manual with
	      (autodetected by default).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="skipstartupversioncheck">
	  <term><literal>SkipStartupVersionCheck</literal></term>
	  <listitem>
	    <para>
	      If set to 1, TrEd will not test if it was upgraded since
	      last run and thus will not ask about managing extensions.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="extensionrepos">
	  <term><literal>ExtensionRepos</literal></term>
	  <listitem>
	    <para>
	      A list of URLs to TrEd Extension repositories separated by
	      spaces.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="extensionsdir">
	  <term><literal>ExtensionsDir</literal></term>
	  <listitem>
	    <para>
	      A directory where TrEd extensions are installed.
	      Defaults to <filename>$HOME/.tred/extensions</filename>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="preinstalledextensionsdir">
	  <term><literal>PreInstalledExtensionsDir</literal></term>
	  <listitem>
	    <para>
	      A directory where pre-installed (or shared) TrEd extensions are located.
	      The user cannot uninstall extensions installed in this directory 
	      but can override by installing the same extension to
	      the ExtensionsDir.
	    </para>
	    <para>
	      Defaults to <filename>$TREDDIR/tred-extensions</filename>
	      for TrEd installed to a directory and
	      <filename>$PREFIX/share/tred-extensions</filename>
	      for TrEd installed to a prefix.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="libdir">
	  <term><literal>LibDir</literal></term>
	  <listitem>
	    <para>
	      This option forces <application>TrEd</application> to search for its library
	      files in the specified directory.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="perllib">
	  <term><literal>PerlLib</literal></term>
	  <listitem>
	    <para>
	      This option may contain a colon-separated (on Windows
	      comma-separated) list of additional directories where Perl modules
	      are located (this has similar effect as setting the
	      environment variable <varname>PERLLIB</varname>).
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="macrofile">
	  <term><literal>MacroFile</literal></term>
	  <listitem>
	    <para>
	      Path to a file with macros for TrEd.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="defaultmacrofile">
	  <term><literal>DefaultMacroFile</literal></term>
	  <listitem>
	    <para>
	      Path to a file with the default set of macros for TrEd.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="maxundo">
	  <term><literal>MaxUndo</literal></term>
	  <listitem>
	    <para>
	      Maximum number of operations stored by Undo/Redo functions.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="noconvertwarning">
	  <term><literal>NoConvertWarning</literal></term>
	  <listitem>
	    <para>
	      When a ImageMagick printing extension is used
	      on Windows or with a black-listed version of ImageMagick,
	      a warning dialog pops-up. This option can be set to 1 to
	      disable this behaviour.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="reversenodeorder">
	  <term><literal>ReverseNodeOrder</literal></term>
	  <listitem>
	    <para>
	      Draw nodes (and value line values) in reverse order.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="uselocales">
	  <term><literal>UseLocales</literal></term>
	  <listitem>
	    <para>
	      If <literal>1</literal> is set here, 
	      <application>TrEd</application> 
	      uses locales. This is especially useful in macros 
	      e.g. for sorting. <literal>LC_CTYPE</literal> 
	      locale settings may also affect keyboard input and other
	      charset-related stuff in the GUI.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="useczechlocales">
	  <term><literal>UseCzechLocales</literal></term>
	  <listitem>
	    <para>
	      If <literal>1</literal> is set here,
	      <application>TrEd</application> uses
	      Czech (cs_CZ) locales. This option is present for rather
	      historical reasons.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="displaynonasciilefttoright">
	  <term><literal>displayNonAsciiLeftToRight</literal></term>
	  <listitem>
	    <para>
	      This option adds a poor-man's bidi-support.
	      It reverses all non ASCII-strings before displaying.
	      This option is not intended for Arabic, since
	      TrEd already contains better arab-remixing
	      algorigthms contributed by Ota Smrz.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="defaultmacroencoding">
	  <term><literal>defaultMacroEncoding</literal></term>
	  <listitem>
	    <para>
	      The default encoding used when parsing TrEd macros.
	      This option only takes effect for
	      <literal>Perl 5.8</literal> or higher.
	      Default macro encoding can be overriden
	      in the macro itself as described in 
	      <xref linkend="macroencodings"/>. Defaults to UTF-8.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry id="displaystatusline">
	  <term><literal>displayStatusLine</literal></term>
	  <listitem>
	    <para>
	      Turn on/off displaying status line. Default is on.
	      Currently, status line content can only be controlled
	      from macros, via <link linkend="get_status_line_hook"><literal>get_status_line_hook</literal></link>.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
    <section>
      <title>Debugging options</title>
      <variablelist>
	<varlistentry id="backenddebug">
	  <term><literal>backenddebug</literal></term>
	  <listitem>
	    <para>Print debugging information for I/O backends.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="hookdebug">
	  <term><literal>hookdebug</literal></term>
	  <listitem>
	    <para>Print debugging information when hooks are called.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="keyboarddebug">
	  <term><literal>keyboarddebug</literal></term>
	  <listitem>
	    <para>Print debugging on keyboard events.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="macrodebug">
	  <term><literal>macrodebug</literal></term>
	  <listitem>
	    <para>Print debugging when macros are invoked.</para>
	  </listitem>
	</varlistentry>
	<varlistentry id="treddebug">
	  <term><literal>treddebug</literal></term>
	  <listitem>
	    <para>Print various debugging information not covered
	      by the debugging options listed above.</para>
	  </listitem>
	</varlistentry>
      </variablelist>
    </section>
  </section>
  <section id="commandline">
    <title>Command-line options</title>
    <section>
      <title>Synopsis</title>
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tred_cmd.xml" xpointer="xpointer(/article/section/title[.='SYNOPSIS']/following-sibling::*)"/>
    </section>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tred_cmd.xml" xpointer="xpointer(/article/section/section[title='Filename arguments'])"/>
    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tred_cmd.xml" xpointer="xpointer(/article/section/section[title='Options'])"/>
<!--
    <para>
      The general usage is as follows:
      <cmdsynopsis sepchar=" ">
	<command>tred</command>
	<arg rep="norepeat" choice="opt">-q</arg>
	<group choice="opt">
	  <arg rep="norepeat" choice="plain">-R</arg>
	  <arg rep="norepeat" choice="plain">-X
	    <replaceable>gov</replaceable>,<replaceable>ord</replaceable></arg>
	</group>
	<arg rep="norepeat" choice="opt">-G</arg>
	<arg rep="norepeat" choice="opt">-Y</arg>
	<arg rep="norepeat" choice="opt">-H</arg>
	<arg rep="norepeat" choice="opt">-c <replaceable>config-file</replaceable></arg>
	<arg rep="norepeat" choice="opt">-m <replaceable>macro-file</replaceable></arg>
	<arg rep="norepeat" choice="opt">-t <replaceable>context</replaceable></arg>
	<arg rep="norepeat" choice="opt">-s <replaceable>stylesheet</replaceable></arg>
	<arg rep="norepeat" choice="opt">-n <replaceable>FS-file-encoding</replaceable></arg>
	<arg rep="norepeat" choice="opt">-p <replaceable>number-of-views</replaceable></arg>
	<arg rep="norepeat" choice="opt">-B <replaceable>backends</replaceable></arg>
	<arg rep="norepeat" choice="opt">-l <replaceable>file list</replaceable></arg>
	<arg rep="norepeat" choice="opt">-W <replaceable>window-id</replaceable></arg>
	<group rep="repeat">
	  <arg choice="plain"><replaceable>file</replaceable></arg>
	  <arg choice="plain"><replaceable>file</replaceable>##<replaceable>N</replaceable></arg>
	  <arg choice="plain"><replaceable>file</replaceable>##<replaceable>N</replaceable>.<replaceable>M</replaceable></arg>
	</group>
      </cmdsynopsis>
      or
      <cmdsynopsis sepchar=" ">
	<command>tred</command>
	<group choice="opt" rep="norepeat">
	  <arg choice="plain" rep="norepeat">-u</arg>
	  <arg choice="plain" rep="norepeat">-h</arg>
	</group>
      </cmdsynopsis>
      to obtain short instructions on usage (<parameter>-u</parameter>)
      or a brief help (<parameter>-h</parameter>).
    </para>
    <para>
      The optional command-line parameters have the following meaning:
    </para>
    <variablelist>
      <varlistentry>
	<term><parameter>-m</parameter></term>
	<listitem>
	  <para>This parameter may be used to force <application>TrEd</application> to use a different 
	    macro file from that given in TrEd's configuration file.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-c</parameter></term>
	<listitem>
	  <para>This parameter may be used to force <application>TrEd</application> to use 
	    a certain configuration file.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-t</parameter></term>
	<listitem>
	  <para>Prefer the given annotation mode as the initial annotation mode
	    for every opened file.
	    This annotation mode may however be overriden by some hooks such as
	    <literal>start_hook</literal>
	    or <literal>file_opened_hook</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-s</parameter></term>
	<listitem>
	  <para>Use given stylesheet as the initial stylesheet for
	    every view.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-n</parameter></term>
	<listitem>
	  <para>Allows to specify character encoding for the
	    <literal>FS</literal> backend (unlike e.g. XML
	    files, FS files provide no means to 
	    determine their character encoding).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-p</parameter></term>
	<listitem>
	  <para>A positive (or negative) integer value specifying the initial
	    number of vertical (or horizontal) views. If this option is 
	    used, TrEd automatically splits the window into that many views
	    and displays the <replaceable>n</replaceable>'th file on the command-line in the
	    <replaceable>n</replaceable>'th view (for
	    <replaceable>n</replaceable> up to the number of views).
	    If no files were specified on the command-line, but
	    <parameter>-l</parameter> was used, then
	    <replaceable>n</replaceable>'th view is associated with
	    <replaceable>n</replaceable>'th file list specified in <parameter>-l</parameter>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-l</parameter></term>
	<listitem>
	  <para>This parameter may contain a comma-separated
	    list of files each containing one or more file-names
	    (one per line). TrEd reads these files and 
	    creates file lists
	    named <literal>CmdLine-1</literal>,
	    <literal>CmdLine-2</literal>, etc. correspondingly.
	    Note that you may use <literal>-</literal>
	    notation for the standard input, e.g. if
	    called with <literal><command>tred</command> -l-</literal>,
	    <application>TrEd</application> will
	    expect file-names for <literal>CmdLine-1</literal>
	    on the standard input.
	    See also <xref linkend="filelists"/>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-q</parameter></term>
	<listitem>
	  <para>Request quiet operation, with as little
	    output from tred, as possible.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-W</parameter></term>
	<listitem>
	  <para>Under X Window System, embed TrEd's main window into 
	    the window with given <replaceable>window-id</replaceable>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-B</parameter></term>
	<listitem>
	  <para>Comma separated list of additional 
	    I/O <replaceable>backends</replaceable> to
	    import.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-G</parameter></term>
	<listitem>
	  <para>Do not resize TrEd's main window to its last saved
	    geomtery on startup (this option is useful when using
	    <parameter>-W</parameter> to embed TrEd into other
	    applications).</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-Y</parameter></term>
	<listitem>
	  <para>Do not pre-load so called secondary files,
	    i.e. files with additional trees requested by main files (i.e. the
	    files opened by the user). This doesn't apply to
	    external resources loaded directly by I/O backends.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-R</parameter></term>
	<listitem>
	  <para>
	    This option is specific to the CSTS backend.
	    When parsing CSTS files, try to restore structure from
	    <literal>&lt;TRg&gt;</literal> tags rather than from
	    <literal>&lt;g&gt;</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-X <replaceable>gov</replaceable>,<replaceable>ord</replaceable></parameter></term>
	<listitem>
	  <para>
	    This option is specific to the CSTS backend.
	    When parsing CSTS files, try to restore structure from tags
	    <literal>&lt;<replaceable>gov</replaceable>&gt;</literal> and
	    <literal
	     >&lt;<replaceable>ord</replaceable>&gt;</literal>
	    rather then from
	    <literal>&lt;<replaceable>g</replaceable>&gt;</literal> and
	    <literal
	     >&lt;<replaceable>r</replaceable>&gt;</literal>.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-h</parameter></term>
	<listitem>
	  <para>Prints a brief help and exits.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-u</parameter></term>
	<listitem>
	  <para>Prints a short help on usage and exits.</para>
	</listitem>
      </varlistentry>
    </variablelist>
    <para>
      All other arguments passed to <application>TrEd</application> on the command line
      are treated as file-names. 
      Unless <parameter>-p</parameter> was used,
      <application>TrEd</application> opens the first of the
      files and the user may navigate to the next file and back
      using the <menuchoice>
	<guimenu>File</guimenu>
	<guimenuitem>Next File</guimenuitem>
      </menuchoice> and
      <menuchoice>
	<guimenu>File</guimenu>
	<guimenuitem>Previous File</guimenuitem></menuchoice> menu commands.)
    </para>
    <para>
      Every file-name either on the command-line or in a file list
      may be followed by a suffix specifying a particular tree or node in
      the file. This node is activated when <application>TrEd</application>
      opens the file (if no suffix is given then the root node of the first
      tree in the file is activated). <application>TrEd</application>
      recognizes the following suffix forms:
    </para>
    <variablelist>
      <varlistentry>
	<term><literal>##<replaceable>N</replaceable></literal></term>
	<listitem>
	  <para>
	    where <replaceable>N</replaceable> is a positive integer number.
	    This suffix specifies the root of the <replaceable>N</replaceable>'th
	    tree in the file.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><literal>##<replaceable>N</replaceable>.<replaceable>M</replaceable></literal></term>
	<listitem>
	  <para>
	    where <replaceable>N</replaceable> is a positive integer number
	    and <replaceable>M</replaceable> is a non-negative integer number.
	    This suffix specifies the <replaceable>M</replaceable>'th
	    node of the <replaceable>N</replaceable>'th
	    tree in the file. The ordering of nodes 
	    <replaceable>M</replaceable> refers to is
	    the ordering of the deep-first traversal.
	  </para>
	</listitem>
      </varlistentry>
    </variablelist>
-->
  </section>
  <section id="macros">
    <title>User Macros</title>
    <para>
      This section describes in detail
      <application>TrEd</application>'s support for user macros
      and is dedicated mainly to programmers.
    </para>
    <para>
      As was already mentioned, <application>TrEd</application> is
      itself written in Perl and therefore it is natural that also
      user macros are written in the Perl language. The details of the
      Perl language syntax are not described here. You may find
      them in various literature on programming in Perl as well as in
      manual pages of Perl language. A large volume of documentation
      on Perl and many specific Perl modules is collected for example
      by <ulink url="http://www.activestate.com/ASPN/Reference">ActiveState</ulink>.
      In this text, we concentrate on the 
      <application>TrEd</application>'s macro
      specifics only.
    </para>
    <section>
      <title>A Macro</title>
      <para>
	A macro for <application>TrEd</application> is simply a Perl
	routine defined using the <literal>sub
	  <replaceable>name</replaceable> { ... }</literal>
	construct, e.g.:
      </para>
      <programlisting format="linespecific">sub my_first_macro {
 print "Hallo World\n";
}</programlisting>
      <para>
	Macros may be called from other macros in the same way as
	any other sub-routines in Perl, for example:
      </para>
      <programlisting format="linespecific">sub my_first_macro {
	my_second_macro();  # call to another macro
}</programlisting>
      <para>
	In this case, macros may use the usual Perl mechanisms
	to pass any number of argumens to the called macro.
      </para>
      <para>
	To make the macro accessible from
	<application>TrEd</application>, two more things should be
	done. First, a special <quote>binding directive</quote> can be added,
	so that the macro is associated with a keyboard shortcut
	and/or
	added to the list of named macros and filed under
	the <guimenu>Macros</guimenu> menu under a short descriptive name, where users can easily find and invoke it.
	Second, the macro
	must be stored in some file and
	<application>TrEd</application>
	must be told where to look for the file. This (and more) is
	discussed in the following sections.
      </para>      
    </section>
    <section>
      <title>Macro files</title>
      <para>
	On startup, <application>TrEd</application>
	looks for two files with macros.
	<orderedlist continuation="restarts" inheritnum="ignore">
	  <listitem>
	    <para>The default set of macros (described in more detail
	      in <xref linkend="defaultmacros"/>)
	      <filename>tred.def</filename>
	    </para>
	  </listitem>
	  <listitem>
	    <para>The set of extension macros <filename>tred.mac</filename>
	      or any other file given after the
	      <parameter>-m</parameter> parameter on the command line 
	      or a file specified in the
	      <application>TrEd</application>'s configuration
	      option <literal>MacroFile</literal>.	      
	    </para>
	  </listitem>
	</orderedlist>
	Developers of macros should never modify the
	<filename>tred.def</filename> file directly.
	In theory, 
	the file <filename>tred.mac</filename> can be modified when
	preparing a customized installation of TrEd, but it is seldom needed.
	In fact, in the current development model, the file <filename>tred.mac</filename>
	plays the role of a testing ground for macros that are supposed to eventually make it into 
	<filename>tred.def</filename> but whose API is not yet guaranteed to remain unchanged.
	It also creates initial keyboard and menu bindings for the <literal>TredMacro</literal> annotation
	mode (see <xref linkend="contexts"/>).
      </para>
      <para>
	Instead, the developers of macros are encouraged either to place
	their macros into an 
	<link linkend="extension_packages">extension package</link>,
	or to create a subfolder with a <filename>contrib.mac</filename> file
	in <filename>tredlib/contrib/</filename>, e.g. <filename><replaceable>tredlib/contrib/subdir_name</replaceable>/contrib.mac</filename>, which will be automatically included into <filename>tred.mac</filename>
	(the standard version of <filename>tred.mac</filename>
	includes the file <filename>tredlib/contrib/contrib.mac</filename>
	which in turn does a wildcard include of <filename>*/contrib.mac</filename>,
	as described below).
      </para>
      <para>
	One Macro file may be included into other macro file
	using one of the following
	<literal>#include</literal> directives where
	<replaceable>filename</replaceable> is supposed to provide
	a relative or absolute path to the macro file, under the
	terms described below:
      </para>
      <variablelist>
	<varlistentry>
	  <term><literal>#include "<replaceable>filename</replaceable>"</literal></term>
	  <listitem>
	    <para>The <replaceable>filename</replaceable> must be
	      relative to the directory of the file to which it is
	      included.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>#include &lt;<replaceable>filename</replaceable>&gt;</literal></term>
	  <listitem>
	    <para>The <replaceable>filename</replaceable> must
	      be relative to the TrEd's library directory.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>#include "&lt;<replaceable>wildcard</replaceable>&gt;"</literal></term>
	  <listitem>
	    <para>Expands <replaceable>wildcard</replaceable> 
	      relatively to the directory of the file containing the
	      directive and includes all matching file.</para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>#include <replaceable>filename</replaceable></literal></term>
	  <listitem>
	    <para>
	      The <replaceable>filename</replaceable> may be
	      both absolute or relative. In the latter case the directories are
	      searched in the following order:
	      <orderedlist continuation="restarts" inheritnum="ignore">
		<listitem>
		  <para>Current directory is searched.</para>
		</listitem>
		<listitem>
		  <para>The directory of the file where the
		    <literal>#include</literal> directive occured
		    is searched.
		  </para>
		</listitem>
		<listitem>
		  <para><application>TrEd</application>'s library directory
		    is searched.
		  </para>
		</listitem>
	      </orderedlist>
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>
	If <literal>#include</literal> fails to find given file,
	it is a fatal error and
	<application>TrEd</application>/<application>bTrEd</application>
	immediatelly stops. You may use
	<literal>#ifinclude</literal> directive, if you wish
	<literal>TrEd</literal> to continue (without error or warning)
	even if the requested file was not found.
      </para>
    </section>
    <section id="macroencodings">
      <title>Using various character encodings</title>
      <note>
	<para>This section applies only to <application>TrEd</application>/<application>bTrEd</application> running under Perl 5.8
	and higher.</para>
      </note>
      <para>
	If non-ASCII characters should occur in macro code, it is
	necessary to indicate the character encoding used.  Otherwise
	<application>TrEd</application> wouldn't be able to translate the non-ASCII characters
	into an internal Unicode representation.  Failing to indicate
	encoding used in macro code can therefore lead to unexpected
	behaviour of the code and/or fatal run-time errors.
      </para>
      <para>
	By default, <application>TrEd</application> 
	expects UTF-8 encoded macro code (unless specified
	otherwise using the <link linkend="defaultmacroencoding">
	  <literal>defaultMacroEncoding</literal> configuration option</link>).
	Any other character encoding must be indicated using
	<literal>#encoding</literal> directive, followed by name of
	the encoding, such as <literal>utf-8</literal>,
	<literal>iso-8859-1</literal>, <literal>windows-1256</literal>,
	etc. The encoding indicated by an <literal>#encoding</literal>
	directive applies on the macro file strating from the line following the directive
	to the end of the file or to another <literal>#encoding</literal>
	directive occurence, whichever happens first. Encoding directive does not
	apply to included macro files.
      </para>
      <example>
	<title>Indicating macro character encoding</title>
	<programlisting format="linespecific">
  (UTF-8 encoded macro code)

#encoding iso-8859-2
  
  (latin-2 encoded macro code)

#encoding utf-8

  (UTF-8 encoded macro code continues)
	</programlisting>
      </example>
    </section>
    <section>
      <title>Conditional macro code</title>
      <para>
	If macro code is spanned across	several files or is shared
	between <application>TrEd</application> and
	<application>bTrEd</application>, it may be useful
	to make some parts of the macro code (such as an
	<literal>#include</literal> directive) conditional.
      </para>
      <para>
	For this purpose <application>TrEd</application>,
	provides similar mechanisms as standard <literal>C</literal>
	pre-processors using
	<literal>#define</literal>,
	<literal>#undefine</literal>,
	<literal>#ifdef</literal>,
	<literal>#ifndef</literal>, and
	<literal>#endif</literal> directives.
	These directives must appear on the very beginning of line.
	Any code enclosed within
	<literallayout class="normal" format="linespecific">#ifdef	<replaceable>symbol-name</replaceable></literallayout> 
	and <literallayout class="normal" format="linespecific">#endif</literallayout> directives
	is included if and only if
	the symbol <literal><replaceable>symbol-name</replaceable></literal>
	was previously defined using a <literal>#define
	<replaceable>symbol-name</replaceable></literal>
	directive. 
	Any code enclosed within
	<literallayout class="normal" format="linespecific">#ifndef <replaceable>symbol-name</replaceable></literallayout> 
	and <literallayout class="normal" format="linespecific">#endif</literallayout> directives
	is included if and only if
	the symbol <literal><replaceable>symbol-name</replaceable></literal>
	is not defined.
	A defined
	symbol can later be undefined 
	with <literal>#undefine
	<replaceable>symbol-name</replaceable></literal>.
	Unlike <literal>C</literal> macros,
	symbols in <application>TrEd</application> have no other
	purpose than this.
      </para>
      <para>
	Except for symbols defined by a <literal>#define</literal>
	directive, symbol <literal>TRED</literal> is always initially
	defined in <application>TrEd</application>, symbol
	<literal>BTRED</literal> is always initially defined in
	<application>bTrEd</application>. This may help to simplify
	sharing macro code with specific parts for
	<application>TrEd</application> and
	<application>bTrEd</application> between these two
	applications.
      </para>
    </section>
    <section id="bindings">
      <title>Associating macros with menu entries and keyboard shortcuts</title>
      <para>
	The last set of directives is used to 
	associate a macro with a keyboard shortcut
	and to add it to the list of macros and 
	and the <guimenu>Macros</guimenu> menu under a short descriptive name, so that the user can easily find and invoke it.
      </para>
      <para>
	To connect a macro named <literal>my_first_macro</literal> with a 
	new entries labeled <guimenuitem>My First
	Macro</guimenuitem>
	in the
	<menuchoice>
	  <guisubmenu>Macros</guisubmenu>
	  <guimenuitem>List of Macros...</guimenuitem>
	</menuchoice>
	dialog and also in the menu 
	<menuchoice>
	  <guisubmenu>Macros</guisubmenu>
	  <guisubmenu>All Modes</guisubmenu>
	  <guimenuitem><replaceable>mode</replaceable></guimenuitem>
	</menuchoice>,
	the following directive should appear in some macro
	file read by <application>TrEd</application>:
      </para>
      <literallayout class="normal" format="linespecific">#insert <replaceable>my_first_macro</replaceable> as menu <replaceable>My First Macro</replaceable></literallayout>
      <para>
	Actually the words <literal>as</literal> and
	<literal>menu</literal> may be omitted, so it is
	possible to write the above directive also as:
      </para>
      <literallayout class="normal" format="linespecific">#insert <replaceable>my_first_macro</replaceable> as <replaceable>My First Macro</replaceable></literallayout>
      <para>or even</para>
      <literallayout class="normal" format="linespecific">#insert <replaceable>my_first_macro</replaceable> <replaceable>My First Macro</replaceable></literallayout>
      <para>
	Association between a macro and a keyboard shortcut is defined
	using the directive <literal>#bind</literal>.
	For example, to <quote>bind</quote> a macro named
	<literal>my_first_macro</literal> to say
	<keycombo action="simul">
	  <keycap>Ctrl</keycap>
	  <keycap>Alt</keycap>
	  <keycap>Del</keycap>
	</keycombo>
	keyboard shortcut, the following line should appear somewhere
	in the macro file:
      </para>
      <literallayout class="normal" format="linespecific">#bind <replaceable>my_first_macro</replaceable> to key <replaceable>Ctrl+Alt+Del</replaceable></literallayout>
      <para>
	Again, the <literal>to</literal> and
	<literal>key</literal> keywords may be omitted.	
      </para>
      <warning>
	<para>
	  Using the particular shortcut chosen here as a funny example
	  is a silly idea indeed, since this very shortcut is typicaly
	  used to restart the system. Remember that only shortcuts
	  that are not interpreted by the operating system or the
	  desktop environment can possibly work as expected.
	</para>
      </warning>
      <para>Both a menu item and a keyboard shortcut can be associated
	with a macro in one step with a directive of the following :
      </para>
      <literallayout class="normal" format="linespecific">#bind <replaceable>my_first_macro</replaceable> to key <replaceable>Ctrl+Alt+Del</replaceable> menu <replaceable>My First Macro</replaceable></literallayout>
      <para>
	If more than one keyboard shortcut or menu item are associated
	with the same macro, any of them may be used to invoke the
	macro. If more than one macro was associated with the same
	keyboard shortcut, then the latest binding is used.  Also, if
	two or more macros with the same name appear in the loaded
	macro files (within the same package), the last one is used,
	but that holds in general for any Perl subroutine.
      </para>
      <literallayout class="normal" format="linespecific">#unbind-key <replaceable>Ctrl+Alt+Del</replaceable></literallayout>
      <literallayout class="normal" format="linespecific">#remove-menu <replaceable>My First Macro</replaceable></literallayout>
      <para>
	The first of the  directives above removes an existing key-bindning from
	current annotation mode(s). The second one removes an existing menu entry
	from the macro menu
	of the current annotation mode (<menuchoice>
	  <guisubmenu>Macros</guisubmenu>
	  <guisubmenu>All Modes</guisubmenu>
	  <guimenuitem><replaceable>annotation mode</replaceable></guimenuitem>
	</menuchoice>).
	These directives is especially useful for disabling certain functionality and bindings of an incuded
	macro file.
      </para>
    </section>
    <section>
      <title>When macro ends</title>
      <para>
	When an interactively invoked macro returns, <application>TrEd</application> performs the following
	steps:
	<itemizedlist>
	  <listitem>
	    <para>the node referenced in <literal>$this</literal>
	      is activated in the current view (provided it belongs to
	      the current tree)
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      all views are redrawn (unless specified otherwise in the
	      variable<literal>$Redraw</literal>), see
	      below.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      unless the value of the variable <literal>$FileChanged</literal> (see <xref linkend="defaultmacros"/>) is set to 0,
	      the save-status of the current file is turned to <literal>modified</literal>
	      (as indicated by the state of the
		<inlinemediaobject><imageobject><imagedata fileref="pics/filesave.png" format="PNG" role="html"/></imageobject><imageobject><imagedata fileref="pics/filesave.eps" format="EPS" role="latex"/></imageobject><imageobject><imagedata fileref="pics/filesave" format="linespecific"/></imageobject><textobject><phrase>save-file</phrase></textobject></inlinemediaobject>
		button). 
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
      <para>
	The variable <literal>$Redraw</literal> may have the following
	values:
	<variablelist>
	  <varlistentry>
	    <term><literal>file</literal> (the default)</term>
	    <listitem>
	      <para>redraw all windows displaying current file</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><literal>tree</literal></term>
	    <listitem>
	      <para>redraw all windows displaying current tree</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><literal>win</literal></term>
	    <listitem>
	      <para>redraw current window</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><literal>all</literal></term>
	    <listitem>
	      <para>redraw all windows</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><literal>tie</literal></term>
	    <listitem>
	      <para>redraw all windows if TrEd windows are tied
		otherwise redraw only the current one</para>
	    </listitem>
	  </varlistentry>
	  <varlistentry>
	    <term><literal>none</literal></term>
	    <listitem>
	      <para>disables redrawing</para></listitem>
	  </varlistentry>
	</variablelist>
      </para>
      <para>
	Because <application>TrEd</application> has no way to identify
	whether the current file (or in fact any other file) was
	actually modified by the macro, it always assumes it was.  To
	prevent this and indicate that no actual changes which would
	require the user to save the file were done to the current
	file, the macro must explicitly set a special variable named
	<literal>$FileChanged</literal> to zero.  Even
	better (to prevent accidental collisions between several
	assignments to this variable), instead of directly assigning
	to this variable, call the default macro
	<literal>ChangingFile(0)</literal>.
      </para>
      <para>
	To make things more complicated, it should be noted, that
	<command>btred</command>, the off-line variant of
	TrEd, never saves any processed file unless the variable
	<literal>$FileChanged</literal> has been explicitely set to
	<literal>1</literal> or <literal>-S</literal> command-line
	switch is used. So, conversely, in <command>btred</command>, a macro
	should indicate making a change worth saving by calling <literal>ChangingFile(1)</literal>.
      </para>
      <note>
	<para>If the state of the file was already
	  <emphasis>modified and not saved</emphasis> when a
	  macro was interactively invoked, then any changes to
	  the <literal>$FileChanged</literal> variable made
	  by the macro are ignored. Macro may however force the
	  file status to return to <emphasis>saved</emphasis>
	  by setting the variable <literal>$forceFileSaved</literal>
	  to <literal>1</literal> (typically after an
	  explicit call to <literal>Save()</literal>).
	</para>
      </note>
      <note>
	<para>For historical reasons, there exists an alias for
	  <literal>$FileChanged</literal> named
	  <literal>$FileNotSaved</literal>. These variables are
	  identical.
	</para>
      </note>
    </section>
    <section>
      <title>Accessing tree nodes</title> 
      <para>A tree in <application>TrEd</application> is represented by its root node.
      The root node can be distinguished from other nodes by having no parent node.
      Similarly leaf nodes have no children (see <literal>firstson()</literal> method described bellow).
      </para>
      <para>All tree nodes in
      <application>TrEd</application> are represented
      by <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> Perl objects. These objects are
      basically only hash references where the
      attribute-name/attribute-value information is stored as a
      key/value pair (except that some hash keys are reserved for
      representing the tree structure).  
      <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> objects provide several basic
      methods, most of which are related to accessing their neighbouring nodes
      (i.e. traversing the tree) and modifying the tree structure
      by means of cut and paste operations.
      </para>
      <para>Macros usually start from the nodes accessible via
	global variables (these variables are declared in the <literal>TredMacro</literal>
	package, but exported by default to any other derived package):
      </para>
      <variablelist>
	<varlistentry>
	  <term><literal>$this</literal></term>
	  <listitem>
	    <para>is the active node in the current tree.
	      Macros may use this variable to access the active node,
	      its attributes, methods etc. They also may assign
	      to this variable to activate a different node.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal>$root</literal></term>
	  <listitem>
	    <para>is the root of the current tree.  Macros may use
	      this variable to access the root of the tree and (by
	      following the tree edges) to access the whole tree.
	      Assigning to this variable has no visible effect.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <section>
	<title>Node types</title>
	<para>
	  Each node may be associated with a PML type
	  (see also <xref linkend="pml_representation"/>)
	  dictating e.g. which the attributes the node may or must carry
	  and for each attribute its data type.
	</para>
	<note>
	  <para>
	    Some older I/O backends do not provide PML-based typing
	    and produce nodes that are untyped.
	    In such a case, the names, types, and roles of the attributes
	    can be
	    obtained from the
	    <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> object
	    associated with the document (see below).
	  </para>
	</note>
	<para>
	  The object representation of the data type of a node is returned
	  by the method <literal>$node->type()</literal>
	  (see <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink>).
	  It may be either from the class
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema/Struct.pm"><classname>Treex::PML::Schema::Struct</classname></ulink>
	  (or derived)
	  if the node is represented in PML by a structure
	  or
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema/Container.pm"><classname>Treex::PML::Schema::Container</classname></ulink>
	  (or derived)
	  if the node is represented in PML by a container.
	  To get the object representation of the complete PML schema
	  where the node type is declared
	  (<ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema.pm"><classname>Treex::PML::Schema</classname></ulink>), one 
	  may call <literal>$node->type()->schema()</literal>,
	  provided <literal>$node->type()</literal> is known to be defined.
	</para>
      </section>
      <section>
	<title>Accessing node attributes</title>
	<para>
	  Let <literal>$node</literal> be a
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> object, i.e. a node of the
	  tree. Typically, nodes are attribute-value structures, so the
	  attribute named <literal><replaceable>attrib</replaceable></literal>
	  is accessible as <literal>$node-&gt;{<replaceable>attrib</replaceable>}</literal>.
	  Assigning a different value, say <replaceable>$val</replaceable>, to the attribute
	  <literal><replaceable>attrib</replaceable></literal> is
	  as simple as this:
	</para>
	<literallayout class="normal" format="linespecific">$node-&gt;{<replaceable>attrib</replaceable>}=$val;</literallayout>
	<para>
	  Attribute values may not always be atomic, i.e. numbers or
	  strings (although for most backends this is the case). They
	  may also be AVS structures (represented as
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Struct.pm"><classname>Treex::PML::Struct</classname></ulink> objects, which are
	  basically just Perl hashes), lists (represented as Perl ARRAY
	  references of the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm"><classname>Treex::PML::List</classname></ulink> class)
	  and alternatives (represented as Perl ARRAY references of
	  the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm"><classname>Treex::PML::List</classname></ulink> class). So let's
	  suppose for a while, that the value of <literal>$node-&gt;{<replaceable>attrib</replaceable>}</literal>
	  is an AVS structure with attribute
	  <replaceable>level2-attrib</replaceable> and its value is a
	  list of structures with an attribute
	  <replaceable>level3-attrib</replaceable> whose value (of
	  whatever type it is) we want to get and possibly change.  To
	  access the attribute
	  <replaceable>level3-attrib</replaceable>, we may either use
	  Perl-only syntax and proceed e.g. as follows:
	  <literallayout>$node-&gt;{attrib}{level2-attrib}[0]{level3-attrib}</literallayout>
	  Notice, that from the list of structures in
	  <replaceable>level2-attrib</replaceable> we have only
	  selected the first one (in Perl, array indexes start with
	  0).  This approach has a non-obvious drawback: if on some
	  level the value is not defined, Perl
	  <quote>auto-creates</quote> an empty structure on that level
	  (this <quote>auto-creation</quote> continues also for all
	  further levels of the expression). Hence, by querying a
	  value, we have actually made a change. This typically is an
	  undesirable effect. There are two ways to avoid it: first
	  would be to follow the nesting of the Perl structures one
	  level at a time and on every step first check that the value
	  on that level is non-empty. This is however makes the code
	  less readable and unnecessarily complex.  Second method
	  provides the same functionality with a nice syntax using so
	  called <firstterm>attribute-paths</firstterm>.  Attribute
	  path is an expression similar to a directory path or XPath
	  and expresses a path in the nesting of the Perl structures.
	  Using attribute-paths, the expression
	  <programlisting>$node-&gt;{<replaceable>attrib</replaceable>}{<replaceable>level2-attrib</replaceable>}[0]{<replaceable>level3-attrib</replaceable>}</programlisting>
	  could be rewritten as
	  <programlisting>$node-&gt;attr('<replaceable>attrib</replaceable>/<replaceable>level2-attrib</replaceable>/[1]/<replaceable>level3-attrib</replaceable>')</programlisting>
	  The method <methodname>attr</methodname> resolves
	  attribute-paths safely, avoiding auto-creation of Perl
	  structures on the way. Note, that in the attribute-path,
	  list and alternative members are indexed starting from 1.
	  In fact, if we want to access the 1st element, we may
	  completely skip the index specification and write:
	  <programlisting>$node-&gt;attr(<replaceable>'attrib</replaceable>/<replaceable>level2-attrib</replaceable>/<replaceable>level3-attrib</replaceable>')</programlisting>
	  Sometimes it is necessary to iterate over all list members
	  of some attributes. The macro <literal>ListV</literal> (and
	  its cousin macro <literal>AltV</literal> used for
	  alternatives) can be used to produce a list of all values of
	  a given attribute, e.g.  <programlisting>foreach my $member
	  (ListV($node-&gt;attr('<replaceable>attrib</replaceable>/<replaceable>level2-attrib</replaceable>')))
	  { # process list member $member print
	  $member-&gt;{<replaceable>level3-attrib</replaceable>},"\n";
	  }</programlisting>
	</para>
	<para>Values of attributes can be changed by pure Perl
	assignments, e.g.
	  <programlisting>$node-&gt;{<replaceable>attrib</replaceable>} = <replaceable>new_value</replaceable>;</programlisting>
	  or
	  <programlisting>$node-&gt;{<replaceable>attrib</replaceable>}{<replaceable>level2-attrib</replaceable>}[0]{<replaceable>level3-attrib}</replaceable> = <replaceable>new_value</replaceable></programlisting>
	  The previous assign ment may also be achieved using
	  <programlisting>$node-&gt;set_attr('<replaceable>attrib</replaceable>/<replaceable>level2-attrib</replaceable>/[1]/<replaceable>level3-attrib</replaceable>',<replaceable>new_value</replaceable>);</programlisting>
	</para>
	<para>The macro <literal>List</literal> can be used to
	  construct a new list value. Several other default macros for
	  dealing with list and alternative values exists (see <xref linkend="defaultmacros"/>).</para>
      </section>
      <section>
	<title>Accessing neighboring nodes</title>
	<para>
	  There is a few methods provided by every
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> reference that can be used
	  to access other nodes in the tree. Each of the methods
	  returns either a <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> reference
	  pointing to the requested node, or zero if 
	  the requested node does not exist. For example, the
	  following code may be used to make the active node's
	  parent node active:
	</para>
	<programlisting format="linespecific">$this = $this-&gt;parent if ($this-&gt;parent);</programlisting>
	<para>
	  The above code states: activate the parent node of the
	  currently active node in case the currently active node
	  has a parent.
	</para>
	<para>
	  The following table describes some
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> methods.
	  For a complete list, refer to the documentation of <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML.pm">Treex::PML.pm</ulink>.
	</para>
	<table id="fsnode_methods">
	  <title><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> methods</title>
	  <tgroup cols="2">
	    <colspec colnum="1" align="left"/>
	    <colspec colnum="2" align="justify"/>
	    <thead>
	      <row>
		<entry>Method name</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><literal>parent</literal></entry>
		<entry>Return node's parent node.</entry>
	      </row>
	      <row>
		<entry><literal>firstson</literal></entry>
		<entry>Return the first child node of the given node
		  (the first node depending on the given node).</entry>
	      </row>
	      <row>
		<entry><literal>rbrother</literal></entry>
		<entry>
		  Return the right
		  brother of the given node. However, hence the nodes
		  may be displayed in the order given by the special
		  FS-format numbering attribute <literal>@N</literal>,
		  the returned node need not necessarily be displayed to
		  the right of the given node. This is because the
		  ordering according to the special numbering attribute
		  does not have to correspond to the deep-first structure
		  ordering of the tree.
		</entry>
	      </row>
	      <row>
		<entry><literal>lbrother</literal></entry>
		<entry>
		  Return the left
		  brother of the given node. However, as for the 
		  right brother, hence the nodes
		  may be displayed in the order given by the special
		  FS-format numbering attribute <literal>@N</literal>,
		  the returned node need not necessarily be displayed to
		  the left of the given node. This is because the
		  ordering according to the special numbering attribute
		  does not have to correspond to the deep-first structure
		  ordering of the tree.
		</entry>
	      </row>
	      <row>
		<entry><literal>following(<replaceable>top</replaceable>?)</literal></entry>
		<entry>
		  Return the next node of the given node in the
		  natural ordering of the tree provided by the
		  tree structure. E.g. if the given node has a child,
		  this child is returned. If the node has no childs
		  but does have a right brother,
		  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink>
		  reference to the right brother is returned.
		  If no child and no right brother exists for the
		  given node, the method looks for a right brother
		  of its nearest ancestor, etc. Starting from the root
		  of the tree and calling this method repeatedly
		  on the returned nodes ensures that all the nodes
		  in the trees are accessed during the procedure.
		  If the optional argument <replaceable>top</replaceable>
		  contains a <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> reference,
		  the searching is limited to the subtree governed by 
		  the node of <replaceable>top</replaceable>.
		</entry>
	      </row>
	      <row>
		<entry><literal>previous(<replaceable>top</replaceable>?)</literal></entry>
		<entry>
		  Return the previous node of the given node in the
		  deep-first ordering of the tree provided by the tree
		  structure (see the above description of the
		  <literal>following</literal>
		  method for more detail on the ordering).
		  If the optional argument <replaceable>top</replaceable>
		  contains a <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink> reference,
		  the searching is limited to the subtree governed by 
		  the node of <replaceable>top</replaceable>.
		</entry>
	      </row>
	      <row>
		<entry><literal>children</literal></entry>
		<entry>
		  Return a list of all child-nodes of the given node.
		  The nodes in the list are ordered in their
		  structural order starting from the first son of their parent,
		  each node followed by its right brother.
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
      </section>
      <section>
	<title>Accessing other trees</title>
	<para>
	  For this purpose many default macros exist and we recommend
	  read their documentation first (see <xref linkend="defaultmacros"/>). In this section we describe more
	  low-level approach that utilizes one of the most fundamental
	  internal structures used by <application>TrEd</application>,
	  namely the <quote>grouping</quote> structure. This structure
	  may be accessed using the <literal>$grp</literal> variable.  There is really a
	  lot of things that can be achieved by using this variable in
	  a proper way, but because it is an open gate to
	  <application>TrEd</application> internals, it may also be
	  dangerous. Here, we only pay our attention to a few of the
	  safe features of <literal>$grp</literal>. In most cases,
	  using wrappers over this structure provided by default
	  macros, is still a much safer option.
	</para>
	<para>
	  The current file is accessed via the
	  <literal>CurrentFile()</literal> reference. This reference
	  is a pointer to an object of the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink>
	  class. The following methods are provided for the class:
	</para>
	<table id="fsfile_methods">
	  <title><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink> class methods</title>
	  <tgroup cols="2">
	    <colspec colnum="1" align="left"/>
	    <colspec colnum="2" align="justify"/>
	    <thead>
	      <row>
		<entry>Method name</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry><literal>filename</literal></entry>
		<entry>Returns current file's name.</entry>
	      </row>
	      <row>
		<entry><literal>changeFilename(<replaceable>name</replaceable>)</literal></entry>
		<entry>Change current file's name.</entry>
	      </row>
	      <row>
		<entry><literal>FS</literal></entry>
		<entry>Return a reference to an associated
		  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> object.
		</entry>
	      </row>
	      <row>
		<entry><literal>trees</literal></entry>
		<entry>Return a list of all trees (i.e.
		  a list of <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink>
		  object references pointing to the roots
		  of the trees).
		</entry>
	      </row>
	      <row>
		<entry><literal>hint</literal></entry>
		<entry>Return the <application>TrEd</application>'s
		hint pattern associated with the file.</entry>
	      </row>
	      <row>
		<entry><literal>changeHint(<replaceable>pattern</replaceable>)</literal></entry>
		<entry>Change the <application>TrEd</application>'s
		  hint pattern associated with the file.
		</entry>
	      </row>
	      <row>
		<entry><literal>pattern(<replaceable>n</replaceable>)</literal></entry>
		<entry>Return the <replaceable>n</replaceable>'th 
		  attribute pattern associated with the file.</entry>
	      </row>
	      <row>
		<entry><literal>patterns</literal></entry>
		<entry>Return a list of all attribute patterns
		associated with the file.</entry>
	      </row>
	      <row>
		<entry><literal>pattern_count</literal></entry>
		<entry>Return the number of display attribute patterns
		associated with the file.</entry>
	      </row>
	      <row>
		<entry><literal>changePatterns(<replaceable>patterns</replaceable>)</literal></entry>
		<entry>Change the list of  attribute patterns
		  associated with the file.</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	<para>
	  Actually, some other <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink> methods
	  exist, but as they are not intended to be used from the
	  macros directly, there is no reason to describe them here.
	</para>
	<para>
	  The most important of the methods above is the <literal>FS</literal> method which may be used to
	  access the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> class object
	  associated with the given file. Similarly as in the case of
	  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink> class, only the most importand
	  methods of the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> class are
	  described here.
	</para>
	<table>
	  <title><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> class methods</title>
	  <tgroup cols="2">
	    <colspec colnum="1" align="left"/>
	    <colspec colnum="2" align="justify"/>

	    <thead>
	      <row>
		<entry>Method name</entry>
		<entry>Description</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row id="FS.order">
		<entry><literal>order</literal></entry>
		<entry>Return the name of the special numerical FS attribute
		  responsible for providing the tree order. This
		  attribute is declared in the FS file as <literal>@N</literal>.
		</entry>
	      </row>
	      <row id="FS.sentord">
		<entry><literal>sentord</literal></entry>
		<entry>Return the name of the special numerical FS attribute
		  responsible for providing the order of the values
		  to form a <quote>sentence</quote>. This
		  attribute is declared in the FS file as
		  <literal>@W</literal>.
		</entry>
	      </row>
	      <row id="FS.value">
		<entry><literal>value</literal></entry>
		<entry>Return the name of the special FS attribute
		  providing a descriptive value of the node used when
		  forming a <quote>sentence</quote>. This
		  attribute is declared in the FS file as
		  <literal>@V</literal>.</entry>
	      </row>
	      <row>
		<entry><literal>hide</literal></entry>
		<entry>Return the name of the special FS attribute
		  which can be used for hiding subtrees. This
		  attribute is declared in the FS file as
		  <literal>@H</literal>; a subtree is
		  hidden if its governing node's value for this
		  attribute is <literal>'hide'</literal> or
		  <literal>1</literal>.</entry>
	      </row>
	      <row>
		<entry><literal>isHidden(<replaceable>node</replaceable>)</literal></entry>
		<entry>Return true if the given <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm"><classname>Treex::PML::Node</classname></ulink>
		<replaceable>node</replaceable> belongs to a hidden subtree.
		</entry>
	      </row>
	      <row>
		<entry><literal>isList(<replaceable>attr</replaceable>)</literal></entry>
		<entry>Return true if the given attribute is of list
		  type with a strictly defined set of possible
		  values. This type of attributes is declared by
		  the <literal>@L</literal> header in the FS format.
		</entry>
	      </row>
	      <row>
		<entry><literal>listValues(<replaceable>attr</replaceable>)</literal></entry>
		<entry>Return a list of all possible values for the
		given attribute <replaceable>attr</replaceable>. Empty
		list is retured in case the attribute is not of the
		list type.
		</entry>
	      </row>
	      <row>
		<entry><literal>color(<replaceable>attr</replaceable>)</literal></entry>
		<entry>
		  Return one of the <literal>Shadow</literal>,
		  <literal>Hilite</literal>,
		  <literal>XHilite</literal> and
		  <literal>normal</literal>
		  values, depending on the
		  color specified in the FS file header.
		  See also <link linkend="usefscolors">UseFSColors</link> configuration option.
		</entry>
	      </row>
	      <row>
		<entry><literal>attributes</literal></entry>
		<entry>Return a list containing names of all the
		attributes declared in the FS file header.</entry>
	      </row>
	      <row>
		<entry><literal>atno(<replaceable>n</replaceable>)</literal></entry>
		<entry>Return name of the
		  <replaceable>n</replaceable>'th
		  attribute.
		</entry>
	      </row>
	      <row>
		<entry><literal>indexOf(<replaceable>attr</replaceable>)</literal></entry>
		<entry>Return index of the attribute named 
		  <replaceable>attr</replaceable>, according
		  to the order in which attributes are defined in the
		  FS file.
		</entry>
	      </row>
	      <row>
		<entry><literal>count</literal></entry>
		<entry>Return the number of attributes defined in the FS file.</entry>
	      </row>
	      <row>
		<entry><literal>exists(<replaceable>attr</replaceable>)</literal></entry>
		<entry>Return true if attribute named
		  <replaceable>attr</replaceable> exists for the FS
		  file. If it is not the case, false (i.e. zero) is returned.
		</entry>
	      </row>
	      <row>
		<entry><literal>make_sentence(<replaceable>root_node</replaceable>)</literal></entry>
		<entry>Return a string forming a
		  <quote>sentence</quote> for the given node's subtree. 
		  The sentence is formed in the following way:
		  <orderedlist continuation="restarts" inheritnum="ignore">
		    <listitem>
		      <para>
			All the nodes of the
			<replaceable>root_node</replaceable> node's
			subtree and ordered according to their values
			for the special numerical FS sentence ordering
			attribute (see method <link linkend="FS.sentord"><literal>sentord</literal></link>
			above). The special FS numbering attribute
			(see method <link linkend="FS.order"><literal>order</literal></link>
			above) is used if no sentence ordering
			attribute is declared in the FS file.
		      </para>
		    </listitem>
		    <listitem>
		      <para>
			For every such node, its descriptive value
			(see
			method <link linkend="FS.order"><literal>value</literal></link>
			above) is taken.
		      </para>
		    </listitem>
		    <listitem>
		      <para>
			The values obtained in this way and order
			are joined into a single string with fields
			separated by the value of
			<replaceable>separator</replaceable>.  </para>
		    </listitem>
		  </orderedlist>
		</entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>
	<para>
	  The methods <literal>sentord</literal>,
	  <literal>order</literal>,
	  <literal>value</literal>, and
	  <literal>hide</literal> described above
	  are useful especially in macros of
	  general purposes, where names of the corresponding
	  attributes are not known in advance
	</para>
	<note>
	  <para>
	    In PML there is no equivalent of 
	    <literal>sentord</literal>, <literal>value</literal> and <literal>hide</literal>.
	    Nodes associated with a PML type implement
	    the methods 
	    <literal>$node->get_ordering_member_name()</literal>
	    and
	    <literal>$node->get_order()</literal>
	    to get the name and value of their ordering attribute
	    (i.e. associated with PML role #ORDER).
	  </para>
	</note>
	<note>
	<para>
	  Calling the FSFormat methods
	  <literal>sentord</literal>,
	  <literal>order</literal>,
	  <literal>value</literal>, and
	  <literal>hide</literal>
	  (as well as Node methods
	  <literal>get_order</literal> and
	  <literal>get_ordering_member_name</literal>
	  too many times (e.g. in a sort or map operations on a set of nodes)
	  may result in bad performence,
	  so it is recommended to store their return values
	  in local variables. Here is an example:
	</para>
	<informalexample>
	  <programlisting format="linespecific">
  my $ord    = FS()-&gt;sentord or FS()-&gt;order;
  my $value  = FS()-&gt;value;
  return join( ' ',
	       map { $_-&gt;{$value} }
	       sort { $a-&gt;{$ord} &lt;=&gt; $b-&gt;{$ord} } GetDisplayedNodes() );
	  </programlisting>
	</informalexample>
	<para>
	  If the values of <literal>value</literal>, <literal>sentord</literal> or
	  possibly <literal>order</literal> were evaluated each
	  time the Perl <literal>sort</literal> or
	  <literal>map</literal> function needs to compare or map
	  nodes, the performance of the code would considerably decrease.
	</para>
	</note>
      </section>
    </section>
    <section id="defaultmacros">
      <title>Public API: pre-defined macros</title>
      <para>
	The role of a public API available to macros is played by a set of
	macros defined in the <literal>TredMacro</literal> package
	in the file named <filename>tred.def</filename>.
	Most of these pre-defined macros are just safe wrappers for 
	<application>TrEd</application> internal function
	calls. Pre-defined macros and object methods (namely those of
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm">Treex::PML::Node</ulink></literal>, <literal>Treex::PML::Document</literal> and
	<ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink> should be the only access points
	used by a macro to interact with <application>TrEd</application>. 
	All other ways of creeping into <application>TrEd</application>'s
	internals are dangerous and should be avoided.
      </para>
      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="tred_def.xml" xpointer="xpointer(/article/section/section)"/>
    </section>
    <section id="hooks">
      <title>Hooks: automatically executed macros</title>
      <para>
	There is a special set of macros that was not
	mentioned yet. These macros, called hooks, are automatically
	executed by <application>TrEd</application> on certain
	occasions. By defining such macros a little more of the
	<application>TrEd</application>'s implicit behaviour may be
	influenced, for example the execution of a planned action may
	be aborted.
      </para>
      <warning>
	<para>Writing hooks correctly is a little bit more difficult than
	  writing simple macros. An incorrectly written hook may result
	  in errorneous behavior of <application>TrEd</application>,
	  which in some cases may even lead to a crash. When in doubt
	  about where exactly is a particular hook called, with what parameters
	  and what it is expected to do, it is best to peek directly
	  into <filename>tred</filename> or <filename>btred</filename>
	  sources. The possibility of doing so is one of the nice
	  advantages of dealing with free software - in the Richard Stallman's
	  sense - the joy of which I feel obliged not to deprive you of.
	</para>
      </warning>
      <para>
	Hooks differ from other macros in the following aspects:
	<orderedlist continuation="restarts" inheritnum="ignore">
	  <listitem>
	    <para>User cannot choose a name for a hook; on the
	      contrary, hook is recognized as a macro having a
	      special name identifying it as being a certain hook.
	    </para>
	  </listitem>
	  <listitem>
	    <para>Sometimes parameters are passed to hooks.</para>
	  </listitem>
	  <listitem>
	    <para>No modifications of the tree or current node
	      are reflected after the hook returns, i.e. the tree is not
	      redrawn, changes to <literal>$this</literal> variable
	      are not reflected. If necessary, a hook must provide this
	      functionality itself.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      Unlike macros, hooks are not expected to modify
	      the tree unless they explicitly state that, typically
	      by calling 
	      <literal>ChangingFile(1)</literal>.
	    </para>
	  </listitem>
	</orderedlist>
      </para>
      <para>
	There is a special class of hooks that may be used to prevent
	<application>TrEd</application> from finishing a planned
	action, e.g. enabling the user to modify certain attribute
	value etc. The value returned by a hook of this class is checked and
	the action is aborted in case the value equals to
	<quote><literal>stop</literal></quote>.
      </para>
      <para>In the following table the hooks which may be used to
	prevent <application>TrEd</application> from executing a
	certain action are marked by <literal>yes</literal> in the
	column <quote>Stop</quote>.
      </para>
      <table>
	<title>Hooks</title>
	<tgroup cols="3">
	  <colspec colnum="1" align="left"/>
	  <colspec colnum="2" align="center"/>
	  <colspec colnum="3" align="justify"/>
	  <thead>
	    <row>
	      <entry>Name</entry>
	      <entry>Stop</entry>
	      <entry>Hook event description</entry>
	    </row>
	  </thead>
	  <tbody><row id="about_file_hook">
	      <entry><literal>about_file_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>stringref</replaceable></literal></para><para>This hook is executed before the
		<guilabel>About</guilabel> window is displayed.
		The hook takes one argument: a reference to a scalar
		variable. The hook may populate the referenced
		variable with any information which is then displayed
		as a part of the <guilabel>About</guilabel> window message.
	      </para></entry>
	    </row><row id="after_autosave_hook">
	      <entry><literal>after_autosave_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>output_filename</replaceable></literal>, 
		  <literal role="params"><replaceable>success</replaceable></literal>
		</para><para>Executed after TrEd's attempt to auto-save a file.
		  This hook is intended to be used e.g. for post-processing
		  of auto-saved files.
		  The hook obtains the filename of the auto-saved file
		  and a save status
		  (which is 1 in case of success and 0 or undefined if auto-saving failed). 
		  Warnings or die messages produced by the hook
		  appear as warnings on the standard output.
		  The hook may return the string <literal>"stop"</literal> to
		  indicate that TrEd should consider auto-saving failed.
		</para>
	      </entry>
	    </row><row id="after_edit_attr_hook">
	      <entry><literal>after_edit_attr_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>attr</replaceable>,<replaceable>result</replaceable></literal></para><para>Executed after a node's attribute was edited
		in the <guilabel>Edit Attribute</guilabel>
		dialog window. The <replaceable>result</replaceable>
		argument contains <literal>1</literal> if the user pressed
		<guibutton>Ok</guibutton> button to close the dialog,
		and it contains <literal>0</literal> if the user
		closed the dialog with the
	      <guibutton>Close</guibutton> button.
	      </para></entry> 
	    </row><row id="after_edit_node_hook">
	      <entry><literal>after_edit_node_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>result</replaceable></literal></para><para>Executed after a node's attribute values were edited
		in the <guilabel>Edit Node ...</guilabel>
		dialog window. The <replaceable>result</replaceable>
		argument contains <literal>1</literal> if the user pressed
		<guibutton>Ok</guibutton> button to close the dialog,
		and it contains <literal>0</literal> if the user
		closed the dialog with the
	      <guibutton>Close</guibutton> button.
	      </para></entry> 
	    </row><row id="after_redraw_hook">
	      <entry><literal>after_redraw_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed every time a tree is redrawn.
	      The hook gets a TrEd::TreeView object as an argument.</para></entry>
	    </row><row id="after_save_hook">
	      <entry><literal>after_save_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>output_filename</replaceable></literal>, 
		  <literal role="params"><replaceable>success</replaceable></literal>
		</para><para>Executed after TrEd's attempt to save a file
		  (but not after auto-saves).
		  This hook is intended to be used e.g. for post-processing
		  of saved files.
		  The hook obtains the filename and a save status
		  (which is 1 in case of success and 0 or undefined if saving failed). 
		  Warnings or die messages produced by the hook
		  are presented to the user as warnings.
		  The hook may return the string <literal>"stop"</literal> to
		  indicate that TrEd should abort further actions
                  like opening a next file, etc. 
		  The document is however considered to be saved.
		  The hook may return the string <literal>"stop_nonfatal"</literal>  to indicate that TrEd should abort further actions
                  like opening a next file, etc, 
		  keep the output file but
		  consider the document not saved.
                  Finally, the hook may return the string <literal>"stop_fatal"</literal>
		  to make TrEd revert the output file from a backup and report the save operation as failed; the document is considered not saved.
		</para></entry>
	    </row><row id="allow_switch_context_hook">
	      <entry><literal>allow_switch_context_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>previous</replaceable>,<replaceable>next</replaceable></literal></para><para>Executed in the new annotation mode, but before the 
		annotation mode is actually changed (see <xref linkend="contexts"/>)
		and before <literal>pre_switch_context_hook</literal>
		is called (in the old-annotation mode).
		The <replaceable>previous</replaceable> argument
		contains the name of the current annotation mode while
		<replaceable>next</replaceable> contains the name of the
		target annotation mode.
	      </para></entry>
	    </row><row id="attr_choices_hook">
	      <entry><literal>attr_choices_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed when a CDATA attribute value
	      is editied in the 
	      <link linkend="new_editnode_interface">attribute editor</link>
	      and may be used to provide a list of values
	      to offer to the user using a list box. The hook gets the following
	      arguments:
	      an attribute path, the node, the <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema/Decl.pm">Treex::PML::Schema::Decl</ulink></literal> object
	      corresponding to the attribute type, and
	      a reference to the <literal>Tk::TrEdNodeEdit</literal>
	      which is an object derived from <literal>Tk::HList</literal>.
	      The hook may return a reference to a list of strings.
	      </para></entry>
	    </row><row id="attr_validate_hook">
	      <entry><literal>attr_validate_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>
		Executed when the user modifies a CDATA attribute value
		in the
		<link linkend="new_editnode_interface">attribute editor</link>.
		May be used to provide custom validation
		for attribute values. The hook gets the following
		arguments:
		current value of the attribute,
		an attribute path, the node, the <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema/Decl.pm">Treex::PML::Schema::Decl</ulink></literal> object
		corresponding to the attribute type, and
		a reference to the <literal>Tk::TrEdNodeEdit</literal>
		which is an object derived from <literal>Tk::HList</literal>.
		The hook must return a non-zero defined value to indicate that the value is valid
		or 0 to indicate that the value is invalid.
		If the hook returns undef, the default <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema.pm">Treex::PML::Schema</ulink></literal>-based validation
		takes place.
	      </para></entry>
	    </row><row id="current_node_change_hook">
	      <entry><literal>current_node_change_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>current_node</replaceable>,<replaceable>prev_current_node</replaceable></literal></para><para>executed when a new active node is selected.</para></entry>
	    </row><row id="customize_attrs_hook">
	      <entry><literal>customize_attrs_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Executed before the dialog for customizing attribute
		patterns is displayed.
	      </para></entry>
	    </row><row id="determine_node_type_hook">
	      <entry><literal>determine_node_type_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed when TrEd attempts to determine
	      the node type of a node that has no type associated with it.
	      The hook may be used to set type of the node.
	      Otherwise the user is asked to choose the node type
	      (if ambiguous). Gets the node as an argument.
	      </para></entry>
	    </row><row id="do_edit_attr_hook">
	      <entry><literal>do_edit_attr_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>attr</replaceable>,<replaceable>node</replaceable></literal></para><para>
		Executed before a dialog window for editing an
		attribute value is displayed (usually when the 
		user double-clicks the displayed attribute value).
		If <literal>stop</literal> is returned,
		the dialog is suppressed.
	      </para></entry>
	    </row><row id="do_edit_node_hook">
	      <entry><literal>do_edit_node_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable></literal></para><para>Executed before the <guilabel>Edit Node</guilabel>
		dialog is displayed, i.e. when the user
		double-clicks a node, presses <keysym>Enter</keysym> in the
		main window or issues <menuchoice>
		  <guimenu>Node</guimenu>
		  <guimenuitem>Edit Node Attributes...</guimenuitem></menuchoice>.
		If the hook returns <literal>stop</literal>, the dialog is suppressed.
	      </para></entry>
	    </row><row id="enable_attr_hook">
	      <entry><literal>enable_attr_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>attr</replaceable>,<replaceable>type</replaceable>,<replaceable>node</replaceable></literal></para><para>
		Executed before any text field for an attribute value
		modification or list of possible values
		is created. If the hook returns
		<quote><literal>stop</literal></quote>,
		the field or list is made read-only. The
		<replaceable>type</replaceable>
		argument may have one of the following values:
		<literal>ambiguous</literal> (in case
		of multiple values or an attribute with
		a given list of possible values) or
		<literal>normal</literal>.
		The argument <replaceable>node</replaceable>
		is the node whose attribute is to be edited.
		If this hook returns <literal>stop</literal>, the 
		corresponding edit fields in a displayed dialog are
		disabled (read-only); for a dialog that only displays
		the particular attribute, this means that the confirmation 
		<guibutton>OK</guibutton> button is removed.
	      </para></entry>
	    </row><row id="enable_edit_node_hook">
	      <entry><literal>enable_edit_node_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable></literal></para><para>Executed before the <guilabel>Edit Node</guilabel>
		dialog is displayed, i.e. when the user
		double-clicks a node, presses <keysym>Enter</keysym> in the
		main window or issues <menuchoice>
		  <guimenu>Node</guimenu>
		  <guimenuitem>Edit Node Attributes...</guimenuitem></menuchoice>, but
		after <literal>do_edit_node_hook</literal> was called (and
		only if it didn't return <literal>stop</literal>). 
		If this hook returns <literal>stop</literal>, the dialog is
		displayed, but only with a <guibutton>Cancel</guibutton>
		button, i.e. making it impossible to confirm and save the edits.
	      </para></entry>
	    </row><row id="event_hook">
	      <entry><literal>event_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>Tk-XEvent</replaceable>,<replaceable>Tk-win</replaceable>,<replaceable>shortcuts...</replaceable></literal></para><para>This is a very low-level hook, executed when a non-predefined keyboard shortcut
		was issued. It can be used to block certain keyboard events
		(in which case it should return <literal>stop</literal>) or 
		to provide <quote>on-the-fly</quote> bindings (by returning
		the name of a macro to be executed).
		The first argument is an Tk::XEvent object which can be used to
		obtain a detailed information of the event. The second argument
		is a Tk::Widget that caught the event and the rest of the
		arguments are keyboard-binding shortcuts computed from the event
		(these are the shortcuts that TrEd would try to look up in the current annotation mode
		bindings if this hook returns no macro name).
	      </para></entry>
	    </row><row id="exit_hook">
	      <entry><literal>exit_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed when the main window
		of <application>TrEd</application> is destroyed,
		before the user is prompted to save the modified files.
	      </para></entry>
	    </row><row id="file_autosave_hook">
	      <entry><literal>file_autosave_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>fsfile</replaceable></literal></para><para>Executed before TrEd attempts to create an auto-save file
		for the given<replaceable>fsfile</replaceable>. Note that
		this is not necessarily the file displayed in the
		active view and accessible via the <literal>$grp</literal> variable.
	      </para></entry>
	    </row><row id="file_close_hook">
	      <entry><literal>file_close_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed before TrEd attempts to close a file
		(this hook is called even if the file remains open
		but postponed if the close fails e.g. because
		the file being closed is required by another open file).</para></entry>
	    </row><row id="file_opened_hook">
	      <entry><literal>file_opened_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed after a file is opened but before the first
		tree is displayed.
	      </para></entry>
	    </row><row id="file_reloaded_hook">
	      <entry><literal>file_reloaded_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed after a file has been successfully
		  reloaded during the <guibutton>Reload file</guibutton>
		  action accessible from TrEd's main
		  <link linkend="toolbar">tollbar</link>.
		  (Note that this is the only hook called during this 
		  action, since
		  neither <link linkend="file_opened_hook">file_opened_hook</link>
		  nor <link linkend="file_resumed_hook">file_resumed_hook</link> are called!)
	      </para></entry>
	    </row>
	    <row id="guess_context_hook">
	      <entry><literal>guess_context_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>This hook is defined
	      in the default <filename>tredlib/contrib/contrib.mac</filename> file
	      and there is usually no need to redefine it!
	      Instead, use
	      <programlisting>context_guessing { <replaceable>...callback-code...</replaceable> };</programlisting>
	      or (for compatibility with older TrEd versions)
	      <programlisting>push @TredMacro::AUTO_CONTEXT_GUESSING, sub { <replaceable>...callback-code...</replaceable> };</programlisting>
	      where <replaceable>...callback-code...</replaceable> is a code
	      that attempts to detect a suitable annotation mode for the current file and
	      return the annotation mode name if successful. If the callback code
	      cannot positively determine a suitable annotation mode, it should return nothing (empty list).
	      The standard <literal>guess_context_hook</literal> will
	      call all registered callbacks one by one (but in no particular order) until
	      it gets a defined value and will then use
	      the value to set a the current annotation mode.
	      The callbacks are supposed to be very reserved,
	      i.e. they should only return some annotation mode name if
	      the file schema, attribute-set or whatever exactly
	      matches the data type for which the particular annotation 
	      mode is primarily intended. This will prevent
	      extensions to steal files one from another.
	    </para>
	    </entry>
	    </row>
	    <row id="file_resumed_hook">
	      <entry><literal>file_resumed_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed after an already open (kept) file is resumed.</para></entry>
	    </row><row id="file_save_hook">
	      <entry><literal>file_save_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>output_filename</replaceable></literal></para><para>Executed before TrEd attempts to save a file.</para></entry>
	    </row><row id="get_backends_hook">
	      <entry><literal>get_backends_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>backends...</replaceable></literal></para><para>Executed before a new file is opened. It receives a list 
		of available I/O backends known by TrEd as arguments. It should
		return a new array-ref consisting of backends that TrEd
		should actually try to use. This may be used both to
		add custom backends to the list or to prevent some
		standard backends from being used (by omitting them in the
		returned array-ref).
	      </para></entry>
	    </row><row id="get_nodelist_hook">
	      <entry><literal>get_nodelist_hook</literal></entry>
	      <entry>no</entry> <entry><para>Arguments: <literal role="params"><replaceable>fsfile</replaceable>,<replaceable>treeNo</replaceable>,<replaceable>recentActiveNode</replaceable>,<replaceable>show_hidden</replaceable></literal></para><para>This hook may be used to supply
	      custom node ordering given a fsfile, treeNo and hidden
	      node visibility state.  If used, it should return a
	      two-element array reference with the first element being
	      a array reference to a list of nodes to be displayed (in
	      a left-to-right order) and the second element being a
	      node to be set up as the initial active node.
	      </para></entry>
	    </row><row id="get_status_line_hook">
	      <entry><literal>get_status_line_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Supply status-line content.
		This hook is responsible for providing the content for
		a status-line. The value returned from 
		<literal>get_status_line_hook</literal> should
		have the form 
		<literal>[<replaceable>field-definitions</replaceable>,
		  <replaceable>style-definitions</replaceable>,
		  ]</literal>.
		<replaceable>field-definitions</replaceable>
		is an array reference of the form
		<literal>[<replaceable>text1</replaceable>,<replaceable>tags1</replaceable>,
		  <replaceable>text2</replaceable>,<replaceable>tags2</replaceable>,...
		  ]</literal> specifying
		one or more pieces of textual content of the
		status-line. Each piece of text is followed
		by another array reference, containing a list of
		<literal>tags</literal> associated with the text.
		Tags may be arbitrary strings.
		<replaceable>style-definitions</replaceable> is 
		an array reference which can map some tags
		to visual appearance attributes. It has a form
		<literal>[<replaceable>tag1</replaceable>,
		  [<replaceable>option =&gt; value</replaceable>,
	      <replaceable>option =&gt; value</replaceable>, ...],
		  <replaceable>tag2</replaceable>,
		  [<replaceable>option =&gt; value</replaceable>,
		  <replaceable>option =&gt; value</replaceable>, ...], ...
		  ]</literal>
		where <replaceable>option</replaceable> may
		be one of <literal>-foreground</literal>,
		<literal>-background</literal> and <literal>-underline</literal>.
	      </para></entry>
	    </row><row id="get_value_line_hook">
	      <entry><literal>get_value_line_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>fsfile</replaceable>,<replaceable>treeNo</replaceable>,<replaceable>type</replaceable></literal></para><para>Supply custom value-line content based on given
		<replaceable>fsfile</replaceable>,
		<replaceable>treeNo</replaceable>, and 
		<replaceable>type</replaceable>,
		where type determines the situation
		in which the hook is used:
		<literal>value_line</literal> (value is used 
		as the content of the value line, i.e.
		the text field
		above tree views),
		<literal>print</literal> (value used for a label
		under a printed tree),
		<literal>sent_list</literal> (value used
		in the list of sentences),
		<literal>html</literal>
		(value used for HTML export).
		</para><para>
		The value returned from the hook may be either 
		a string or an array reference
		consisting of a list of array references
		representing individual nodes. In the later case,
		the array references representing individual nodes
		must be of the form
		<literal>[<replaceable>text</replaceable>,
		  <replaceable>node</replaceable>,<replaceable>options...</replaceable>]</literal>
		where <replaceable>text</replaceable> is a text
		to be used,
		<replaceable>node</replaceable>
		is the node represented by the array reference
		and <literal>options...</literal> is arbitrary set 
		of strings (tags). If these strings are of the form
		<literal>-option =&gt; value</literal>
		where <literal>option</literal> is
		one of <literal>foreground</literal>,
		<literal>background</literal>,
		<literal>underline</literal>,
		they are used to alter visual appearance
		of the corresponding part of the text displayed on the
		value-line. All other strings are used as tags	
		(<literal>value_line</literal> type only)
		and are passed to hooks
		like
		<link linkend="value_line_doubleclick_hook">value_line_doubleclick_hook</link> or <link linkend="value_line_click_hook">value_line_click_hook</link> if the user clicks the corresponding part of the text.
	      </para></entry>
	    </row><row id="goto_file_hook">
	      <entry><literal>goto_file_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>
		Executed before the next or previous file in the current
		file list is opened.
	      </para></entry>
	    </row><row id="highlight_value_line_tag_hook">
	      <entry><literal>highlight_value_line_tag_hook</literal></entry>
	      <entry>no</entry>
	      <entry>
		<para>Arguments: <literal role="params"><replaceable>node</replaceable></literal></para>
		<para>Invoked every time a node is selected. The hook should
		return a tag associated with some text in the value
		line. The text is then highlighted in the value line.</para></entry>
	    </row><row id="init_hook">
	      <entry><literal>init_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Executed on start-up, before the first file specified on
		the command-line is opened (i.e. also before the <literal>start_hook</literal>).</para></entry>
	    </row><row id="initialize_bindings_hook">
	      <entry><literal>initialize_bindings_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed immediatelly after macros are loaded or re-loaded.
	      The hook has no arguments.
	      </para></entry>
	    </row><row id="line_click_hook">
	      <entry><literal>line_click_hook</literal></entry>
		<entry>no</entry> 
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>tag</replaceable>,<replaceable>button</replaceable>,<replaceable>double</replaceable>,<replaceable>mod</replaceable>,<replaceable>XEvent</replaceable></literal></para><para>Called when a line (segment of an edge) is clicked or double-clicked. Argument values are as follows:
		  <replaceable>node</replaceable> is the node the line pertains to (i.e. the one whose stylesheet specification caused the line to be drawn); <replaceable>tag</replaceable>
		  is the part of the stylesheet value <literal>Line-tag</literal>
		  corresponding to the particular segment of the  line;
		  <replaceable>button</replaceable> is the number of mouse button (1,2,3);
		  <replaceable>double</replaceable> is 1 if the event was a double-click
		  and 0 otherwise; <replaceable>mod</replaceable>
		  is a keyboard modifier (<literal>Control</literal>,
		<literal>Shift</literal>,
		<literal>Alt</literal>, or
		<literal>Meta</literal>);
		  <replaceable>XEvent</replaceable> is a <literal>Tk::XEvent</literal> object
		  which can be used to obtain detailed information
		  of the event (such as position of the mouse pointer, etc.).
		  The hook is responsible for calling
		<literal>Redraw_FSFile_Tree()</literal> or
		similar default macro to redraw the tree as well as for 
		setting <literal>$FileChanged=1</literal> if needed.
	      </para></entry>
	    </row><row id="macros_reloaded_hook">
	      <entry><literal>macros_reloaded_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed after macros has been re-loaded
		(i.e. after the user issued <menuchoice>
		  <guimenu>Macros</guimenu>
		  <guimenuitem>Reload Macros</guimenuitem>
		</menuchoice>). At the moment of the call to this hook,
		the newly loaded macros are already in effect.
	      </para></entry>
	    </row><row id="node_click_hook">
	      <entry><literal>node_click_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>modifier</replaceable>,<replaceable>XEvent</replaceable></literal></para><para>Executed when the user clicks on a node
		with a mouse button while holding a keyboard modifier
		(one of <keycap>Shift</keycap>, <keycap>Control</keycap>,
		<keycap>Alt</keycap>, <keycap>Meta</keycap>).
		The first argument is a node the user clicked on.
		The second argument is the keyboard modifier
		to which the suffix <literal>-2</literal> or
		<literal>-3</literal> has been appended 
		if the user pressed mouse button <mousebutton>2</mousebutton>
		or <mousebutton>3</mousebutton> respectivelly.
		The last argument is a raw <literal>Tk::XEvent</literal> object
		  which can be used to obtain details about 
		  the event (such as position of the mouse pointer, etc.).
	      </para></entry>
	    </row><row id="node_doubleclick_hook">
	      <entry><literal>node_doubleclick_hook</literal></entry>
		<entry>no</entry> 
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>mod</replaceable></literal></para><para>Called when a node is double-clicked
		  while a modifier key was pressed.
		  <replaceable>mod</replaceable> is a keyboard
		modifier string, such as <literal>Control</literal>,
		<literal>Shift</literal>,
		<literal>Alt</literal>, or
		<literal>Meta</literal>.
		  The hook is responsible for calling
		<literal>Redraw_FSFile_Tree()</literal> or
		similar default macro to redraw the tree as well as for 
		setting <literal>$FileChanged=1</literal> if needed.
	      </para></entry>
	    </row><row id="node_motion_hook">
	      <entry><literal>node_motion_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>modifier</replaceable>,<replaceable>XEvent</replaceable></literal></para><para>Executed repeatedly while the user drags 
		a node while holding a keyboard modifier.
		Arguments passed to this hook
		are same as for the <literal>node_click_hook</literal>.
	      </para></entry>
	    </row><row id="node_moved_hook">
	      <entry><literal>node_moved_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>old-parent</replaceable></literal></para><para>called after a node is moved using a mouse</para></entry>
	    </row><row id="node_release_hook">
	      <entry><literal>node_release_hook</literal></entry>
		<entry>yes</entry> <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>target-node</replaceable>,<replaceable>mod</replaceable></literal></para><para>Called when a node is released
		over another node after a mouse
		drag. <replaceable>mod</replaceable> is a keyboard
		modifier string, such as <literal>Control</literal>,
		<literal>Shift</literal>,
		<literal>Alt</literal>, or
		<literal>Meta</literal>.
		  It can also be empty.  If
		<literal>mod</literal> is empty, the hook should
		either result 'stop', to disable the default action
		of cutting <replaceable>node</replaceable> and pasting it on
		<replaceable>target-node</replaceable>, or 
		take no action. In all other cases, the hook may
		reorganize the tree in arbitrary way, but
		it should call <literal>Redraw_FSFile_Tree()</literal>
		and set <literal>$FileChanged=1</literal> if needed.
	      </para></entry>
	    </row><row id="node_style_hook">
	      <entry><literal>node_style_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>syles</replaceable></literal></para><para>This hook is called for every node of a tree every time
		the tree is being drawn. It may be used to provide
		additional styling information on top of
		the information provided by a current stylesheet.
		The first argument is the particular
		node. The second argument is a hash-reference containing
		current styling information provided by defaults 
		and the current stylesheet.
		It consists of key - value pairs, where key is 
		a styled object
		(<literal>Node</literal>,<literal>NodeLabel</literal>,
		<literal>EdgeLabel</literal>, <literal>Oval</literal>,
		<literal>Line</literal>, <literal>Text</literal>,
		<literal>TextBg</literal>, <literal>TextBox</literal>)
		and values are array-references consisting
		of feature - value pairs for these objects.
		The hook may alter this hash-reference and thus
		the styling of the particular node. It is recommended
		to take the advantage of the <literal>AddStyle</literal>
		default macro when altering the content of the
		<replaceable>styles</replaceable> hash-ref.
	      </para></entry>
	    </row><row id="open_file_hook">
	      <entry><literal>open_file_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Executed before TrEd
	      attempts to open a document. The hook
	      gets a filename and a HASH reference
	      containing various flags.
	      The hook may be used for example to redirect 
	      to a different filename by
	      calling the <literal>Open()</literal> macro
	      passing it the filename and the hash-reference flags.
	      </para></entry>
	    </row><row id="pre_switch_context_hook">
	      <entry><literal>pre_switch_context_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>previous</replaceable>,<replaceable>next</replaceable>,<replaceable>window</replaceable></literal></para><para>Executed in the old annotation mode before the 
		  annotation mode is changed (see <xref linkend="contexts"/>)
		and when switching to a different view,
		and when closing a view.
		The <replaceable>previous</replaceable> argument
		contains the name of the
		current annotation mode while
		<replaceable>next</replaceable> contains the name of the
		new annotation mode, or the string '&lt;NONE&gt;' if the current view is being closed.
		The <replaceable>window</replaceable> argument is the next view 
		to be focused. If the annotation mode is changed without focusing a different view,
		<replaceable>window</replaceable> is equal to
		<literal>$grp</literal>. If the focus moves to a different view 
		with the same annotation mode as in the current view,
		<replaceable>previous</replaceable> and <replaceable>next</replaceable>
		are equal and both contain the name of the annotation mode.
	      </para></entry>
	    </row><row id="pre_switch_stylesheet_hook">
	      <entry><literal>pre_switch_stylesheet_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>previous</replaceable>,<replaceable>next</replaceable></literal></para><para>Executed when user attempts to switch the current
		stylesheet from <replaceable>previous</replaceable> to
		<literal>next</literal>.
	      </para></entry>
	    </row><row id="preload_hook">
	      <entry><literal>preload_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Only used by <application>btred</application>.
		Executed before a file is preloaded.
	      </para></entry>
	    </row><row id="print_tree_filename_hook">
	      <entry><literal>print_tree_filename_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed when
		<menuchoice>
		  <guimenu>File</guimenu>
		  <guimenuitem>Print ...</guimenuitem>
		</menuchoice>
		command is invoked in order to obtain a suggestion for
		the target file-name used when printing to file.
	      </para></entry>
	    </row><row id="reload_macros_hook">
	      <entry><literal>reload_macros_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Executed before macros are re-loaded
		(i.e. when the user issues <menuchoice>
		  <guimenu>Macros</guimenu>
		  <guimenuitem>Reload Macros</guimenuitem>
		</menuchoice>).
		This macro may be used to do clean-up (e.g. cleanly deallocate
		non-perl resources, break circular dependences, etc.) before TrEd sweeps away
		the memory and code currently occupied and used by macros.</para></entry>
	    </row><row id="root_style_hook">
	      <entry><literal>root_style_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>root-node</replaceable>,<replaceable>syles</replaceable></literal></para><para>This hook is executed once every time
		the tree is being drawn before
		the content of a currently selected stylesheet
		is applied and before <literal>node_style_hook</literal>
		is called. The first argument is the root node of
		the tree and <replaceable>styles</replaceable> are
		as in <literal>node_style_hook</literal> above.
	      </para></entry>
	    </row><row id="sort_attrs_hook">
	      <entry><literal>sort_attrs_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>arrayRef</replaceable>,<replaceable>baseAttrPath</replaceable>,<replaceable>node</replaceable></literal></para>
	      <para>Executed when attributes are to be sorted by name
		(see <link linkend="sortattributes"><literal>SortAttributes</literal></link>
		configuration options). The
		<replaceable>arrayRef</replaceable>
		parameter passed to the hook is an array reference
		containing a list of attribute names to sort.
		The hook may modify this list (in place) by
		changing the order of its elements
		or by removing certain elements from the list.
		If a true value is returned by the hook,
		the (possibly modified) list is used for displaying purposes 
		without any further reordering.
		The arguments
		<replaceable>baseAttrPath</replaceable>
		and <replaceable>node</replaceable>
		contain, respectively,
		a base attribute path for the given list of attributes
		and optionally the <replaceable>Treex::PML::Node</replaceable>
		whose attributes are being displayed (optional).
	      </para>
	    </entry>
	    </row><row id="sort_attr_values_hook">
	      <entry><literal>sort_attr_values_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>arrayRef</replaceable>,<replaceable>baseAttrPath</replaceable>,<replaceable>node</replaceable></literal></para>
	      <para>Executed when values in an attribute value choice are to be ordered
		(see <link linkend="sortattributevalues"><literal>SortAttributeValues</literal></link>
		configuration options). The
		<replaceable>arrayRef</replaceable>
		parameter passed to the hook is an array reference
		containing a list of values to sort.
		The hook may modify this list (in place) by
		changing the order of its elements
		or by removing certain elements from the list.
		If a true value is returned by the hook,
		the (possibly modified) list is used for displaying purposes 
		without any further reordering.
		The arguments
		<replaceable>attrPath</replaceable> 
		and <replaceable>node</replaceable> 
		contain, respectively,
		an attribute path for the attribute whose possible values
		are being listed
		and the <replaceable>Treex::PML::Node</replaceable>
		whose attribute is involved (optional).
	      </para></entry>
	    </row><row id="start_hook">
	      <entry><literal>start_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Executed on start-up, before the main event loop
		is entered.</para></entry>
	    </row><row id="status_line_click_hook">
	      <entry><literal>status_line_click_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>tags...</replaceable></literal></para><para>Called when the user clicks the status-line
		with the same arguments as
		<literal>status_line_doubleclick_hook</literal>
		above.
	      </para></entry>
	    </row><row id="status_line_doubleclick_hook">
	      <entry><literal>status_line_doubleclick_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>tags...</replaceable></literal></para><para>Called when the user double-clicks the status-line.
		Arguments are the tags associated with
		the clicked field (see above). Tag may be arbitrary
		strings and it is up to user's will to
		set up some useful convention for tagging text of
		the status-line.
	      </para></entry>
	    </row><row id="switch_context_hook">
	      <entry><literal>switch_context_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>previous</replaceable>,<replaceable>current</replaceable></literal></para><para>Executed just after an annotation mode is changed (see <xref linkend="contexts"/>).
		The <replaceable>previous</replaceable> argument
		contains the name of the previous annotation mode while
		<replaceable>next</replaceable> contains the name of the
		new current annotation mode.
	      </para></entry>
	    </row><row id="switch_stylesheet_hook">
	      <entry><literal>switch_stylesheet_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>previous</replaceable>,<replaceable>current</replaceable></literal></para>
	      <para>Executed after switching stylesheets.
		The fist argument is the previous stylesheet.
		The second argument is the newly selected current stylesheet.
	      </para></entry>
	    </row><row id="text_click_hook">
	      <entry><literal>text_click_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>attribute</replaceable>,<replaceable>modifier</replaceable>,<replaceable>XEvent</replaceable></literal></para>
	      <para>Executed when the user double-clicks on
		a node label linked to a particular node attribute.
		The <replaceable>modifier</replaceable> and 
		<replaceable>XEvent</replaceable> arguments are 
		as described in <literal>node_click_hook</literal> above.
	      </para>
	      </entry>
	    </row><row id="text_doubleclick_hook">
	      <entry><literal>text_doubleclick_hook</literal></entry>
		<entry>no</entry> 
	      <entry><para>Arguments: <literal role="params"><replaceable>node</replaceable>,<replaceable>attr</replaceable>,<replaceable>mod</replaceable></literal></para><para>Called when an attribute in a displayed
		  node or edge label is double-clicked
		  while a modifier key was pressed.
		  <replaceable>mod</replaceable> is a keyboard
		modifier string, such as <literal>Control</literal>,
		<literal>Shift</literal>,
		<literal>Alt</literal>, or
		<literal>Meta</literal>.
		  <replaceable>node</replaceable> is the  <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm">Treex::PML::Node</ulink> object
		  whose attribute was clicked.
		  <replaceable>attr</replaceable> is name of the
		  attribute which was clicked.
		  The hook is responsible for calling
		<literal>Redraw_FSFile_Tree()</literal> or
		similar default macro to redraw the tree as well as for 
		setting <literal>$FileChanged=1</literal> if needed.
	      </para></entry>
	    </row><row id="value_line_click_hook">
	      <entry><literal>value_line_click_hook</literal></entry>
	      <entry>no</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>$button,$modif,$tags_array_ref</replaceable></literal></para><para>Called when the user clicks or doubleclicks the text window displayed above the tree
		  with any mouse button and possibly a keyboard modifier.
		Arguments are:
		  the mouse button (1,2,3),
		  the modifier (Alt, Meta, Control, Shift),
		  and an array-ref consisting of
		  the tags associated with
		the clicked part of the text. Tag may be arbitrary
		strings associated with the text in the
		<literal>value_line_hook</literal> or
		a serialized form of a node reference
		if the text is associated with a particular node.
		(More specifically,
		the Perl expression <literal>$tag eq $node</literal> is
		true for one of the tags and the corresponding node,
		where <literal>$tag</literal> is a simple scalar, i.e. astring.
		Hence, if necessary, the macro has to iterated through the tree
		in order to find the corresponding node.)
		For a double-click with the 1st mouse button, 
		<literal>value_line_doubleclick_hook</literal> is called
		before this hook.
	      </para></entry>
	    </row><row id="value_line_doubleclick_hook">
	      <entry><literal>value_line_doubleclick_hook</literal></entry>
	      <entry>yes</entry>
	      <entry><para>Arguments: <literal role="params"><replaceable>@tags</replaceable></literal></para><para>Called when the user double-clicks the text
		in the value line, i.e. text field above the tree view.
		Arguments are the tags associated with
		the clicked part of the text. Tag may be arbitrary
		strings associated with the text in the
		<literal>value_line_hook</literal> or
		a serialized form of a node reference
		if the text is associated with a particular node.
		(More specifically,
		the Perl expression <literal>$tag eq $node</literal> is
		true for one of the tags and the corresponding node,
		where <literal>$tag</literal> is a simple scalar, i.e. astring.
		Hence, if necessary, the macro has to iterated through the tree
		in order to find the corresponding node.)
		The hook may return a node to focus or 'stop' to prevent
		focusing a node associated with the part of the text that was double-clicked.
	      </para></entry>
	    </row><!-- row>
	      <entry>goto_tree_hook</entry>
	      <entry>yes</entry>
	      <entry>
		Executed before a different tree is displayed.
	      </entry>
	    </row --></tbody>
	</tgroup>

      </table>
    </section>
    <section id="contexts">
      <title>Using different sets of macros in different situations</title>
      <subtitle>Annotation modes</subtitle>
      <para>
	<application>TrEd</application> adopts a mechanism similar
	e.g. to <application>Emacs</application> major-modes which
	allow the user to safely create several sets of macros with possibly
	coliding key and menu bindings, macro names, and other functionality.
	In TrEd, this mechanism is called <emphasis>annotation mode</emphasis>.
      </para>
      <para>
	TrEd macros are organized into Perl packages (namespaces).
	The default package for TrEd macros is called
	<literal>TredMacro</literal>. Most pre-defined macros are defined within this package.
	<emphasis>Never</emphasis> use the package <literal>main</literal>
	or a package starting with <literal>TrEd::</literal> or
	<literal>Treex::PML::</literal> for your macros.
      </para>
      <para>
	A new package for a set of TrEd macros named, say <replaceable>MyPackage</replaceable>,
	use the following commands:
</para>
      <informalexample>
	<programlisting format="linespecific">
package MyPackage;
BEGIN { import TredMacro; }

sub my_first_macro {
  InfoMessage("Hallo from my first macro!")
}
</programlisting>
</informalexample>
<para>This also imports the default 
	<literal>TredMacro</literal> package (e.g. the pre-defined
	macros) so that the macros and global variables defined there can be called used
	without a package namespace prefix. Finally, it defines a new macro named
	<replaceable>my_first_macro</replaceable> in the new package.
      </para>
      <para>
	The macro <replaceable>my_first_macro</replaceable>
	from the last example can be called from a different package
	using its full name:
	<programlisting format="linespecific">
MyPackage::my_first_macro();   # call to a macro defined in MyPackage
</programlisting>
      </para>
      <para>
	In the interactive work, packages are used to create
	so called <emphasis>annotation modes</emphasis>,
	which usually correspond to macro packages.
	Only one annotation mode can be	active in TrEd at a time. 
	The current annotation mode is displayed on and may be selected from a
	menu on the right end of the menu bar.
      </para>
      <para>
	To turn a package into an annotation mode
	we just need to assign at least one keyboard or menu
	binding to some of the macros we have defined.
	(Note that annotation modes are refered to as
	binding contexts or just contexts in the old TrEd API jargon.)
	This is done using a special comment-like directives
	understood by TrEd anywhere in the macro code
	<literallayout class="normal" format="linespecific">#binding-context MyPackage
#bind my_first_macro to key Alt+e
#insert my_first_macro as menu Run My First Macro
</literallayout>
        First, the <literal>#binding-context</literal> directive says that
	all subsequent directives should apply to the <literal>MyPackage</literal>
	annotation mode
	and also that non-qualified subroutine names are to be assumed
	to belong to the package named <literal>MyPackage</literal>.
	Then the <literal>#bind</literal> directive
	creates a new keyboard shortcut for the
	macro <literal>my_first_macro</literal>
	(which upon pressing <keycombo action="simul"><keysym>Alt</keysym><keysym>e</keysym></keycombo>
	invokes the Perl subroutine as <literal>MyPackage-&gt;my_first_macro</literal>).
	Finally, the <literal>#insert</literal> directive creates a menu entry
	for the current macro in the <guimenu>Macros</guimenu> menu hierarchy.
	All directives must start at the beginning of a new line.
      </para>
      <para>
	An annotation mode may also copy all
	menu and keyboard bindings from other annotation mode(s) using
	<literallayout class="normal" format="linespecific">#key-binding-adopt <replaceable>other_mode(s)</replaceable></literallayout>
	and
	<literallayout class="normal" format="linespecific">#menu-binding-adopt <replaceable>other_mode(s)</replaceable></literallayout>
	directives. To remove some of the copied bindings from the current context,
	use <literal>#unbind-key</literal> and
	<literal>#remove-menu</literal> directives.
      </para>
      <para>
	For each annotation mode,
	a separate submenu with macros is created 
	in the 
	<menuchoice>
	  <guimenuitem>Macros</guimenuitem>
	  <guimenuitem>All Modes</guimenuitem></menuchoice> menu;
	  the <menuchoice>
	  <guimenuitem>Macros</guimenuitem>
	  <guimenuitem>Current Mode</guimenuitem></menuchoice> menu
	provides a short cut to the submenu with macros for the current annotation mode.
	For annotation modes with a large number of menu bindings it
	is usually more comfortable to select a macro 
	using <menuchoice>
	  <guimenuitem>Macros</guimenuitem>
	  <guimenuitem>List of Macros</guimenuitem>
	</menuchoice>.</para>
      <para> When a keyboard shortcut
	is pressed, <application>TrEd</application> first searches for a
	macro bound to the shortcut within the active annotation mode
	and if such macro exists, <application>TrEd</application>
	invokes it. In this case, the macro is supposed to be defined
	or imported in a package of the same name as is the name of
	the current annotation mode. If no macro is
	bound to the shortcut within the active annotation mode,
	<application>TrEd</application> tries to find a binding in the
	default <literal>TredMacro</literal> annotation mode. The macro
	is then supposed to be defined within the
	<literal>TredMacro</literal> package.
	If the search
	fails, no action is taken. The same holds for hooks as well.
      </para>
      <para>The following example shows a mechanism 
	which enables <application>TrEd</application> to automatically
	decide which annotation mode to use when a file is opened. It is
	quite similar to the <application>Emacs</application> concept
	of <quote>auto-modes</quote>, except that content of the file
	is considered here, not the file-name extension. In the
	example, the name of a PML schema is used
	to decide which annotation mode to use.
	This mechanism is used by the default implementation
	of the <link linkend="guess_context_hook">guess_context_hook</link>:
      </para>
      <example>
	<title>Guessing correct annotation modes</title>
	<programlisting format="linespecific">
package Conll2009;
BEGIN { import TredMacro; }

#binding-context Conll2009
#bind EditAttributes to space

use strict;

# check if this annotation mode applies to the current file
sub is_conll2009_file {
  return (((PML::SchemaName()||'') eq 'conll2009') ? 1 : 0);
}

push @TredMacro::AUTO_CONTEXT_GUESSING, sub {
  my ($hook)=@_;
  my $resuming = ($hook eq 'file_resumed_hook');
  my $current = CurrentContext();
  if (is_conll2009_file()) {
    SetCurrentStylesheet('conll2009') if $resuming;
    return 'Conll2009';
  }
  return;
};

# do not use this annotation mode for other files
sub allow_switch_context_hook {
  return 'stop' if not is_conll2009_file();
}

# set correct stylesheet when entering this annotation mode
sub switch_context_hook {
  SetCurrentStylesheet('conll2009');
  Redraw() if GUI();
}
</programlisting>
      </example>
    </section>
  </section>
  <section id="backends">
    <title>I/O backends</title>
    <para>This section briefly introduces the existing I/O backends
      and then provides a quick introduction to writing a custom backend.
    </para>
    <section id="iobackend">
      <title>Treex::PML::IO</title>
      <para>
	Actually, this is not a I/O backend per se. It is a base class and a function
	library
	used by Treex::PML and may of the other I/O backends. It provides a simple
	abstraction layer over some common low-level tasks, such as pipe-line redirection,
	gzip-compression, URL resolving, as well as fetching and
	uploading files using remote protocols. Due to this backend,
	<application>TrEd</application> transparently handles
	gzip-compression/de-compression of files with <filename>.gz</filename>
	extension as well as remote file transfer over
	<literal>ftp://</literal>,
	<literal>http://</literal>,
	<literal>ssh://</literal> and other protocols. Note however that availability
	of remote file transfer highly depends on a particular setup
	(currently only UNIX systems are fully supported) and may require
	some external tools, such as <link linkend="curl">curl</link>,
	<link linkend="kioclient">kioclient</link>,
	<link linkend="ssh">ssh</link>, 
	<link linkend="gzip">gzip</link>.
      </para>
    </section>
    <section id="fsbackend">
      <title>FS backend</title>
      <para>
	FS backend deals with a format called FS (feature structure). FS-format
	was the first format supported by tred, and for a long time also the only one.
	As a result, some methods of the Perl classes 
	used by <application>TrEd</application> and defined in the the underlying Perl library
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm">Treex::PML</ulink></literal>
	still bear the name of the format (even though they
	are now equally used to represent data obtained from any other I/O
	backend).
      </para>
      <para>
	FS format provides a simple and effective way for storing trees.
	In this format, each node of the
	tree uses the same set of attributes declared in the FS-file header. 
	FS format supports string values,
	enumerated values and flat lists of these
	(i.e. strings consisting of a <literal>|</literal>-separated list of
	values of the first two types). There is no direct support
	for nested AVS structures, complex lists and alternatives.
      </para>
      <para>
	Recent versions of
	<application>TrEd</application> and <literal>Treex::PML</literal>
	provide a simple nested-AVS emulation
	(attiribute-value structure) for FS attribute values, meaning the
	following: an attribute whose name contains one
	or more slashes is represented as a (possibly nested) AVS structure where
	each slash represents one level of nesting. Attributes sharing a
	common name-part followed by a slash are thus represented as members of
	the same structure. For example, attirubtes <literal>a</literal>,
	<literal>b/u/x</literal>,
	<literal>b/v/x</literal> and
	<literal>b/v/y</literal> result in the following structure:
<literallayout>
{
  a =&gt; <replaceable>value-of-a</replaceable>,
  b =&gt; { u =&gt; { x =&gt; <replaceable>value-of-a/u/x</replaceable> },
         v =&gt; { x =&gt; <replaceable>value-of-a/v/x</replaceable>,
                y =&gt; <replaceable>value-of-a/v/y</replaceable> 
              }
       }

}
</literallayout>
	In case that attributes with names <literal>a</literal>
	<literal>a/b</literal> would both exists, the nested-AVS emulation is
	abandoned and all attributes are represented literally (i.e.
	with slashes in their names).
      </para>
      <note>
	<para>Even with the recently added nested-AVS emulation, FS format is not 
	  in general fully capable of capturing data originating in other backends
	  such as PML.
	</para>
      </note>
      <para>
	FS format is fully described in
	<ulink url="http://ufal.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html">http://ufal.mff.cuni.cz/pdt/Corpora/PDT_1.0/Doc/fs.html</ulink>
      </para>
    </section>
    <section id="storablebackend">
      <title>Storable backend</title>
      <para>This backend is based on an excelent Perl module
	<literal>Storable</literal>, which can store
	and retrieve almost arbitrary Perl structure in an instant. Because of its
	general	nature, this backend can save and keep intact files
	originating from any other backend. Due to its speed
	with which it saves and retrieves data, it is often
	useful to transfer all data temporarily into this format
	(e.g. using <command>btred</command>) and
	revert to the original format only after all work on the data is done.
      </para>
    </section>
    <section id="csts_sgml_sp_backend">
      <title>CSTS_SGML_SP backend</title>
      <para>This backend provides
	support for the CSTS format. CSTS stands for <quote>Czech
	sentence tree structure</quote>. Since it is an application of SGML,
	the backend requires an external sgml parser (namely
	<command><link linkend="sgmls">nsgmls</link></command>) and a
	document type definition (DTD)
	(<filename>csts.doctype</filename>).  This backend represents
	CSTS data as trees with a fixed set of attributes, specific to
	the purpose for which CSTS was created, namely morphological and
	syntactical annotation of Czech texts.
	CSTS has been the primary format of the Prague Dependency
	Treebank 1.0.

      </para>
    </section>
    <section id="ntredbackend">
      <title>NTRED backend</title> <para>This backend used for
      exchanging of data between <application>TrEd</application> and
	btred servers, or in other words to <quote>peek</quote>
      into the memory of running btred servers.
      This backend only accepts filenames (or we should rather
      say URLs) starting with the <filename>ntred://</filename>
      protocol specification and followed by a real file name.  When
      this backend opens a file, it uses <command>ntred</command>
      client to fetch the file from any currently running btred
      server. If some btred server has a in-memory copy of
      the specified file (possibly edited during previous
      <command>ntred</command> requests), it sends this copy to the
      client and via the <literal>NTRED</literal>  backend to
      <application>TrEd</application>. Saving is performed in a
	reversed way, i.e. <command>ntred</command> client
	is used to communicate the (possibly edited) file back
      to the btred server replaces its previous in-memory copy of the
      file with the file obtained in this way.
      </para>
      <para>
	Instead of requesting a whole file from the 
	servers, is also possible (and sometimes faster) to request
	only a single tree. This can be achieved by appending
	a suffix of the form
	<literal>@<replaceable>N</replaceable></literal> to the
	<literal>ntred://</literal> URL, where
	<replaceable>N</replaceable> is the number of the requested
	tree (counting from 1). In that case,
	<application>TrEd</application> obtains a file containing only
	the requested tree. So, such URL as
	<literal>ntred://<replaceable>filename</replaceable>@3##1.4</literal>,
	opens a file containing the 3rd tree in <replaceable>filename</replaceable> (as
	represented in memory of a btred server) and opens that
	file on the 4th node of its first and only tree. URLs of this
	form are produced by the <literal>TredMacro</literal> 
	function <literal>NPosition()</literal> (see <xref linkend="defaultmacros"/>).
      </para>
    </section>
    <section id="pmlbackend">
      <title>PML backend</title>
      <section>
	<title>Introduction</title>
      <para>
	This backend provies  support for a generic XML-based
	format called PML (the <ulink url="http://ufal.mff.cuni.cz/jazz/PML/index_en.html">Prague Markup
	Language</ulink>), used for capturing rich linguistic annotation.
	PML is the base of the data format of the <ulink url="http://ufal.mff.cuni.cz/pdt2.0/">Prague Dependency
	Treebank 2.0</ulink>.
      </para>
      <para>
	Since all XML data can be easily transformed into PML and back
	(usually with a few lines of XSLT), this backend also provides
	a bridge between any other XML data format and
	<literal>TrEd</literal>, as described below in
	<xref linkend="pmlbackend_xslt"/>
      </para>
      <para>
	Each application of PML is described using a
	special XML file called <firstterm>PML schema</firstterm>. 
	This schema file defines which elements and attributes
	construe the nodes and structure of the tree, 
	declares value types of node attributes, etc.
      </para>
      <para>
	Updated version of the full PML specification can be found on the
	<ulink url="http://ufal.mff.cuni.cz/jazz/PML/index_en.html">PML project</ulink>
	page.
      </para>
      <para>
	While PML can possibly capture all kinds of structured data, the
	<literal>PML</literal> backend of <application>TrEd</application>
	is limited only to those applications of PML which satisfy the
	following criteria:
	<itemizedlist>
	  <listitem>
	    <para>
	      the data contain exactly one PML sequence or PML list
	      with the PML role <literal>#TREES</literal> consisting of
	      data with the role <literal>#NODE</literal>.
	      In case of a PML sequence, the
	      <literal>#NODE</literal>-elements must form a contiguous
	      block in the sequence, but may be preceded and/or
	      followed by some non-<literal>#NODE</literal> elements.
	    </para>
	  </listitem>
	  <listitem>
	    <para>Of all PML data types only PML structures and PML containers
	      may bear the role <literal>#NODE</literal>.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      A structure with the role <literal>#NODE</literal> 
	      may have a member with the role <literal>#CHILDNODES</literal>,
	      containing a list or sequence of structures/containers
	      with the role <literal>#NODE</literal>.
	    </para>
	  </listitem>
	  <listitem>
	    <para>
	      A container with
	      the role <literal>#NODE</literal> may contain
	      a list or sequence with the role <literal>#CHILDNODES</literal>
	      consisting of structures/containers
	      with the role <literal>#NODE</literal>.
	    </para>
	  </listitem>
	</itemizedlist>
      </para>
      </section>
      <section id="pmlbackend_xslt">
	<title>Support for non-PML XML-based formats</title>
	<para>
	  PML backend has its own configuration file
	  <filename>pmlbackend_conf.xml</filename> which is looked for
	  in the directories listed in <link linkend="resourcepath">ResourcePath</link>.
	  The <literal>transform_map</literal> section of the configuration file is automatically merged
	  with all files named
	  <filename>pmlbackend_conf.inc</filename> found in
	  <link linkend="resourcepath">ResourcePath</link>
	  (e.g. in a <filename>resource</filename> subdirectory
	  of an <link linkend="extension_packages">extension package</link>).
	  The
	  configuration file may specify transformation rules for
	  transparent conversion from legacy XML format to PML and
	  back. The configuration file is a PML file and may look
	  as on the following example:
	</para>
<programlisting><![CDATA[
<?xml version="1.0"?>
<pmlbackend xmlns="http://ufal.mff.cuni.cz/pdt/pml/">
  <head>
    <schema href="pmlbackend_conf_schema.xml"/>
  </head>
  <transform_map>

    <!--
      Transformation for Alpino XML format.
     -->
    <transform id="alpino" test="alpino_ds[@version='1.1']">
      <in type="xslt" href="alpino2pml.xsl"/>
      <out type="xslt" href="pml2alpino.xsl"/>
    </transform>

    <!--
      Transformation for TEI P5 XML format.
     -->
    <transform id="tei" test="TEI.2">
      <in type="xslt" href="tei2pml.xsl">
        <param name="only_fLib">'foo bar'</param>
      </in>
      <out type="xslt" href="pml2tei.xsl"/>
    </transform>

  </transform_map>
</pmlbackend>
]]></programlisting>
	<para>
	  This example configuration file defines two XSLT-based
	  transformations (<literal>type="xslt"</literal>, i.e. XSLT
	  1.0, is currently the only type of transformation
	  implemented by PML backend), each of which consists of a XSLT
	  stylesheet declared in the <sgmltag>&lt;in&gt;</sgmltag> tag,
	  used by PML backend to convert documents from the original
	  XML format to PML, and a XSLT stylesheet declared in the
	  <sgmltag>&lt;out&gt;</sgmltag> tag, used by PML backend to
	  convert documents from PML back to the original XML format.
	  Each stylesheet can take zero or more parameters
	  specified as <literal>&lt;param
	  name="<replaceable>parameter-name</replaceable>"&gt;<replaceable>parameter-value</replaceable>&lt;/param&gt;</literal>,
	  where <replaceable>parameter-value</replaceable> is an XPath
	  expression evaluated in the context of the transformed
	  document by the XSLT processor.
	  The transformations are further conditioned by
	  an XPath expression in the <literal>test</literal> attribute,
	  which selects to which documents is the transformation
	  applicable.
	</para>
	<para>
	  When PML backend opens an XML document and detects that this
	  document does not belong to the PML namespace, it evaluates
	  the XPath expression <literal>test</literal> for every
	  transformation rule in the order in which the rules appear in the
	  configuration file, until one of the expressions returns a true value
	  (boolean true, non-zero number, non-empty node-set, or
	  non-empty string) or the last expression fails.  The input
	  stylesheet of the transformation whose test had first
	  succeeded is used to transform the document into PML.
	  The <literal>id</literal> of this transformation
	  is remembered and the 
	  output stylesheet of the same transformation
	  is used to convert back from PML when
	  the document is saved.
	</para>
	<para>
	  We now summarize the steps necessary for adding 
	  support for a new XML-based format to TrEd (via XSLT
	  and PML backend):
	  <itemizedlist>
	    <listitem>
	      <para>Write a PML schema for the resulting PML version
		of the data so that all necessary information stored
		in the original format is captured.
	      </para>
	    </listitem>
	    <listitem>
	      <para>Write a XSLT transformation from
		the original format to a PML format described by the 
		previously written PML schema.
	      </para>
	    </listitem>
	    <listitem>
	      <para>Write a XSLT transformation from
		the PML format to the original format.
		This is step is not necessary if one
		only wishes to open the documents in TrEd for reading.
	      </para>
	    </listitem>
	    <listitem>
	      <para>
		Create a <literal>pmlbackend_conf.xml</literal> in one
		of the <link linkend="resourcepath"><literal>ResourcePath</literal></link>
		directories unless it already exists and
		add a transformation rule to it with 
		the input and output XSLT stylesheets and
		an XPath test approximating documents in the format.
		If writing an <link linkend="extension_format">extension</link>,
		one can create a file 
		<literal>pmlbackend_conf.inc</literal>
		in the <literal>resources</literal>
		directory of the extension, instead.
	      </para>
	      <para>
		Instead of specifying the output XSLT stylesheet one may
		also define an identity output transformation
		which simply writes back the data in PML.
		In that case the <literal>out</literal> tag
		should look as follows:
	      </para>
	      <literallayout>&lt;out type="identity"/&gt;</literallayout>
	    </listitem>
	  </itemizedlist>
	</para>
      </section>
      <section id="pml_representation">
	<title>Internal representation of PML data</title>
      <para>
	This section describes how PML data types are represented in
	<application>TrEd</application>.
      </para>
      <para>
	PML schema is represented by a <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Schema.pm"><literal>Treex::PML::Schema</literal></ulink>
	object. This object can be retrieved from the current
	<literal>Treex::PML::Document</literal> using the macro
	  <literal>MetaData('schema')</literal>.
      </para>
      <para>
	PML structures are represented as
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Struct.pm">Treex::PML::Struct</ulink></literal> objects,
	and so are PML containers, whose attributes
	and content value become members of the
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Struct.pm">Treex::PML::Struct</ulink></literal> object, the content value
	being represented by a special member named
	<literal>#content</literal>.  In both cases, if the role is
	<literal>#NODE</literal>, then <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm">Treex::PML::Node</ulink></literal>
	object is used instead of <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Struct.pm">Treex::PML::Struct</ulink></literal>.
	PML lists are represented as <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/List.pm">Treex::PML::List</ulink></literal>
	objects and PML alternatives as <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Alt.pm">Treex::PML::Alt</ulink></literal>
	objects. PML sequences as <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq.pm">Treex::PML::Seq</ulink></literal>
	objects and its elements as
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq/Element.pm">Treex::PML::Seq::Element</ulink></literal> objects.  The only
	exceptions are: a PML sequences with the role
	<literal>#TREES</literal>, which is represented by the list of
	the trees of the <literal>Treex::PML::Document</literal> object and a PML
	sequence with role <literal>#CHILDNODES</literal>, which is
	represented by the child-nodes of the node it belongs to.
	Elements of these sequences therefore represented by by
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm">Treex::PML::Node</ulink></literal> (rather than
	<literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Seq/Element.pm">Treex::PML::Seq::Element</ulink></literal>) objects with a
	dedicated attribute <literal>#name</literal> carrying the
	element's name.
      </para>
      <para>
	The non-tree data structures contained in the root element of
	the PML instance can be obtained either from
	<literal>MetaData('pml_root')</literal>.  If the root element
	contains a sequence with role <literal>#TREES</literal>,
	<literal>MetaData('pml_root')</literal> is empty and
	non-tree members of the sequence preceding trees are
        stored in a sequence
	<literal>MetaData('pml_prolog')</literal> while
	non-tree members that follow all trees are stored in a sequence
        <literal>MetaData('pml_epilog')</literal>.
      </para>
	<para>PML structures/containers that have a member or attribute
	  with the role <literal>#ID</literal> are indexed
	  by their IDs in a HASH <literal>AppData('id-hash')</literal>.
	</para>
      <para>
	If the PML schema declares a reference to an external resource
	and this declaration has the attribute
	<literal>readas="dom"</literal>, then the
	<literal>PML</literal> backend
	loads the corresponding PML instance
	as a DOM (Document Object Model) tree (using the Perl module
	<literal>XML::LibXML</literal>) and attaches this DOM tree
	to the application data section of the in-memory
	representation of the file.
      </para>
      <para>
	If the PML schema declares a reference to an external resource
	and this declaration has the attribute
	<literal>readas="pml"</literal>, then the
	<literal>PML</literal> backend
	loads the corresponding PML instance
	as a <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Instance.pm"><literal>Treex::PML::Instance</literal></ulink>
	object and attaches this object
	to the application data section of the in-memory
	representation of the file.
      </para>
      <para>
	If the PML schema declares a reference to an external resource
	and this declaration bears the attribute
	<literal>readas="trees"</literal>, then the
	<literal>PML</literal> backend passes the file-name 
	of the corresponding resource to
	<application>TrEd</application>
	and <application>TrEd</application> loads it as an ordinary
	file. This file can be edited and treated as any other file in
	<application>TrEd</application>. In <command>btred</command>,
	this file is opened as a so called
	<firstterm>secondary</firstterm> file, i.e. a file
	which is not implicitly processed by the macro specified by
	user, but as it is loaded in memory, the macro may explicitly
	choose to process it.
      </para>
	<para>The following HASH references carry information about
	  external resources: <literal>MetaData('refnames')</literal>
	  maps reference names to reference IDs,
	  <literal>MetaData('references')</literal>
	  maps reference IDs to URLs, 
	  and, for DOM and Treex::PML::Instance resources,
	  <literal>AppData('ref')</literal> maps
	  reference IDs to objects representing the
	  resources in <literal>TrEd</literal>.
      </para>
      <para>
	The
	<literal>PML</literal> backend supports so-called <quote>knitting</quote>
	of PML instances, i.e. replacing certain type of PML
	references with the content of the referenced entities
	occurring in other PML instance.
	Conversely, when a PML instance on which this
	<quote>knitting</quote>
	has been applied is saved, the (possible edited) content 
	replaces the content of the referenced entities
	in its original PML instance.
	Knitting only applies to:
	<orderedlist>
	  <listitem>
	    <para>
	members of PML structures containing a
	PML reference and having PML role <literal>#KNIT</literal>,
	</para>
	  </listitem>
	  <listitem>
	    <para>to members of PML structures containing a list with PML
	role <literal>#KNIT</literal>, with PML references as list
	members.
	    </para>
	  </listitem>
	</orderedlist>
	If knitting applies to such a member, then a possible trailing
	<literal>.rf</literal> part of its name is stripped and its
	content (either a single PML reference or a list of them) is
	replaced with the corresponding entities in the referenced PML
	instance. It is required that all such PML references refer to
	resources specified in the PML schema either as
	<literal>readas="dom"</literal> (in which case <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML.pm"><classname>Treex::PML</classname></ulink>
	representation of the referred data structure is created and
	transformed back into DOM only at save) or
	<literal>readas="pml"</literal> (in which case, after
	knitting, the referred and referring PML instances share the
	knitted data structure).
      </para>
      </section>
    </section>
    <section id="trxmlbackend">
      <title>TrXML backend</title>
      <para>The
	<literal>TrXML</literal> backend was intended as a XML
	replacement of the FS format. Unfortunatelly, never fully
	developed and thoroughly tested. It is obsoleted by PML and
	therefore not recommended for any future work.
      </para>
    </section>
    <section id="teixmlbackend">
      <title>TEIXML backend</title>
      <para>
	This backend reads and stores trees represented in a specific
	subset of the TEI XML format. The format used by this backend
	was (is?) used in the <ulink url="http://nl.ijs.si/sdt/">Slovene Treebank Project</ulink>.
      </para>
    </section>
    <section>
      <title>Writing a new I/O backend</title>
      <para>
	While for XML-based formats it is recommended to
	use XSTL transformation to PML as described in
	<xref linkend="pmlbackend_xslt"/>, adding support for 
	other formats requires writing a new I/O backend.
	An I/O backend is a Perl module defining at least the
	following five subroutines (listed in the order in which they
	are typically called by <application>TrEd</application>):
      </para>
      <variablelist>
	<varlistentry>
	  <term><literal><function>test</function>(<replaceable>$filename</replaceable>,<replaceable>$encoding</replaceable>)</literal></term>
	  <listitem>
	    <para>
	      This function should only quickly peek in the given file
	      in order to determine if it is a file suitable by the
	      backend. If this function accepts the file by returns a
	      defined non-zero value (e.g. 1), then the file is
	      processed by this backend. If the file is not suitable
	      for the backend, this function must reject the file
	      by returning 0 or <literal>undef</literal>,
	      so that other backends in the list of backends could
	      try their luck.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal><function>open_backend</function>(<replaceable>$filename</replaceable>,<replaceable>$mode</replaceable>,<replaceable>$encoding</replaceable>)</literal></term>
	  <listitem>
	    <para>This function should open and return a filehandle for a given
	      file. If <replaceable>$mode</replaceable> is
	      <literal>r</literal>, then this filehandle should be
	      open for reading, if <replaceable>$mode</replaceable> is
	      <literal>w</literal>, it should be open for writing.
	      The third, <replaceable>$encoding</replaceable>, contains
	      the encoding specified by the user in the <link linkend="defaultfileencoding">defaultFileEncoding</link>
	      configuration option. This information may be ignored if
	      the data format provides another way to determine the
	      encoding. Most backends do not re-implement this
	      function, but simply import (i.e. inherit) it from the
	      base class <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/IO.pm"><classname>Treex::PML::IO</classname></ulink>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal><function>read</function>(<replaceable>$filehandle</replaceable>,<replaceable>$fsfile</replaceable>)</literal></term>
	  <listitem>
	    <para>
	      This is the key function that implements converting data
	      from the specific data format to the corresponding
	      memory representation in <application>TrEd</application>.
	      This function obtains two arguments: the
	      <replaceable>$filehandle</replaceable> previously
	      obtained by a call to backend's <function>open_backend</function>, 
	      and an empty <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink> object (i.e.
	      with no trees). It is supposed to parse the data format,
	      build tree representation of the data (usually using
	      functions such as <literal><ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Node.pm">Treex::PML::Factory</ulink>-&gt;createNode()</literal>,
	      and <literal><function>$child->paste(</function>(<replaceable>$parent</replaceable>,<replaceable>$ordering_attribute</replaceable>)</literal>
	      and populate the <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink>
	      with the resulting trees (e.g. using its
	      <methodname>changeTrees</methodname> method).
	      It should also setup <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink>
	      object associated with the
	      <replaceable>$fsfile</replaceable>
	      (<literal><replaceable>$fsfile</replaceable>-&gt;FS</literal>).
	      Any additional information related to the file (but not representable
	      as trees or <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/FSFormat.pm"><classname>Treex::PML::FSFormat</classname></ulink>) may be attached to the file e.g. using 
	      <literal><replaceable>$fsfile</replaceable>-&gt;<methodname>changeMetaData(<replaceable>$key</replaceable>,<replaceable>$value</replaceable>)</methodname></literal>.
	    </para>
	  </listitem>
	</varlistentry>
	<varlistentry>
	  <term><literal><function>write</function>(<replaceable>$filehandle</replaceable>,<replaceable>$fsfile</replaceable>)</literal></term>
	  <listitem>
	    <para>
	      This function is the opposite of
	      <function>read</function>. By examining the
	      <ulink url="http://search.cpan.org/dist/Treex-PML/lib/Treex/PML/Document.pm"><classname>Treex::PML::Document</classname></ulink> object
	      <replaceable>$fsfile</replaceable>
	      (especially its trees and meta data),
	      it should write the corresponding representation
	      in the specific data format to the given
	      <replaceable>$filehandle</replaceable>.
	    </para>
	  </listitem>
	</varlistentry>	    
	<varlistentry>
	  <term><literal><function>close_backend</function>(<replaceable>$filehandle</replaceable>)</literal></term>
	  <listitem>
	    <para>This function should close a given filehandle
	      created by a previous call to
	      <function>open_backend</function>.  It usually only
	      consists of applying a Perl function
	      <function>close</function> on the filehandle, but if
	      additional cleanup is necessary, it should be done here.
	      Most backends do not re-implement this function, but
	      simply import (i.e. inherit) it from the base class
	      <ulink url="Treex/PML/IO"><classname>Treex::PML::IO</classname></ulink>.
	    </para>
	  </listitem>
	</varlistentry>
      </variablelist>
      <para>
	There are several ways to make <application>TrEd</application>
	know about a user-defined I/O backend, namely:
	<itemizedlist>
	  <listitem>
	    <para>listing addtional backends in the <link linkend="iobackends">Treex::PML::IOs</link> configuration option,</para>
	  </listitem>
	  <listitem>
	    <para>listing addtional backends after
	      <parameter>-B</parameter> on the command-line (see <xref linkend="commandline"/></para>
	  </listitem>
	  <listitem>
	    <para>defining a 
	      <link linkend="get_backends_hook">get_backends_hook</link></para>
	  </listitem>
	</itemizedlist>
      </para>
    </section>
  </section>
  <section id="extension_packages">
    <title>Extension Packages</title>
    <para>
      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 <link linkend="extension_manager">Extension Manager</link>
      and selecting the extensions of their choice.
      Extensions can depend on other
      extensions and the TrEd installer
      attempts to resolve the dependencies automatically.
    </para>
    <para>
      The following sections describe in detail the content and format of an extension
      package and the format of a web repository.
    </para>
    <section id="extension_format">
      <title>Extension Package Format and Content</title>
      <para>
	An extension package is simply a ZIP file that among other files contains
	in the root directory a PML file named <literal>package.xml</literal>
	conforming to the PML schema <literal>tred_extension_schema.xml</literal>
	that can be found in the <filename>resources</filename> subdirectory
	of a TrEd installation.
	The information provided in the <literal>package.xml</literal> file
	is used by the Extension Manager to present the extension to the user.
	The <literal>package.xml</literal> file
	can look  like this:
      </para>
      <programlisting><![CDATA[<?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>]]><replaceable>sample_extension</replaceable><![CDATA[</pkgname>
  <title>]]><replaceable>A Sample TrEd Extension</replaceable><![CDATA[</title>
  <version>]]><replaceable>3.1</replaceable><![CDATA[</version>
  <copyright year="]]><replaceable>2008</replaceable><![CDATA[">]]><replaceable>Petr Pajas</replaceable><![CDATA[</copyright>
  <description>]]><replaceable>This is extension provides an example of how a TrEd extension might look like.</replaceable><![CDATA[</description>
  <require>]]><replaceable><![CDATA[
    <extension name="pdt20" min_version="1.0" href="http://ufal.mff.cuni.cz/~pajas/tred/extensions/pdt20"/>
    <extension name="padt" min_version="1.0" href="http://ufal.mff.cuni.cz/~pajas/tred/extensions/padt"/>]]></replaceable><![CDATA[
  </require>
</tred_extension>
]]>
      </programlisting>
      <para>
	An extension is uniquely identified by its short name
	(identifier), which in the above example is
	<replaceable>sample_extension</replaceable>. 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
	(<replaceable>A Sample TrEd Extension</replaceable> 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
	<literal>package.xml</literal> 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 <literal>pdt20</literal>
	and <literal>padt</literal> 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.
      </para>
      <para>
	Beside the <literal>package.xml</literal> file,
	an extension can contain arbitrary files,
	some of which, however, have special meaning to TrEd:
      </para>
      <itemizedlist>
	<listitem>
      <para>If the extension contains a directory
      <filename>contrib</filename>,
      TrEd looks
      for all files named <filename>contrib.mac</filename>
      located either directly in the <filename>contrib</filename> directory
      or in its first level subdirectories
      and attempts to loads these
      files as files with macros.
      Also, an <programlisting>#include &lt;<replaceable>contrib/filename</replaceable>&gt;</programlisting>
      directive used in a macro file
      of any extension looks for  <replaceable>contrib/filename</replaceable>
      in all (!) extensions. 
      To avoid filename clashes, 
      it is therefore recommended
      to put 
      <filename>contrib.mac</filename>
      and all other macro files of an extension to
      a subdirectory (usually named after the extension)
      of <filename>contrib</filename>,
      e.g. to create the directory structure like this:
      <programlisting>contrib/
contrib/sample_extension/
contrib/sample_extension/contrib.mac
contrib/sample_extension/sample_macros1.mak
contrib/sample_extension/sample_macros2.mak
      </programlisting>
      Then
      <programlisting>#include &lt;<replaceable>contrib/sample_extension/sample_macros2.mak</replaceable>&gt;</programlisting>
      can be used to include the macro file <filename>sample_macros2.mak</filename>
      provided by this extension from a macro file of some other extension.
      </para>
	</listitem>
	<listitem>
      <para>
	If the package contains a directory named
	<literal>libs</literal>,
	TrEd adds this directory to the
	Perl module search path (<literal>@INC</literal>).
      </para>
	</listitem>
	<listitem>
      <para>
	If the package contains a directory named
	<literal>resources</literal>,
	TrEd adds this directory to its list
	of resource paths 
	(see <link linkend="resourcepath">resourcePath configuration option</link>).
      </para>
	</listitem>
	<listitem>
      <para>
	If the package contains a directory named
	<literal>stylesheets</literal>,
	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 <link linkend="pattern_syntax">TrEd stylesheet syntax</link>.
	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 <ulink url="http://en.wikipedia.org/wiki/Percent-encoding">http://search.cpan.org/dist/Treex-PML/lib/>URI-escaped</ulink>.
	If the user modifies a stylesheet loaded from an extension,
	TrEd saves the modified version into the user's private
	stylesheet directory <filename>~/tred.d/stylesheets</filename>,
	which always appears first in the stylesheet directory list,
	so the modified version has precedence.
      </para>
	</listitem>
	<listitem>
      <para>
	If the package contains a directory named
	<literal>documentation</literal>
	and this directory contains an HTML or XHTML file named <literal>index.pm</literal>,
	TrEd adds a menu item 
	<menuchoice>
	  <guimenu>Help</guimenu>
	  <guisubmenu>Extension manuals</guisubmenu>
	  <guimenuitem><replaceable>extension name</replaceable></guimenuitem>
	</menuchoice>
	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.
      </para>
	</listitem>
	<listitem>
      <para>
	If the resource folder contains
	a PML file name <literal>pmlbackend_conf.inc</literal>
	with transformation rules for the 
	<link linkend="pmlbackend">PML_backend</link>,	       <!---->
	the transformatino rules 
	are prepended to the list of transformation rules
	contained in <literal>pmlbackend_conf.xml</literal>
	and are used as described
	in section <xref linkend="pmlbackend_xslt"/>.
      </para>
	</listitem>
      </itemizedlist>
    </section>
    <section id="extension_repo">
      <title>Extension Repository</title>
      <para>
	Extension repository is a local directory 
	or a directory located on the web accessible by
	HTTP prococol that contains the following files:
      </para>
      <itemizedlist>
	<listitem>
	  <para>a file named
	  <literal>extensions.lst</literal>
	  containing a list of short package
	  names of extensions available in this repository.
	  Each extension name must be given on a separate line.
	  </para>
	</listitem>
	<listitem>
	  <para>for each package listed in
	  <literal>extensions.lst</literal>, a ZIP file
	  <literal><replaceable>pkgname</replaceable>.zip</literal>
	  where <replaceable>pkgname</replaceable> is the short name of
	  the extension, containing the extension data (and most notably the file
	  <literal><replaceable>package.xml</replaceable></literal>).
	  </para>
	</listitem>
	<listitem>
	  <para>for each package listed in <literal>extensions.lst</literal>
	  a subdirectory <literal><replaceable>pkgname</replaceable></literal>
	  (where <literal><replaceable>pkgname</replaceable></literal> is the name of the extension)
	  containing a file <literal><replaceable>package.xml</replaceable></literal>
	  (described above) which should be exactly same as the one contained in the ZIP package
	  of the extension.
	  </para>
	</listitem>
      </itemizedlist>
      <para>When TrEd reads the content of a repository, it first
      fetches the file <literal>extensions.lst</literal> and for each
      entry listed there it requests the file
      <literal><replaceable>pkgname</replaceable>/package.xml</literal>.
      If the user chooses to install or upgrade a given package, the
      ZIP file
      <literal><replaceable>pkgname</replaceable>.zip</literal> is
      requested and extracted to a subdirectory
      <literal>.tred.d/extensions/<replaceable>pkgname</replaceable>/</literal>
      in the user's home directory (<filename>Application Data</filename> on Windows).
      </para>
    </section>
    <section>
      <title>Developing Extensions</title>
      <para>
	The file <literal>devel/pack_extension.sh</literal>
	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 <literal>pacakge.xml</literal> file and other files pertaining by the extension)
	and a path to a directory containing a package repository.
	The script performs the following steps:
      </para>
      <itemizedlist>
	<listitem>
	  <para>Check that there is a valid <literal>pacakge.xml</literal> file
	  (validation requires the script <literal>pml_validate</literal>
	  from the <ulink url="http://ufal.mff.cuni.cz/jazz/PML">PML Toolkit</ulink>).
	  </para>
	  <para>compress the the content of the extension directory into a ZIP archive</para>
	  <para>check if a similarly named ZIP file is already contained in the repository:
	  <itemizedlist>
	    <listitem>
	      <para>If not, it creates an entry in <literal>extensions.lst</literal> in the repository,
	  copies the ZIP file to the repository and creates there the corresponding subfolder with the
	  <literal>package.xml</literal> file.</para>
	    </listitem>
	    <listitem>
	      <para>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 <literal>package.xml</literal> in the extension directory,
	      a new ZIP file is created with the updated <literal>package.xml</literal>
	      and both the ZIP and the 
	      <literal>package.xml</literal> are copied to the repository directory.
	      </para>
	    </listitem>
	  </itemizedlist>
	  </para>
	</listitem>
      </itemizedlist>
      <tip>
	<para>
	  To test a development version of an extension
	  from a live working copy, one can
	  e.g. go to the <literal>~/.tred.d/extensions</literal>
	  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 <literal>Uninstall</literal>
	  is performed on the extension from the 
	  <link linkend="extension_manager">Extension Manager</link>
	  (only the symlink gets deleted).
	</para>
      </tip>
    </section>
  </section>
</article>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:no
sgml-shorttag:yes
sgml-namecase-general:nil
sgml-general-insert-case:lower
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:2
sgml-indent-data:t
sgml-parent-document:nil
sgml-exposed-tags:nil
sgml-local-ecat-files:nil
End:
-->
