Debian Codegraph @

texmf-dist/doc/latex/tikz-qtree/tikz-qtree-manual.tex

raw
1 \documentclass{article}
2
3 \usepackage{mathspec,xltxtra}
4
5 \setmainfont[Mapping=tex-text]{DejaVu Serif}
6 \setmonofont[Scale=0.95]{DejaVu Sans Mono}
7 \newfontfamily\verbfont[Scale=0.8]{DejaVu Sans Mono}
8 \newfontfamily\ar[Script=Arabic]{DejaVu Sans}
9 \newfontfamily\ja{Hiragino Maru Gothic Pro}
10 \newfontfamily\javerbfont[Scale=0.85,LetterSpace=5.0]{Hiragino Maru Gothic Pro}
11 \setmathrm{DejaVu Serif} \setmathfont(Digits,Latin){DejaVu Serif}
12
13 \usepackage{tikz}
14 \usepackage{tikz-qtree}
15
16 \usepackage{fullpage}
17
18 \usepackage{fancyvrb,fvrb-ex}
19 \fvset{gobble=0,xleftmargin=0.5in,xrightmargin=2.75in,formatcom=\verbfont}
20 \VerbatimFootnotes
21
22 \newcommand\tikztree{\texttt{tikz-qtree}}
23
24 \tikzset{>=latex}
25
26 \title{\tikztree: better trees with TikZ}
27 \author{David Chiang\\\texttt{[email protected]}}
28 \date{Version 1.2 (22 Apr 2012)}
29
30 \begin{document}
31
32 \maketitle
33
34 The \tikztree{} package provides a macro for drawing trees with
35 TikZ\footnote{\texttt{http://sourceforge.net/projects/pgf/}} using the
36 easy syntax of Alexis Dimitriadis'
37 Qtree\footnote{\texttt{http://www.ling.upenn.edu/advice/latex/qtree/}}. It
38 improves on TikZ's standard tree-drawing facility by laying out tree
39 nodes without collisions; it improves on Qtree by adding lots of
40 features from TikZ; and it improves on \verb|pst-qtree| in being
41 usable with pdf\TeX{} and
42 \XeTeX{}.\footnote{Although \XeTeX{} works with \verb|pst-qtree| using the \verb|xetex-pstricks| package. For typesetting very large trees or a large number of trees, this may be the better option.}
43
44 \section{Basics}
45
46 To load the package in \LaTeX{}:
47 \begin{Verbatim}
48 \usepackage{tikz}
49 \usepackage{tikz-qtree}
50 \end{Verbatim}
51 %
52 The simplest usage is identical to Qtree:
53 \begin{center}
54 \begin{SideBySideExample}
55 \Tree [.S [.NP [.Det the ] [.N cat ] ]
56 [.VP [.V sat ]
57 [.PP [.P on ]
58 [.NP [.Det the ] [.N mat ] ] ] ] ]
59 \end{SideBySideExample}
60 \end{center}
61 Subtrees are delimited by square brackets. A subtree's root label is
62 joined by a dot (\verb|.|) to its opening bracket.\footnote{You can
63 also write the label after the closing bracket instead of the opening
64 bracket, or both, or neither. Please see the Qtree documentation for
65 details.} As in Qtree, spaces are required after every (internal or
66 leaf) node label.
67
68 \verb|\Tree| works inside or outside a
69 \verb|tikzpicture| environment, but many of the features described
70 below require the explicit \verb|tikzpicture| environment.
71
72 \goodbreak
73
74 \section{Tree options}
75
76 Some options for standard TikZ trees work for \verb|\Tree| as
77 well:
78 \begin{itemize}
79 \item \verb|level distance|: vertical distance between the anchors of a parent and its children
80 \item \verb|sibling distance|: horizontal distance between the boundaries of sister subtrees (not the anchors of their roots, as in standard TikZ trees). Note that TikZ nodes already have some horizontal space around them (\verb|inner xsep|, by default \verb|0.3333em|), so even \verb|sibling distance=0pt| leaves some room.
81 \end{itemize}
82 These are set either by writing
83 \verb|\tikzset{|\textit{option}\verb|=|\textit{value}\verb|}| or by
84 writing \verb|[|\textit{option}\verb|=|\textit{value}\verb|]| after a
85 \verb|\begin{tikzpicture}| or \verb|\begin{scope}|.\footnote{Allowing
86 options after \verb|\Tree| would have made sense, but there would be
87 no way to disambiguate the two uses of square brackets.} For example:
88
89 \begin{center}
90 \begin{SideBySideExample}
91 \begin{tikzpicture}
92 \tikzset{level distance=60pt}
93 \Tree [.NP [.Adj tall ] [.N tree ] ]
94 \end{tikzpicture}
95 %
96 \begin{tikzpicture}[sibling distance=72pt]
97 \Tree [.NP [.Adj fat ] [.N tree ] ]
98 \end{tikzpicture}
99 \end{SideBySideExample}
100 \end{center}
101
102 The \verb|grow=|\textit{direction}\/ and \verb|grow'=|\textit{direction}\/ options control the orientation of trees just as for standard TikZ trees. However, \textit{direction}\/ must be one of \verb|up|, \verb|down|, \verb|left|, or \verb|right|. The difference between \verb|grow| and \verb|grow'| is that \verb|grow| places children counterclockwise with respect to their parent and \verb|grow'| places them clockwise:
103 \begin{center}
104 \begin{SideBySideExample}
105 \begin{tikzpicture}[grow'=down]
106 \Tree [.NP [.Adj reverse ] [.N tree ] ]
107 \end{tikzpicture}
108 %
109 \begin{tikzpicture}[grow'=up]
110 \Tree [.NP [.Adj upside-down ] [.N tree ] ]
111 \end{tikzpicture}
112 \end{SideBySideExample}
113 \vspace{3ex}
114 \begin{SideBySideExample}
115 \begin{tikzpicture}[grow=left]
116 \tikzset{level distance=60pt,sibling distance=18pt}
117 \tikzset{execute at begin node=\strut}
118 \Tree [.NP [.Adj sideways ] [.N tree ] ]
119 \end{tikzpicture}
120 \end{SideBySideExample}
121 \end{center}
122 Note that in sideways trees, \verb|level distance| is horizontal and \verb|sibling distance| is vertical. Sideways trees do take a little extra adjusting to look right, since the defaults are geared towards vertically growing trees. The meaning of the option \verb|execute at begin node=\strut| is, before typesetting the label of every node, insert the command \verb|\strut|, which is an invisible box that maximizes the height and depth of the node.
123
124 \section{Styles}
125
126 \subsection{Node styles}
127
128 The following TikZ styles are automatically applied to tree nodes,
129 providing a hook for you to change the appearance of nodes or particular kinds of nodes:
130 \begin{itemize}
131 \item \verb|every tree node| applies to every node (default: \verb|anchor=base|)
132 \item \verb|every internal node| applies to every internal node
133 \item \verb|every leaf node| applies to every leaf node
134 \item \texttt{every level $n$ node} applies to every node at level $n$, where $n=0$ is the root
135 \end{itemize}
136
137 The options for nodes are all handled by TikZ and are
138 described in detail in the TikZ documentation. For example, if you
139 have a font named \verb|\ar| and want to set all the leaf labels in
140 this font:
141 \begin{center}
142 \begin{SideBySideExample}
143 \begin{tikzpicture}
144 \tikzset{grow'=down}
145 \tikzset{every leaf node/.style={font=\ar}}
146 \Tree [.S [.NP القط ]
147 [.VP [.V وجلس ]
148 [.PP [.P على ] [.NP حصيرة ] ] ] ]
149 \end{tikzpicture}
150 \end{SideBySideExample}
151 \end{center}
152
153 You can make the nodes in a sideways tree line up on their left edge using \verb|anchor=base west|:
154 \begin{center}
155 \begin{SideBySideExample}
156 \begin{tikzpicture}
157 \tikzset{grow'=right,level distance=32pt}
158 \tikzset{execute at begin node=\strut}
159 \tikzset{every tree node/.style={anchor=base west}}
160 \Tree [.S [.NP [.Det the ] [.N cat ] ]
161 [.VP [.V sat ]
162 [.PP [.P on ]
163 [.NP [.Det the ] [.N mat ] ] ] ] ]
164 \end{tikzpicture}
165 \end{SideBySideExample}
166 \end{center}
167
168 In Qtree, it was allowed to use a line break (\verb|\\|) inside a node. TikZ nodes by default don't allow this, but the \verb|align| option (in PGF/TikZ version 2.1 or later) enables it as a side effect:\footnote{Thanks to Alan Munn for figuring this out. Prior to PGF/TikZ version 2.1, the fix was to use the options \verb|text width=2em,text centered|.}
169 \begin{center}
170 \begin{SideBySideExample}
171 \begin{tikzpicture}
172 \tikzset{every tree node/.style={align=center,anchor=north}}
173 \Tree [.S [.NP Det\\the N\\cat ]
174 [.VP V\\sat
175 [.PP P\\on
176 [.NP Det\\the N\\mat ] ] ] ]
177 \end{tikzpicture}
178 \end{SideBySideExample}
179 \end{center}
180
181 \subsection{Edge styles}
182
183 The \verb|edge from parent| style applies to every edge (default value: \verb|draw|). By defining this style, you can change the appearance of all the edges in a tree. For example, if you want the edges to be a little darker:
184 \begin{center}
185 \begin{SideBySideExample}
186 \begin{tikzpicture}
187 \tikzset{edge from parent/.append style={very thick}}
188 \Tree [.S [.NP [.Det the ] [.N cat ] ]
189 [.VP [.V sat ]
190 [.PP [.P on ]
191 [.NP [.Det the ] [.N mat ] ] ] ] ]
192 \end{tikzpicture}
193 \end{SideBySideExample}
194 \end{center}
195 Note that we must say \verb|.append style| instead of just \verb|.style|, in order to retain the \verb|draw| option without which the edge will be invisible.
196 As a more complex example, edges have an
197 \verb|edge from parent path| option which lets you change the shape of
198 the edge. Its value is a TikZ path expressed in terms of
199 \verb|\tikzparentnode|, the parent node, and \verb|\tikzchildnode|,
200 the child node.
201 \begin{center}
202 \begin{SideBySideExample}
203 \begin{tikzpicture}
204 \tikzset{edge from parent/.style=
205 {draw,
206 edge from parent path={(\tikzparentnode.south)
207 -- +(0,-8pt)
208 -| (\tikzchildnode)}}}
209 \Tree [.S [.NP [.Det the ] [.N cat ] ]
210 [.VP [.V sat ]
211 [.PP [.P on ]
212 [.NP [.Det the ] [.N mat ] ] ] ] ]
213 \end{tikzpicture}
214 \end{SideBySideExample}
215 \end{center}
216
217 \subsection{Node placement styles}
218
219 The following styles aren't applied to nodes, but affect the placement of nodes. By defining these styles, you can change the options \verb|level distance| or \verb|sibling distance| for different parts of the tree.\footnote{Thanks to Andrew Stacey for helping with the implementation.}
220 \begin{itemize}
221 \item \texttt{level $n$} applies to the placement of level $n$ (relative to level $n-1$)
222 \item \texttt{level $n$+} applies to level $n$ and below
223 \item \verb|interior| applies to the placement of internal nodes (except the root)
224 \item \verb|frontier| applies to the placement of leaves
225 \end{itemize}
226
227 \begin{center}
228 \begin{SideBySideExample}
229 \begin{tikzpicture}
230 \tikzset{level 1/.style={level distance=36pt}}
231 \tikzset{level 2/.style={level distance=32pt}}
232 \tikzset{level 3+/.style={level distance=28pt}}
233 \Tree [.S [.NP [.Det the ] [.N cat ] ]
234 [.VP [.V sat ]
235 [.PP [.P on ]
236 [.NP [.Det the ] [.N mat ] ] ] ] ]
237 \end{tikzpicture}
238 \end{SideBySideExample}
239 \end{center}
240
241 In this context, you can also set the option \verb|distance from root|, which positions a level relative to the root instead of the parent level. This is particularly useful for aligning all the leaf nodes:
242 \begin{center}
243 \begin{SideBySideExample}
244 \begin{tikzpicture}
245 \tikzset{frontier/.style={distance from root=150pt}}
246 \Tree [.S [.NP [.Det the ] [.N cat ] ]
247 [.VP [.V sat ]
248 [.PP [.P on ]
249 [.NP [.Det the ] [.N mat ] ] ] ] ]
250 \end{tikzpicture}
251 \end{SideBySideExample}
252 \end{center}
253 Unfortunately, the depth of the deepest leaf node is a global property of the tree and not easy to know during tree rendering, so you do have to specify the absolute depth of the leaf nodes. It will typically be an integer multiple of \verb|level distance|.
254
255 \section{Embedding TikZ nodes}
256
257 Inside a \verb|\Tree|, in place of a node label, you can use a TikZ
258 \verb|\node| command.\footnote{\verb|\Tree| specifically watches out
259 for the token \verb|\node|; do not use \verb|\path node| or other
260 equivalents.}
261 \begin{quote}
262 \verb|\node [|\textit{options}\verb|] (|\textit{name}\verb|) {|\textit{label}\verb|};|
263 \end{quote}
264 Don't forget the terminating semicolon. The
265 \verb|[|\textit{options}\verb|]|, which are optional, let you change
266 the appearance of the node; for example, the \verb|draw| option draws
267 a border around the node. The \verb|(|\textit{name}\verb|)|, which is
268 also optional, can be used for drawing lines/arrows to/from the node.
269 \begin{center}
270 \begin{Example}
271 \begin{tikzpicture}
272 \Tree [.CP [.NP \node(wh){what}; ]
273 [.C$'$ [.I did ]
274 [.\node[draw]{IP};
275 [.NP [.Det the ] [.N cat ] ]
276 [.VP [.V sit ]
277 [.PP [.P on ]
278 [.\node[draw]{NP};
279 [.NP [.Det a ] [.N book ] ]
280 [.PP [.P about ] [.NP \node(t){$t$}; ] ] ] ] ] ] ] ]
281 \draw[semithick,->] (t)..controls +(south west:5) and +(south:5)..(wh);
282 \end{tikzpicture}
283 \end{Example}
284 \end{center}
285
286 You can also refer to the whole subtree rooted at the node named \textit{name}\/ using \verb|\subtreeof{|\textit{name}\verb|}|:
287 \begin{center}
288 \begin{SideBySideExample}
289 \begin{tikzpicture}
290 \Tree [.S [.NP [.Det the ] [.N cat ] ]
291 [.\node(site){VP}; [.V sat ] ] ]
292 \begin{scope}[shift={(1in,0.5in)}]
293 \Tree [.\node(root){VP}; VP$^\ast$
294 [.PP [.P on ]
295 [.NP [.Det the ] [.N mat ] ] ] ]
296 \end{scope}
297 \draw[->](\subtreeof{root}.140)..
298 controls +(west:1) and +(east:1)..(site);
299 \end{tikzpicture}
300 \end{SideBySideExample}
301 \end{center}
302
303 \noindent Another example for machine translation people:
304 \begin{center}
305 \fvset{formatcom=\javerbfont}
306 \begin{SideBySideExample}
307 \begin{tikzpicture}
308 \begin{scope}[frontier/.style={distance from root=150pt}]
309 \Tree [.S [.NP [.Det \node(e1){the}; ]
310 [.N \node(e2){cat}; ] ]
311 [.VP [.V \node(e3){sat}; ]
312 [.PP [.P \node(e4){on}; ]
313 [.NP [.Det \node(e5){the}; ]
314 [.N \node(e6){mat}; ] ] ] ] ]
315 \end{scope}
316 \begin{scope}[xshift=9pt,yshift=-5in,grow'=up,
317 frontier/.style={distance from root=150pt}]
318 \tikzset{every leaf node/.style={font=\ja}}
319 \Tree [.S [.NP \node(j1){猫が}; ]
320 [.VP [.PP [.NP [.NP \node(j2){マット}; ]
321 [.Part \node(j3){の}; ]
322 [.NP \node(j4){上}; ] ]
323 [.P \node(j5){に}; ] ]
324 [.V \node(j6){土}; ] ] ]
325 \end{scope}
326 \begin{scope}[dashed]
327 \draw (e1)--(j1);
328 \draw (e2)--(j1);
329 \draw (e3)--(j6);
330 \draw (e4)--(j4);
331 \draw (e4)--(j5);
332 \draw (e5)--(j2);
333 \draw (e6)--(j2);
334 \end{scope}
335 \end{tikzpicture}
336 \end{SideBySideExample}
337 \end{center}
338
339 \section{Explicit edges}
340
341 The edge from a parent to a child node is normally automatically drawn
342 for you, but you can do it yourself with an \verb|\edge| command
343 \emph{before}\/ the corresponding child node. It is similar to the
344 TikZ \verb|edge from parent| command.\footnote{Except that a TikZ
345 \texttt{edge from parent} comes after the child node. I thought it was
346 more logical to put it before.}
347 \begin{quote}
348 \verb|\edge [|\textit{options}\verb|];|
349 \end{quote}
350 Again, don't forget the semicolon. The
351 \verb|[|\textit{options}\verb|]|, which are optional, let you change
352 the appearance of the edge, as described above.
353
354 There is a predefined edge style \verb|roof| that draws a triangle-shaped edge over a node, like Qtree's \verb|\qroof|:
355 \begin{center}
356 \begin{Example}
357 \begin{tikzpicture}[level distance=40pt]
358 \Tree [.S [.NP [.N this ] ]
359 [.VP [.V is ]
360 [.NP \edge[roof]; {a noun phrase the complexity of which
361 is too great for me to parse} ] ] ]
362 \end{tikzpicture}
363 \end{Example}
364 \end{center}
365
366 You can also add a label to the edge, using the following syntax:
367 \begin{quote}
368 \verb|\edge [|\textit{options}\verb|] node [|\textit{options}\verb|] {|\textit{label}\verb|};|
369 \end{quote}
370 Typically one will use the \verb|auto| option for edge labels, which
371 places the label to the side of the edge.
372 \begin{center}
373 \begin{SideBySideExample}[xrightmargin=1.25in]
374 \newcommand{\initial}[1]{\ensuremath{\alpha_{\textrm{\scriptsize #1}}}}
375 \newcommand{\auxiliary}[1]{\ensuremath{\beta_{\textrm{\scriptsize #1}}}}
376 \begin{tikzpicture}[level distance=36pt,sibling distance=12pt]
377 \Tree [.\initial{sat}
378 \edge node[auto=right]{1}; \initial{cat}
379 \edge[dashed] node[auto=left]{2};
380 [.\auxiliary{on}
381 \edge node[auto=left]{2}; \initial{mat} ] ]
382 \end{tikzpicture}
383 \end{SideBySideExample}
384 \end{center}
385 The fact that \verb|auto=left| draws a label on the right and
386 \verb|auto=right| draws a label on the left makes sense if you think
387 about the tree growing from the root to the leaves.
388
389 \section{Qtree compatibility}
390
391 For basic trees, \tikztree{} can be used as a drop-in replacement for Qtree, but most of Qtree's advanced features are either not accessed in the same way in \tikztree{} or not implemented at all. There is a package \verb|tikz-qtree-compat| which can be loaded to improve compatibility. Supported so far are:
392 \begin{itemize}
393 \item Superscripts and subscripts outside of math mode, and \verb|\automath|
394 \item The \verb|\0|, \verb|\1|, and \verb|\2| commands, and \verb|\qtreeprimes|
395 \item The \verb|\qroof| command
396 \end{itemize}
397 For unsupported commands, warning messages are printed, but your file should compile.
398
399 \section*{Acknowledgements}
400 This was all Dan Gildea's idea. Thanks to Alan Munn for his very helpful suggestions, and to Andrew Stacey for modifications.
401
402 \end{document}