summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/luatex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-07-13 22:32:08 +0000
committerKarl Berry <karl@freefriends.org>2016-07-13 22:32:08 +0000
commit588acb7430d398501af794108005cd9d326a3769 (patch)
treea9b14cb6a55108938cfd9ccd9e79fae79c3dd4d3 /Master/texmf-dist/source/luatex
parent0b8f35b425fc6748f9b8503315068e72fb65cd48 (diff)
nodetree (13jul16)
git-svn-id: svn://tug.org/texlive/trunk@41684 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/luatex')
-rw-r--r--Master/texmf-dist/source/luatex/nodetree/nodetree.dtx358
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).
+![nodetree](graphics/packagename.png)
+
+# 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;
+![nodetree](graphics/packagename.png)
+
+## 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}
```
+![nodetree](graphics/math.png)
+
+## 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}
+```
+
+![nodetree](graphics/ligatures.png)
+
%</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 = {}