diff options
Diffstat (limited to 'Master/texmf-dist/source/luatex/nodetree/nodetree.dtx')
| -rw-r--r-- | Master/texmf-dist/source/luatex/nodetree/nodetree.dtx | 358 |
1 files changed, 296 insertions, 62 deletions
diff --git a/Master/texmf-dist/source/luatex/nodetree/nodetree.dtx b/Master/texmf-dist/source/luatex/nodetree/nodetree.dtx index fbe344976d3..145284e3932 100644 --- a/Master/texmf-dist/source/luatex/nodetree/nodetree.dtx +++ b/Master/texmf-dist/source/luatex/nodetree/nodetree.dtx @@ -28,7 +28,7 @@ %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01] %<package>\ProvidesPackage{nodetree} %<*package> - [2016/07/07 Package to visualize node lists in a tree view] + [2016/07/13 Package to visualize node lists in a tree view] %</package> %<*driver> \documentclass{ltxdoc} @@ -39,6 +39,7 @@ filecolor=red, urlcolor=red, ]{hyperref} +%\usepackage{nodetree} \EnableCrossrefs \CodelineIndex \RecordChanges @@ -49,6 +50,11 @@ \def\secref#1{(\rightarrow\ \ref{#1})} +\newcommand{\tmpgraphics}[1]{ + \noindent + \includegraphics[scale=0.4]{graphics/#1} +} + \DefineVerbatimEnvironment{code}{Verbatim} { frame=single, @@ -70,7 +76,7 @@ \maketitle \noindent -\includegraphics[width=\linewidth]{graphics/nodetree} +\includegraphics[width=\linewidth]{graphics/packagename} \newpage @@ -78,12 +84,16 @@ \newpage +%----------------------------------------------------------------------- +% Abstract +%----------------------------------------------------------------------- + \section{Abstract} |nodetree| is a development package that visualizes the structure of -node lists. |nodetree| shows its debug informations in the console +node lists. |nodetree| shows its debug informations in the consoles’ output when you compile a Lua\TeX{} file. It uses a similar visual -representation for node lists as the UNIX |tree| command for a +representation for node lists as the UNIX |tree| command uses for a folder structure. Node lists are the main building blocks of each document generated by @@ -91,6 +101,10 @@ the \TeX{} engine \emph{Lua\TeX}. The package |nodetree| doesn‘t change the rendered document. The tree view can only be seen when using a terminal to generate the document. +|nodetree| is inspired by a +\href{https://gist.github.com/pgundlach/556247} +{gist from Patrick Gundlach}. + %----------------------------------------------------------------------- % Usage %----------------------------------------------------------------------- @@ -169,7 +183,7 @@ Lorem ipsum dolor. \end{code} %----------------------------------------------------------------------- -% +% Macros %----------------------------------------------------------------------- \section{Macros} @@ -285,8 +299,8 @@ The same applies for the macro |\usepackage|: \nodetreecallback{postline}{postlinebreakfilter}{post_linebreak_filter} \nodetreecallback{hpack}{hpackfilter}{hpack_filter} \nodetreecallback{vpack}{vpackfilter}{vpack_filter} -%\nodetreecallback{hpackq}{hpackquality}{hpack_quality} -%\nodetreecallback{vpackq}{vpackquality}{vpack_quality} +\nodetreecallback{hpackq}{hpackquality}{hpack_quality} +\nodetreecallback{vpackq}{vpackquality}{vpack_quality} \nodetreecallback{process}{processrule}{process_rule} \nodetreecallback{preout}{preoutputfilter}{pre_output_filter} \nodetreecallback{hyph}{hyphenate}{hyphenate} @@ -325,6 +339,69 @@ package. \end{code} %% +% unit +%% + +\subsection{Option \texttt{unit}} + +The option |unit| sets the length unit to display all length values of +the nodes. The default option for |unit| is |pt|. See figure +\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} + +%% % decimalplaces %% @@ -350,11 +427,15 @@ If |decimalplaces| is set to |0| only integer values are shown. \end{code} %----------------------------------------------------------------------- -% +% Visual tree structure %----------------------------------------------------------------------- \section{Visual tree structure} +%% +% Two different connections +%% + \subsection{Two different connections} Nodes in Lua\TeX{} are connected. The |nodetree| package distinguishs @@ -367,6 +448,10 @@ between the |list| and |field| connections. |previous| fields, e. g. |head|, |pre|. \end{itemize} +%% +% Unicode characters +%% + \subsection{Unicode characters to show the tree view} \renewcommand{\arraystretch}{1.5} @@ -407,13 +492,70 @@ For |list| connections \emph{light} characters are shown. \end{code} %----------------------------------------------------------------------- -% +% Examples %----------------------------------------------------------------------- -\section{Example tree views} +\newpage -\noindent -\includegraphics[width=\linewidth]{graphics/mhlist} +\section{Examples} + +%% +% packagename +%% + +\subsection{The node list of the package name} + +\begin{code} +\documentclass{article} +\usepackage{nodetree} +\begin{document} +nodetree +\end{document} +\end{code} + +\tmpgraphics{packagename} + +%% +% math +%% + +\newpage + +\subsection{The node list of a mathematical formula} + +\begin{code} +\documentclass{article} +\usepackage[callback={mhlist}]{nodetree} +\begin{document} +\[\left(a\right)\left[\frac{b}{a}\right]=a\,\] +\end{document} +\end{code} + +\tmpgraphics{math} + +%% +% ligatures +%% + +\newpage + +\subsection{The node list of the word \emph{Office}} + +The characters \emph{ffi} are deeply nested in a discretionary node. + +\begin{code} +\documentclass{article} +\usepackage{nodetree} +\begin{document} +Office +\end{document} +\end{code} + +\tmpgraphics{ligatures} + +%----------------------------------------------------------------------- +% Index +%----------------------------------------------------------------------- \DocInput{nodetree.dtx} \pagebreak @@ -423,47 +565,110 @@ For |list| connections \emph{light} characters are shown. \end{document} %</driver> %<*readme> -# nodetree -Inspired by a [gist from Patrick Gundlach](https://gist.github.com/pgundlach/556247). + + +# Abstract + +`nodetree` is a development package that visualizes the structure of +node lists. `nodetree` shows its debug informations in the consoles’ +output when you compile a LuaTeX file. It uses a similar visual +representation for node lists as the UNIX `tree` command uses for a +folder structure. + +Node lists are the main building blocks of each document generated by +the TeX engine LuaTeX. The package `nodetree` doesn‘t change +the rendered document. The tree view can only be seen when using a +terminal to generate the document. + +`nodetree` is inspired by a +[gist from Patrick Gundlach](https://gist.github.com/pgundlach/556247). + +# License + +Copyright (C) 2016 by Josef Friedrich <josef@friedrich.rocks> +------------------------------------------------------------------------ +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. + +# CTAN + +Since July 2016 the cloze package is included in the Comprehensive TeX +Archive Network (CTAN). + +* TeX archive: http://mirror.ctan.org/tex-archive/macros/luatex/generic/nodetree +* Package page: http://www.ctan.org/pkg/nodetree + +# Repository + +https://github.com/Josef-Friedrich/nodetree + +# Installation + +Get source: + + git clone git@github.com:Josef-Friedrich/nodetree.git + cd nodetree + +Compile: + + make + +or manually: + + luatex nodetree.ins + lualatex nodetree.dtx + makeindex -s gglo.ist -o nodetree.gls nodetree.glo + makeindex -s gind.ist -o nodetree.ind nodetree.idx + lualatex nodetree.dtx -`nodetree` displays some debug informations of the node list in the -terminal, when you render a Latex document. +# Examples +## The node list of the package name + +```latex +\documentclass{article} +\usepackage{nodetree} +\begin{document} +nodetree +\end{document} ``` -post_linebreak_filter: -│ -├─GLUE subtype: baselineskip; width: 5.06pt; -└─HLIST subtype: line; width: 345pt; height: 6.94pt; dir: TLT; glue_order: 2; glue_sign: 1; glue_set: 304.99993896484; - ╚═head: - ├─LOCAL_PAR dir: TLT; - ├─HLIST subtype: indent; width: 15pt; dir: TLT; - ├─GLYPH char: "O"; font: 15; left: 2; right: 3; uchyph: 1; width: 7.78pt; height: 6.83pt; - ├─DISC subtype: regular; penalty: 50; - │ ╠═post: - │ ║ └─GLYPH subtype: ghost; char: "\12"; font: 15; width: 5.56pt; height: 6.94pt; - │ ║ ╚═components: - │ ║ ├─GLYPH subtype: ligature; char: "f"; font: 15; left: 2; right: 3; uchyph: 1; width: 3.06pt; height: 6.94pt; - │ ║ └─GLYPH subtype: ligature; char: "i"; font: 15; left: 2; right: 3; uchyph: 1; width: 2.78pt; height: 6.68pt; - │ ╠═pre: - │ ║ ├─GLYPH char: "f"; font: 15; left: 2; right: 3; uchyph: 1; width: 3.06pt; height: 6.94pt; - │ ║ └─GLYPH char: "-"; font: 15; left: 2; right: 3; uchyph: 1; width: 3.33pt; height: 4.31pt; - │ ╚═replace: - │ └─GLYPH subtype: ghost; char: "\14"; font: 15; width: 8.33pt; height: 6.94pt; - │ ╚═components: - │ ├─GLYPH subtype: ghost; char: "\11"; font: 15; width: 5.83pt; height: 6.94pt; - │ │ ╚═components: - │ │ ├─GLYPH subtype: ligature; char: "f"; font: 15; left: 2; right: 3; uchyph: 1; width: 3.06pt; height: 6.94pt; - │ │ └─GLYPH subtype: ligature; char: "f"; font: 15; left: 2; right: 3; uchyph: 1; width: 3.06pt; height: 6.94pt; - │ └─GLYPH subtype: ligature; char: "i"; font: 15; left: 2; right: 3; uchyph: 1; width: 2.78pt; height: 6.68pt; - ├─GLYPH char: "c"; font: 15; left: 2; right: 3; uchyph: 1; width: 4.44pt; height: 4.31pt; - ├─GLYPH char: "e"; font: 15; left: 2; right: 3; uchyph: 1; width: 4.44pt; height: 4.31pt; - ├─PENALTY penalty: 10000; - ├─GLUE subtype: parfillskip; stretch: 65536; stretch_order: 2; - └─GLUE subtype: rightskip; + + +## The node list of a mathematical formula + +```latex +\documentclass{article} +\usepackage[callback={mhlist}]{nodetree} +\begin{document} +\[\left(a\right)\left[\frac{b}{a}\right]=a\,\] +\end{document} ``` + + +## The node list of the word 'Office' + +The characters 'ffi' are deeply nested in a discretionary node. + +```latex +\documentclass{article} +\usepackage{nodetree} +\begin{document} +Office +\end{document} +``` + + + %</readme> % \fi % @@ -488,6 +693,7 @@ post_linebreak_filter: % % \changes{v0.1}{2015/06/16}{Converted to DTX file} % \changes{v1.0}{2016/07/07}{Inital release} +% \changes{v1.1}{2016/07/13}{Fix the registration of same callbacks} % % \DoNotIndex{\newcommand,\newenvironment,\def,\directlua} % @@ -557,7 +763,7 @@ post_linebreak_filter: % \subsection{The file \tt{nodetree.sty}} % % \begin{macrocode} -\input{nodetree.tex} +\input{nodetree} \directlua{ nodetree.set_option('engine', 'lualatex') } @@ -575,6 +781,11 @@ post_linebreak_filter: % \end{macrocode} % % \begin{macrocode} +\DeclareStringOption[term]{channel} +\define@key{NT}{channel}[]{\nodetreeoption[channel]{#1}} +% \end{macrocode} +% +% \begin{macrocode} \DeclareStringOption[postlinebreak]{callback} \define@key{NT}{callback}[]{\nodetreeoption[callback]{#1}} % \end{macrocode} @@ -590,6 +801,11 @@ post_linebreak_filter: % \end{macrocode} % % \begin{macrocode} +\DeclareStringOption[1]{unit} +\define@key{NT}{unit}[]{\nodetreeoption[unit]{#1}} +% \end{macrocode} +% +% \begin{macrocode} \DeclareStringOption[1]{decimalplaces} \define@key{NT}{decimalplaces}[]{\nodetreeoption[decimalplaces]{#1}} % \end{macrocode} @@ -950,8 +1166,8 @@ end % \begin{macrocode} function tpl.length(input) input = tonumber(input) - input = input / 2^16 - return string.format('%gpt', tpl.round(input)) + input = input / tex.sp('1' .. options.unit) + return string.format('%g%s', tpl.round(input), options.unit) end % \end{macrocode} % @@ -1230,7 +1446,15 @@ end % % \begin{macrocode} function tpl.print(text) - print(text) + + if options.channel == 'log' then + if not log then + log = io.open(tex.jobname .. '_nodetree.log', 'a') + end + log:write(text, '\n') + else + print(' ' .. text) + end end % \end{macrocode} % @@ -1249,10 +1473,23 @@ function tree.format_field(head, field) % % \begin{macrocode} if options.verbosity < 2 and + -- glyph + field == 'font' or + field == 'left' or + field == 'right' or + field == 'uchyph' or + -- hlist + field == 'dir' or + field == 'glue_order' or + field == 'glue_sign' or + field == 'glue_set' or + -- glue + field == 'stretch_order' then + return '' + elseif options.verbosity < 3 and field == 'prev' or field == 'next' or field == 'id' - or field == 'attr' then return '' end @@ -1343,7 +1580,6 @@ function tree.analyze_node(head, level) for field_id, field_name in pairs(node.fields(head.id, head.subtype)) do if field_name ~= 'next' and field_name ~= 'prev' and - field_name ~= 'attr' and node.is_node(head[field_name]) then fields[field_name] = head[field_name] else @@ -1449,7 +1685,7 @@ function callbacks.vpack_filter(head, groupcode, size, packtype, maxdepth, direc groupcode = groupcode, size = size, packtype = packtype, - maxdepth = maxdepth, + maxdepth = tpl.length(maxdepth), direction = direction, attributelist = attributelist, } @@ -1459,33 +1695,29 @@ function callbacks.vpack_filter(head, groupcode, size, packtype, maxdepth, direc end % \end{macrocode} % -% TODO: Fix registration % \begin{macrocode} -function callbacks.hpack_qualtity(incident, detail, head, first, last) +function callbacks.hpack_quality(incident, detail, head, first, last) local variables = { incident = incident, detail = detail, first = first, last = last, } - tpl.callback('hpack_qualtity', variables) + tpl.callback('hpack_quality', variables) tree.analyze_callback(head) - return true end % \end{macrocode} % -% TODO: Fix registration % \begin{macrocode} -function callbacks.vpack_qualtity(incident, detail, head, first, last) +function callbacks.vpack_quality(incident, detail, head, first, last) local variables = { incident = incident, detail = detail, first = first, last = last, } - tpl.callback('vpack_qualtity', variables) + tpl.callback('vpack_quality', variables) tree.analyze_callback(head) - return true end % \end{macrocode} % @@ -1554,7 +1786,6 @@ function callbacks.insert_local_par(local_par, location) end % \end{macrocode} % -% TODO: Implement newhead as return value % \begin{macrocode} function callbacks.mlist_to_hlist(head, display_type, need_penalties) local variables = { @@ -1563,6 +1794,7 @@ function callbacks.mlist_to_hlist(head, display_type, need_penalties) } tpl.callback('mlist_to_hlist', variables) tree.analyze_callback(head) + return node.mlist_to_hlist(head, display_type, need_penalties) end % \end{macrocode} % @@ -1583,6 +1815,8 @@ function base.set_default_options() engine = 'luatex', color = 'colored', decimalplaces = 2, + unit = 'pt', + channel = 'term', } if not options then options = {} |