Directory macros/latex/contrib/qobitree

Copyright 1996 Jeffrey Mark Siskind

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either version 1.3
of this license or (at your option) any later version.
The latest version of this license is in
  http://www.latex-project.org/lppl.txt
and version 1.3 or later is part of all distributions of LaTeX
version 2005/12/01 or later.

This work has the LPPL maintenance status `unmaintained'.

This work consists of all files listed in manifest.txt.

Copyright and licensing notice added 2008/11/29 by
Clea F. Rees on behalf of Jeffrey Mark Siskind.

While writing my PhD thesis, I put together some useful LaTeX macros for
typesetting trees. I thought that they would be of general interest so I am
making them available. I gave an earlier version of these macros to Phil
Resnik a few months ago. These new macros are much easier to use and produce
much nicer output. For arcane reasons, the new macros, however, use a
different calling sequence. To use the new package get the file
~qobi/tex/QobiTree/QobiTree.tex from unagi and put in wherever you put your TeX
macros. Put the line:

\input{QobiTree}

somewhere at the beginning of your LaTeX file. The tree macros operate like a
stack machine. You push TeX boxes onto the stack containing text for the nodes
of the tree and then you pop them off the make branching nodes which get
pushed back on the stack. The following commands are supported:

\leaf{<text>}

Pushes a node onto the stack containing <text>. The <text> can contain
`\\' commands to create a node with more than one line. For example:

\leaf{NP\\{\em John}}

creates a two line node with NP (in roman) on top of John (in italics).
You can put any TeX box inside a leaf node, including math mode, LaTeX
picture environments, tables, embedded postscript, and other trees.
QobiTree automatically figures out how big the node is and sizes the tree and
its branches accordingly.

The command:

\branch{n}{<text>}

pops n nodes off the stack and creates a branching node with n children and
pushes it back on the stack. The first node popped off becomes the rightmost
child and the last node popped off becomes the leftmost child. n must be an
integer between 1 and 5. (It is possible to extend QobiTree to handle trees of
greater branching factor. See me if you need to.) The branching node created
is given <text> as its label. Again <text> can have `\\' commands and can be
any TeX box. For example:

\leaf{NP\\{\em John}}
\leaf{V\\{\em saw}}
\leaf{NP\\{\em Mary}}
\branch{2}{VP\\{em saw Mary}}
\branch{2}{S\\{\em John saw Mary}}

creates a simple binary branching tree.

The \leaf and \branch command don't generate any typeset output. They just
push trees onto the stack. The output is generated with the following command:

\tree

which pops one node off the stack and typesets it as a single box. Usually you
would center this box as in:

\leaf{NP\\{\em John}}
\leaf{V\\{\em saw}}
\leaf{NP\\{\em Mary}}
\branch{2}{VP\\{em saw Mary}}
\branch{2}{S\\{\em John saw Mary}}
\begin{center}
\tree
\end{center}

but it is also possible to put a tree in a sentence, in a table, in a math
mode formula, in a picture environment, or in another tree.
The file ~qobi/tex/QobiTree/examples.tex contains some examples taken
from my thesis.

Most of the time, QobiTree does a good job of figuring out how to space the
children of a tree. It never mistakingly overlaps children. Unlike the earlier
version of the tree macros I gave Phil, it is  usually able to space the tree
better without inordinate growth in deep trees. Sometimes however, you can
give it some help to produce even better looking output. The command:

\faketreewidth{<text>}

tells QobiTree to override its default calculation of the width of the node on
the top of the stack and replace it with the width of <text> (which again can
have `\\' commands etc.) <text> is not actually typeset but is used just to
compute the fake width of the node on the top of the stack. When you use
\faketreewidth you are on your own. This can either shrink or enlarge the
space taken by the node and may result in trees with overlapping children.
Usually a few tries with xdvi and you can adjust the tree widths to produce
the desired output. See ~qobi/tex/QobiTree/examples.tex for some
examples using \faketreewidth.

I hope that people find these macros useful. Feel free to pass them on to
whoever wants them.
	Jeff