%! 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}
