Debian Codegraph @

texmf-dist/doc/luatex/nodetree/nodetree-doc.tex

raw
1 %!TEX program = lualatex
2 \documentclass{ltxdoc}
3 \usepackage{paralist,fontspec,microtype}
4 \usepackage[
5 colorlinks=true,
6 linkcolor=red,
7 filecolor=red,
8 urlcolor=red,
9 ]{hyperref}
10 \usepackage{nodetree-embed}
11 \mdfsetup{
12 innerleftmargin=0.2em,
13 innerrightmargin=0.2em,
14 }
15 \EnableCrossrefs
16 \CodelineIndex
17 \RecordChanges
18
19 % Improve ltxdoc's `|...|` feature by allowing breaks.
20 \usepackage{fvextra}
21 \fvset{breaklines=true,breakbefore=.-_}
22 \AtBeginDocument{\DefineShortVerb{\|}}
23
24 % We use 'pmboxdraw' to draw box elements in minted environments.
25
26 % https://tex.stackexchange.com/questions/281368/print-box-drawing-characters-with-pdflatex/355403#355403
27 \usepackage{pmboxdraw}
28 \begingroup
29 \def\DeclareUnicodeCharacter#1{%
30 \begingroup
31 \lccode`\~="#1\relax
32 \lowercase{\endgroup
33 \global\catcode`~=\active
34 \gdef~%
35 }%
36 }%
37 \input{pmboxdrawenc.dfu}%
38 \endgroup
39
40 % https://tex.stackexchange.com/questions/108127/block-element-characters-pmboxdraw-are-shown-too-wide-in-verbatim-and-verbatim
41 \pmboxdrawsetup{
42 Block/box={\texttt{0}},
43 }
44
45 \usepackage{minted}
46 \usemintedstyle{colorful}
47 \BeforeBeginEnvironment{minted}{\begin{mdframed}[backgroundcolor=gray!3]}
48 \AfterEndEnvironment{minted}{\end{mdframed}}
49 \setminted{
50 breaklines=true,
51 fontsize=\footnotesize,
52 }
53 \setmintedinline{
54 fontsize=auto
55 }
56
57 \def\TmpLuaCodeInline#1{\texttt{\scantokens{\catcode`\_=12\relax#1}}}
58
59 \def\TmpSecRef#1{(\rightarrow\ \ref{#1})}
60
61 \def\TmpPageSecRef#1{
62 Page
63 \pageref{#1},
64 Section
65 \ref{#1}
66 }
67
68 \newcommand{\TmpExample}[2]{
69 \begin{NodetreeEmbedView}[fontsize=#2]
70 \input{examples/#1.nttex}
71 \end{NodetreeEmbedView}
72 }
73
74 \newcommand{\TmpVerbExample}[2]{
75 \VerbatimInput[firstline=4]{examples/#1.tex}
76 \TmpExample{#1}{#2}
77 }
78
79 \newcommand\TmpMacroName[1]{%
80 \texorpdfstring{\cs{#1}}{\textbackslash #1}%
81 }
82
83 \DefineVerbatimEnvironment{code}{Verbatim}
84 {
85 frame=single,
86 fontsize=\footnotesize,
87 }
88
89 \newcommand{\TmpLuaFunction}[1]{
90 \marginpar{%
91 \raggedleft%
92 \MacroFont%
93 \texttt{%
94 \scantokens{\catcode`\_=12\relax#1}%
95 }%
96 }%
97 }
98
99 \begin{document}
100
101 \providecommand*{\url}{\texttt}
102 \GetFileInfo{nodetree.dtx}
103 \title{The \textsf{nodetree} package}
104 \author{%
105 Josef Friedrich\\%
106 \url{[email protected]}\\%
107 \href{https://github.com/Josef-Friedrich/nodetree}{github.com/Josef-Friedrich/nodetree}\\%
108 with contributions by Werner Lemberg
109 }
110 \date{v2.4.1 from 2025/06/03}
111
112 \maketitle
113
114 \begin{NodetreeEmbedEnv}
115 nodetree
116 \end{NodetreeEmbedEnv}
117
118 \newpage
119
120 \tableofcontents
121
122 \newpage
123
124 %-----------------------------------------------------------------------
125 % Abstract
126 %-----------------------------------------------------------------------
127
128 \section{Abstract}
129
130 |nodetree| is a Lua\TeX{} development package for both plain \TeX{}
131 and \LaTeX{} that visualizes the structure of node lists while
132 compiling with the \TeX{} engine. It uses a visual representation of
133 node lists similar to the UNIX |tree| command’s output for folder
134 trees. The processed document isn’t changed.
135
136 The tree view can be emitted to the console, to a log file, or as a
137 \LaTeX{} input file. Its appearance is highly customizable; multiple
138 color and B/W themes together with various levels of verbosity are
139 provided.
140
141 Node lists are the main building blocks of the \TeX{} engine, which
142 Lua\TeX{} allows to inspect and modify. |nodetree| is inspired by a
143 \href{https://gist.github.com/pgundlach/556247} {gist from Patrick
144 Gundlach}.
145
146 %-----------------------------------------------------------------------
147 % Usage
148 %-----------------------------------------------------------------------
149
150 \section{Usage}
151
152 The package |nodetree| has four usage scenarios.
153 It can be used as a standalone Lua module, as a plain Lua\TeX{}, a
154 Lua\LaTeX{} package or as package to embed nodetree views in a
155 Lua\LaTeX{} document.
156
157 %-----------------------------------------------------------------------
158 %
159 %-----------------------------------------------------------------------
160
161 \newpage
162
163 \subsection{As a plain Lua\TeX{} package}
164
165 Run |luatex luatex-test.tex| for example to list the nodes using
166 Lua\TeX{}.
167
168 \begin{minted}{latex}
169 \input{nodetree.tex}
170 \NodetreeRegisterCallback{postline}
171
172 Lorem ipsum dolor.
173 \bye
174 \end{minted}
175
176 \subsubsection{Available macros}
177
178 \def\TmpTabularMacrosPlainTeX{
179 \cmd{\NodetreeRegisterCallback}\marg{callbacks} &
180 \TmpPageSecRef{sec:cmd:nodetree-register-callback} \\
181
182 \cmd{\NodetreeUnregisterCallback}\marg{callbacks} &
183 \TmpPageSecRef{sec:cmd:nodetree-unregister-callback} \\
184
185 \cmd{\NodetreeSetOption}\oarg{option}\marg{value} &
186 \TmpPageSecRef{sec:cmd:nodetree-set-option} \\
187
188 \cmd{\NodetreeResetOption}\marg{option} &
189 \TmpPageSecRef{sec:cmd:nodetree-reset-option} \\
190
191 \cmd{\NodetreeReset} &
192 \TmpPageSecRef{sec:cmd:nodetree-reset} \\
193 }
194
195 \begin{tabular}{ll}
196 \textbf{Macro name} &
197 \textbf{Reference} \\
198
199 \TmpTabularMacrosPlainTeX
200
201 \end{tabular}
202
203 \subsubsection{Available options}
204
205 \def\TmpTabularOptionsBase{\scantextokens{
206 |callback| &
207 \TmpPageSecRef{sec:option:callback} \\
208
209 |verbosity| &
210 \TmpPageSecRef{sec:option:verbosity} \\
211
212 |color| &
213 \TmpPageSecRef{sec:option:color} \\
214
215 |unit| &
216 \TmpPageSecRef{sec:option:unit} \\
217
218 |decimalplaces| &
219 \TmpPageSecRef{sec:option:decimalplaces} \\
220 }}
221
222 \begin{tabular}{ll}
223 \textbf{Option name} &
224 \textbf{Reference} \\
225
226 \TmpTabularOptionsBase
227
228 |channel| &
229 \TmpPageSecRef{sec:option:channel} \\
230 \end{tabular}
231
232 %-----------------------------------------------------------------------
233 %
234 %-----------------------------------------------------------------------
235
236 \newpage
237
238 \subsection{As a Lua\LaTeX{} package}
239
240 Run |lualatex lualatex-test.tex| to show a node tree using
241 Lua\LaTeX{}. In Lua\LaTeX{} you can omit a call to
242 |\NodetreeRegisterCallback{postline}|, since |\usepackage{nodetree}|
243 registers the |post_linebreak_filter| by default. Use
244 |\NodetreeUnregisterCallback{postline}| if you don’t want to debug the
245 |post_linebreak_filter|.
246
247 \begin{minted}{latex}
248 \documentclass{article}
249 \usepackage{nodetree}
250
251 \begin{document}
252 Lorem ipsum dolor.
253 \end{document}
254 \end{minted}
255
256 \subsubsection{Available macros}
257
258 \begin{tabular}{ll}
259 \textbf{Macro name} &
260 \textbf{Reference} \\
261
262 \TmpTabularMacrosPlainTeX
263
264 \cmd{\NodetreeSet}\marg{kv-options} &
265 \TmpPageSecRef{sec:cmd:nodetree-set} \\
266 \end{tabular}
267
268 \subsubsection{Available options}
269
270 \begin{tabular}{ll}
271 \textbf{Option name} &
272 \textbf{Reference} \\
273
274 \TmpTabularOptionsBase
275
276 |channel| &
277 \TmpPageSecRef{sec:option:channel} \\
278 \end{tabular}
279
280 %-----------------------------------------------------------------------
281 %
282 %-----------------------------------------------------------------------
283
284 \newpage
285
286 \subsection{As a Lua module}
287
288 Import the Lua module of the package inside
289 \mintinline{latex}{\directlua{}}
290 with this command:
291 \mintinline{lua}{local nodetree = require('nodetree')}.
292 Then use the Lua function
293 \mintinline{lua}{nodetree.print(head, options)}
294 to debug nodes inside your Lua code.
295
296 \begin{minted}{lua}
297 local nodetree = require('nodetree')
298
299 local rule1 = node.new('rule')
300 rule1.width = 20 * 65536
301 rule1.height = 10 * 65536
302 rule1.depth = 10 * 65536
303 nodetree.print(vbox)
304 \end{minted}
305
306 \noindent
307 The function \mintinline{lua}{nodetree.print()} takes as a second
308 argument a Lua table to configure the output.
309
310 \begin{minted}{lua}
311 nodetree.print(vbox, { verbosity = 2, unit = 'cm' })
312 \end{minted}
313
314 \noindent
315 These are the default options:
316
317 \begin{minted}{lua}
318 options = {
319 callback = 'post_linebreak_filter',
320 channel = 'term',
321 color = 'colored',
322 decimalplaces = 2,
323 unit = 'pt',
324 verbosity = 0,
325 firstline = 1,
326 lastline = -1,
327 }
328 \end{minted}
329
330 Options |firstline| and |lastline| only have an effect on function
331 \mintinline{lua}{nodetree.input(filename)}, which is used to implement
332 \cmd{\NodetreeEmbedInput} \TmpSecRef{sec:cmd:nodetree-embed-input}.
333
334 The following code snippet demonstrates the usage in Lua\TeX{}.
335 |head| is the current node.
336
337 \begin{minted}{latex}
338 \directlua{
339 local nodetree = require('nodetree')
340 local test = function (head)
341 nodetree.print(head)
342 end
343 callback.register('post_linebreak_filter', test)
344 }
345
346 Lorem ipsum dolor.
347 \bye
348 \end{minted}
349
350 \noindent
351 This example illustrates how the function has to be applied in
352 Lua\LaTeX{}.
353
354 \begin{minted}{latex}
355 \documentclass{article}
356 \usepackage{nodetree}
357
358 \begin{document}
359
360 \directlua{
361 local nodetree = require('nodetree')
362 local test = function (head)
363 nodetree.print(head)
364 end
365 luatexbase.add_to_callback('post_linebreak_filter', test, 'test')
366 }
367
368 Lorem ipsum dolor.
369 \end{document}
370 \end{minted}
371
372 %-----------------------------------------------------------------------
373 %
374 %-----------------------------------------------------------------------
375
376 \newpage
377 \subsection{The package \texttt{nodetree-embed}}
378
379 The single purpose of this auxiliary package is to provide a view
380 similar to a terminal (console) output.
381 This view mimics the output
382 of |nodetree| in a terminal.
383 The view can be embedded in a Lua\LaTeX{} file. You have to
384 compile documents using this embedded view with the option
385 |--shell-escape|.
386 The main environment of this package is |NodetreeEmbed|.
387 Markup
388 inside this environment is written into a temporary \LaTeX{} file.
389 This file is compiled in the background by |latexmk| and the
390 |nodetree| output is embedded into this view.
391 The following list shows each intermediate step:
392
393 \begin{enumerate}
394
395 \item |jobname.tex|
396
397 \begin{minted}{latex}
398 \begin{NodetreeEmbedEnv}
399 nodetree
400 \end{NodetreeEmbedEnv}
401 \end{minted}
402
403 \item |_nodetree-jobname/1.tex|
404
405 \begin{minted}{latex}
406 %!TEX program = lualatex
407 \documentclass{article}
408 \usepackage{nodetree}
409 \NodetreeSetOption[channel]{tex}
410 \NodetreeSetOption[verbosity]{0}
411 \NodetreeSetOption[unit]{pt}
412 \NodetreeSetOption[decimalplaces]{2}
413 \NodetreeUnregisterCallback{post_linebreak_filter}
414 \NodetreeRegisterCallback{post_linebreak_filter}
415 \begin{document}
416 nodetree
417 \end{document}
418 \end{minted}
419
420 \item |_nodetree-jobname/1.nttex|: This temporary Lua\LaTeX{} file is
421 compiled using |latexmk| and embedded in the environment |NodetreeEmbed|
422 (the trailing |\| character indicates line continuation).
423
424 \begin{minted}{latex}
425 Callback: \textcolor{NTEred}{post\_linebreak\_filter}\par
426 ------------------------------------------\par
427 \mbox{├─\textcolor{NTEmagentabright}{GLUE}\hspace{0.5em}(baselineskip)\
428 \textcolor{NTEyellow}{wd} 5.06\textcolor{NTEwhite}{pt}}\par
429 ...
430 \end{minted}
431
432 \item Finally the result:
433
434 \begin{NodetreeEmbedEnv}
435 nodetree
436 \end{NodetreeEmbedEnv}
437
438 \end{enumerate}
439
440 \subsubsection{Available macros}
441
442 \begin{tabular}{ll}
443 \textbf{Macro name} &
444 \textbf{Reference} \\
445
446 \TmpTabularMacrosPlainTeX
447
448 \cmd{\NodetreeSet}\marg{kv-options} &
449 \TmpPageSecRef{sec:cmd:nodetree-set} \\
450
451 \cmd{\NodetreeEmbedCmd}\oarg{kv-options}\marg{tex-markup} &
452 \TmpPageSecRef{sec:cmd:nodetree-embed-cmd} \\
453
454 \cmd{\NodetreeEmbedInput}\oarg{kv-options}\marg{nttex-file} &
455 \TmpPageSecRef{sec:cmd:nodetree-embed-input} \\
456 \end{tabular}
457
458 \subsubsection{Available environment}
459
460 \begin{tabular}{ll}
461 \textbf{Environment name} &
462 \textbf{Reference} \\
463
464 |\begin{NodetreeEmbedEnv}|\oarg{kv-options} & % |\end{NodetreeEmbedEnv}|
465 \TmpPageSecRef{sec:env:nodetree-embed-env} \\
466 \end{tabular}
467
468 \subsubsection{Available options}
469
470 \begin{tabular}{ll}
471 \textbf{Option name} &
472 \textbf{Reference} \\
473
474 \TmpTabularOptionsBase
475
476 |theme| &
477 \TmpPageSecRef{sec:option:theme} \\
478
479 |thememode| &
480 \TmpPageSecRef{sec:option:thememode} \\
481
482 |font| &
483 \TmpPageSecRef{sec:option:font} \\
484
485 |fontsize| &
486 \TmpPageSecRef{sec:option:fontsize} \\
487
488 |firstline| &
489 \TmpPageSecRef{sec:option:firstlastline} \\
490
491 |lastline| &
492 \TmpPageSecRef{sec:option:firstlastline} \\
493 \end{tabular}
494
495 %-----------------------------------------------------------------------
496 % Macros
497 %-----------------------------------------------------------------------
498 \newpage
499 \section{Macros}
500
501 %%
502 % \NodetreeRegisterCallback
503 %%
504
505 \subsection{\TmpMacroName{NodetreeRegisterCallback}}
506 \label{sec:cmd:nodetree-register-callback}
507
508 \DescribeMacro{\NodetreeRegisterCallback}
509 \cmd{\NodetreeRegisterCallback}\marg{callbacks}: Globally register
510 \marg{callbacks}, which is a comma-separated list of callback aliases
511 \TmpSecRef{sec:option:callback}.
512
513 %%
514 % \NodetreeUnregisterCallback
515 %%
516
517 \subsection{\TmpMacroName{NodetreeUnregisterCallback}}
518 \label{sec:cmd:nodetree-unregister-callback}
519
520 \DescribeMacro{\NodetreeUnregisterCallback}
521 \cmd{\NodetreeUnregisterCallback}\marg{callbacks}: Globally unregister
522 \marg{callbacks}, which is a separated list of callback aliases
523 \TmpSecRef{sec:option:callback}.
524
525 %%
526 % \NodetreeSetOption
527 %%
528
529 \subsection{\TmpMacroName{NodetreeSetOption}}
530 \label{sec:cmd:nodetree-set-option}
531
532 \DescribeMacro{\NodetreeSetOption}
533 \cmd{\NodetreeSetOption}\oarg{option}\marg{value}: Globally set a
534 single \oarg{option} to \marg{value} \TmpSecRef{sec:options}.
535
536 %%
537 % \NodetreeResetOption
538 %%
539
540 \subsection{\TmpMacroName{NodetreeResetOption}}
541 \label{sec:cmd:nodetree-reset-option}
542
543 \DescribeMacro{\NodetreeResetOption}
544 \cmd{\NodetreeResetOption}\marg{option}: Globally reset a single
545 \marg{option} to its default value \TmpSecRef{sec:options}.
546
547 %%
548 % \NodetreeSet
549 %%
550
551 \subsection{\TmpMacroName{NodetreeSet}}
552 \label{sec:cmd:nodetree-set}
553
554 \DescribeMacro{\NodetreeSet}
555 \cmd{\NodetreeSet}\marg{kv-options}: Globally set multiple options at
556 once. It can only be used along with Lua\LaTeX{}. \marg{kv-options}
557 are key-value pairs.
558
559 \begin{code}
560 \NodetreeSet{color=no,callbacks={hpack,vpack},verbosity=2}
561 \end{code}
562
563 %%
564 % \NodetreeReset
565 %%
566
567 \subsection{\TmpMacroName{NodetreeReset}}
568 \label{sec:cmd:nodetree-reset}
569
570 \DescribeMacro{\NodetreeReset}
571 \cmd{\NodetreeReset}: Globally reset multiple options to their default
572 values.
573
574 %%
575 %
576 %%
577
578 \subsection{\TmpMacroName{NodetreeEmbedCmd}}
579 \label{sec:cmd:nodetree-embed-cmd}
580
581 \DescribeMacro{\NodetreeEmbedCmd}
582 \cmd{\NodetreeEmbedCmd}\oarg{kv-options}\marg{tex-markup}:
583
584 Main macro (cmd) to evaluate some \TeX{} markup and generate a
585 node tree from it. See environment version
586 \TmpSecRef{sec:cmd:nodetree-embed-cmd}. Uses |xparse|'s |+v| option to
587 grab the verbatim content. \marg{kv-options} are key-value pairs and
588 set locally only.
589
590 Only available in package |nodetree-embed|; you need option
591 |--shell-escape|.
592
593 %%
594 % \NodetreeEmbedInput
595 %%
596
597 \subsection{\TmpMacroName{NodetreeEmbedInput}}
598 \label{sec:cmd:nodetree-embed-input}
599
600 \DescribeMacro{\NodetreeEmbedInput}
601 \cmd{\NodetreeEmbedInput}\oarg{kv-options}\marg{nttex-file}: The path or
602 file name of the |*.nttex| file without the extension.
603 \marg{kv-options} are key-value pairs and set locally only.
604
605 Only available in package |nodetree-embed|. This command works without
606 option |--shell-escape|.
607
608 %-----------------------------------------------------------------------
609 % Environments
610 %-----------------------------------------------------------------------
611
612 \newpage
613 \section{Environments}
614
615 \subsection{\texttt{NodetreeEmbedEnv}}
616 \label{sec:env:nodetree-embed-env}
617
618 \DescribeEnv{NodetreeEmbedEnv}
619 |\begin{NodetreeEmbedEnv}|\oarg{kv-options}\\
620 \dots{} \textit{\TeX{} markup for evaluation} \dots\\
621 |\end{NodetreeEmbedEnv}|
622
623 Main environment (env) to evaluate some \TeX{} markup and generate a
624 node tree from it. See command version
625 \TmpSecRef{sec:cmd:nodetree-embed-cmd}. Uses the \cmd{\detokenize}
626 command to grab the verbatim content. \marg{kv-options} are key-value
627 pairs and set locally only.
628
629 Only available in package |nodetree-embed|; you need option
630 |--shell-escape|.
631
632 %-----------------------------------------------------------------------
633 % Options
634 %-----------------------------------------------------------------------
635 \newpage
636 \section{Options}
637 \label{sec:options}
638
639 %%
640 % callback
641 %%
642
643 \subsection{Option \texttt{callback}}
644 \label{sec:option:callback}
645
646 The option |callback| is the most important setting of the package. It
647 is possible to specify an alias to select the callback. Take a look at
648 the overview of callbacks (\rightarrow{} Figure~\ref{fig:callback}).
649 |nodetree| supports all node-related callbacks as listed in the
650 Lua\TeX{} reference manual.
651
652 These macros process callback options:
653
654 \begin{quote}
655 \cmd{\NodetreeRegisterCallback}\marg{callbacks}\\
656 \cmd{\NodetreeUnregisterCallback}\marg{callbacks}\\
657 \cmd{\NodetreeSet}\marg{callback=<callbacks>}\\
658 \cmd{\usepackage}\oarg{callback=<callbacks>}\marg{nodetree}
659 \end{quote}
660
661 The |nodetree| package can watch the node tree before and after the
662 functions of a callback are executed: It is possible to prepend and/or
663 append a colon (|:|) to indicate the desired watchpoint position,
664 which defaults to 'before' if no colon is used.
665
666 Use commas to specify multiple callbacks; trailing and leading
667 whitespace is ignored. For example, this call
668
669 \begin{code}
670 \NodetreeRegisterCallback{:preline, line, :postline:}
671 \end{code}
672
673 \noindent
674 watches the node tree before the |preline| callback functions, before
675 the |line| callback functions, and before and after the |postline|
676 callback functions. In case there are no callback functions
677 registered for one of the |hyphenate|, |kerning|, |ligaturing|, and
678 |mlist_to_hlist| callbacks, Lua\TeX{} executes some internal code
679 instead. It thus makes sense to watch the node tree before and after
680 these (empty) callbacks even in this case.
681
682 Wrap your callback aliases in curly braces for the macro
683 |\NodetreeSet|. Note that no whitespace between |=| and |{| is
684 allowed.
685
686 \begin{code}
687 \NodetreeSet{callback={:preline, line, :postline:}}
688 \end{code}
689
690 The same applies for the macro |\usepackage|:
691
692 \begin{code}
693 \usepackage{callback={:preline, line, :postline:}}
694 \end{code}
695
696 The callbacks in Figure~\ref{fig:callback} are listed in the same
697 order as in the Lua\TeX{} reference manual. Note that the |ligaturing|
698 and |kerning| callbacks only have an effect on ligatures and kernings,
699 respectively, if the |luaotfload| package (which is the default for
700 Lua\LaTeX{}, and an optional package for Lua\TeX{}) handles the
701 affected font with |mode=base| (see the
702 \href{http://mirrors.ctan.org/macros/luatex/generic/luaotfload/luaotfload-latex.pdf}
703 {documentation} for more details).
704
705 %%
706 % Tabular callbacks
707 %%
708
709 \newcommand{\TmpCallbackRow}[3]{
710 \TmpLuaCodeInline{#1} & \TmpLuaCodeInline{#2} & \TmpLuaCodeInline{\footnotesize#3} \\
711 }
712
713 \begin{figure}
714 \begin{tabular}{lll}
715 \textbf{Callback} & \textbf{Alias} & \textbf{Alias (longer)} \\
716 \TmpCallbackRow{contribute_filter}
717 {contribute}
718 {contributefilter}
719
720 \TmpCallbackRow{buildpage_filter}
721 {buildfilter} %
722 {buildpagefilter}
723
724 % new
725 \TmpCallbackRow{build_page_insert}
726 {buildinsert}
727 {buildpageinsert}
728
729 \TmpCallbackRow{pre_linebreak_filter}
730 {preline}
731 {prelinebreakfilter}
732
733 \TmpCallbackRow{linebreak_filter}
734 {line}
735 {linebreakfilter}
736
737 \TmpCallbackRow{append_to_vlist_filter}
738 {append}
739 {appendtovlistfilter}
740
741 \TmpCallbackRow{post_linebreak_filter}
742 {postline}
743 {postlinebreakfilter}
744
745 \TmpCallbackRow{hpack_filter}
746 {hpack}
747 {hpackfilter}
748
749 \TmpCallbackRow{vpack_filter}
750 {vpack}
751 {vpackfilter}
752
753 \TmpCallbackRow{hpack_quality}
754 {hpackq}
755 {hpackquality}
756
757 \TmpCallbackRow{vpack_quality}
758 {vpackq}
759 {vpackquality}
760
761 \TmpCallbackRow{process_rule}
762 {process}
763 {processrule}
764
765 \TmpCallbackRow{pre_output_filter}
766 {preout}
767 {preoutputfilter}
768
769 \TmpCallbackRow{hyphenate}
770 {hyph}
771 {}
772
773 \TmpCallbackRow{ligaturing}
774 {liga}
775 {}
776
777 \TmpCallbackRow{kerning}
778 {kern}
779 {}
780
781 \TmpCallbackRow{insert_local_par}
782 {insert}
783 {insertlocalpar}
784
785 \TmpCallbackRow{mlist_to_hlist}
786 {mhlist}
787 {mlisttohlist}
788 \end{tabular}
789
790 \caption{The callback aliases}
791 \label{fig:callback}
792 \end{figure}
793
794 %%
795 % channel
796 %%
797
798 \subsection{Option \texttt{channel}}
799 \label{sec:option:channel}
800
801 You can select the debug output channel with this option. The default
802 value for the option |channel| is |term|, which displays the node tree in
803 the current terminal. Specify |log| and the package creates a log file
804 named |<jobname>.ntlog|. Specify |tex| and a log file named
805 |<jobname>.nttex| is created. |nt...| stands for |nodetree|.
806 |<jobname>| is the basename of your file you want to debug. The debug
807 channel is only useful for the auxiliary package |nodetree-embed|. Paste
808 the markup in the environment |NodetreeEmbedView| and you get a
809 terminal-like view in your document.
810
811 %%
812 % verbosity
813 %
814
815 \subsection{Option \texttt{verbosity}}
816 \label{sec:option:verbosity}
817
818 Higher integer values result in a more verbose output. The default value
819 for this option is~|0|. At the moment verbosity levels |0| to~|3| are
820 implemented.
821
822 \def\TmpExampleVerbosity#1{
823 \subsubsection{Example: \texttt{verbosity=#1}}
824 \begin{NodetreeEmbedEnv}[verbosity=#1,callback=pre_linebreak_filter,
825 fontsize=\fontsize{5.5}{6.6}\selectfont]
826 .
827 \end{NodetreeEmbedEnv}
828 }
829
830 \TmpExampleVerbosity{0}
831 \TmpExampleVerbosity{1}
832 \TmpExampleVerbosity{2}
833 \TmpExampleVerbosity{3}
834
835 %%
836 % color
837 %%
838
839 \subsection{Option \texttt{color}}
840 \label{sec:option:color}
841
842 The default option for |color| is |colored|. Use any other string (for
843 example |none| or |no|) to disable the colored terminal output of the
844 package.
845
846 \begin{code}
847 \usepackage[color=no]{nodetree}
848 \end{code}
849
850 %%
851 % unit
852 %%
853
854 \subsection{Option \texttt{unit}}
855 \label{sec:option:unit}
856
857 The option |unit| sets the length unit to display all length values of
858 the nodes. The default option for |unit| is |pt|. See figures
859 \ref{fig:fixed-units} and~\ref{fig:relative-units} for possible values.
860
861 \begin{figure}
862 \begin{tabular}{lp{10cm}}
863 \textbf{Unit} &
864 \textbf{Description} \\
865
866 pt &
867 Point 1/72.27 inch. The conversion to metric units, to two decimal
868 places, is 1 point = 2.85 mm = 28.45 cm. \\
869
870 pc &
871 Pica, 12 pt \\
872
873 in &
874 Inch, 72.27 pt \\
875
876 bp &
877 Big point, 1/72 inch. This length is the definition of a point in
878 PostScript and many desktop publishing systems. \\
879
880 cm &
881 Centimeter \\
882
883 mm &
884 Millimeter \\
885
886 dd &
887 Didot point, 1.07 pt \\
888
889 cc &
890 Cicero, 12 dd \\
891
892 sp &
893 Scaled point, 1/65536 pt \\
894 \end{tabular}
895 \caption{Fixed units}
896 \label{fig:fixed-units}
897 \end{figure}
898
899 \begin{figure}
900 \begin{tabular}{lp{10cm}}
901 \textbf{Unit} &
902 \textbf{Description} \\
903
904 ex &
905 x-height of the current font \\
906
907 em &
908 Width of the capital letter M \\
909 \end{tabular}
910 \caption{Relative units}
911 \label{fig:relative-units}
912 \end{figure}
913
914 \def\TmpExampleUnit#1{
915 \subsubsection{Example: \texttt{unit=#1}}
916 \begin{NodetreeEmbedEnv}[unit=#1,callback=pre_linebreak_filter]
917 Lorem.
918 \end{NodetreeEmbedEnv}
919 }
920
921 \TmpExampleUnit{pt}
922 \TmpExampleUnit{sp}
923 \TmpExampleUnit{cm}
924
925 %%
926 % decimalplaces
927 %%
928
929 \subsection{Option \texttt{decimalplaces}}
930 \label{sec:option:decimalplaces}
931
932 The options |decimalplaces| sets the number of decimal places for some
933 node fields. If |decimalplaces| is set to |0| only integer values are shown.
934
935 \begin{code}
936 \NodetreeSetOption[decimalplaces]{4}
937 \end{code}
938
939 \def\TmpExampleDecimalplaces#1{
940 \subsubsection{Example: \texttt{decimalplaces=#1}}
941 \begin{NodetreeEmbedEnv}[unit=cc,decimalplaces=#1,callback=pre_linebreak_filter]
942 Lorem.
943 \end{NodetreeEmbedEnv}
944 }
945
946 \TmpExampleDecimalplaces{0}
947 \TmpExampleDecimalplaces{2}
948 \TmpExampleDecimalplaces{5}
949
950 %%
951 % theme and thememode
952 %%
953
954 \def\TmpExampleTheme#1#2{
955 \subsubsection{Example: \texttt{theme=#1} \texttt{thememode=#2}}
956 \begin{NodetreeEmbedEnv}[callback=pre_linebreak_filter,theme=#1,thememode=#2,fontsize=\small]
957 .
958 \end{NodetreeEmbedEnv}
959 }
960
961 \subsection{Option \texttt{theme} and \texttt{thememode}}
962 \label{sec:option:theme}
963 \label{sec:option:thememode}
964
965 % bw
966 \TmpExampleTheme{bwdark}{dark}
967 \TmpExampleTheme{bwlight}{light}
968
969 % monokaisoda
970 \TmpExampleTheme{monokaisoda}{dark}
971 \TmpExampleTheme{monokaisoda}{light}
972
973 %%
974 % font
975 %%
976
977 \subsection{Option \texttt{font}}
978 \label{sec:option:font}
979
980 \NodetreeSet{fontsize=\footnotesize}
981
982 \def\TmpExampleFont#1{
983 \subsubsection{Example: \texttt{font=\{#1\}}}
984 \begin{NodetreeEmbedEnv}[font={#1}]
985 .
986 \end{NodetreeEmbedEnv}
987 }
988
989 |nodetree-embed| passes the option |font| down to the
990 command |\setmonofont{}| of the |fontspec| package. The used font
991 should be monospaced and have some box drawing glyphs (see
992 table~\ref{fig:unicode}).
993
994 \TmpExampleFont{Liberation Mono}
995 \TmpExampleFont{Ubuntu Mono}
996
997 %%
998 % fontsize
999 %%
1000
1001 \subsection{Option \texttt{fontsize}}
1002 \label{sec:option:fontsize}
1003
1004 \def\TmpExampleFontSize#1{
1005 \subsubsection{Example: \TmpMacroName{#1}}
1006 \begin{NodetreeEmbedEnv}[callback=pre_linebreak_filter,
1007 fontsize=\csname #1\endcsname]
1008 .
1009 \end{NodetreeEmbedEnv}
1010 }
1011
1012 \TmpExampleFontSize{small}
1013 \TmpExampleFontSize{tiny}
1014
1015 \subsection{Options \texttt{firstline} and \texttt{lastline}}
1016 \label{sec:option:firstlastline}
1017
1018 These two options are for function \cmd{\NodetreeEmbedInput} only
1019 \TmpSecRef{sec:cmd:nodetree-embed-input}. They specify the first
1020 and last shown line of the read |*.nttex| file. Values |1|, |2|,
1021 \ldots, corresponds to the first line, second, line, etc. Values
1022 |-1|, |-2|, \ldots, correspond to the last line, the line before the
1023 last line, etc. The default values are |firstline = 1| and
1024 |lastline = -1| to display the whole file.
1025
1026 %-----------------------------------------------------------------------
1027 % Visual tree structure
1028 %-----------------------------------------------------------------------
1029 \newpage
1030 \section{Visual tree structure}
1031
1032 %%
1033 % Two different connections
1034 %%
1035
1036 \subsection{Two different connections}
1037
1038 Nodes in Lua\TeX{} are connected. The |nodetree| package distinguishes
1039 between \emph{list} and \emph{field} connections.
1040
1041 \begin{itemize}
1042 \item list: Nodes that are doubly connected by |next| and
1043 |previous| fields.
1044 \item field: Connections to nodes by other fields than |next| and
1045 |previous|, for example, using |head| and |pre|.
1046 \end{itemize}
1047
1048 %%
1049 % Unicode characters
1050 %%
1051
1052 \subsection{Unicode characters to show the tree view}
1053
1054 \renewcommand{\arraystretch}{1.5}
1055
1056 The package |nodetree| uses the unicode box drawing symbols. Your
1057 default terminal font should contain this characters to obtain the tree
1058 view. Eight box drawing characters are necessary.
1059
1060 \begin{figure}
1061 {
1062 \fontspec{DejaVu Sans Mono}
1063 \begin{tabular}{lcl}
1064 \textbf{Code} & \textbf{Character} & \textbf{Name} \\
1065 U+2500 & ─ & BOX DRAWINGS LIGHT HORIZONTAL \\
1066 U+2502 & │ & BOX DRAWINGS LIGHT VERTICAL \\
1067 U+2514 & └ & BOX DRAWINGS LIGHT UP AND RIGHT \\
1068 U+251C & ├ & BOX DRAWINGS LIGHT VERTICAL AND RIGHT \\
1069 U+2550 & ═ & BOX DRAWINGS DOUBLE HORIZONTAL \\
1070 U+2551 & ║ & BOX DRAWINGS DOUBLE VERTICAL \\
1071 U+255A & ╚ & BOX DRAWINGS DOUBLE UP AND RIGHT \\
1072 U+2560 & ╠ & BOX DRAWINGS DOUBLE VERTICAL AND RIGHT \\
1073 \end{tabular}
1074 }
1075 \caption{The Unicode box drawings glyphs}
1076 \label{fig:unicode}
1077 \end{figure}
1078
1079 \noindent
1080 For |list| connections \emph{light} characters are shown.
1081
1082 {
1083 \setmonofont{DejaVu Sans Mono}
1084 \begin{code}
1085 │ │
1086 │ ├─list1
1087 │ └─list2
1088 └─list3
1089 \end{code}
1090 }
1091
1092 \noindent
1093 |field| connections are visialized by \emph{Double} characters.
1094
1095 {
1096 \setmonofont{DejaVu Sans Mono}
1097 \begin{code}
1098 ║ ║
1099 ║ ╠═field1
1100 ║ ╚═field2
1101 ╚═field3
1102 \end{code}
1103 }
1104
1105 %-----------------------------------------------------------------------
1106 % Examples
1107 %-----------------------------------------------------------------------
1108 \newpage
1109 \section{Examples}
1110
1111 This section lists some examples of the |nodetree| output.
1112
1113 %%
1114 % packagename
1115 %%
1116
1117 \subsection{The node list of the package name}
1118
1119 \begin{NodetreeEmbedEnv}[showmarkup=true,callback=post_linebreak_filter]
1120 nodetree
1121 \end{NodetreeEmbedEnv}
1122
1123 %%
1124 % math
1125 %%
1126
1127 \subsection{The node list of a mathematical formula}
1128
1129 \begin{NodetreeEmbedEnv}[showmarkup=true,callback=post_linebreak_filter]
1130 $1+2$
1131 \end{NodetreeEmbedEnv}
1132
1133 %%
1134 % ligatures
1135 %%
1136
1137 \subsection{The node list of the word \emph{Office}}
1138
1139 The characters \emph{ffi} are deeply nested in a discretionary node.
1140
1141 \begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=0]
1142 Office
1143 \end{NodetreeEmbedEnv}
1144
1145 %-----------------------------------------------------------------------
1146 % Node types
1147 %-----------------------------------------------------------------------
1148
1149 \section{Node types}
1150
1151 This section shows some node types in a |nodetree| view.
1152
1153 \newcommand{\TmpHeadingNodeTypeSub}[4]{
1154 \subsection{Type \texttt{#1(#2)}, subtype \texttt{#3(#4)}}
1155 }
1156
1157 \newcommand{\TmpNodeTypeSub}[6]{
1158 \subsection{Type \texttt{#1(#2)}, subtype \texttt{#3\_#4(#5)}}
1159 \TmpVerbExample{#2#1#5#3#4}{#6}
1160 }
1161
1162 \newcommand{\TmpHeadingNodeType}[2]{
1163 \subsection{Type \texttt{#1(#2)}}
1164 }
1165
1166 %%
1167 %
1168 %%
1169
1170 \TmpHeadingNodeTypeSub{hlist}{0}{line}{1}
1171
1172 \begin{NodetreeEmbedEnv}[showmarkup=true]
1173 Lorem
1174 \end{NodetreeEmbedEnv}
1175
1176 %%
1177 %
1178 %%
1179
1180 \TmpHeadingNodeTypeSub{hlist}{0}{box}{2}
1181
1182 \begin{NodetreeEmbedEnv}[showmarkup=true]
1183 L\hbox to 40pt{ore}m
1184 \end{NodetreeEmbedEnv}
1185
1186 %%
1187 %
1188 %%
1189
1190 \TmpHeadingNodeTypeSub{hlist}{0}{indent}{3}
1191
1192 \begin{NodetreeEmbedEnv}[showmarkup=true,unit=cm]
1193 \setlength{\parindent}{5cm}
1194 I
1195 \end{NodetreeEmbedEnv}
1196
1197 %%
1198 %
1199 %%
1200
1201 \TmpHeadingNodeType{vlist}{1}
1202
1203 \begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=1]
1204 L\vbox to 40pt{O}L
1205 \end{NodetreeEmbedEnv}
1206
1207 %%
1208 %
1209 %%
1210
1211 \TmpHeadingNodeType{rule}{2}
1212
1213 \begin{NodetreeEmbedEnv}[showmarkup=true,unit=mm]
1214 \rule[-2mm]{10mm}{4mm}
1215 \end{NodetreeEmbedEnv}
1216
1217 %%
1218 %
1219 %%
1220
1221 \TmpHeadingNodeType{mark}{4}
1222
1223 \begin{NodetreeEmbedEnv}[showmarkup=true,callback=pre_output_filter]
1224 \mark{Lorem}.
1225 \end{NodetreeEmbedEnv}
1226
1227 %%
1228 %
1229 %%
1230
1231 \TmpHeadingNodeTypeSub{disc}{7}{discretionary}{0}
1232
1233 \begin{NodetreeEmbedEnv}[showmarkup=true]
1234 L\discretionary{}{}{}L
1235 \end{NodetreeEmbedEnv}
1236
1237 %%
1238 %
1239 %%
1240
1241 \TmpHeadingNodeTypeSub{disc}{7}{explicit}{1}
1242
1243 \begin{NodetreeEmbedEnv}[showmarkup=true]
1244 L\-O\-L
1245 \end{NodetreeEmbedEnv}
1246
1247 %%
1248 %
1249 %%
1250
1251 \TmpHeadingNodeTypeSub{disc}{7}{regular}{3}
1252
1253 \begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=0]
1254 Office
1255 \end{NodetreeEmbedEnv}
1256
1257 %%
1258 %
1259 %%
1260
1261 \TmpNodeTypeSub{whatsit}{8}{pdf}{action}{22}{\fontsize{5.5}{6.6}\selectfont}
1262 \TmpNodeTypeSub{whatsit}{8}{pdf}{colorstack}{28}{\footnotesize}
1263
1264 %%
1265 %
1266 %%
1267
1268 \TmpHeadingNodeType{dir}{10}
1269
1270 \begin{NodetreeEmbedEnv}[showmarkup=true]
1271 \textdir TRT nur {\textdir TLT run \textdir TRT NUR} nur
1272 \end{NodetreeEmbedEnv}
1273
1274 %%
1275 %
1276 %%
1277
1278 \TmpHeadingNodeTypeSub{glue}{12}{baselineskip}{2}
1279
1280 \NodetreeEmbedCmd[showmarkup=true,unit=cm]{
1281 \baselineskip=5cm
1282 Lorem
1283
1284 Lorem
1285 }
1286
1287 %%
1288 %
1289 %%
1290
1291 \TmpHeadingNodeTypeSub{glue}{12}{parskip}{3}
1292
1293 \NodetreeEmbedCmd[showmarkup=true,callback=pre_output_filter]{
1294 \parskip=5cm
1295 Lorem
1296
1297 Lorem
1298 }
1299
1300 %%
1301 %
1302 %%
1303
1304 \TmpHeadingNodeTypeSub{glue}{12}{spaceskip}{13}
1305
1306 \begin{NodetreeEmbedEnv}[showmarkup=true]
1307 \spaceskip=5cm
1308 a a
1309 \end{NodetreeEmbedEnv}
1310
1311 %%
1312 %
1313 %%
1314
1315 \TmpHeadingNodeTypeSub{glue}{12}{leaders}{100}
1316
1317 \begin{NodetreeEmbedEnv}[showmarkup=true]
1318 a \leavevmode\leaders\hbox{ . }\hfill\kern0pt a
1319 \end{NodetreeEmbedEnv}
1320
1321 %%
1322 %
1323 %%
1324
1325 \TmpHeadingNodeTypeSub{glue}{12}{cleaders}{101}
1326
1327 \begin{NodetreeEmbedEnv}[showmarkup=true]
1328 a \leavevmode\cleaders\hbox{ . }\hfill\kern0pt a
1329 \end{NodetreeEmbedEnv}
1330
1331 %%
1332 %
1333 %%
1334
1335 \TmpHeadingNodeTypeSub{glue}{12}{xleaders}{102}
1336
1337 \begin{NodetreeEmbedEnv}[showmarkup=true]
1338 a \leavevmode\xleaders\hbox{ . }\hfill\kern0pt a
1339 \end{NodetreeEmbedEnv}
1340
1341 %%
1342 %
1343 %%
1344
1345 \TmpHeadingNodeTypeSub{glue}{12}{gleaders}{102}
1346
1347 \begin{NodetreeEmbedEnv}[showmarkup=true]
1348 a \leavevmode\gleaders\hbox{ . }\hfill\kern0pt a
1349 \end{NodetreeEmbedEnv}
1350
1351 %%
1352 %
1353 %%
1354
1355 \TmpHeadingNodeTypeSub{kern}{13}{userkern}{0}
1356
1357 \begin{NodetreeEmbedEnv}[showmarkup=true]
1358 a\kern2pt
1359 \end{NodetreeEmbedEnv}
1360
1361 %%
1362 %
1363 %%
1364
1365 \TmpHeadingNodeTypeSub{kern}{13}{fontkern}{1}
1366
1367 \begin{NodetreeEmbedEnv}[showmarkup=true]
1368 Ve
1369 \end{NodetreeEmbedEnv}
1370
1371 %%
1372 %
1373 %%
1374
1375 \TmpHeadingNodeTypeSub{kern}{13}{accentkern}{2}
1376
1377 \begin{NodetreeEmbedEnv}[showmarkup=true]
1378 \accent96 a
1379 \end{NodetreeEmbedEnv}
1380
1381 %%
1382 %
1383 %%
1384
1385 \TmpHeadingNodeTypeSub{kern}{13}{italiccorrection}{3}
1386
1387 \begin{NodetreeEmbedEnv}[showmarkup=true]
1388 \textit{L}\/OL
1389 \end{NodetreeEmbedEnv}
1390
1391 %%
1392 %
1393 %%
1394
1395 \TmpHeadingNodeType{penalty}{14}
1396
1397 \begin{NodetreeEmbedEnv}[showmarkup=true]
1398 L \penalty 23 OL
1399 \end{NodetreeEmbedEnv}
1400
1401 %%
1402 %
1403 %%
1404
1405 \TmpHeadingNodeType{glyph}{29}
1406
1407 \begin{NodetreeEmbedEnv}[showmarkup=true]
1408 abc
1409 \end{NodetreeEmbedEnv}
1410
1411 %%
1412 %
1413 %%
1414
1415 % It seems that 'attribute' nodes don't appear in node trees.
1416 %
1417 % \TmpHeadingNodeType{attribute}{38}
1418 %
1419 % \begin{NodetreeEmbedEnv}[showmarkup=true]
1420 % {\attribute0=1 A}
1421 % \end{NodetreeEmbedEnv}
1422
1423 %%
1424 %
1425 %%
1426
1427 \TmpHeadingNodeType{attributelist}{40}
1428
1429 \begin{NodetreeEmbedEnv}[showmarkup=true,callback=hpackfilter]
1430 {\attribute0=1 A}
1431 \end{NodetreeEmbedEnv}
1432
1433 \DocInput{nodetree.dtx}
1434
1435 \subsection{The file \texttt{nodetree.lua}}
1436
1437 % Compilation failure:
1438 % lualatex: ../../../texk/web2c/luatexdir/lang/texlang.c:986: hnj_hyphenation: Assertion `(((varmem[(wordstart)].hh.u.B1) & (1 << 0)) && !((varmem[(wordstart)].hh.u.B1) & (1 << 1) ) && !((varmem[(wordstart)].hh.u.B1) & (1 << 2) ))' failed
1439 % \inputminted{lua}{nodetree.lua}
1440 There is a source code documentation of the file nodetree.lua compiled
1441 with Ldoc on Github:
1442 \url{http://josef-friedrich.github.io/nodetree/}
1443
1444 \end{document}