<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
<article>
  <articleinfo>
    <title>Converting between SGML and FS</title>
    <author>
      <firstname>Petr</firstname>
      <surname>Pajas</surname>
      <affiliation>
	<address><email>pajas@ufal.mff.cuni.cz</email></address>
      </affiliation>
    </author>
  </articleinfo>
  <sect1>
    <title>Introduction</title>
    <para><command>any2any</command> is a command-line utility
    for conversion between different file formats representing
    dependency tree
      structures, including FS format (<application>Graph</application>'s and
      <application>TrEd</application>'s native format),
      CSTS (PDT1.0 specific SGML format) and TrTree XML (which is a simple XML
      variant of the general FS format).
    </para>
  </sect1>
  <sect1>
    <title>Installation</title>
    <para><command>any2any</command> is a part of
      <application>TrEd</application> distribution, so if
      <application>Perl</application> and <application>TrEd</application>
      are installed properly <command>any2any</command> should work
      fine. There is also a <ulink url="any2any">stand-alone</ulink> distribution of
      <command>any2any</command>
      for those who do not wish to install
      <application>TrEd</application>.
      To install the stand-alone distribution, simply copy the whole
      <ulink url="any2any"><filename>any2any</filename></ulink>
      directory to any location you want
      and run <command>any2any</command> from that location. Make sure,
      that <application>Perl 5</application> is installed on your
      system
      (Windows(TM)
      version from <ulink
	url="http://www.activestate.com">ActiveState</ulink>
      may be found <ulink
	url="../../Tools/Tree_Editors/Tred/PerlTk/APi522e.exe">here</ulink>).
      James Clark's <ulink url="../../Support/nsgmls/index.html">SGML
    parser <application>nsgmls</application></ulink> is required
      for conversion from CSTS SGML format. Make sure, that this tool is
      installed on your system and that the path to the
      <command>nsgmls</command> binary executable is in your
      <varname>PATH</varname>.      
    </para>
  </sect1>
  <sect1>
    <title>Usage</title>
    <cmdsynopsis>
	<command>any2any</command>
	<arg choice="opt">-s <replaceable>suffix-pattern</replaceable></arg>
	<arg choice="opt">-a <replaceable>suffix</replaceable></arg>
	<arg choice="opt">-p <replaceable>prefix-pattern</replaceable></arg>
	<arg choice="opt">-r <replaceable>prefix</replaceable></arg>
	<arg choice="opt">-f
	<replaceable>output-format</replaceable></arg>
	<arg choice="opt">-m <replaceable>filename</replaceable></arg>
	<arg choice="opt">-n <replaceable>number</replaceable></arg>
	<group choice="opt">
	  <arg>-T</arg>
	</group>
	<group choice="opt">
	  <arg>-R</arg>
	</group>
	<group choice="opt">
	  <arg>-A</arg>
	</group>
	<group choice="opt">
	  <arg>-N</arg>
	</group>
	<group choice="opt">
	  <arg>-G</arg>
	</group>
	<group choice="opt">
	  <arg>-C</arg>
	</group>
	<group choice="opt">
	  <arg>-E</arg>
	</group>
	<group choice="opt">
	  <arg>-D</arg>
	</group>
	<arg choice="plain"
	  rep="repeat"><replaceable>input-file</replaceable></arg>
      </cmdsynopsis>
    <para>or</para>
      <cmdsynopsis>
	<command>any2any</command>
	<group>
	  <arg>-u</arg>
	  <arg>-h</arg>
	</group>
      </cmdsynopsis>
    
    <para>
      Each input file is opened and converted to the output format
      specified in the <parameter>-f</parameter> parameter. File name of
      the output file is made-up from the input file name in the
      following way:
    </para>
    <para>
      By default, output file name is the same as that of the input
      file and backup file (with a tilde <literal>~</literal>
      appended) is created to keep a copy of the original file.
      If <parameter>-s</parameter> pattern is given, it is interpreted
      as an regular expression and if a trailing part of the file name
      matches the regular expression, it is deleted.
      The value of <parameter>-a</parameter> parameter  (if any) is
      appended to the end of the file name.
      If <parameter>-p</parameter> pattern is given, it is interpreted
      as an regular expression and the matching part of the beginning of the
      file name (including extension) is deleted.
      The filename is then prepended by the suffix given after
      <parameter>-r</parameter> (if any).      
    </para>
    <variablelist>
      <title>Options</title>
      <varlistentry>
	<term><parameter>-f</parameter></term>
	<listitem>
	  <para>
	    Output format. The following output formats are
	    available: <literal>fs</literal>
	    (<application>TrEd</application>'s native file
	    format),
	    <literal>csts</literal> (PDT 1.0 specific SGML
	    format),
	    <literal>TrXML</literal> (XML variant of the
	    general FS format).		
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-s</parameter></term>
	<listitem>
	  <para>
	    Regular expression that should match the trailing part
	    of the file name which is to be deleted.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-a</parameter></term>
	<listitem>
	  <para>
	    Suffix to be appended to the output file name (after
	    the trailing part matched by <parameter>-s</parameter>
	    is deleted from it).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-p</parameter></term>
	<listitem>
	  <para>
	    Regular expression that should match the beginning
	    of the file name (including path) which is to be deleted.
	  </para>
	</listitem>	    
      </varlistentry>
      <varlistentry>
	<term><parameter>-r</parameter></term>
	<listitem>
	  <para>
	    Prefix to be inserted to the beginning of the output file name (after
	    the part matched by <parameter>-p</parameter> is deleted from it).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-m</parameter></term>
	<listitem>
	  <para>
	    Merge all given files into one huge file. The implementation is
	    rather imperfect since for instance CSTS headers are not merged.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-n</parameter></term>
	<listitem>
	  <para>
	    This option may be used in combination with
	    <parameter>-m</parameter> to merge all given files into
	    one or more output files containing at most the given
	    number of trees. If this option is used, the filename
	    specified with <parameter>-m</parameter> must contain
	    <literal>%d</literal> or similar sprintf format
	    instruction which will be replaced by the number of the
	    output file (starting from one).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-x</parameter></term>
	<listitem>
	  <para>
	    Comma separated list of non-CSTS attributes to preserve when
	    converting to CSTS as
	    <literal>&lt;x name="<replaceable>attribute-name</replaceable>"&gt;</literal>.
	  </para>
	</listitem>
      </varlistentry>


    </variablelist>
    <variablelist>
      <title>Conversion flags</title>
      <varlistentry>
	<term><parameter>-T</parameter></term>
	<listitem>
	  <para>Build tectogrammatical tree
	    structure and use tectogrammatical FS-File header
	    when converting from CSTS.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-R</parameter></term>
	<listitem>
	  <para>
	    Same as -T (for compatibility with TrEd/bTrEd).
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-A</parameter></term>
	<listitem>
	  <para>
	    When converting from csts, use header for Arabic PADT treebank.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-N</parameter></term>
	<listitem>
	  <para>Fill empty ordering attributes with sentence ordering
	    number when converting from CSTS.</para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-G</parameter></term>
	<listitem>
	  <para>If set, the element <sgmltag class="starttag">g</sgmltag> is not written to the
	    output for nodes dependent on the node with
	    <literal><sgmltag class="starttag">g</sgmltag>0</literal>
	    (usually the root node) when converting to CSTS.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-C</parameter></term>
	<listitem>
	  <para>This flag is provided for backward compatibility
	    with Dan Zeman's older conversion tool called 
	    <command>cstsfs</command> where some CSTS elements
	    are treated in a different way.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-E</parameter></term>
	<listitem>
	  <para>
	    When converting to CSTS, save err1 attribute to (non-CSTS!)
	    <literal>&lt;err&gt;</literal> element.
	  </para>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term><parameter>-D</parameter></term>
	<listitem>
	  <para>
	    Print various debugging information during conversion.
	  </para>
	</listitem>
      </varlistentry>

    </variablelist>
  </sect1>
  <sect1>
    <title>Expamles</title>
    <para>
      To convert all FS files <filename>*.fs</filename> in the
      <filename>fs/</filename> subdirectory to CSTS SGML format,
      storing the output files in <filename>sgml/</filename>
      subdirectory with the <filename>.csts</filename> extensions, the
      following command may be used:
      <informalexample>
	<blockquote><literal>any2any -s fs -a csts -p fs/ -r sgml/ -f csts fs/*.fs</literal></blockquote>
      </informalexample>      
    </para>
    <para>
      To do exactly the vice versa, converting CSTS files from
      <filename>sgml/</filename> to FS files in
      <filename>fs/</filename>, the following command may be used:
      <informalexample>
	<blockquote><literal>any2any -s csts -a fs -p sgml/ -r fs/ -f fs sgml/*.csts</literal></blockquote>
      </informalexample>
    </para>
    <note>
      <para>On some systems you may have to call
	<command>any2any</command> as <command>perl any2any</command>.
      </para>
    </note>
  </sect1>
</article>
<!-- Keep this comment at the end of the file
Local variables:
mode: xml
sgml-omittag:nil
sgml-shorttag:nil
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:
-->
