diff options
Diffstat (limited to 'Master/texmf-dist/doc/luatex/nodetree/nodetree-doc.tex')
-rw-r--r-- | Master/texmf-dist/doc/luatex/nodetree/nodetree-doc.tex | 1444 |
1 files changed, 1444 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/luatex/nodetree/nodetree-doc.tex b/Master/texmf-dist/doc/luatex/nodetree/nodetree-doc.tex new file mode 100644 index 00000000000..d9531ad9f25 --- /dev/null +++ b/Master/texmf-dist/doc/luatex/nodetree/nodetree-doc.tex @@ -0,0 +1,1444 @@ +%!TEX program = lualatex +\documentclass{ltxdoc} +\usepackage{paralist,fontspec,microtype} +\usepackage[ + colorlinks=true, + linkcolor=red, + filecolor=red, + urlcolor=red, +]{hyperref} +\usepackage{nodetree-embed} +\mdfsetup{ + innerleftmargin=0.2em, + innerrightmargin=0.2em, +} +\EnableCrossrefs +\CodelineIndex +\RecordChanges + +% Improve ltxdoc's `|...|` feature by allowing breaks. +\usepackage{fvextra} +\fvset{breaklines=true,breakbefore=.-_} +\AtBeginDocument{\DefineShortVerb{\|}} + +% We use 'pmboxdraw' to draw box elements in minted environments. + +% https://tex.stackexchange.com/questions/281368/print-box-drawing-characters-with-pdflatex/355403#355403 +\usepackage{pmboxdraw} +\begingroup + \def\DeclareUnicodeCharacter#1{% + \begingroup + \lccode`\~="#1\relax + \lowercase{\endgroup + \global\catcode`~=\active + \gdef~% + }% + }% + \input{pmboxdrawenc.dfu}% +\endgroup + +% https://tex.stackexchange.com/questions/108127/block-element-characters-pmboxdraw-are-shown-too-wide-in-verbatim-and-verbatim +\pmboxdrawsetup{ + Block/box={\texttt{0}}, +} + +\usepackage{minted} +\usemintedstyle{colorful} +\BeforeBeginEnvironment{minted}{\begin{mdframed}[backgroundcolor=gray!3]} +\AfterEndEnvironment{minted}{\end{mdframed}} +\setminted{ + breaklines=true, + fontsize=\footnotesize, +} +\setmintedinline{ + fontsize=auto +} + +\def\TmpLuaCodeInline#1{\texttt{\scantokens{\catcode`\_=12\relax#1}}} + +\def\TmpSecRef#1{(\rightarrow\ \ref{#1})} + +\def\TmpPageSecRef#1{ + Page + \pageref{#1}, + Section + \ref{#1} +} + +\newcommand{\TmpExample}[2]{ +\begin{NodetreeEmbedView}[fontsize=#2] +\input{examples/#1.nttex} +\end{NodetreeEmbedView} +} + +\newcommand{\TmpVerbExample}[2]{ +\VerbatimInput[firstline=4]{examples/#1.tex} +\TmpExample{#1}{#2} +} + +\newcommand\TmpMacroName[1]{% + \texorpdfstring{\cs{#1}}{\textbackslash #1}% +} + +\DefineVerbatimEnvironment{code}{Verbatim} +{ + frame=single, + fontsize=\footnotesize, +} + +\newcommand{\TmpLuaFunction}[1]{ + \marginpar{% + \raggedleft% + \MacroFont% + \texttt{% + \scantokens{\catcode`\_=12\relax#1}% + }% + }% +} + +\begin{document} + +\providecommand*{\url}{\texttt} +\GetFileInfo{nodetree.dtx} +\title{The \textsf{nodetree} package} +\author{% + Josef Friedrich\\% + \url{josef@friedrich.rocks}\\% + \href{https://github.com/Josef-Friedrich/nodetree}{github.com/Josef-Friedrich/nodetree}\\% + with contributions by Werner Lemberg +} +\date{v2.3.0 from 2023/09/10} + +\maketitle + +\begin{NodetreeEmbedEnv} +nodetree +\end{NodetreeEmbedEnv} + +\newpage + +\tableofcontents + +\newpage + +%----------------------------------------------------------------------- +% Abstract +%----------------------------------------------------------------------- + +\section{Abstract} + +|nodetree| is a Lua\TeX{} development package for both plain \TeX{} +and \LaTeX{} that visualizes the structure of node lists while +compiling with the \TeX{} engine. It uses a visual representation of +node lists similar to the UNIX |tree| command’s output for folder +trees. The processed document isn’t changed. + +The tree view can be emitted to the console, to a log file, or as a +\LaTeX{} input file. Its appearance is highly customizable; multiple +color and B/W themes together with various levels of verbosity are +provided. + +Node lists are the main building blocks of the \TeX{} engine, which +Lua\TeX{} allows to inspect and modify. |nodetree| is inspired by a +\href{https://gist.github.com/pgundlach/556247} {gist from Patrick + Gundlach}. + +%----------------------------------------------------------------------- +% Usage +%----------------------------------------------------------------------- + +\section{Usage} + +The package |nodetree| has four usage scenarios. +It can be used as a standalone Lua module, as a plain Lua\TeX{}, a +Lua\LaTeX{} package or as package to embed nodetree views in a +Lua\LaTeX{} document. + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\newpage + +\subsection{As a plain Lua\TeX{} package} + +Run |luatex luatex-test.tex| for example to list the nodes using +Lua\TeX{}. + +\begin{minted}{latex} +\input{nodetree.tex} +\NodetreeRegisterCallback{postline} + +Lorem ipsum dolor. +\bye +\end{minted} + +\subsubsection{Available macros} + +\def\TmpTabularMacrosPlainTeX{ +\cmd{\NodetreeRegisterCallback}\marg{callbacks} & +\TmpPageSecRef{sec:cmd:nodetree-register-callback} \\ + +\cmd{\NodetreeUnregisterCallback}\marg{callbacks} & +\TmpPageSecRef{sec:cmd:nodetree-unregister-callback} \\ + +\cmd{\NodetreeSetOption}\oarg{option}\marg{value} & +\TmpPageSecRef{sec:cmd:nodetree-set-option} \\ + +\cmd{\NodetreeResetOption}\marg{option} & +\TmpPageSecRef{sec:cmd:nodetree-reset-option} \\ + +\cmd{\NodetreeReset} & +\TmpPageSecRef{sec:cmd:nodetree-reset} \\ +} + +\begin{tabular}{ll} +\textbf{Macro name} & +\textbf{Reference} \\ + +\TmpTabularMacrosPlainTeX + +\end{tabular} + +\subsubsection{Available options} + +\def\TmpTabularOptionsBase{\scantextokens{ +|callback| & +\TmpPageSecRef{sec:option:callback} \\ + +|verbosity| & +\TmpPageSecRef{sec:option:verbosity} \\ + +|color| & +\TmpPageSecRef{sec:option:color} \\ + +|unit| & +\TmpPageSecRef{sec:option:unit} \\ + +|decimalplaces| & +\TmpPageSecRef{sec:option:decimalplaces} \\ +}} + +\begin{tabular}{ll} +\textbf{Option name} & +\textbf{Reference} \\ + +\TmpTabularOptionsBase + +|channel| & +\TmpPageSecRef{sec:option:channel} \\ +\end{tabular} + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\newpage + +\subsection{As a Lua\LaTeX{} package} + +Run |lualatex lualatex-test.tex| to show a node tree using +Lua\LaTeX{}. In Lua\LaTeX{} you can omit a call to +|\NodetreeRegisterCallback{postline}|, since |\usepackage{nodetree}| +registers the |post_linebreak_filter| by default. Use +|\NodetreeUnregisterCallback{postline}| if you don’t want to debug the +|post_linebreak_filter|. + +\begin{minted}{latex} +\documentclass{article} +\usepackage{nodetree} + +\begin{document} +Lorem ipsum dolor. +\end{document} +\end{minted} + +\subsubsection{Available macros} + +\begin{tabular}{ll} +\textbf{Macro name} & +\textbf{Reference} \\ + +\TmpTabularMacrosPlainTeX + +\cmd{\NodetreeSet}\marg{kv-options} & +\TmpPageSecRef{sec:cmd:nodetree-set} \\ +\end{tabular} + +\subsubsection{Available options} + +\begin{tabular}{ll} +\textbf{Option name} & +\textbf{Reference} \\ + +\TmpTabularOptionsBase + +|channel| & +\TmpPageSecRef{sec:option:channel} \\ +\end{tabular} + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\newpage + +\subsection{As a Lua module} + +Import the Lua module of the package inside +\mintinline{latex}{\directlua{}} +with this command: +\mintinline{lua}{local nodetree = require('nodetree')}. +Then use the Lua function +\mintinline{lua}{nodetree.print(head, options)} +to debug nodes inside your Lua code. + +\begin{minted}{lua} +local nodetree = require('nodetree') + +local rule1 = node.new('rule') +rule1.width = 20 * 65536 +rule1.height = 10 * 65536 +rule1.depth = 10 * 65536 +nodetree.print(vbox) +\end{minted} + +\noindent +The function \mintinline{lua}{nodetree.print()} takes as a second +argument a Lua table to configure the output. + +\begin{minted}{lua} +nodetree.print(vbox, { verbosity = 2, unit = 'cm' }) +\end{minted} + +\noindent +These are the default options: + +\begin{minted}{lua} +options = { + callback = 'post_linebreak_filter', + channel = 'term', + color = 'colored', + decimalplaces = 2, + unit = 'pt', + verbosity = 0, + firstline = 1, + lastline = -1, +} +\end{minted} + +Options |firstline| and |lastline| only have an effect on function +\mintinline{lua}{nodetree.input(filename)}, which is used to implement +\cmd{\NodetreeEmbedInput} \TmpSecRef{sec:cmd:nodetree-embed-input}. + +The following code snippet demonstrates the usage in Lua\TeX{}. +|head| is the current node. + +\begin{minted}{latex} +\directlua{ + local nodetree = require('nodetree') + local test = function (head) + nodetree.print(head) + end + callback.register('post_linebreak_filter', test) +} + +Lorem ipsum dolor. +\bye +\end{minted} + +\noindent +This example illustrates how the function has to be applied in +Lua\LaTeX{}. + +\begin{minted}{latex} +\documentclass{article} +\usepackage{nodetree} + +\begin{document} + +\directlua{ + local nodetree = require('nodetree') + local test = function (head) + nodetree.print(head) + end + luatexbase.add_to_callback('post_linebreak_filter', test, 'test') +} + +Lorem ipsum dolor. +\end{document} +\end{minted} + +%----------------------------------------------------------------------- +% +%----------------------------------------------------------------------- + +\newpage +\subsection{The package \texttt{nodetree-embed}} + +The single purpose of this auxiliary package is to provide a view +similar to a terminal (console) output. +This view mimics the output +of |nodetree| in a terminal. +The view can be embedded in a Lua\LaTeX{} file. You have to +compile documents using this embedded view with the option +|--shell-escape|. +The main environment of this package is |NodetreeEmbed|. +Markup +inside this environment is written into a temporary \LaTeX{} file. +This file is compiled in the background by |latexmk| and the +|nodetree| output is embedded into this view. +The following list shows each intermediate step: + +\begin{enumerate} + +\item |jobname.tex| + +\begin{minted}{latex} +\begin{NodetreeEmbedEnv} +nodetree +\end{NodetreeEmbedEnv} +\end{minted} + +\item |_nodetree-jobname/1.tex| + +\begin{minted}{latex} +%!TEX program = lualatex +\documentclass{article} +\usepackage{nodetree} +\NodetreeSetOption[channel]{tex} +\NodetreeSetOption[verbosity]{0} +\NodetreeSetOption[unit]{pt} +\NodetreeSetOption[decimalplaces]{2} +\NodetreeUnregisterCallback{post_linebreak_filter} +\NodetreeRegisterCallback{post_linebreak_filter} +\begin{document} +nodetree +\end{document} +\end{minted} + +\item |_nodetree-jobname/1.nttex|: This temporary Lua\LaTeX{} file is +compiled using |latexmk| and embedded in the environment |NodetreeEmbed| +(the trailing |\| character indicates line continuation). + +\begin{minted}{latex} +Callback: \textcolor{NTEred}{post\_linebreak\_filter}\par +------------------------------------------\par +\mbox{├─\textcolor{NTEmagentabright}{GLUE}\hspace{0.5em}(baselineskip)\ + \textcolor{NTEyellow}{wd} 5.06\textcolor{NTEwhite}{pt}}\par +... +\end{minted} + +\item Finally the result: + +\begin{NodetreeEmbedEnv} +nodetree +\end{NodetreeEmbedEnv} + +\end{enumerate} + +\subsubsection{Available macros} + +\begin{tabular}{ll} +\textbf{Macro name} & +\textbf{Reference} \\ + +\TmpTabularMacrosPlainTeX + +\cmd{\NodetreeSet}\marg{kv-options} & +\TmpPageSecRef{sec:cmd:nodetree-set} \\ + +\cmd{\NodetreeEmbedCmd}\oarg{kv-options}\marg{tex-markup} & +\TmpPageSecRef{sec:cmd:nodetree-embed-cmd} \\ + +\cmd{\NodetreeEmbedInput}\oarg{kv-options}\marg{nttex-file} & +\TmpPageSecRef{sec:cmd:nodetree-embed-input} \\ +\end{tabular} + +\subsubsection{Available environment} + +\begin{tabular}{ll} +\textbf{Environment name} & +\textbf{Reference} \\ + +|\begin{NodetreeEmbedEnv}|\oarg{kv-options} & % |\end{NodetreeEmbedEnv}| +\TmpPageSecRef{sec:env:nodetree-embed-env} \\ +\end{tabular} + +\subsubsection{Available options} + +\begin{tabular}{ll} +\textbf{Option name} & +\textbf{Reference} \\ + +\TmpTabularOptionsBase + +|theme| & +\TmpPageSecRef{sec:option:theme} \\ + +|thememode| & +\TmpPageSecRef{sec:option:thememode} \\ + +|font| & +\TmpPageSecRef{sec:option:font} \\ + +|fontsize| & +\TmpPageSecRef{sec:option:fontsize} \\ + +|firstline| & +\TmpPageSecRef{sec:option:firstlastline} \\ + +|lastline| & +\TmpPageSecRef{sec:option:firstlastline} \\ +\end{tabular} + +%----------------------------------------------------------------------- +% Macros +%----------------------------------------------------------------------- +\newpage +\section{Macros} + +%% +% \NodetreeRegisterCallback +%% + +\subsection{\TmpMacroName{NodetreeRegisterCallback}} +\label{sec:cmd:nodetree-register-callback} + +\DescribeMacro{\NodetreeRegisterCallback} +\cmd{\NodetreeRegisterCallback}\marg{callbacks}: Globally register +\marg{callbacks}, which is a comma-separated list of callback aliases +\TmpSecRef{sec:option:callback}. + +%% +% \NodetreeUnregisterCallback +%% + +\subsection{\TmpMacroName{NodetreeUnregisterCallback}} +\label{sec:cmd:nodetree-unregister-callback} + +\DescribeMacro{\NodetreeUnregisterCallback} +\cmd{\NodetreeUnregisterCallback}\marg{callbacks}: Globally unregister +\marg{callbacks}, which is a separated list of callback aliases +\TmpSecRef{sec:option:callback}. + +%% +% \NodetreeSetOption +%% + +\subsection{\TmpMacroName{NodetreeSetOption}} +\label{sec:cmd:nodetree-set-option} + +\DescribeMacro{\NodetreeSetOption} +\cmd{\NodetreeSetOption}\oarg{option}\marg{value}: Globally set a +single \oarg{option} to \marg{value} \TmpSecRef{sec:options}. + +%% +% \NodetreeResetOption +%% + +\subsection{\TmpMacroName{NodetreeResetOption}} +\label{sec:cmd:nodetree-reset-option} + +\DescribeMacro{\NodetreeResetOption} +\cmd{\NodetreeResetOption}\marg{option}: Globally reset a single +\marg{option} to its default value \TmpSecRef{sec:options}. + +%% +% \NodetreeSet +%% + +\subsection{\TmpMacroName{NodetreeSet}} +\label{sec:cmd:nodetree-set} + +\DescribeMacro{\NodetreeSet} +\cmd{\NodetreeSet}\marg{kv-options}: Globally set multiple options at +once. It can only be used along with Lua\LaTeX{}. \marg{kv-options} +are key-value pairs. + +\begin{code} +\NodetreeSet{color=no,callbacks={hpack,vpack},verbosity=2} +\end{code} + +%% +% \NodetreeReset +%% + +\subsection{\TmpMacroName{NodetreeReset}} +\label{sec:cmd:nodetree-reset} + +\DescribeMacro{\NodetreeReset} +\cmd{\NodetreeReset}: Globally reset multiple options to their default +values. + +%% +% +%% + +\subsection{\TmpMacroName{NodetreeEmbedCmd}} +\label{sec:cmd:nodetree-embed-cmd} + +\DescribeMacro{\NodetreeEmbedCmd} +\cmd{\NodetreeEmbedCmd}\oarg{kv-options}\marg{tex-markup}: + +Main macro (cmd) to evaluate some \TeX{} markup and generate a +node tree from it. See environment version +\TmpSecRef{sec:cmd:nodetree-embed-cmd}. Uses |xparse|'s |+v| option to +grab the verbatim content. \marg{kv-options} are key-value pairs and +set locally only. + +Only available in package |nodetree-embed|; you need option +|--shell-escape|. + +%% +% \NodetreeEmbedInput +%% + +\subsection{\TmpMacroName{NodetreeEmbedInput}} +\label{sec:cmd:nodetree-embed-input} + +\DescribeMacro{\NodetreeEmbedInput} +\cmd{\NodetreeEmbedInput}\oarg{kv-options}\marg{nttex-file}: The path or +file name of the |*.nttex| file without the extension. +\marg{kv-options} are key-value pairs and set locally only. + +Only available in package |nodetree-embed|. This command works without +option |--shell-escape|. + +%----------------------------------------------------------------------- +% Environments +%----------------------------------------------------------------------- + +\newpage +\section{Environments} + +\subsection{\texttt{NodetreeEmbedEnv}} +\label{sec:env:nodetree-embed-env} + +\DescribeEnv{NodetreeEmbedEnv} +|\begin{NodetreeEmbedEnv}|\oarg{kv-options}\\ +\dots{} \textit{\TeX{} markup for evaluation} \dots\\ +|\end{NodetreeEmbedEnv}| + +Main environment (env) to evaluate some \TeX{} markup and generate a +node tree from it. See command version +\TmpSecRef{sec:cmd:nodetree-embed-cmd}. Uses the \cmd{\detokenize} +command to grab the verbatim content. \marg{kv-options} are key-value +pairs and set locally only. + +Only available in package |nodetree-embed|; you need option +|--shell-escape|. + +%----------------------------------------------------------------------- +% Options +%----------------------------------------------------------------------- +\newpage +\section{Options} +\label{sec:options} + +%% +% callback +%% + +\subsection{Option \texttt{callback}} +\label{sec:option:callback} + +The option |callback| is the most important setting of the package. It +is possible to specify an alias to select the callback. Take a look at +the overview of callbacks (\rightarrow{} Figure~\ref{fig:callback}). +|nodetree| supports all node-related callbacks as listed in the +Lua\TeX{} reference manual. + +These macros process callback options: + +\begin{quote} + \cmd{\NodetreeRegisterCallback}\marg{callbacks}\\ + \cmd{\NodetreeUnregisterCallback}\marg{callbacks}\\ + \cmd{\NodetreeSet}\marg{callback=<callbacks>}\\ + \cmd{\usepackage}\oarg{callback=<callbacks>}\marg{nodetree} +\end{quote} + +The |nodetree| package can watch the node tree before and after the +functions of a callback are executed: It is possible to prepend and/or +append a colon (|:|) to indicate the desired watchpoint position, +which defaults to 'before' if no colon is used. + +Use commas to specify multiple callbacks; trailing and leading +whitespace is ignored. For example, this call + +\begin{code} +\NodetreeRegisterCallback{:preline, line, :postline:} +\end{code} + +\noindent +watches the node tree before the |preline| callback functions, before +the |line| callback functions, and before and after the |postline| +callback functions. In case there are no callback functions +registered for one of the |hyphenate|, |kerning|, |ligaturing|, and +|mlist_to_hlist| callbacks, Lua\TeX{} executes some internal code +instead. It thus makes sense to watch the node tree before and after +these (empty) callbacks even in this case. + +Wrap your callback aliases in curly braces for the macro +|\NodetreeSet|. Note that no whitespace between |=| and |{| is +allowed. + +\begin{code} +\NodetreeSet{callback={:preline, line, :postline:}} +\end{code} + +The same applies for the macro |\usepackage|: + +\begin{code} +\usepackage{callback={:preline, line, :postline:}} +\end{code} + +The callbacks in Figure~\ref{fig:callback} are listed in the same +order as in the Lua\TeX{} reference manual. Note that the |ligaturing| +and |kerning| callbacks only have an effect on ligatures and kernings, +respectively, if the |luaotfload| package (which is the default for +Lua\LaTeX{}, and an optional package for Lua\TeX{}) handles the +affected font with |mode=base| (see the +\href{http://mirrors.ctan.org/macros/luatex/generic/luaotfload/luaotfload-latex.pdf} +{documentation} for more details). + +%% +% Tabular callbacks +%% + +\newcommand{\TmpCallbackRow}[3]{ + \TmpLuaCodeInline{#1} & \TmpLuaCodeInline{#2} & \TmpLuaCodeInline{\footnotesize#3} \\ +} + +\begin{figure} +\begin{tabular}{lll} +\textbf{Callback} & \textbf{Alias} & \textbf{Alias (longer)} \\ +\TmpCallbackRow{contribute_filter} +{contribute} +{contributefilter} + +\TmpCallbackRow{buildpage_filter} +{buildfilter} % +{buildpagefilter} + +% new +\TmpCallbackRow{build_page_insert} +{buildinsert} +{buildpageinsert} + +\TmpCallbackRow{pre_linebreak_filter} +{preline} +{prelinebreakfilter} + +\TmpCallbackRow{linebreak_filter} +{line} +{linebreakfilter} + +\TmpCallbackRow{append_to_vlist_filter} +{append} +{appendtovlistfilter} + +\TmpCallbackRow{post_linebreak_filter} +{postline} +{postlinebreakfilter} + +\TmpCallbackRow{hpack_filter} +{hpack} +{hpackfilter} + +\TmpCallbackRow{vpack_filter} +{vpack} +{vpackfilter} + +\TmpCallbackRow{hpack_quality} +{hpackq} +{hpackquality} + +\TmpCallbackRow{vpack_quality} +{vpackq} +{vpackquality} + +\TmpCallbackRow{process_rule} +{process} +{processrule} + +\TmpCallbackRow{pre_output_filter} +{preout} +{preoutputfilter} + +\TmpCallbackRow{hyphenate} +{hyph} +{} + +\TmpCallbackRow{ligaturing} +{liga} +{} + +\TmpCallbackRow{kerning} +{kern} +{} + +\TmpCallbackRow{insert_local_par} +{insert} +{insertlocalpar} + +\TmpCallbackRow{mlist_to_hlist} +{mhlist} +{mlisttohlist} +\end{tabular} + +\caption{The callback aliases} +\label{fig:callback} +\end{figure} + +%% +% channel +%% + +\subsection{Option \texttt{channel}} +\label{sec:option:channel} + +You can select the debug output channel with this option. The default +value for the option |channel| is |term|, which displays the node tree in +the current terminal. Specify |log| and the package creates a log file +named |<jobname>.ntlog|. Specify |tex| and a log file named +|<jobname>.nttex| is created. |nt...| stands for |nodetree|. +|<jobname>| is the basename of your file you want to debug. The debug +channel is only useful for the auxiliary package |nodetree-embed|. Paste +the markup in the environment |NodetreeEmbedView| and you get a +terminal-like view in your document. + +%% +% verbosity +% + +\subsection{Option \texttt{verbosity}} +\label{sec:option:verbosity} + +Higher integer values result in a more verbose output. The default value +for this option is~|0|. At the moment verbosity levels |0| to~|3| are +implemented. + +\def\TmpExampleVerbosity#1{ + \subsubsection{Example: \texttt{verbosity=#1}} + \begin{NodetreeEmbedEnv}[verbosity=#1,callback=pre_linebreak_filter, + fontsize=\fontsize{5.5}{6.6}\selectfont] + . + \end{NodetreeEmbedEnv} +} + +\TmpExampleVerbosity{0} +\TmpExampleVerbosity{1} +\TmpExampleVerbosity{2} +\TmpExampleVerbosity{3} + +%% +% color +%% + +\subsection{Option \texttt{color}} +\label{sec:option:color} + +The default option for |color| is |colored|. Use any other string (for +example |none| or |no|) to disable the colored terminal output of the +package. + +\begin{code} +\usepackage[color=no]{nodetree} +\end{code} + +%% +% unit +%% + +\subsection{Option \texttt{unit}} +\label{sec:option:unit} + +The option |unit| sets the length unit to display all length values of +the nodes. The default option for |unit| is |pt|. See figures +\ref{fig:fixed-units} and~\ref{fig:relative-units} for possible values. + +\begin{figure} +\begin{tabular}{lp{10cm}} +\textbf{Unit} & +\textbf{Description} \\ + +pt & +Point 1/72.27 inch. The conversion to metric units, to two decimal +places, is 1 point = 2.85 mm = 28.45 cm. \\ + +pc & +Pica, 12 pt \\ + +in & +Inch, 72.27 pt \\ + +bp & +Big point, 1/72 inch. This length is the definition of a point in +PostScript and many desktop publishing systems. \\ + +cm & +Centimeter \\ + +mm & +Millimeter \\ + +dd & +Didot point, 1.07 pt \\ + +cc & +Cicero, 12 dd \\ + +sp & +Scaled point, 1/65536 pt \\ +\end{tabular} +\caption{Fixed units} +\label{fig:fixed-units} +\end{figure} + +\begin{figure} +\begin{tabular}{lp{10cm}} +\textbf{Unit} & +\textbf{Description} \\ + +ex & +x-height of the current font \\ + +em & +Width of the capital letter M \\ +\end{tabular} +\caption{Relative units} +\label{fig:relative-units} +\end{figure} + +\def\TmpExampleUnit#1{ + \subsubsection{Example: \texttt{unit=#1}} + \begin{NodetreeEmbedEnv}[unit=#1,callback=pre_linebreak_filter] + Lorem. + \end{NodetreeEmbedEnv} +} + +\TmpExampleUnit{pt} +\TmpExampleUnit{sp} +\TmpExampleUnit{cm} + +%% +% decimalplaces +%% + +\subsection{Option \texttt{decimalplaces}} +\label{sec:option:decimalplaces} + +The options |decimalplaces| sets the number of decimal places for some +node fields. If |decimalplaces| is set to |0| only integer values are shown. + +\begin{code} +\NodetreeSetOption[decimalplaces]{4} +\end{code} + +\def\TmpExampleDecimalplaces#1{ + \subsubsection{Example: \texttt{decimalplaces=#1}} + \begin{NodetreeEmbedEnv}[unit=cc,decimalplaces=#1,callback=pre_linebreak_filter] + Lorem. + \end{NodetreeEmbedEnv} +} + +\TmpExampleDecimalplaces{0} +\TmpExampleDecimalplaces{2} +\TmpExampleDecimalplaces{5} + +%% +% theme and thememode +%% + +\def\TmpExampleTheme#1#2{ + \subsubsection{Example: \texttt{theme=#1} \texttt{thememode=#2}} + \begin{NodetreeEmbedEnv}[callback=pre_linebreak_filter,theme=#1,thememode=#2,fontsize=\small] + . + \end{NodetreeEmbedEnv} +} + +\subsection{Option \texttt{theme} and \texttt{thememode}} +\label{sec:option:theme} +\label{sec:option:thememode} + +% bw +\TmpExampleTheme{bwdark}{dark} +\TmpExampleTheme{bwlight}{light} + +% monokaisoda +\TmpExampleTheme{monokaisoda}{dark} +\TmpExampleTheme{monokaisoda}{light} + +%% +% font +%% + +\subsection{Option \texttt{font}} +\label{sec:option:font} + +\NodetreeSet{fontsize=\footnotesize} + +\def\TmpExampleFont#1{ + \subsubsection{Example: \texttt{font=\{#1\}}} + \begin{NodetreeEmbedEnv}[font={#1}] + . + \end{NodetreeEmbedEnv} +} + +|nodetree-embed| passes the option |font| down to the +command |\setmonofont{}| of the |fontspec| package. The used font +should be monospaced and have some box drawing glyphs (see +table~\ref{fig:unicode}). + +\TmpExampleFont{Liberation Mono} +\TmpExampleFont{Ubuntu Mono} + +%% +% fontsize +%% + +\subsection{Option \texttt{fontsize}} +\label{sec:option:fontsize} + +\def\TmpExampleFontSize#1{ + \subsubsection{Example: \TmpMacroName{#1}} + \begin{NodetreeEmbedEnv}[callback=pre_linebreak_filter, + fontsize=\csname #1\endcsname] + . + \end{NodetreeEmbedEnv} +} + +\TmpExampleFontSize{small} +\TmpExampleFontSize{tiny} + +\subsection{Options \texttt{firstline} and \texttt{lastline}} +\label{sec:option:firstlastline} + +These two options are for function \cmd{\NodetreeEmbedInput} only +\TmpSecRef{sec:cmd:nodetree-embed-input}. They specify the first +and last shown line of the read |*.nttex| file. Values |1|, |2|, +\ldots, corresponds to the first line, second, line, etc. Values +|-1|, |-2|, \ldots, correspond to the last line, the line before the +last line, etc. The default values are |firstline = 1| and +|lastline = -1| to display the whole file. + +%----------------------------------------------------------------------- +% Visual tree structure +%----------------------------------------------------------------------- +\newpage +\section{Visual tree structure} + +%% +% Two different connections +%% + +\subsection{Two different connections} + +Nodes in Lua\TeX{} are connected. The |nodetree| package distinguishes +between \emph{list} and \emph{field} connections. + +\begin{itemize} + \item list: Nodes that are doubly connected by |next| and + |previous| fields. + \item field: Connections to nodes by other fields than |next| and + |previous|, for example, using |head| and |pre|. +\end{itemize} + +%% +% Unicode characters +%% + +\subsection{Unicode characters to show the tree view} + +\renewcommand{\arraystretch}{1.5} + +The package |nodetree| uses the unicode box drawing symbols. Your +default terminal font should contain this characters to obtain the tree +view. Eight box drawing characters are necessary. + +\begin{figure} +{ +\fontspec{DejaVu Sans Mono} +\begin{tabular}{lcl} +\textbf{Code} & \textbf{Character} & \textbf{Name} \\ +U+2500 & ─ & BOX DRAWINGS LIGHT HORIZONTAL \\ +U+2502 & │ & BOX DRAWINGS LIGHT VERTICAL \\ +U+2514 & └ & BOX DRAWINGS LIGHT UP AND RIGHT \\ +U+251C & ├ & BOX DRAWINGS LIGHT VERTICAL AND RIGHT \\ +U+2550 & ═ & BOX DRAWINGS DOUBLE HORIZONTAL \\ +U+2551 & ║ & BOX DRAWINGS DOUBLE VERTICAL \\ +U+255A & ╚ & BOX DRAWINGS DOUBLE UP AND RIGHT \\ +U+2560 & ╠ & BOX DRAWINGS DOUBLE VERTICAL AND RIGHT \\ +\end{tabular} +} +\caption{The Unicode box drawings glyphs} +\label{fig:unicode} +\end{figure} + +\noindent +For |list| connections \emph{light} characters are shown. + +{ +\setmonofont{DejaVu Sans Mono} +\begin{code} +│ │ +│ ├─list1 +│ └─list2 +└─list3 +\end{code} +} + +\noindent +|field| connections are visialized by \emph{Double} characters. + +{ +\setmonofont{DejaVu Sans Mono} +\begin{code} +║ ║ +║ ╠═field1 +║ ╚═field2 +╚═field3 +\end{code} +} + +%----------------------------------------------------------------------- +% Examples +%----------------------------------------------------------------------- +\newpage +\section{Examples} + +This section lists some examples of the |nodetree| output. + +%% +% packagename +%% + +\subsection{The node list of the package name} + +\begin{NodetreeEmbedEnv}[showmarkup=true,callback=post_linebreak_filter] +nodetree +\end{NodetreeEmbedEnv} + +%% +% math +%% + +\subsection{The node list of a mathematical formula} + +\begin{NodetreeEmbedEnv}[showmarkup=true,callback=post_linebreak_filter] +$1+2$ +\end{NodetreeEmbedEnv} + +%% +% ligatures +%% + +\subsection{The node list of the word \emph{Office}} + +The characters \emph{ffi} are deeply nested in a discretionary node. + +\begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=0] +Office +\end{NodetreeEmbedEnv} + +%----------------------------------------------------------------------- +% Node types +%----------------------------------------------------------------------- + +\section{Node types} + +This section shows some node types in a |nodetree| view. + +\newcommand{\TmpHeadingNodeTypeSub}[4]{ + \subsection{Type \texttt{#1(#2)}, subtype \texttt{#3(#4)}} +} + +\newcommand{\TmpNodeTypeSub}[6]{ + \subsection{Type \texttt{#1(#2)}, subtype \texttt{#3\_#4(#5)}} + \TmpVerbExample{#2#1#5#3#4}{#6} +} + +\newcommand{\TmpHeadingNodeType}[2]{ + \subsection{Type \texttt{#1(#2)}} +} + +%% +% +%% + +\TmpHeadingNodeTypeSub{hlist}{0}{line}{1} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +Lorem +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{hlist}{0}{box}{2} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +L\hbox to 40pt{ore}m +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{hlist}{0}{indent}{3} + +\begin{NodetreeEmbedEnv}[showmarkup=true,unit=cm] +\setlength{\parindent}{5cm} +I +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{vlist}{1} + +\begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=1] +L\vbox to 40pt{O}L +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{rule}{2} + +\begin{NodetreeEmbedEnv}[showmarkup=true,unit=mm] +\rule[-2mm]{10mm}{4mm} +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{mark}{4} + +\begin{NodetreeEmbedEnv}[showmarkup=true,callback=pre_output_filter] +\mark{Lorem}. +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{disc}{7}{discretionary}{0} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +L\discretionary{}{}{}L +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{disc}{7}{explicit}{1} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +L\-O\-L +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{disc}{7}{regular}{3} + +\begin{NodetreeEmbedEnv}[showmarkup=true,decimalplaces=0] +Office +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpNodeTypeSub{whatsit}{8}{pdf}{action}{22}{\fontsize{5.5}{6.6}\selectfont} +\TmpNodeTypeSub{whatsit}{8}{pdf}{colorstack}{28}{\footnotesize} + +%% +% +%% + +\TmpHeadingNodeType{dir}{10} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +\textdir TRT nur {\textdir TLT run \textdir TRT NUR} nur +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{baselineskip}{2} + +\NodetreeEmbedCmd[showmarkup=true,unit=cm]{ +\baselineskip=5cm +Lorem + +Lorem +} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{parskip}{3} + +\NodetreeEmbedCmd[showmarkup=true,callback=pre_output_filter]{ +\parskip=5cm +Lorem + +Lorem +} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{spaceskip}{13} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +\spaceskip=5cm +a a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{leaders}{100} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +a \leavevmode\leaders\hbox{ . }\hfill\kern0pt a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{cleaders}{101} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +a \leavevmode\cleaders\hbox{ . }\hfill\kern0pt a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{xleaders}{102} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +a \leavevmode\xleaders\hbox{ . }\hfill\kern0pt a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{glue}{12}{gleaders}{102} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +a \leavevmode\gleaders\hbox{ . }\hfill\kern0pt a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{kern}{13}{userkern}{0} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +a\kern2pt +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{kern}{13}{fontkern}{1} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +Ve +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{kern}{13}{accentkern}{2} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +\accent96 a +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeTypeSub{kern}{13}{italiccorrection}{3} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +\textit{L}\/OL +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{penalty}{14} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +L \penalty 23 OL +\end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{glyph}{29} + +\begin{NodetreeEmbedEnv}[showmarkup=true] +abc +\end{NodetreeEmbedEnv} + +%% +% +%% + +% It seems that 'attribute' nodes don't appear in node trees. +% +% \TmpHeadingNodeType{attribute}{38} +% +% \begin{NodetreeEmbedEnv}[showmarkup=true] +% {\attribute0=1 A} +% \end{NodetreeEmbedEnv} + +%% +% +%% + +\TmpHeadingNodeType{attributelist}{40} + +\begin{NodetreeEmbedEnv}[showmarkup=true,callback=hpackfilter] +{\attribute0=1 A} +\end{NodetreeEmbedEnv} + +\DocInput{nodetree.dtx} + +\subsection{The file \texttt{nodetree.lua}} + +% Compilation failure: +% 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 +% \inputminted{lua}{nodetree.lua} +There is a source code documentation of the file nodetree.lua compiled +with Ldoc on Github: +\url{http://josef-friedrich.github.io/nodetree/} + +\end{document} |