summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/cprotectinside/cprotectinside.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/cprotectinside/cprotectinside.tex')
-rw-r--r--macros/latex/contrib/cprotectinside/cprotectinside.tex167
1 files changed, 167 insertions, 0 deletions
diff --git a/macros/latex/contrib/cprotectinside/cprotectinside.tex b/macros/latex/contrib/cprotectinside/cprotectinside.tex
new file mode 100644
index 0000000000..976d067ec7
--- /dev/null
+++ b/macros/latex/contrib/cprotectinside/cprotectinside.tex
@@ -0,0 +1,167 @@
+%%! TEX program = lualatex
+\ProvidesFile{cprotectinside.tex} [2022/06/25 v0.0.0 Use cprotect arbitrarily deeply nested]
+\documentclass{l3doc}
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\usepackage{hyperref}
+\usepackage{csquotes}
+%\MakeOuterQuote{"}
+\begin{document}
+\GetFileInfo{\jobname.tex}
+
+\title{\textsf{cprotectinside} --- Use cprotect arbitrarily deeply nested
+\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}
+
+\let\backtick=`
+\MakeShortVerb{`}
+
+\begin{abstract}
+ Extends on `cprotect` package to allow users to use verbatim-like commands inside arbitrary
+ parameters.
+
+\end{abstract}
+
+\section{Usage}
+
+
+\subsection{Main function}
+\begin{function}{\cprotectinside}
+ \begin{syntax}
+ \cs{cprotectinside} \meta{delimiter} \meta{content} \\
+ \end{syntax}
+ Execute \meta{content} that possibly contains verbatim content.
+
+ This is a bit hard to explain. To give an example:
+
+ Take an example from \url{https://tex.stackexchange.com/q/24574},
+ you want to write \verb+\textbf{using \verb|-i| as}+. Unfortunately, `\textbf` does not accept
+ `\verb` %` %workaround for syntax highlighter
+ in input.
+
+ Then you need to
+
+ \begin{itemize}
+ \item Wrap the whole code inside `\cprotectinside{!}{ ... }`
+ \item Wrap each `\verb` %`
+ command (and its arguments) inside `!...!`.
+ \end{itemize}
+
+The resulting code would be:
+
+ \begin{verbatim}
+ \cprotectinside{!}{\textbf{\using !\verb|-i|! as}}}
+ \end{verbatim}
+
+The first argument `!` is the delimiter, it can be changed as long as it's changed correspondingly in the \meta{content} part.
+
+In this simple case, it's possible to simply use `cprotect`. Nevertheless this package is useful in some cases, for example...
+
+\begin{itemize}
+ \item Value of keyval argument:
+
+ \begin{verbatim}
+ \cprotectinside{*}{
+ \begin{lstlisting}[language=Perl,
+ caption={text *\verb+myverb+* some more text}]
+ code code
+ code code
+ \end{lstlisting}
+ }
+ \end{verbatim}
+
+ \item Pseudo-environments (contrived example):
+
+ \begin{verbatim}
+ \cprotectinside{*}{
+ \begin{align}
+ 1 &= 2+\text{text *\verb+text+* text}
+ \end{align}
+ }
+ \end{verbatim}
+\end{itemize}
+
+
+
+\end{function}
+
+
+\subsection{Common issues}
+
+\begin{itemize}
+
+ \item If you get the error message
+
+ \begin{quote}
+ LaTeX cmd Error: Verbatim-like command \backtick `\cprotectinside`' illegal in argument.
+ \end{quote}
+
+ You can't use a literal TAB character inside \meta{content}
+ because of a known bug: \url{https://tex.stackexchange.com/q/508001}
+
+ (when the tab character is at the begin of a line -- which is the most common case, it will give no error message but they will be removed from the code. Which might matter for `verbatim` environments, for example.)
+
+ \item Note that the following code will not work as desired
+ \begin{verbatim}
+ \cprotectinside{!}{
+ some content
+ %}
+ some other content
+ }
+ \end{verbatim}
+ because of the unbalanced brace in the comment. It's possible to use characters different from braces to delimit the second argument
+ \begin{verbatim}
+ \cprotectinside{!}|
+ some content
+ %}
+ some other content
+ |
+ \end{verbatim}
+ or use the workarounds described in the documentation of \texttt{cprotect} package.
+
+ \item Contents that is intended to be passed as
+ \enquote{text}
+ to the outer command must not be `cprotect`ed.
+
+ As a general rule of thumb, if the content inside can be replaced with a `\includegraphics` with no compilation error,
+ it can be `cprotect`ed.
+
+
+\end{itemize}
+
+\subsection{Implementation note}
+
+The working of the code is similar to how \texttt{cprotect} package works. Described in more details
+in \url{https://tex.stackexchange.com/q/622512} (post by the package author).
+
+In particular, given the code
+\verb+\textbf{using \verb|-i| as}+
+the command might transform it to become
+\verb+\textbf{using \cpiContentAi/ as}+
+then execute the resulting code.
+Where `\cpiContentAi/` is defined to be something similar to `\input{inner.tex}`, with the (imaginary) file
+`inner.tex` has the content `\verb|-i|\empty`.
+
+The string to be appended inside each inner chunk defaults to `\empty`, used to remove the space generated at the
+end of each file (similar in purpose to `^^E^^L` used by `cprotect` package), but it can be configured:
+
+\begin{variable}{\cprotectinsideAppend}
+ The content to be appended to every inner macro. Should already be detokenized. Defaults to the detokenized string \texttt{\textbackslash empty}.
+\end{variable}
+
+
+\StopEventually{%
+ \PrintChanges
+ \PrintIndex
+}
+\Finale
+\end{document}