
                                    LTREE

                     Lisp Tree -> Postscript Translator

                                 Terence Parr
                          Parr Research Corporation
                                September 1995
                           parrt@parr-research.com

        ftp://ftp.parr-research.com/pub/pccts/contrib/ltree.tar (32k)


INTRODUCTION

LTREE is a simple utility that accepts a lisp-like notation and
generates Postscript that visualizes the tree using a first-child,
next-sibling structure.  For example, the input (+ 3 4) results in
something resembling:

	+
	|
	3--4

in encapsulated Postscript.  The font size can be changed for each
tree with a command-line option and individual atoms may be made
italics.

LTREE has proven extraordinarily useful when creating documentation
for language tools and language applications.


TREE FORMAT

LTREE accepts tree definitions of the form:

	( root-atom element_1 ... element_n )

where element_i may be a tree (i.e., trees may be nested) or an atom.
The root-atom must always be an atom.  Tree descriptions may also be
single nodes:

	atom

To specify a list of sibling elements with no root, specify:

	( nil element_1 ... element_n )

Atoms may be words (such as PLUS or even punctuation marks such as +)
or quoted strings of anything.

To change the font size from the default of 10 pts (COURIER font), use
command-line option "-fs n".  To make an individual atom italics, put
the atom in quotes and prefix it with "\i ":

"\i atom"

Note that this screws up the space computations (because that's
nontrivial to do for nonconstant-width fonts).  It still looks ok for
most things, however.


INPUT GRAMMAR

Formally, LTREE accepts (in PCCTS notation):

description
	:	element
	;

tree	:	"\(" atom ( element )* "\)"
	;

element	:	tree
	|	atom
	;

atom	:	WORD
	|	STRING
	|	"nil"
	|	"NIL"
	;

/* WORDs are groups of anything but ", whitespace, ), or ( */
#token WORD	"~[\"\ \t\n\(\)]+"
/* STRINGs are anything inside double quotes; escaped quotes not allowed */
#token STRING	"\"~[\"]+\""


PORTABILITY

This has been tested under g++ 2.7.0 on a NeXTStep 3.2 machine and
on a Sun using C++ 3.0.1.

It should work with any decent C++ compiler.

LTREE was written in C and then partially converted to C++, so some of
the code looks kinda strange.  It used to be pretty small, but it's
still only 57k executable on a pentium NeXTStep box.


RIGHTS

Parr Research Corporation maintains the copyright on this software,
but any individual or company may use LTREE free of charge.  LTREE may
not be incorporated into commercial software or for commercial gain
without permission from Parr Research Corporation, but the postscript
output may be used for any purpose.  The source for LTREE may be
freely distributed as long as the headers and this README are
distributed along with the software and the files remain unmodified.

LTREE uses PCCTS, which is public-domain software developed by Parr
Research Corporation--some PCCTS files have been included.


WARRANTY

Parr Research Corporation makes no claims that this software does
anything useful, that it works, or even that it compiles.  "Your
mileage may vary."
