diff options
author | Norbert Preining <norbert@preining.info> | 2022-07-09 03:01:16 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2022-07-09 03:01:16 +0000 |
commit | 7891283a2f2fb8a8a884bb212c36da8082764a9b (patch) | |
tree | 98a050dec8439492144177997c6f66e4f9543d62 /macros/latex/contrib/prettytok/prettytok.tex | |
parent | c600912bde983d6a04c7ce42321d50d4c7c1a50b (diff) |
CTAN sync 202207090301
Diffstat (limited to 'macros/latex/contrib/prettytok/prettytok.tex')
-rw-r--r-- | macros/latex/contrib/prettytok/prettytok.tex | 171 |
1 files changed, 127 insertions, 44 deletions
diff --git a/macros/latex/contrib/prettytok/prettytok.tex b/macros/latex/contrib/prettytok/prettytok.tex index d21af2d0fe..96878ec457 100644 --- a/macros/latex/contrib/prettytok/prettytok.tex +++ b/macros/latex/contrib/prettytok/prettytok.tex @@ -1,10 +1,6 @@ %! TEX program = lualatex -\ProvidesFile{prettytok.tex} [2022/05/28 v0.0.0 Pretty-print token lists] -% yes, this is not dtx +\ProvidesFile{prettytok.tex} [2022/07/08 v0.0.1 ] \documentclass{l3doc} -%\usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry} -%\usepackage[numbered]{hypdoc} -%\usepackage{\jobname} \EnableCrossrefs \CodelineIndex \RecordChanges @@ -13,7 +9,7 @@ \DoNotIndex{\newcommand,\newenvironment} \title{\textsf{prettytok} --- Pretty-print token lists\thanks{This file - describes version \fileversion, last revised \filedate.} + describes version \fileversion, last revised \filedate.} } \author{user202729% %\thanks{E-mail: (not set)} @@ -25,29 +21,76 @@ \changes{v0.0.0}{2022/05/18}{First public release} \begin{abstract} - Pretty-print token lists. +Pretty-print token lists to HTML file for debugging purposes. +Open the file in any browser to view the result. + +Can be used to replace |\tl_analysis_show:n|. \end{abstract} \section{Usage} \subsection{Main function} \begin{function}{\pretty:n,\pretty:x,\pretty:o,\pretty:V} - \begin{syntax} - \cs{pretty:n} \Arg{token list} \\ - \end{syntax} - Print the content of \meta{token list}. + \begin{syntax} + \cs{pretty:n} \Arg{token list} + \end{syntax} + Print the content of \meta{token list}. \end{function} \begin{function}{\pretty:N,\pretty:c} - \begin{syntax} - \cs{pretty:N} \meta{token} \\ - \cs{pretty:c} \Arg{control sequence name} \\ - \end{syntax} - Print \meta{token}. \\ - This function is not very useful. Usually it's preferable to use |\pretty:V| to print a token list variable's value, - or |\prettyshow:N| to print a control sequence's meaning. + \begin{syntax} + \cs{pretty:N} \meta{token} + \cs{pretty:c} \Arg{control sequence name} + \end{syntax} + Print \meta{token}. + + This function is not very useful. Usually it's preferable to use |\pretty:V| to print a token list variable's value, + or |\prettyshow:N| to print a control sequence's meaning. +\end{function} + +\begin{function}{\prettyinit:} + \begin{syntax} + \cs{prettyinit:} + \end{syntax} + Do necessary initialization. + + This should be called right after the package is loaded, after setting the configuration variables described below. \end{function} +\subsection{Expandable interface (\LuaTeX\ only)} + +\cs{prettyinit:} must be called before calling the functions in this section. + +\begin{function}[EXP]{\prettye:n} + \begin{syntax} + \cs{prettye:n} \Arg{token list} + \end{syntax} + Print the token list, similar to \cs{pretty:n}, but is fully expandable. +\end{function} + +\begin{function}[EXP]{\prettye:w} + \begin{syntax} + \cs{prettye:w} \meta{tokens} \cs{prettystop} + \end{syntax} + Print the tokens until \cs{prettystop} is seen. Useful for inspecting the content of the input stream. + + Note that the input stream will be tokenized and has catcode frozen. Use with care. +\end{function} + +\subsection{Lua programming interface} + +\cs{prettyinit:} must also be called before calling the functions in this section. + +\begin{function}{prettyprint} + \begin{syntax} + |prettyprint(|\meta{content}|)| + \end{syntax} + Print the content, which should be a table of token objects. + + For convenience, you can pass multiple arguments. Strings are also supported. +\end{function} + + \subsection{View result} The result is printed to a HTML file named |pretty-|\meta{jobname}|.html| by default. @@ -58,24 +101,17 @@ Note that the HTML file will not be touched if nothing is printed, as such it's Why HTML file? \begin{itemize} - \item Because if the TeX program stops with error / has some error that corrupts the PDF output, the output will even with corrupted more by the debug print. - \item Printing to the console is extremely limited (difficult syntax highlighting/scrolling/line wrapping), and most likely cluttered with the traceback/other TeX default output. - \item Output to another \TeX\ file to be compiled is a bit absurd, and compiling \TeX\ file takes longer than loading a HTML file. + \item If the \TeX\ program stops with error / has some error that corrupts the PDF output, the output will even with corrupted more by the debug print. + \item Printing to the console is extremely limited (difficult syntax highlighting/scrolling/line wrapping), and most likely cluttered with the traceback/other \TeX\ default output. + + (nevertheless, there might be plan to support output to console with syntax highlighting later.) + \item Output to another \TeX\ file to be compiled works as well; however it's necessary to run another instance of |latexmk| (or other tool used to compile \TeX\ code) + and compiling \TeX\ file takes longer than loading a HTML file. \end{itemize} -By default, the output refreshes whenever the TeX file is recompiled. The behavior +By default, the output refreshes whenever the \TeX\ file is recompiled. The behavior can be customized with \cs{prettyrefreshstrategy} and \cs{prettyrefreshduration}. -\subsection{\LaTeX2 interface} - - -\begin{function}{\prettyN,\prettyX,\prettyO,\prettyV} - \begin{syntax} - \cs{prettyN} \Arg{token list} \\ - \end{syntax} - Alias of the correspondingly-named commands. -\end{function} - \subsection{Additional functions} There are also these functions, for convenience. @@ -85,30 +121,82 @@ There are also these functions, for convenience. \cs{pretty:nn} \Arg{token list} \Arg{token list} \cs{pretty:nnn} \Arg{token list} \Arg{token list} \Arg{token list} \end{syntax} - Print multiple token lists. + Print multiple token lists. Its effect is similar to multiple consecutive calls to \cs{pretty:n}. +\end{function} + +\begin{function}[EXP]{\prettye:nn, \prettye:nnn} + \begin{syntax} + \cs{prettye:nn} \Arg{token list} \Arg{token list} + \cs{prettye:nnn} \Arg{token list} \Arg{token list} \Arg{token list} + \end{syntax} + Similar to multiple consecutive calls to \cs{prettye:n}. +\end{function} + +\begin{function}[EXP]{\prettye:nw, \prettye:nnw} + \begin{syntax} + \cs{prettye:nw} \Arg{token list} \meta{tokens} \cs{prettystop} + \cs{prettye:nnw} \Arg{token list} \Arg{token list} \meta{tokens} \cs{prettystop} + \end{syntax} + Similar to call(s) to \cs{prettye:n} followed by a call to \cs{prettye:w}. \end{function} \begin{function}{\pretty:w} \begin{syntax} \cs{pretty:w} \meta{token list} \cs{prettystop} \end{syntax} - Print the content of \meta{token list}. For now, it must be brace-balanced. + Print the content of \meta{token list}. + + Same restriction applies -- the catcode is frozen. + + In addition -- for now, it must be brace-balanced and if \meta{token list} has a surrounding brace group it will be removed. Use \cs{prettye:w} instead if possible. \end{function} -\begin{function}{\prettyshow:N} +\begin{function}[EXP]{\prettystop} + \begin{syntax} + \cs{prettystop} + \end{syntax} + Only used as a delimiter for |:w| functions. For convenience, this function is defined to do nothing. +\end{function} + +\begin{function}{\prettyshow:N,\prettyshow:c} \begin{syntax} \cs{prettyshow:N} \meta{token} + \cs{prettyshow:c} \Arg{control sequence name} \end{syntax} Show the meaning of a |N|-type argument. \end{function} +\subsection{\LaTeXe\ interface} + +\begin{function}{\prettyN,\prettyX,\prettyO,\prettyV,\prettyinit,\prettyshowN,\prettyshowC} + \begin{syntax} + \tn{prettyN} \Arg{token list} + \tn{prettyX} \Arg{token list} + \tn{prettyO} \Arg{token list} + \tn{prettyV} \meta{tl var} + \tn{prettyinit} + \tn{prettyshowN} \meta{token} + \tn{prettyshowC} \Arg{control sequence name} + \end{syntax} + Alias of the correspondingly-named commands. +\end{function} + +\begin{function}[EXP]{\prettyeN,\prettyeW} + \begin{syntax} + \cs{prettyeN} \Arg{token list} + \cs{prettyeW} \meta{tokens} \cs{prettystop} + \end{syntax} + Alias of the correspondingly-named commands. Only available in \LuaTeX. +\end{function} + + \subsection{Customization} These variables can be redefined before the -first call to |\pretty:n| to customize the behavior. +first call to \cs{pretty:n} or \cs{prettyinit:} to customize the behavior. \begin{variable}{\prettyfilename} - The output file name. Defaults to |pretty-|\meta{jobname}|.html|, as mentioned above. + The output file name. Defaults to |pretty-|\meta{jobname}|.html|, as mentioned above. \end{variable} \begin{variable}{\prettyrefreshstrategy} @@ -121,18 +209,13 @@ first call to |\pretty:n| to customize the behavior. The duration between two consecutive refresh check, in milliseconds. Defaults to 1000. \end{variable} -\begin{variable}{\prettypreamble} - The HTML source code preamble. This can be redefined to change styles, but the - behavior is not guaranteed. -\end{variable} - \section{Implementation} Unfortunately, the implementation is not typesetted in \TeX. Read the |.sty| file. \StopEventually{^^A - \PrintChanges - \PrintIndex + \PrintChanges + \PrintIndex } \Finale |