Introduction
------------
The tptp2X utility converts TPTP problems from the TPTP format, to formats used
by existing ATP systems.  Additionally, it can apply various transformations to
the clauses.

The utility consists of several files :
  tptp2X           - The main file of the tptp2X utility.
  tptp2X.config    - Configuration file with site specific information.
  tptpread         - Procedures for reading TPTP syntax files.
  transform.<TRAN> - Procedures  for   doing  <TRAN>  transformations   on  the
                     clauses,  where <TRAN> is one of arrange, equality, magic,
                     shorten.
  format.<ATP>     - Procedures for  outputing clauses  in <ATP>  format, where
                     <ATP> is one  of meteor, mgtp, otter, pttp, setheo, sprfn, 
                     tptp.


Installation
------------
The tptp2X code should run on most Prolog systems**. There is some code that is
specific to the BinProlog, SICStus 2.1,  SICStus 0.7, Quintus and Sepia  Prolog 
dialects.  This dialect specific code deals with preserving variable names when 
reading clauses,  and  making a  saved-state.  The distributed  version of  the 
tptp2X utility is  configured for a generic Prolog dialect.  To use the dialect 
specific  code,   the  appropriate  facts  need   to  be  uncommented  in   the 
tptp2X.config file (and the generic fact commented out).

Before using  the tptp2X utility,  it is also necessary to set  the name of the
TPTP directory,  in the tptp_directory/1 fact in the tptp2X.config file.  It is
currently  set to  ~/TPTP.  It must  be changed  to the  absolute name  of  the
directory that contains the Problems and Axioms directories.

** In particular,  the tptp2X code will run on BinProlog.  BinProlog is written
   by Paul Tarau of the University of Moncton (Canada), and is freely available
   by anonymous ftp, from
       clement.info.umoncton.ca:BinProlog
   or from the CMU AI Repository
       ftp.cs.cmu.edu:/user/ai/lang/prolog/impl/prolog/bin_pl/bp
   See tptp2X.config for setting up for BinProlog.


Using tptp2X
------------
The main entry point to the tptp2X utility is tptp2X/4, in the form :

?-tptp2X(<TPTP file>,<Transformation>,<Output format>,<Output directory>).

where:
+ <TPTP file> is  the file name of  the TPTP problem file.  If the file name is
  not absolute, then it considered to be relative to the directory specified in
  the tptp_directory/1 fact.  If the  file name  is specified  as "user",  then
  input is taken from standard input.
+ <Transformation>  is a  transformation  or  list of  (possibly  sublists  of) 
  transformations.  A  transformation  is applied  directly.  For  a list,  the
  transformations  are applied  sequentially in  the order  they appear  in the 
  list.  If a  sublist  of  transformations  appears  in the  list,  then  each 
  transformation  in  the  sublist  is  used  as part  of  a different  overall 
  transformation sequence.  The total number of transformation sequences is the 
  product of the  sizes of the sublists,  or 1 if  there are  no sublists.  The 
  available transformations are :
      none,               to do  nothing (same  as omitting it,  but useful  in
                             sublists).
      lr,                 to reverse the literals in the clauses.
      cr,                 to reverse the clauses in the problem.
      clr,                to do both  reversals.  The rearrangment  of  clauses
                             and/or literals in  a problem facilitates  testing
                             the sensitivity  of an ATP system  to the order in
                             which the clauses and literals are presented.
      equality(<Remove>), to remove  equality axioms  and substitution  axioms.
      <Remove> is a Prolog list that indicates which equality axioms to remove.
      The list elements can be :
          reflexivity,    to remove reflexivity,
          symmetry,       to remove symmetry,
          transitivity,   to remove transitivity,
          function_sub,   to remove function substitution,
          predicate_sub,  to remove predicate substitution.
      These may be abbreviated to their first letters, i.e., r, s, t, f, and p.
      magic,              to do Mark Stickel's magic set transformation.
      shorten,            to replace  all the symbols in the  problem by short,
                             meaningless  symbols.  This is  useful if  you are
                             only interested  in the syntax of the problem, and
                             do not  want to read through the long,  meaningful
                             symbols that are often used in TPTP problems.
+ <Format> is an output format  or a list of output formats.  An output file is
  written for each output format specified. The available output formats are :
      meteor,             to convert to the METEOR format.
      mgtp,               to convert to the MGTP format.
      otter(<SoS>,<Otter options>), to convert to the Otter .in format.
      <SoS> specifies the Set of Support to use. It can be one of :
          theorem,        to use the clauses whose status is theorem;
          hypothesis,     to use the clauses whose status is hypothesis or
                             theorem;
          positive,       to use the positive clauses;
          negative,       to use the negative clauses;
          unit,           to use the unit clauses;
          none,           to use no clauses.
      <Otter options> is  a Prolog list of  Otter options which will  be output
      before the clause lists.
      pttp,               to convert to the PTTP format.
      setheo,             to convert to the SETHEO .lop format.
      sprfn,              to convert to the SPRFN format.
      tptp,               to convert to the TPTP format.
+ <Output directory> is  where the output files  are placed.  If the  directory
  is specified as "user", then output is sent to standard output.

There is  a secondary entry point  to the tptp2X utility, tptp2X/0.  This entry
point interactively  prompts for the four arguments required for tptp2X/4,  and
then calls  the tptp2X/4 entry point.  Input to the tptp2X/0 prompts must be in
Prolog form,  i.e., . terminated, and with non-trivial file names '' quoted (to
form Prolog atoms).


Using tptp2X Interactively
--------------------------
An executable version of the tptp2X utility,  that starts at the tptp2X/0 entry
point, may be created using  the make_tptp2X_interactive/0 entry point##.  This
creates an  executable  (saved  state)  version  of  the  tptp2X  utility.  The
executable is named tptp2X_interactive.


Using tptp2X as a Filter
------------------------
A filter version  of the  tptp2X utility,  that takes  its input  from standard
input  and  sends it  output to  standard  output,  may be  created  using  the
make_tptp2X_filter/0 entry point##.  This creates an executable  (saved  state)
version of  the tptp2X  utility.  The executable  is named  tptp2X_filter.  The
transformations and output format  for the filter are specified in a file named
tptp2Xrc.  This file  may exist either  in the current directory  or the TPTP2X
directory.  The current directory is searched before the TPTP2X directory.  The
first line of  the file must be a list of transformations,  and the second line
must be the output format.  Both lines must be . terminated.  If an appropriate
file cannot be found,  the filter defaults  to apply no transformations  and to
output in the TPTP format.

## When using  these entry  points,  depending on  the Prolog  dialect you  are 
   using,  the tptp2X utility  may start to execute  as if the saved executable
   had been invoked. At this stage simply abort execution.
   

The tptp2X Output Files
-----------------------
The output files produced by the tptp2X utility are named according to the TPTP
file  name and the  options used.  The name of the TPTP  problem (the file name
without  the  .p)  forms  the  basis  of  the  output  file  names.   For  each
transformation  a suffix is  appended to the base name. The suffixes for the
transformations are :
    Transformation         Suffix
    --------------         ------
    none
    lr                     -lr
    cr                     -cr
    clr                    -clr
    shorten                -short
    magic                  -nhms
    equality(<Remove>)     -eq_<Remove>

An extension to indicate the output format is appended to  the transformed file
name. The suffixes for the output formats are :
    Format                 Extension
    ------                 ---------
    mgtp                   .mgtp
    otter                  .in
    pttp                   .pttp
    setheo                 .lop
    sprfn                  .sprfn
    tptp                   .tptp


Example
-------
The following is a typical tptp2X/4 run.

coral:~/TPTP/TPTP2X> sicstus
SICStus 2.1 #9: Thu Apr 21 09:39:25 +1000 1994
| ?- compile(tptp2X).

yes
| ?- tptp2X('Problems/GRP/GRP001-1.p',[[lr,cr],equality([s,t,f,p])],
     otter(hypothesis,[set(hyper_res),set(para_into)]),otter_directory).

yes
| ?- ^D

This use  of  the tptp2X  utility converts  the problem GRP001-1  to two  Otter 
format files.  In one file the literals are reversed, and in the other file the
clauses are reversed.  In both files all  equality literals except  reflexivity 
are removed.  In both files  the clauses with  status hypothesis or theorem are 
placed in the Set of Support list. Hyper-resolution and paramodulation-into are 
set as the inference rules. Two output files are produced : 
    otter_directory/GRP001-1-cr-eq_stfp.in and 
    otter_directory/GRP001-1-lr-eq_stfp.in. 
Note that the TPTP file name is quoted in the query, to form a Prolog atom.


Specifying your own Transformations and Output Formats
------------------------------------------------------
The transformations  and output formats are  specified in the  transform.<TRAN>
and format.<ATP> files, respectively.  It is simple to add  new transformations
and output formats to  the tptp2X utility,  by creating new transformation  and
format files.  New files  should follow  the structure  of the  existing files.
Typically, a new file can be created by modifying a copy of one of the existing
files.

The  entry  point  in  a  transformation  file  is  <Transformation>/6,   where
<Transformation> is the  principle symbol  of the transformation  specification
(currently one of none, lr, cr, clr, shorten, magic, equality). The first three
arguments are inputs : a list of the problem's clauses, the variable dictionary
(a  bit complicated),  and  the transformation  specification.  The next  three
arguments  are outputs :  the transformed  clauses,  the  transformed  variable
dictionary (typically the same as the input dictionary), and the transformation
suffix.

The entry point in a format file is <Format>/2, where <Format> is the principle
symbol of the output format specification  (currently one of mgtp, otter, pttp,
setheo, sprfn, tptp).  The two arguments are : a list of the problem's clauses,
and the  format specification.  As well as the  <Format>/2 entry point,  a fact
<Format>_format_information/2 must be provided.  The two arguments of this fact
are the  format extension and  a character that can  be used to start a comment
in the output file.

New transformation  and format files  must be compiled in with the tptp2X file.
This is done by adding a compile query in the tptp2X.config file, alongside the
queries that compile in the existing files.
