From c00656779e19523d32d1d563e37f48709e487ce3 Mon Sep 17 00:00:00 2001
From: Norbert Preining <norbert@preining.info>
Date: Sun, 29 May 2022 03:00:41 +0000
Subject: CTAN sync 202205290300

---
 macros/latex/contrib/prettytok/prettytok.tex | 139 +++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 macros/latex/contrib/prettytok/prettytok.tex

(limited to 'macros/latex/contrib/prettytok/prettytok.tex')

diff --git a/macros/latex/contrib/prettytok/prettytok.tex b/macros/latex/contrib/prettytok/prettytok.tex
new file mode 100644
index 0000000000..d21af2d0fe
--- /dev/null
+++ b/macros/latex/contrib/prettytok/prettytok.tex
@@ -0,0 +1,139 @@
+%! TEX program = lualatex
+\ProvidesFile{prettytok.tex} [2022/05/28 v0.0.0 Pretty-print token lists]
+% yes, this is not dtx
+\documentclass{l3doc}
+%\usepackage[a4paper,margin=25mm,left=50mm,nohead]{geometry}
+%\usepackage[numbered]{hypdoc}
+%\usepackage{\jobname}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\begin{document}
+\GetFileInfo{\jobname.tex}
+\DoNotIndex{\newcommand,\newenvironment}
+
+\title{\textsf{prettytok} --- Pretty-print token lists\thanks{This file
+   describes version \fileversion, last revised \filedate.}
+}
+\author{user202729%
+%\thanks{E-mail: (not set)}
+}
+\date{Released \filedate}
+
+\maketitle
+
+\changes{v0.0.0}{2022/05/18}{First public release}
+
+\begin{abstract}
+	Pretty-print token lists.
+\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}.
+\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.
+\end{function}
+
+\subsection{View result}
+
+The result is printed to a HTML file named |pretty-|\meta{jobname}|.html| by default.
+Open the file in any browser to view the result.
+
+Note that the HTML file will not be touched if nothing is printed, as such it's encouraged to add a line such as |\pretty:n {start}| right after loading the file.
+
+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.
+\end{itemize}
+
+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.
+
+\begin{function}{\pretty:nn, \pretty:nnn}
+	\begin{syntax}
+		\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.
+\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.
+\end{function}
+
+\begin{function}{\prettyshow:N}
+	\begin{syntax}
+		\cs{prettyshow:N} \meta{token}
+	\end{syntax}
+	Show the meaning of a |N|-type argument.
+\end{function}
+
+\subsection{Customization}
+
+These variables can be redefined before the
+first call to |\pretty:n| to customize the behavior.
+
+\begin{variable}{\prettyfilename}
+	The output file name.  Defaults to |pretty-|\meta{jobname}|.html|, as mentioned above.
+\end{variable}
+
+\begin{variable}{\prettyrefreshstrategy}
+	The auto-refresh strategy. Allowed values are 0-4. 0 is no refresh. \\
+	Which value works best depends on the particular browser. \\
+	On Google Chrome, passing |--allow-file-access-from-files| may be useful.
+\end{variable}
+
+\begin{variable}{\prettyrefreshduration}
+	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
+}
+
+\Finale
+\end{document}
-- 
cgit v1.2.3

