Introduce an f-specification argument in ltcmd

base/changes.txt

@@ -6,6 +6,10 @@ to completeness or accuracy and it contains some references to files that are
 not part of the distribution.
 ================================================================================
 
+2024-12-12  Joseph Wright  <[email protected]>
+	* ltcmd.dtx, usrguide.tex
+	New "f"-type argument
+
 2024-12-10  Yukai Chou  <[email protected]>
 	* ltxref.dtx (subsection{Cross Referencing})
 	Replace \@tempa with \reserved@a in \Ref (gh/1579)

base/doc/ltnews41.tex

@@ -227,6 +227,39 @@ \subsection{Fixing the spacing after display math}
 
 \section{New or improved commands}
 
+\subsection{Collecting environment bodies verbatim}
+
+The mechanisms in \pkg{ltcmd} (\enquote{\pkg{xparse}}) offer a powerful way to
+specify a range of types of document command and environment syntax. This
+includes the ability to collect the entire body of an environment, for cases
+where treating it as a standard argument is useful. It is also possible in
+\pkg{ltcmd} to define arguments which grab their content verbatim, another
+specialist argument form. To date, however, it was not possible to combine
+these two ideas.
+
+In this release, a new specifier~\texttt{f} is introduced, which collects the
+body of an environment in a verbatim-like way. Like the existing
+\texttt{v}~specification, each separate line is marked by the special
+\cs{obeyedline} marker, which as standard issues a normal paragraph. Thus, this
+new specifier is usable both for typesetting and collecting file contents (the
+\texttt{f} indicates \enquote{\texttt{filecontents}-like}). Thus, we may use
+\begin{verbatim}
+\NewDocumentEnvironment
+  {MyVerbatim}{!O{\ttfamily} +f}
+  {\begin{center} #1 #2\end{center}} {}
+\begin{MyVerbatim}[\ttfamily\itshape]
+  % Some code is show here
+  $y = mx + c$
+\end{MyVerbatim}
+\end{verbatim}
+to obtain
+\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} +f}
+  {\begin{center} #1 #2\end{center}} {}
+\begin{MyVerbatim}[\ttfamily\itshape]
+  % Some code is show here
+  $y = mx + c$
+\end{MyVerbatim}
+
 \section{Code improvements}
 
 \subsection{Refinement of \cs{MakeTitlecase}}

base/doc/usrguide.tex

@@ -43,7 +43,7 @@
     \texttt{usrguide.tex} for full details.}%
 }
 
-\date{2024-11-17}
+\date{2024-12-12}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -858,6 +858,41 @@ \subsection{Typesetting verbatim-like material}
 Similarly, the \texttt{verbatim} environment sets up the meaning of \cs{par}
 suitable for breaking lines.
 
+\subsection{Verbatim environments}
+\label{sec:cmd:verbenv}
+
+In some cases, as well as grabbing an environment body you will want the
+contents to be treated verbatim. This is available using the argument
+specification~\texttt{f}. Like the \texttt{b} specification, this has to be the
+last one. Thus for example
+\begin{verbatim}
+\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} f}
+  {\begin{center} #1 #2\end{center}} {}
+\begin{MyVerbatim}[\ttfamily\itshape]
+  % Some code is show here
+  $y = mx + c$
+\end{MyVerbatim}
+\end{verbatim}
+will typeset
+\NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} f}
+  {\begin{center} #1 #2\end{center}} {}
+\begin{MyVerbatim}[\ttfamily\itshape]
+  % Some code is show here
+  $y = mx + c$
+\end{MyVerbatim}
+
+As grabbing the entire contents verbatim, newlines are always permitted: there
+is no need for a |+| here. As for the \texttt{v} specification, new lines are
+stored as \cs{obeyedline}. In a similar fashion to the
+\texttt{b}~specification, by default \emph{newlines} are trimmed at both ends
+of the body. Putting the prefix |!| before \texttt{f} suppresses
+space-trimming.
+
+Notice that for technical reasons, we recommend that an optional argument
+coming immediately before an \texttt{f} specification should not allow any
+spaces, achieved by adding the \texttt{!} as showing in the example. However,
+this is left as a choice for the user.
+
 \subsection{Performance}
 
 For document commands where the argument specification is entirely