newverbs.dtx

% \iffalse meta-comment
%<=*COPYRIGHT>
%% Copyright (c) 2012-2022 by Martin Scharrer <martin.scharrer@web.de>
%% --------------------------------------------------------------------
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
%% of this license or (at your option) any later version.
%% The latest version of this license is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3 or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Martin Scharrer.
%%
%% This work consists of the files newverbs.dtx and newverbs.ins
%% and the derived file newverbs.sty.
%<=/COPYRIGHT>
% \fi
%
% \iffalse
%<*driver>
\ProvidesFile{newverbs.dtx}[%
%<=*DATE>
    2022/10/25
%<=/DATE>
%<=*VERSION>
    v1.6a
%<=/VERSION>
    newverbs DTX file]
\documentclass{ydoc}
\GetFileInfo{newverbs.dtx}
\usepackage{newverbs}[\filedate]

%\EnableCrossrefs
%\CodelineIndex
%\RecordChanges
\begin{document}
  \DocInput{newverbs.dtx}
  %\PrintChanges
  %\PrintIndex
\end{document}
%</driver>
% \fi
%
% \CheckSum{465}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
%
% \changes{v1.0}{2010/04/05}{Initial version}
% \changes{v1.1}{2010/04/13}{Added usage of 'csquotes' macros if loaded.}
% \changes{v1.2}{2011/02/16}{Added support for 'tabularx' environments.}
% \changes{v1.2a}{2011/03/19}{Removed spurious spaces.}
% \changes{v1.3}{2011/07/24}{Added macros to collect verbatim arguments.}
% \changes{v1.4}{2019/09/09}{Added several suggested changes.}
% \changes{v1.5}{2020/09/02}{Added support for mathmode.}
% \changes{v1.6}{2021/01/06}{Changed \cs{Verbdef} to define robust commands.}
% \changes{v1.6a}{2022/10/25}{Updated repository URL. Added DEPENDS.txt file.}
%
% \DoNotIndex{\newcommand,\newenvironment,\providecommand}
%
% \GetFileInfo{newverbs.dtx}
% \author{Martin Scharrer}
% \email{martin.scharrer@web.de}
% \github{MartinScharrer/newverbs}
% \maketitle
%
% \begin{abstract}
% This package allows the definition of \cs{verb} variants which add \TeX\ code before and after the verbatim text.
% When used together with the \pkg{shortvrb} package it allows the definition of short verbatim characters which use this variants
% instead of the normal \cs{verb}.
% \end{abstract}
%
% \section{Usage}
%
% \subsection{Defining new variants of \cs{verb}}
%
% \DescribeMacro\newverbcommand     {<\textbackslash macro>}[<\textbackslash verbmacro>]{<code before>}{<code after>}
% \DescribeMacro\renewverbcommand   {<\textbackslash macro>}[<\textbackslash verbmacro>]{<code before>}{<code after>}
% \DescribeMacro\provideverbcommand {<\textbackslash macro>}[<\textbackslash verbmacro>]{<code before>}{<code after>}
% This macros allow the definition of \cs{verb} variants.
% The verbatim content is first processed using \meta{\textbackslash verbmacro} which defaults to \cs{verb}, then the
% given \TeX\ code is added before and afterwards.
% The three definition macros use |\newcommand*|, |\renewcommand*| and |\providecommand*| internally to define \meta{\textbackslash macro}, respectively.
% Afterwards \meta{\textbackslash macro} can be used like \cs{verb}. 
% The star version of \meta{\textbackslash macro} will use \meta{\textbackslash verbmacro}|*| (default: \cs{verb}|*|).
%
% See the implementation of \cs{qverb} in section~\ref{sec:impl} for an example.
%
%
% \subsection{Provided \cs{verb} variants}
%
% Two \cs{verb} variants are provided (i.e. with \cs{provideverbcommand}) by default.
%
% \DescribeMacro\qverb<char><verbatim material><char>
% This macro adds quote characters around the verbatim material.
% Two macros are used to insert the quotes: \cs{qverbbeginquote} (``) and \cs{qverbendquote} ('').
% They can be redefined by the user if required. If the \pkg{csquotes} package was loaded beforehand
% the above macros use its macros \cs{openautoquote} and \cs{closeautoquote} to take advantage of the language 
% dependent quotation marks. See the manual of \pkg{csquotes} for more details.
%
% Using \Macro\qverb<char><verbatim material><char> is equal to \\
% \Macro\qverbbeginquote\AlsoMacro\verb<char><verbatim material><char>\AlsoMacro\qverbendquote, or\\
% \MacroArgs'`'\AlsoMacro\verb<char><verbatim material><char>''
% when the default definition of the quote macros is used.
%
% \DescribeMacro\fverb<char><verbatim material><char>
% This macro adds a frame (|\fbox{}|) around the verbatim text (|\fverb+$&^_%$+| $\to$ \fverb+$&^_$+).
% A \TeX\ box is used to store the content first, then the box is framed.
% The user can define similar command using the following code:\\
% {\ttfamily
% \hspace*{2.5em}|\newverbcommand{\myverb}{\begin{lrbox}{\verbbox}}|\\
% \hspace*{10em}|{\end{lrbox}\mycommand{\usebox{\verbbox}}}|}\\
% The temporary box \cs{verbbox} is only provided inside a |\...verbcommand|.
%
% \subsection{Using \cs{verb} variants with short verbatim character}
%
% \DescribeMacro\MakeSpecialShortVerb {<\textbackslash macro>}{\textbackslash\meta{char}}
% \DescribeMacro\MakeSpecialShortVerb*{<\textbackslash macro>}{\textbackslash\meta{char}}
% This package also defines a special version of the \cs{MakeShortVerb} macro from the \pkg{shortvrb} package.
% The orignal command \Macro\MakeShortVerb*{\textbackslash\meta{char}} changes the meaning of \meta{char} so that 
% \MacroArgs<char><verbatim material><char>\ is a shorter alternative to
% \Macro\verb*<char><verbatim material><char>.
%
% The new macro \Macro\MakeSpecialShortVerb*{\textbackslash\meta{verb variant}}{\textbackslash\meta{char}} does the same, but 
% instead of \Macro\verb*\relax\relax\ it uses a \MacroArgs'\'<verb variant>*\relax which needs to be defined using \cs{newverbcommand}.
% The package \pkg{shortvrb} must be installed in order to make this macro work. It is loaded automatically by \pkg{newverbs}.
%
% The special meaning of \meta{char} can be removed using \pkg{shortvrb}'s \cs{DeleteShortVerb}, i.e.\ the same way as for 
% characters defined with the normal \cs{MakeShortVerb}.
% If a character was already made a short verbatim character it must be ``deleted'' before it can be redefined by \cs{MakeShortVerb} or
% \cs{MakeSpecialShortVerb}.
%
% \bigskip\noindent\textbf{Examples:}\\
% |\MakeSpecialShortVerb{\qverb}{\"}| will make `|"|' a short, quoting verbatim character: |"$^&$"| $\to$ "$^&$".\\
% |\DeleteShortVerb{\"}\MakeSpecialShortVerb{\fverb}{\"}| will change it definition to use \cs{fverb}: \fverb+$^&$+.
%
%
% \DescribeMacro\collectverb{<code>}<char><verbatim material><char>
% \DescribeMacro\collectverb*{<code>}<char><verbatim material><char>
% \DescribeMacro\collectverb{<code>}{<verbatim material>}
% \DescribeMacro\collectverb*{<code>}{<verbatim material>}
% This macro is supposed to be used with its \marg{code} argument at the end of user or package macro which want to typeset verbatim material.
% It will collect everything between the following \meta{char} and its next occurrence as verbatim material.
% An exception is if the following \meta{char} is `|{|', then `|}|' is taken as the end \meta{char} to simulate a normal argument to increase user friendliness.
% Afterwards \meta{code} is expanded with \marg{verbatim material} direct behind it. The macro ensures proper font settings to typeset the verbatim material.
% For this, a group is opened before the material is collected and closed directly after the given code is processed. ^^A \MacroArgs<code>{<verbatim material>}\AlsoMacro\endgroup.
% Therefore all changes done by the \meta{code} are local and the material should be typeset directly.
% (In special cases when the group is disruptive, \meta{code} can be a macro which reads both the verbatim material and the \Macro\endgroup as two arguments.
% However, then special care must be taken to use the correct font and some of the special characters may be active but have lost their definition.)
% The starred version will make spaces appear as `\collectverb*{}: :' instead of displaying them as normal spaces.
%
%
% \DescribeMacro\Collectverb{<code>}<char><verbatim material><char>
% \DescribeMacro\Collectverb*{<code>}<char><verbatim material><char>
% \DescribeMacro\Collectverb{<code>}{<verbatim material>}
% \DescribeMacro\Collectverb*{<code>}{<verbatim material>}
% This macro is supposed to be used with its \marg{code} argument at the end of user or package macro which want to collect plain verbatim material suitable to be 
% written in auxiliary files or log messages.
% It will collect everything between the following \meta{char} and its next occurrence as verbatim material without adjusting the font or defining any characters in a special way (besides being verbatim).
% The starred version will make spaces appear as `\Collectverb*{}: :' when typeset but still be written to auxiliary files as normal spaces.
% An exception is if the following \meta{char} is `|{|', then `|}|' is taken as the end \meta{char} to simulate a normal argument to increase user friendliness.
% Afterwards \meta{code} is expanded with \marg{verbatim material} direct behind it. This macro does not add any group around the code.
% Should the material be typeset after all a proper font (e.g.\ \Macro\ttfamily or \Macro\newverbsfont) must be enabled manually.
%
%
%
% \DescribeMacro\collectverbenv{<code>}
% \DescribeMacro\collectverbenv*{<code>}
% This macro is supposed to be used with its \marg{code} argument at the end of the begin-code of an user or package environment definition.
% It then collects the content of the environment as verbatim material and feeds it as an argument to the provided \meta{code} like \Macro\collectverb does 
% (see there for further details which also apply here).
% This has the following limitations: 
% When used the \Macro\begin of the environment must end with a line break, i.e.\ the source line must not include any other material afterwards.
% If the environment is defined with arguments, which is supported, the line break must be after the arguments.
% The \Macro\end of the macro must be at the beginning of an own source code line. 
% If this conditions are not met incorrect results or an error may occur. Currently trailing material on the \Macro\begin line is simply ignored, but this
% behaviour might change in future versions.
%
% The starred version will make the spaces inside the environment appear as `\collectverb*{}: :'.
% 
% \noindent Example usage:\\
% \leavevmode\noindent\bgroup\footnotesize
% |\newenvironment{myenv}{\maybesomeothercode\collectverbenv{\mycmd}}{\someendcode}| \\
%
%
% \DescribeMacro\Collectverbenv{<code>}
% \DescribeMacro\Collectverbenv*{<code>}
% This macro works like \Macro\collectverbenv but collects the environment content as plain verbatim material suitable to be 
% written in auxiliary files or log messages.
% After collecting the environment the \meta{code} is expanded with \marg{verbatim material} direct behind it. This macro does not add any group around the code.
% Should the material be typeset after all a proper font (e.g.\ \Macro\ttfamily or \Macro\newverbsfont) must be enabled manually.
%
% The starred version will make spaces appear as `\Collectverb*{}: :' when typeset but still be written to auxiliary files as normal spaces.
%
%
% \DescribeMacro\newverbsfont
% Macro which activates the font used by the \pkg{newverbs} package for the verbatim text.
% This macro can be used manually if verbatim material collected with \Macro\Collectverb or \Macro\Collectverbenv should be typeset afterall.
%
% \DescribeMacro\verbdef<\textbackslash macro><char><verbatim material><char>
% \DescribeMacro\verbdef*<\textbackslash macro><char><verbatim material><char>
% \DescribeMacro\verbdef<\textbackslash macro>{<verbatim material>}
% \DescribeMacro\verbdef*<\textbackslash macro>{<verbatim material>}
% This macro defines the \meta{\textbackslash macro} as a robust macro which typesets the \meta{verbatim material} in the usual verbatim font.
% For this the material is placed in a brace group with \Macro\newverbsfont. If a different font is wanted, this macro can be redefined locally.
% 
% If the \meta{\textbackslash macro} existed before it will be overwritten silently. If an error should be raced instead use
% \Macro\newcommand{\textbackslash macro}{} just before the \Macro\verbdef.
%
% Note that this macro is also provided by the \pkg{verbdef} package. If that package is loaded as well it definition of this macro is used, 
% independent on the order of loading the two packages.
%
%
% \DescribeMacro\Verbdef<\textbackslash macro><char><verbatim material><char>
% \DescribeMacro\Verbdef*<\textbackslash macro><char><verbatim material><char>
% \DescribeMacro\Verbdef<\textbackslash macro>{<verbatim material>}
% \DescribeMacro\Verbdef*<\textbackslash macro>{<verbatim material>}
% This macro uses \Macro\Collectverb internally to define \meta{\textbackslash macro} as the plain \meta{verbatim material}.
% This can be used to define macros for special characters, so these can be used in error or warning messages or be written into auxiliary files.
% 
% If the \meta{\textbackslash macro} existed before it will be overwritten silently. If an error should be raced instead use
% \Macro\newcommand{\textbackslash macro}{} just before the \Macro\Verbdef.
%
% Note that for maximum flexibility the such defined macros are not defined as robust macros. Therefore using them inside sectioning commands they should
% be protected using \Macro\protect to avoid syntax issues in the |.aux| file due to verbatim characters.
%
%
% \section{Compatibility with other verbatim packages}
% The compatibility with other verbatim packages is not tested yet. This package relies on the normal internal definition of \cs{verb}
% and \cs{MakeShortVerb}. Any package which changes these might break this package.
% Users which encounter incompatibilities should not hesitate to contact the package author (with details!).
%
% Since v1.2 from 2011/02/16 the new verbatim macros and their short versions can be used inside \env{tabularx} environments.
% This package patches an internal macro of \pkg{tabularx} to achieve this compatibility.
%
% \StopEventually{}
% \section{Implementation}
%
% \iffalse
%<@newverbs.sty>
% \fi
%
% \Finale
\endinput