path: root/Master/texmf-dist/tex/latex/nicetext/niceverb.sty

\NeedsTeXFormat{LaTeX2e}[1994/12/01]
\ProvidesPackage{niceverb}[2015/11/09 v0.61
                           minimize doc markup (UL)] 

%% Copyright (C) 2009-2012, 2014 2015 Uwe Lueck, 
%% http://www.contact-ednotes.sty.de.vu 
%% -- author-maintained in the sense of LPPL below -- 
%%
%% This file can be redistributed and/or modified under 
%% the terms of the LaTeX Project Public License; either 
%% version 1.3a of the License, or any later version.
%% The latest version of this license is in
%%     http://www.latex-project.org/lppl.txt
%% We did our best to help you, but there is NO WARRANTY. 
%%
%% Please report bugs, problems, and suggestions via 
%% 
%%   http://www.contact-ednotes.sty.de.vu 
%%
%% ==== &\newlet                             ====
%% |\newlet<cmd><cnd>| counters the risk of mistyping <cmd> 
%% with `\@ifdefinable', and even saves some code lines:
\providecommand*{\newlet}[2]{\@ifdefinable#1{\let#1#2}}
\@onlypreamble\newlet
%%
%% ==== Switching Category Codes             ====
%% Underscore as a ``private letter," using 'stacklet' with v0.5:
\RequirePackage{stacklet} \PushCatMakeLetter\_          %% 2012/08/27
%% v0.3 introduced `\AssignCatCodeTo' and `\MakeNormal'.
%% v0.5 abolishes the former again and uses             %% former 2012/08/28
%% 'actcodes' for some part of `\catcode' switching:
\RequirePackage{actcodes}
%% |\CatCode{\<character>}| 
%% (or simply |\CatCode\<character>|)
%% saves one token per use and works when the category code 
%% of \qtd{&`} (``single left quote") has changed. 
%% As of v0.5, it may be defined by a different package: 
\providecommand*{\CatCode}{\catcode`}     %% \provi... 2012/08/27
% \newcommand*{\CatCode}[1]{\catcode`#1 } %% no better 2010/02/27
%% `\CatCode' is near to be moved into the 'catcodes' bundle, 
%% and basic commands from 'stacklet' and 'actcodes' 
%% may be reimplemented using it 
%% ('manycats'; 'allcats' for loading entire 'catcodes' 
%%  in good order).
%% 
%% |\AssignCatCodeTo{<number>}{\<char>}| \              %% \ 2012/08/28
%% no longer is considered 
%% useful (counted tokens in `memory.tex') and replaced by 
%% `\CatCode'.
% \newcommand*{\AssignCatCodeTo}[2]{\catcode`#2=#1\relax}
%% |\MakeLetter\<char>| is replaced by the 'stacklet' package---I
%% thought, but \emph{here} it is also needed to declare 
%% the ``private letters" of the package that is documented. 
%% This should be ``variable." OK, the new (v0.5) `\private_letters'
%% is a step towards this:
\newcommand*{\private_letters}{\CatCode\@11\CatCode\_11\relax}
%% |\MakeOther\<char>| and |\MakeActive\<char>| were implemented 
%% here before v0.5, now they are in 'actcodes'~...
% \def        \MakeOther {\AssignCatCodeTo{12}}
%% % |\MakeActive\<char>| just revives the meaning of <char> 
%% % it had most recently 
%% % (as an &\active character ... 
%% %  maybe ``Undefined control sequence" unless ...) 
%% % This is fine for reviving 'niceverb' functionality 
%% % after having disabled it by `\MakeNormal'\linebreak[0]---provided 
%% % no other package used <char> actively in the meantime ...
%% % % \providecommand*{\MakeActive}[1]{\CatCode#1\active}
%% % We take a copy |\MakeActiveHere| of `\MakeActive' 
%% % as the latter may become a dangerous thing for compatibility 
%% % with 'hyperref'.
%% % % \@ifdefinable\MakeActiveHere{%
%% % %    \let\MakeActiveHere\MakeActive}
%% % %    %% <- TODO aliascid + elsewhere 2010/03/12
%% |\MakeActiveLet\<char>\<macro name>| 
%% % is provided by 'actcodes' 
%% % (which does not provide `\MakeActive').    %% rm. 2012/09/27
%% % We take a copy |\MakeActiveLetHere| as well:
%% likewise is in 'actcodes'. 'niceverb' takes a copy 
%% |\MakeActiveLetHere| of it for dealing with 'hyperref' 
%% (see \secref{hyperref}). 
%% 'hyperref'-compatibility of mere `\MakeActive' 
%% is not provided any longer:
\newlet\MakeActiveLetHere\MakeActiveLet
%% %% |\MakeAlign\&| can be used to restore the meaning of `&' after we 
%% %% have made it `\active'.
%% % \providecommand*{\MakeAlign} {\AssignCatCodeTo4}
%% For restoring the usual category codes of \TeX's special 
%% characters later, we store them now.
%% (I.e., these characters are listed in the macro `\dospecials' 
%%  that expands to
%%  $$\mbox{\tt\def\do{\string\do\unskip\string}\dospecials}$$
%%  their category codes are
%% {\CatCode\#6%% was \AssignCat... 2012/08/27
%%  \CatCode\$3%% fifinddo-interference!? TODO 2010/02/27
%%  \CatCode\&4%% fifinddo-interference!? TODO 2010/02/27
%%  \def\do#1{\def\do##1{, 
%%  \the\CatCode##1}\the\CatCode#1}\dospecials} 
%% respectively; ``end of line", ``ignored", ``letter", ``other", and 
%% ``invalid" are missing---cf. {\it \TeX book} Chap.\,7.)
\def\do#1{\expandafter 
%   \chardef \csname normal_catcode_\string#1\expandafter \endcsname
%% <- v0.6 2014/03/22: First I thought ``too few `\expandafter's"; 
%%    actually the original `\expandafter' has no effect ->
  \chardef \csname normal_catcode_\string#1\endcsname
    \CatCode#1\relax}
\dospecials
%% Tests: 
%% %\withcsname\show normal_catcode_\string\\\endcsname %% 2014/03/22
%% ``normal category code" of `\' is 
%% \expandafter\the\csname normal_catcode_\string\\\endcsname,
%% ``normal category code" of `$' is 
%% \expandafter\the\csname normal_catcode_\string\$\endcsname;
%% ``normal category code" of `&' is 
%% \expandafter\the\csname normal_catcode_\string\&\endcsname.%%%
%% \footnote{\LaTeX's \cs{nfss@catcodes} is similar, 
%%           but it makes space-like characters ignored. 
%%           Also cf. 'ltfinal.dtx'. 
%%           TODO: &\RestoreNormalCatcodes.} %% 2010/03/06
%%
% \newcommand*{\make_iii_other}{\MakeOther\\\MakeOther\{\MakeOther\}}
  %% <- replaced 2009/04/05
%% |\MakeNormal\<char>| saves you from remembering ...
\newcommand*{\MakeNormal}[1]{%
  \@ifundefined{\norm_catc_str#1}%
             {\MakeOther#1}%
             {\CatCode#1\csname\norm_catc_str#1\endcsname\relax}}
\newcommand*{\norm_catc_str}{normal_catcode_\string} 
  %% TODO add ^^I and ^^M
  %% TODO save char tokens  %% 2012/08/27
%% We take a copy |\MakeNormalHere| of `\MakeNormal' as 
%% with `\MakeActive'.
\newlet\MakeNormalHere\MakeNormal
%%
%% ==== Robustness by &\IfTypesetting\ or So ====
%% \label{sec:iftype}
%% It seems we need some own ways 
%% of robustifying (as opposed to \LaTeX's `\protect' and %% 2014/03/20
%% `\DeclareRobustCommand'---sometimes, 
%%  especially for certain active characters)
%% to achieve various 
%% compatibilities---using 
%% %\begin{center}
%%   \[|\IfTypesetting{<if>}{<unless>}|\]%%%.
%% %\end{center}
%% It also saves some `\expandafter's.
\providecommand*{\IfTypesetting}{%
%     \relax 
%% <- This `\relax' suppressed ligatures of single right quotes!
%% %%^ arrow 2014/03/20
%% %% removed 2010/03/23
    \ifx \protect\@typeset@protect
          \expandafter \@firstoftwo 
    \else \expandafter \@secondoftwo \fi}
%% %\begin{center}
%%   \[|\nvSelfProtect{<cmd-char>}{<typeset>}|\] 
%% %\end{center}
%% is another idea. 
%% In ``typesetting mode," <typeset> is run. 
%% Otherwise a single unexpanded token <cmd-char> remains.
%% TODO bad at `\shipout'.
%% No `\protect' appears, and as opposed to \LaTeX's 
%% protection mechanism, running <typeset> does not 
%% require a second macro name.
%% The idea is that 
%% %`\nvSelfProtect{<cmd-char>}{<typeset>}'
%% `\nvSelfProtect{#1}{#2}'
%% is the \emph{definition} (substitution text---on 
%% token level) of <cmd-char>.\footnote{This 
%%     may go into a separate package under a different name later.}
\newcommand*{\nvSelfProtect}[2]{%
    \ifx \protect\@typeset@protect
           \nv_expand_else{#2}%                 %% braces 2014/03/26
%   \else  \protect#1\fi}
    \else  \noexpand#1\fi}                      %%  works 2014/03/28
\def\nv_expand_else#1\else#2\fi{\fi#1}
%% %% 2014/03/27
%% Sometimes ``control sequences" get definitions with 
%% `\svSelfProtect' below whose first argument then is 
%% an active character---the ``control sequence" then 
%% is the ``permanent alias" of the active character.
%% This is a somewhat ``indirect self"-protection.
%% At other places, the ``self"-protection is more 
%% direct. Then |\NewSelfProtectedCommand{<cmd>}{<def>}| avoids 
%% mistakes from mistyping <cmd> and saves some code.
%% It works like `\newcommand*', provides the 
%% `\svSelfProtect', and your definition <def> needs to contain 
%% the second argument of `\svSelfProtect' only. 
%% \emph{Arguments} are not supported currently 
%% (TODO---well, 3 applications 2014/03/27):{\sloppy\par}
\newcommand*{\NewSelfProtectedCommand}[2]{%
    \newcommand*#1{\nvSelfProtect#1{#2}}}
\@onlypreamble\NewSelfProtectedCommand
%% TODO 3 applications for the permanent alias case,
%% saving catcode changes ... %% 2014/03/28
%%
%% \strong{Testing:}
\newcommand*{\nvShowProtectedEdef}[1]{%
    \protected@edef\@tempa{#1}\show\@tempa}
%%
%% ==== Shared Shorthand Macros              ====
%% |\begin_min_verb| is a beginning shared by some macros here. 
%% It begins like \LaTeX's `\verb', apart from the final `\tt'.
%% %% 2014/03/18:
%% `\bgroup' is needed for `\hbox' and must be balanced by 
%% an `\egroup' counterpart later.
\newcommand*{\begin_min_verb}{% 
  \relax \ifmmode \hbox \else \leavevmode\null \fi 
  \bgroup \tt}
%% For typographical additions (``decorations") to the verbatim material, 
%% we collect it in a box register addressed by |\niceverb_savebox|:
\newsavebox\niceverb_savebox
%% |\SetNiceVerbSaveBox| starts reading the (``meta-")verbatim 
%% material:
\newcommand*{\SetNiceVerbSaveBox}{%
    \setbox\niceverb_savebox\hbox\bgroup}
%% |\NVerb|, |\HardNVerb|, or |\NiceMaybeMetaVerb|
%% with an optional argument about as `[\<id>_egroup]' should follow, cf. 
%% \secref{nverb}.---There have been two applications 
%% only up to now (2014/03/19), but this may change soon.\footnote{%
%%     Thought of &\qtdnverb, but this doesn't need this kind 
%%     of treatment.}                                           %% 2014/03/20
%%
%% |\TheNiceVerbSaveBox| allows referring to the verbatim material
%% collected, in order to place it a \emph{single time}---and no
%% surrounding braces are needed:
\newcommand*{\TheNiceVerbSaveBox}{\box\niceverb_savebox}
%% TODO: 
%% \begin{center}
%%   |\NewNiceVerbDecoration{\<deco>}{\<end-name>}{<start>}{<end-code>}|
%% \end{center}
%% might save from typing `\<end-name>' twice and from typing 
%% the two `\egroup's.
%%
%% %\section{&\+*[<opt>]{<mand>} `{verbatim}' ``o''} %% 2014/03/28
%% TODO left quote verb moving: braces get lost.    %% 2014/03/28
%% %\nvShowProtectedEdef{``''&\+<name>}
%%  === Implementation of the ``Nice" Syntax ===
%% ==== &\NVerb                                  ====
%% \label{sec:nverb}
%% Discovered mistakes in this section 2014/03/19,              %% 2014/03/20
%% with respect to robustness. \ 
%% (i)~`\NVerb' not really was meant to be a user command,
%% to appear in documentation code (rather to be internal). \
%% (ii)~The attempt to make it robust was incomplete. \
%% (iii)~The code for ``not typesetting" was strange. \
%% (iv)~It is difficult to imagine that somebody attempts 
%%      to use ``verbatim" code, e.g., in a section title
%%      (while with our `&'/`\string' it's ok). 
%%      \emph{At least handy replacement for &\textsf.} \       %% 2014/03/28
%% Well, let's see. May be I once find a useful application. 
%% So I repair the code---`\protect' before &\_...`_false'.
%% |\NVerb<char><code><char>|:
\newcommand*{\NVerb}{%
    \protect\_no_nice_meta_verb_false \NiceMaybeMetaVerb}
%% |\HardNVerb<char><code><char>| does not recognize meta-variables:
\newcommand*{\HardNVerb}{%
    \protect\_no_nice_meta_verb_true \NiceMaybeMetaVerb}
\newif\if_no_nice_meta_verb_
%% %\tracingmacros=1 \tracingonline=1
%% %\pagebreak
%% %\tracingmacros=0
%% v0.6 equips both |\NVerb[<end-cmd>]| and             %% 2014/03/18
%% |\HardNVerb[<end-cmd>]| with an optional argument for a single 
%% parameter-less macro for what to do after reading 
%% verbatim text---for boxing or quoting etc.\footnote{The 
%%   goal resembles that of &\collectverb in Martin Scharrer's
%%   \ctanpkgref{newverbs}. A difference in implementation is 
%%   that the character delimiting the verbatim text 
%%   is used as a parameter delimiter for a new/temporary macro. 
%%   So the verbatim characters are fixed. Our approach will be 
%%   collecting the verbatim material in a box, if we need 
%%   something more complex than %&\niceverb_normal_egroup.
%%                                \cs{niceverb_mormal_egroup}.
%%   This allows changing category codes with &\MetaVar again, 
%%   although there hasn't been a need for this so far. 
%%   It might be useful for allowing shorthand macros in 
%%   &\MetaVar's argument.}
%% |\niceverb_egroup| then is useless and removed.
%% Macros that were assigned to it before v0.6 move into 
%% the new optional arguments.---Actually, the next macro 
%% |\NiceMaybeMetaVerb| shared by `\NVerb' and `\HardNVerb' 
%% gets the optional argument: TODO!?
%% %\tracingmacros=1 \tracingonline=1
% \newcommand*{\nice_maybe_meta_verb}[1]{%
%% %\tracingmacros=0
%% %TODO
%% %\pagebreak %% makes difference with `
\newcommand*{\NiceMaybeMetaVerb}[2][\niceverb_normal_egroup]{%
%% `\newcommand' with v0.6 must suffice for robustness, 
%% so removing 2014/03/20:
% \IfTypesetting{%
%% Mainly avoid `\verb''s noligs list which overrides definitions 
%% of some active characters, while 'cmtt' doesn't have any 
%% ligatures anyway. 
    \begin_min_verb
      \let\do\MakeOther \dospecials
%% Turn off 'niceverb' specials:
      \MakeOther\|\MakeOther\`\MakeOther\'%
      \if_no_nice_meta_verb_ \MakeOther\<%
      %%% \else    \MakeActiveLet\<\MetaVar     %% 2010/12/31
      \else        \MakeActiveLetHere\<\MetaVar %% 2011/06/20
      \fi
%     \MakeActiveLetHere #2\niceverb_egroup
      \MakeActiveLetHere #2#1%                  %% 2014/03/18
%% After the previous line has worked, we use `\def' 
%% instead of `\let', so there is no longer a need 
%% to choose a command name for the verbatim delimiter
%% -- well, \strong{no}, don't define the same 
%% macro several times. Also, the same ``end" macro 
%% might be used for different purposes, e.g., 
%% when a macro in an eventual expansion of the ``end" macro
%% is modified.
%     \MakeActiveDef     #2{#1}%                %% 2014/03/18
      \verb@eol@error %% TODO change message 2009/04/09
%   }{\string\NVerb \string#1}}
%% <- both `\string' very strange 
%%    (second one finds <char>---maybe it's active---but 
%%     then its next occurrence delimiting the verbatim code 
%%     will harm too!), 
%%    also redirecting to `\NVerb'. 
%%    (May have been ok for entries to auxiliary files.)
%%    New difficulties come from the optional argument, 
%%    which needs protection as well.---Ok, the optional 
%%    argument is not protected, and active characters 
%%    <char> must ``protect themselves," so use of 
%%    `\IfTypesetting' changes, cf. \secref{iftype}.
}
%% %2009/04/11: about `etc.' [preceding a box!? 2010/03/14]
%% [2014/03/19 removing/hiding
%%  remarks from 2009f. that I don't understand anymore~...]
\newcommand*{\niceverb_normal_egroup}{%
    \egroup 
    \niceverb_maybe_rq                   %% 2011/09/09 for \AddQuotes
    \ifmmode\else\@\fi}
% \@ifdefinable\niceverb_egroup                      %% rm 2014/03/18
%     {\let\niceverb_egroup\niceverb_normal_egroup}
%%
%% ==== Single Quotes Typeset Meta-Code          ====
%% |\LQverb| will be a ``permanent alias" 
%% for the active left single quote. 
%%
%% The verbatim feature must not act when another single left 
%% quote is ahead---we assume a double quote is intended then, 
%% and we typeset it
%% (thus the left quote feature does not allow to typeset 
%%  something verbatim that starts with a single left quote). 
%% %Rather, double quotes should be typeset then.               rm. 2014/03/25
%% In page headers, a `\protect' 
%% could %%% may                                                %% 2014/03/28
%% be in the way %%%.\footnote{% 
%% %     See \code{\string\show\cs{let_token}} below---tried %% 2014/03/24
%% %     with section title in `niceverb.tex'.}
%% before v0.6.
%% (A hook for `\relax'ing certain things in 
%% `\markboth' and `\markright' would have been an alternative. 
%%  TODO)       %% 2014/03/24
\MakeActive\`
  \newcommand*{\LQverb}{%
%   \IfTypesetting{\lq_double_test}{\protect`}}
%% New approach v0.6:
    \nvSelfProtect`\lq_double_test}
%   \IfTypesetting{\lq_double_test}{\noexpand`}}
\MakeOther\`
\newcommand*{\lq_double_test}{%
%% This test settles the next catcode, so better switch to ``other" 
%% in advance (won't harm if left quote isn't next):
%% TODO switch what?                                %% 2014/03/27
  \begingroup 
    \let\do\MakeOther \dospecials 
    \MakeOther\|%% 2010/03/09!
    \futurelet\let_token \lq_double_decide}
\newcommand*{\lq_double_decide}{%
  \ifx\let_token\LQverb
    \endgroup
    ``\expandafter \@gobble
%% ... alternative ...
%     \expandafter `%
%% does not recognize next left quote---why? TODO---Corresponding 
%% right quotes will become ``other" due to 
%% having no space at the left. 
%% TODO to be changed with 'wiki.sty'.
  \else
%     \ifx\let_token\protect                      %% rm. 2014/03/28
% %     \show\let_token           %% indeed before v0.6, 2014/03/24
%       \expandafter\expandafter\expandafter \lq_double_decide_ii
%     \else
      \endgroup
      \niceverb_maybe_qs                              %% 2011/09/09
      \expandafter\expandafter\expandafter \NVerb 
        \expandafter\expandafter\expandafter \'%
%     \fi
  \fi}
%% `\lq_double_decide_ii' continues test behind `\protect'.
\newcommand*{\lq_double_decide_ii}[1]{%
    \futurelet\let_token \lq_double_decide}
%%
%% ==== Ampersand (or &\cstx) Typesets Meta-Code ====
%% |\CmdSyntaxVerb| will be a permanent alias for the active `&'.
\MakeActive\&
  \newcommand*{\CmdSyntaxVerb}{% 
    \IfTypesetting{%
      \begin_min_verb 
%% v0.3 moves the previous line from &\cmd_syntax_verb 
%% %% <- shows bug is fixed 2010/03/09
%% where it is too late to establish private letters 
%% according to next line which was in `\begin_min_verb' 
%% earlier---an important bug fix!
      \private_letters                                  %% v0.5
      \cmd_syntax_verb
%     }{\protect&\string}}
%     }{\noexpand&\string}}
%% ... with `\string', in an `\edef', the following 
%% command cannot be properly typeset, so 
    }{\noexpand&\noexpand}}                             %% 2014/03/26
%% TODO actually test non-typesetting, maybe introduce 
%% macros that perform tests anywhere ... 
%% %e.g., `\typeout'~... %%% \typeout{``}\show&         %% 2014/03/27
\MakeNormal\&
\newcommand*{\cmd_syntax_verb}[1]{%
  \string#1\futurelet\let_token \after_cs}
%% However, `&' (or `\CmdSyntaxVerb') 
%% may fail with private letters, 
%% % (there should be a hook for them),          %% todo 2010/02/28, 
%%                                               %% rm 2014/03/17 after v0.5
%% especially in \emph{macro arguments}\footnote{%% 2010/03/05
%%     TODO: 'vfoot2e.sty' -- see notes.}
%% and with 'hyperref' in titles of              %% 2010/03/11
%% \emph{sections bearing \cs{label}s},
%% so we provide something like |\cs{<characters>}| from 
%% '\ctanpkgref{tugboat}.sty'. %% 'doc.sty'.%% corr. 2011/05/27 
\DeclareRobustCommand*{\cs}[1]{%
%   \begin_min_verb \backslash_verb #1\egroup} 
%% ... fails with `_' in footnote today (2014/03/19) so:
  \begin_min_verb \withcsname\string#1\endcsname\egroup} %% v0.6
\newcommand*{\backslash_verb}{\char`\\}
%% %% 2011/06/27: undid 2011/05/27
%% Moreover, typing `&\par' in ``short" \emph{macro arguments}
%% fails, you better type `\cs{par}' then. Likewise, 
%% `\cs{if<letters>}' and `\cs{fi}' is safer in case 
%% you want to skip some part of the documentation 
%% (e.g., a package option skips commented code)
%% by \cs{if}`<letters>'\cs{fi}.
%% Finally, there will be PDF bookmarks support for `\cs' 
%% rather than for a real `&' or `\CmdSyntaxVerb' analogue like 
%% |\cstx{<characters>}*[<opt>]{<mand>}| as follows.      %% corr. 2014/03/27
\DeclareRobustCommand*{\cstx}[1]{%              %% corr. 2010/03/17
%   \begin_min_verb \backslash_verb #1%
%% v0.6 like above:
    \begin_min_verb \withcsname\string#1\endcsname
    \futurelet\let_token \after_cs}
\newcommand*{\after_cs}{%
  \ifcat\noexpand\let_token a\egroup \space
  \else \expandafter \decide_verb \fi}
\newcommand*{\test_more_verb}{\futurelet\let_token \decide_verb}
\newcommand*{\decide_verb}{%
    \jumpteg_on_with\bgroup\braces_verb
    \jumpteg_on_with[\brackets_verb
    \jumpteg_on_with*\star_verb
  \egroup}
    %% CAUTION/TODO wrong before (... if cmd without arg
    %%         use \ then or choose usual verb...
    %%         or \MakeLetter\( etc. ... or \xspace
\newcommand*{\jumpteg_on_with}[2]{%
  \ifx\let_token#1\do_jumpteg_with#2\fi}
%% TODO cf. 'xfor', 'xspace' (&\break@loop); 
%% `\DoOrBranch#1'\,...\,`#1' or so. %% found 2010/03/05
%% %% <- `...' fix 2011/01/19
\def\do_jumpteg_with#1#2\egroup{\fi#1}
\def\braces_verb#1{\string{#1\string}\test_more_verb}
\def\brackets_verb[#1]{[#1]\test_more_verb}
\def\star_verb*{*\test_more_verb}
  %% not needed with \Auto... OTHERWISE useful in args!
%% %%2010/03/15:
%% As 'latex.ltx' has `\endgraf' as a permanent alias for the 
%% primitive version of `\par' and `\endline' for `\cr', 
%% we offer |\endcell| as a replacement for the original `&':
\let\endcell&
%%
%% ==== Escape Character Typesets Meta-Code      ====
%% \label{sec:esc}
%% |\BuildCsSyntax| will be a permanent alias for the active escape 
%% character.
\DeclareRobustCommand*{\BuildCsSyntax}{% 
  \futurelet\let_token \build_cs_syntax_sp}
\newcommand*{\build_cs_syntax_sp}{%
  \ifx\let_token\@sptoken 
    \@%                                 %% 2010/12/30
  \else %% TODO ^^M!?
    \expandafter \start_build_cs_syntax
  \fi}
\newcommand*{\start_build_cs_syntax}[1]{%
  \edef\string_built{\string#1}%
%% #1 may be active.---With Donald Arseneau's 'import.sty' (e.g.), 
%% \qtd{&_} may be needed to be `\active' with the meaning of 
%% `\textunderscore', therefore restoring its category code
%% needs some more care than with v0.32 and earlier:
  \edef\before_build_cs_sub{\the\CatCode\_}%
  \private_letters                                  %% v0.5
  \test_more_cs}
\newcommand*{\test_more_cs}{%
  \futurelet\let_token \decide_more_cs}
\newcommand*{\decide_more_cs}{%
  \ifcat\noexpand\let_token a\expandafter \add_to_cs
  \else 
%     \MakeNormalHere\_ 
%% Restoring \qtd{&_} more carefully with v0.4 
%% (`\begingroup' ... `\endgroup'!?): 
%% %% 2010/03/27
    \CatCode\_\before_build_cs_sub
    \MakeOther\@%
%     \expandafter \in@ \expandafter
%       {\csname \string_built \expandafter \endcsname 
%         \expandafter}\expandafter{\niceverbNoVerbList}%
    %% <- useless braces 2014/07/17 ->
    \expandafter \in@ \csname \string_built \expandafter 
        \endcsname \expandafter {\niceverbNoVerbList}%
    \ifin@
      \csname \string_built 
        \expandafter\expandafter\expandafter \endcsname
    \else
      \begin_min_verb \backslash_verb\string_built
        \expandafter\expandafter\expandafter \test_more_verb
    \fi
  \fi}
  %% TODO such \if nestings with ifthen!? 
 %% cf.:
%  \let\let_token,\typeout{\meaning\let_token} 
  %% TEST TODO fuer xspace!? (\ifin@)
\newcommand*{\add_to_cs}[1]{% 
  \edef\string_built{\string_built#1}\test_more_cs}
%%
%% |\AutoCmdSyntaxVerb| starts, |\EndAutoCmdSyntaxVerb| \emph{ends}
%% ``auto mode." 
\newcommand*{\AutoCmdSyntaxVerb}{%
    \MakeActiveLetHere\\\BuildCsSyntax}
\newcommand*{\EndAutoCmdSyntaxVerb}{\CatCode\\\z@}
%% |\NormalCommand{<characters>}| executes `\<characters>'
%% in ``auto mode."
\newcommand*{\NormalCommand}{} \let\NormalCommand\@nameuse
%% %% 2010/03/11:
%% Once I may want to use this feature in {\it Wikipedia}-like 
%% section titles as supported by 'makedoc', yet I cannot really 
%% apply the present feature soon, so this must wait ... 
%% (There is a special problem with `\newlabel' and 'hyperref' ...)
%% 
%% Former tests: 
%  \futurelet\LetToken\relax \relax 
%  \show\LetToken \typeout{\ifcat\noexpand\LetToken aa\else x\fi}
%%
%% |\niceverbNoVerbList| is the list of macros that will be 
%% \emph{executed} instead of being typeset. 
\newcommand*{\niceverbNoVerbList}{%
  \begin\end\item\verb\EndAutoCmdSyntaxVerb\NormalCommand
  \section\subsection\subsubsection} %% TODO!?
%% |\AddToMacro{\niceverbNoVerbList}{<macros>}| can be used to 
%% add <macros> to that list. 
\providecommand*{\AddToMacro}[2]{%   %% TODO move to ... 2010/03/05
  \expandafter \def \expandafter #1\expandafter {#1#2}}
  %% <- was very wrong 2010/03/18
%% Hey, or just |\AddToNoVerbList{<macros>}|: %% 2010/03/28
\newcommand*{\AddToNoVerbList}{\AddToMacro\niceverbNoVerbList}
%%
%% ``Auto mode" probably ain't mean a thing if it ain't invoked using 
%% \[|\AutoCmdInput{<file>}|\] for typesetting <file> in ``auto mode:" 
\newcommand*{\AutoCmdInput}[1]{%
    \begingroup 
      \AddToMacro\niceverbNoVerbList{\ProvidesFile}% 
      %% <- removed `\endinput', will be code! 2010/04/05
      \AutoCmdSyntaxVerb
      \input{#1}%
      \EndAutoCmdSyntaxVerb
    \endgroup
}
%%
%% ==== Meta-Variables                           ====
%% |\MetaVar<var-id>>| will be a permanent alias for the active \qtd{&<}.
%% v0.6 simplifies `\pdfstringdefDisableCommands'. %% was \PDF...
% \def\MetaVar#1>{%
\MakeActive\<
\newcommand*{\MetaVar}{\nvSelfProtect>\nvMetaVar}
\MakeOther\<
\def\nvMetaVar#1>{%
    \mbox{\normalfont\itshape $\langle$#1\/$\rangle$}}
%% As opposed to 'ltxguide.cls', this works outside verbatim as well.
%% TODO: offer without angles as well %% moved down 2014/03/25
%%
%% ==== Hash Mark is Code                        ====
%% |\HashVerb<digit>| will be a permanent alias for the active hash mark. 
\newcommand*{\HashVerb}[1]{{\tt\##1}}
%%
%% ==== Single Right Quotes for &\textsf         ====
%% \label{sec:rqsf}
%% |\RQsansserif| will be a permanent alias for the active single 
%% right quote. 
%%
%% One essential %% 2014/03/25
%% problem with the single right quote feature
%% %problem with the ``single right quote feature" 
%% is that a single right quote may be meant to be an apostrophe. 
%% This is certainly the case at the right of a letter. 
%% On the other hand, we assume that it is \emph{not} an apostrophe 
%%  (i)~in vertical mode (opening a new paragraph), 
%% (ii)~after a horizontal skip. 
%%
%% %% 2014/03/25:
%% Another problem is that with and \LaTeX\ 
%% (as with Plain \TeX---\meta{The \TeX book}\ p.~357), 
%% the right single quote is needed for primes in math mode, 
%% and \LaTeX\ enforces this in `\@outputpage' preparing 
%% `\write's (why? TODO) as well as page headers.
\MakeActive\'
  \newcommand*{\niceverb_rq_choice}[1]{%                %% 2014/03/27
%% We make a deal with `\active@math@prime': in math mode, 
%% the prime functionality acts; outside, the ``right quote
%% sansserif mode" acts. 
%% Test: $a'$ now works with 'niceverb'.---For 
%% page headers, in expanding without typesetting, 
%% the expansion of `\RQsansserif' must contain another active 
%% single right quote.
    \nvSelfProtect'{\ifmmode
                      \expandafter\active@math@prime
                    \else
                      \expandafter#1%
                    \fi}}
%% The following `\do_rq_sansserif' is what |\DoRQsansserif|
%% below was before v0.6. This, too, must be changed for 
%% `\active@math@char', and earlier use of `\DoRQsansserif'
%% in `\niceverb_rq_sf_test' must be replaced.
  \@ifdefinable\do_rq_sansserif
    {\def\do_rq_sansserif#1'{\textsf{#1}}}
  \newcommand*{\RQsansserif}{%
%   \IfTypesetting{\niceverb_rq_sf_test}{\protect'}}
    \niceverb_rq_choice\niceverb_rq_sf_test}
\MakeOther\'
%% Another macro just to avoid more sequences of `\expandafter':
\newcommand*{\niceverb_rq_sf_test}{%
  \ifhmode 
    \ifdim\lastskip>\z@ 
%     \expandafter\expandafter\expandafter \DoRQsansserif
      \expandafter\expandafter\expandafter \do_rq_sansserif
    \else 
      \ifnum\niceverb_spacefactor
        \expandafter\expandafter\expandafter\expandafter
          \expandafter\expandafter\expandafter 
            \do_rq_sansserif %%% \DoRQsansserif
      \else '\fi
    \fi
  \else \ifvmode 
%   \expandafter\expandafter\expandafter \DoRQsansserif
    \expandafter\expandafter\expandafter \do_rq_sansserif
    \else '\fi
  \fi}
% \nvShowProtectedEdef{'niceverb'}
\MakeOther\'
%% |\DoRQsansserif| %% 2010/03/10
%% is \emph{another} (possible) alias for the 
%% active single right quote, below.
\newcommand*{\DoRQsansserif}{%
    \niceverb_rq_choice\do_rq_sansserif}                %% 2014/03/27
%% The following cases are typical and cannot be decided by the 
%% previous criteria:
%% (i)~parenthesis, (ii)~footnotes and after ``horizontal" 
%% environments like `\[<math>\]', (iii)~section titles, 
%% (iv)~`\noindent'. 
%% We introduce some dangerous tricks---redefinitions of 
%% % \LaTeX's internals `\@footnotetext' and `\@sect' 
%% %% <- 2010/03/16 ->
%% \LaTeX's internal `\@sect' and of \TeX's primitives 
%% `\noindent' and `\ignorespaces' as well as by 
%% a signal `\spacefactor' value of 1001. 
%% %In page headers, \LaTeX\ equips the single right quote with the 
%% %meaning of `\active@math@prime' which must be overridden.
%% %TODO more serious! v0.6
%%
%% |\nvAllowRQSS| becomes more powerful with v0.6, 
%% for \secref{listmv}:
\NewSelfProtectedCommand{\nvAllowRQSS}{%
    \MakeActiveLetHere\'\RQsansserif
    \niceverb_rqsf                      %% 2014/03/27
    \niceverb_ignore}                   %% 2010/03/16
%% These and the entire right quote functionality are
%% activated by                 %% removed todo 2010/03/10
%% \[|\nvRightQuoteSansSerif|
%%   \mbox{\quad and disabled by\quad} 
%%   |\nvRightQuoteNormal|\]---at 
%% `\begin{document}'---where we collect previous settings---or 
%% later:
\AtBeginDocument{%
    \edef\before_niceverb_parenthesis{\the\sfcode`\(}%
    \newlet \before_niceverb_ignore   \ignorespaces     %% 2010/03/16
    \newlet \before_niceverb_sect     \@sect    %% \newlet 2014/03/25
    \newlet \before_niceverb_noindent \noindent}        %% 2010/03/08
%% We assume that `\@sect' has the same 
%% % We assume that `\@footnotetext' and `\@sect' have the same 
%% parameters there as in \LaTeX\ 
%% (even if redefined by another package, like 'hyperref').
\def\niceverb_sect#1#2#3#4#5#6[#7]#8{%
    \before_niceverb_sect{#1}{#2}{#3}{#4}{#5}{#6}%
%                       [{\protect\nvAllowRQSS #7}]%
%                        {\protect\nvAllowRQSS #8}}
%% With v0.6, a more general |\NiceVerbMove{<text>}| 
%% is introduced, defined in \secref{listmv}:
                        [\NiceVerbMove{#7}]%
                        {\NiceVerbMove{#8}}}
%% 2010/03/20:
\newcommand*{\niceverb_spacefactor}{\spacefactor=1001\relax}
\newcommand*{\niceverb_noindent}{%
    \before_niceverb_noindent \niceverb_spacefactor} 
\newcommand*{\niceverb_ignore}{% 
    \ifhmode \niceverb_spacefactor \fi \before_niceverb_ignore}
%%
%% Here are the main switches. With v0.6, |\nvRightQuoteSansSerif| 
%% is divided into two parts, for \secref{listmv}:
\newcommand*{\niceverb_rqsf}{%                      %% 2014/03/27
%   \MakeActiveLet\'\RQsansserif
    \sfcode`\(=1001   %% enable in parentheses 2009/04/10
%% I also added \HardNVerb+\sfcode`/=1001+ in the preamble 
%% of 'makedoc.tex'. %% 2010/03/15
%   \let\@footnotetext\niceverb_footnotetext
    \let\ignorespaces\niceverb_ignore               %% 2010/03/16
%   \let\@sect\niceverb_sect
    \let\noindent\niceverb_noindent}                %% 2010/03/08
\newcommand*{\nvRightQuoteSansSerif}{%
    \niceverb_rqsf 
    \MakeActiveLet\'\RQsansserif
    \let\@sect\niceverb_sect
    \def\niceverb_rqsf_kind{\nvAllowRQSS}}
%% <- It really must be `\def' in order to transmit the 
%% choice to the table of contents.
%%
%% With v0.6, in dealing with moving things in 
%% \secref{listmv}, section titles are handled 
%% in a more complex way. We divide the former 
%% |\nvRightQuoteNormal| into two parts:
\newcommand*{\niceverb_rq_normal}{%
%   \MakeNormal\'%                                      %% 2010/03/21
    \sfcode`\(=\before_niceverb_parenthesis\relax
    \let\ignorespaces\before_niceverb_ignore            %% 2010/03/16
    \let\noindent\before_niceverb_noindent}             %% 2010/03/08
\MakeActive\`
\newcommand*{\nvRightQuoteNormal}{%
    \MakeNormal\'%                                      %% 2010/03/21
    \niceverb_rq_normal
    \let\nv_rqsf_kind\@empty
    \ifnum\CatCode\`=\active                %% `=' missing 2015/11/09
      \ifx`\LQverb \else
        \let\@sect\before_niceverb_sect
      \fi
    \else
        \let\@sect\before_niceverb_sect
    \fi}
\MakeOther\`
%% |\nvAllRightQuotesSansSerif| %% 2010/03/10
%% (after `\begin{document}'!)
%% forces the `\textsf' feature 
%% \emph{without} testing for apostrophes. You then must be 
%% sure---DANGER! CARE!---to 
%% use \qtd{&\rq} only for obtaining an apostrophe and the 
%% double quote character \qtd{&"} for closing double quotes, 
%% or our `\dqtd{<text>}' for the entire quoting.{\sloppy\par}
\newcommand*{\nvAllRightQuotesSansSerif}{%
    \niceverb_rq_normal %%% \nvRightQuoteNormal         %% 2014/03/27
%% That's one use of |\DoRQsansserif| with v0.6:
    \MakeActiveLet\'\DoRQsansserif
    \def\niceverb_rqsf_kind{\nvAllRQSS}}                %% 2014/03/27
%% <- must be `\def' for transmissions.
\NewSelfProtectedCommand{\nvAllRQSS}{%
        \niceverb_rq_normal
%% That's the other use of |\DoRQsansserif| with v0.6:
        \MakeActiveLetHere\'\DoRQsansserif}
%% [Hiding remarks from 2010f.\ (`\ctanpkgref') 2014/03/23]
%% %I started v0.31 (signal `\sfcode'=1000, lowercase letters 
%% %get `\sfcode'=1001) because 
%% %\NVerb+\href{http://ctan.org/pkg/<pkg>}{<pkg>}+ failed. 
%% %However, what I actually needed was |\ctanpkgref{<pack-name>}|: 
%% % \DeclareRobustCommand*{\ctanpkgref}[1]{%
%% %     \href{http://ctan.org/pkg/#1}{\textsf{#1}}}
%% %... moves to 'texlinks.sty' 2011/01/24.
%%
%% ==== Boxes Highlighting Commands and Syntax   ====
%% With v0.3, we include one kind of command syntax boxes 
%% whose <content> is (in 'niceverb' syntax) 
%% delimited as \GenCmdBox+|<content>|+.
%% %% 2010/03/14: %% \newsavebox!? moves up 2014/03/19
%% |\GenCmdBox<char><content><char>}| works like 
%% `\NVerb<char><content><char>' except putting the latter's result 
%% into a framed (or coloured or ...) box.{\sloppy\par}
\newcommand*{\GenCmdBox}  {\_no_nice_meta_verb_false \gen_cmd_box}
%% |\HardVerbBox| is a variant of `\GenCmdBox' with the meta-variable 
%% feature disabled 
%% (for the documentation of the present package).
\newcommand*{\HardVerbBox}{\_no_nice_meta_verb_true  \gen_cmd_box}
\newcommand*{\gen_cmd_box}{%
% \let\niceverb_egroup\nice_collect_verb_egroup %% rm 2014/03/18
% \setbox\niceverb_savebox \hbox\bgroup 
%% <- 2014/03/19 ->
  \SetNiceVerbSaveBox
%     \if_no_nice_meta_verb_ 
%           \expandafter \HardNVerb
%     \else \expandafter \NVerb     \fi
%% <- 2014/03/19 -> [TODO use generalization]
    \NiceMaybeMetaVerb[\nice_collect_verb_egroup]%
}
\newcommand*{\nice_collect_verb_egroup}{%
    \egroup \egroup
  \ifvmode \expandafter \VerticalCmdBox
  \else    \ifmmode \hbox \fi
           \expandafter \InlineCmdBox \fi
%               {\box\niceverb_savebox}%
%% <- 2014/03/19 -> 
                \TheNiceVerbSaveBox
%% %Modifying invocation of `\niceverb_normal_egroup' 2011/11/05
%% %according to remark of 2010/03/15 for saving nesting level:
%% (Removing a remark that I don't understand 2014/03/19.)
  \ifmmode\else\@\fi
% \let\niceverb_egroup\niceverb_normal_egroup %%     rm 2014/03/19
}
%% |\nvCmdBox| will be the permanent alias for \qtd{&|}.
\newcommand*{\nvCmdBox}{\GenCmdBox\|}
%% |\VerticalCmdBox{<content>}| 
%% may eventually start a `decl' environment 
%% as in 'ltxguide.cls', looking ahead for another \qtd{&|} 
%% in order to (perhaps) append another row.
%% Another possibility is first to do some
%% \[`\if@nobreak\else \pagebreak[2]\fi'\]
%% etc. and then invoke `\InlineCmdBox'.
%% The user can choose later by some `\renewcommand'. 
%% We do the perhaps most essential thing here 
%% (again cf. `\begin_min_verb'):{\sloppy\par}
\newcommand*{\VerticalCmdBox}{%
%% v0.6 encourages a page break here 
%% according to the above idea, in order to avoid 
%% a page break after explaining subsequent code 
%% (TODO: that's a major functionality change):
             \if@nobreak\else \pagebreak[2]\fi
             \leavevmode\InlineCmdBox}
%% (2011/11/05 removing `\null'.)
%% The command declaration boxes in the documentation of 
%% Nicola Talbot's \ctanpkgref{datatool}
%% would be an especially nice realization of 
%% `\VerticalCmdBox'.\footnote{I find the documentation 
%%     of Martin Scharrer's \ctanpkgref{newverbs} package 
%%     similarly impressive.}
%%
%% |\InlineCmdBox{<content>}|, according to our idea, should not 
%% change baseline skip, even with some `\fboxsep' and `\fboxrule'.
%% (However, it may be a good idea to increase the overall 
%%  normal baseline skip.)
%% We therefore replace actual height and depth of the content by 
%% the height and depth of math parentheses.
\newcommand*{\InlineCmdBox}[1]{%
  \bgroup
%% ... needed in math mode with `\begin_min_verb'.
    \fboxsep 1pt
    \kern\SetOffInlineCmdBoxOuter
    \smash{\SetOffInlineCmdBox{\kern\SetOffInlineCmdBoxInner
                               \InlineCmdBoxArea{#1}%
                               \kern\SetOffInlineCmdBoxInner}}%
    \mathstrut
    \kern\SetOffInlineCmdBoxOuter
  \egroup
}
%% The default choice for |\SetOffInlineCmdBox| is `\fbox':
\newlet\SetOffInlineCmdBox\fbox
%% You can `\renewcommand' it to change `\fboxsep', `\fboxrule'
%% etc. or to use a `\colorbox' with the 'color' package, e.g.,
%% I used the following setting so far:
%% %% 2010/03/10
%% \begin{verbatim}
%%     \RequirePackage{color}
%%     \renewcommand*{\SetOffInlineCmdBox}
%%                   {\colorbox[cmyk]{.1,0,.2,.05}}
%% \end{verbatim}
%% |\SetOffInlineCmdBoxInner| enables controlling the inner 
%% horizontal space to the box margin independently of 
%% `\fboxsep'. 
%% %% We set it to 0\,pt. as default (it is a macro only, 
%% %% for a while).
\newcommand*{\SetOffInlineCmdBoxInner}{-\fboxsep\thinspace}
%% This choice is inspired by `\cstok' for ``boxed" things 
%% in Knuth's 'manmac.tex' which formats {\it The \TeX book}.
%% %% <- 2010/03/10
%%
%% |\SetOffInlineCmdBoxOuter| allows that the box hangs out into the 
%% margin horizontally. 
%% We set it to 0\,pt as default (it is a macro only, for a while).
\newcommand*{\SetOffInlineCmdBoxOuter}{\z@}
%% The height and depth of the frame should be the same for all 
%% inline boxes, we think.
%% The present choice |\InnerCmdBoxArea| for the spacing
%% respects code characters rather than the height and depth 
%% of the angle brackets that surround meta-variable names.
\newcommand*{\InlineCmdBoxArea}[1]{%
    \smash{#1}\vphantom{gjpq\backslash_verb}}
%% \GenCmdBox+\cmdboxitem|<content>|+ is another variant of 
%% `\GenCmdBox'. It should replace `\item[<content>]' in the 
%% `description' environment. %% 2010/03/15
\newcommand*{\cmdboxitem}{%
% \bgroup 
%   \let\niceverb_egroup\cmd_item_egroup
%   \global %% TODO!? 2010/03/15
%   \setbox\niceverb_savebox \hbox\bgroup
%% <- 2014/03/19 ->
    \SetNiceVerbSaveBox
%     \NVerb}
%% <- 2014/03/19 ->
      \NVerb[\cmd_item_egroup]}
\newcommand*{\cmd_item_egroup}{%
      \egroup \egroup %%% \egroup                %% 1 less 2014/03/19
  \item[\InlineCmdBox\TheNiceVerbSaveBox]}
%% %% 2014/03/19:
%% Does it work?
%% \begin{description}
%%   \cmdboxitem+\foo{<arg>}+ could be defined for a test.
%%   \cmdboxitem+\bar{<arg>}+ could be defined for a test as well.
%% \end{description}
%%
%%  === When 'niceverb' Gets Nasty ===
%% These things are new with v0.3.
%% ==== Meta-Variables ====
%% This is even newer than v0.3.    %% 2011/05/09
%%
%% In case you actually need $\lt$ and $\gt$ in math mode, 
%% |\lt| and |\gt| are ``provided" as aliases:
\providecommand*{\gt}{>}
\providecommand*{\lt}{<}
%%
%% ==== Quotes         ====
%% %% WRONG 2010/03/05:
%% % The left quote feature for meta-code requires that the right quote 
%% % feature---for replacing `\textsf'---is activated---no, rather:
%% % that the right quote \qtd{&'} is `\active'.
%% %
%% In order to get \emph{real} single quotes, you could use `\lq <text>\rq', 
%% maybe appending a `\ ', but the code |\qtd{<text>}| may look better 
%% and be easier to type.
\providecommand*{\qtd}[1]{`#1'}             %% provide 2012/11/27
%% However, here we get the problem that the left quote in 
%% \NVerb\+\qtd{`<code>'}+ will be unable to switch into 
%% verbatim mode entirely---then use `&', 
%% e.g., \qtd{&\qtd{&&&&}} typesets \qtd{\qtd{&&}}, i.e., 
%% the ampersand in single (non-verbatim) quotes.
% todo \qtdverb!? alternative meaning for \LQverb!? 2010/03/06
%      rather rare, & takes less space              2010/03/09
%% ... see approaches below~...
%% 
%% |\AddQuotes| automatically surrounds code with single quotes. 
%% I have so often felt that it was a design mistake 
%% to drop them (2011/09/09):
\newcommand*{\AddQuotes}{%
    \let\niceverb_maybe_qs\niceverb_add_qs}
\newcommand*{\niceverb_add_qs}{%
%% In a math display, quotes are suppressed even with `\AddQuotes':
    \ifmmode\else
      `\let\niceverb_maybe_rq\niceverb_rq
    \fi}
\newlet\niceverb_maybe_rq\relax
\newcommand*{\niceverb_rq}{'\let\niceverb_maybe_rq\relax}
%% You can undo this by |\DontAddQuotes|:
\newcommand*{\DontAddQuotes}{\let\niceverb_maybe_qs\relax}
%% The default will be the behaviour that we had before:
\DontAddQuotes 
%% With v0.6, |\qtdnverb<char><m-verb><char>| encloses the 
%% ``meta-verbatim" material with single quotes:
\newcommand*{\qtdnverb}{%
%% Don't ... after `\AddQuotes':---TODO
  \ifx\niceverb_maybe_qs\niceverb_add_qs
    \expandafter\NVerb
  \else
    \lq
%     \expandafter\NVerb\expandafter[\expandafter\egroup\expandafter]
  \fi}
%% |\dqtd{<text>}| can be used for enclosing in \emph{double} quotes 
%% with the dangerous `\nvAllRightQuotesSansSerif' (see above).
\providecommand*{\dqtd}[1]{``#1"}                   %% 2012/11/27
%%
%% ==== 'hyperref'     ====
%% \label{sec:hyperref}
%% This is for\slash about compatibility with the 'hyperref' package. 
%% (One preliminary thing: in doubt, don't load 'niceverb' earlier 
%% than 'hyperref'.) %% TODO 2010/03/14 
%%
%% We need some substitutions for PDF bookmarks with 
%% 'hyperref'. We issue them at `\begin{document}' when we know 
%% if 'hyperref' is at work.\footnote{An alternative approach would be 
%%                                    using 
%%                                    \ctanpkgref{afterpackage}
%%                                    by Alex Rozhenko.}
\AtBeginDocument{%
  \@ifpackageloaded{hyperref}{%
    \newcommand*{\PDFcstring}{%         %% moved here 2010/03/09
      \134\expandafter\@gobble\string}% %% ASCII octal encoding
    \pdfstringdefDisableCommands{%
      \let\nvAllowRQSS\empty            %% not \relax 2010/03/12
      \let\NiceVerbGeneral\empty        %% 2014/03/27
      \let\nvAllRQSS\empty              %% 2014/03/27
      \MakeActiveLetHere\<<%            %% 2014/03/28
      %% 2010/03/12
      \MakeActiveLetHere\`\lq \MakeActiveLetHere\'\rq
      \MakeActiveLetHere\&\PDFcstring 
      \def\cs{\134}%                    %% 2010/03/17, 2011/06/27
%% The typesetting version of `\BuildCsSyntax' (\secref{esc}): 2014/07/16
%%                                             %% showfile.tex 2014/07/12
      \withcsname\def BuildCsSyntax \endcsname{\cs}%
%% ... disables `\niceverbNoVerbList'; better switch off 
%% auto mode with section headings TODO                 %% 2014/07/17
%% (modify `\@startsection')
      \let\decide_more_cs\bookmark_more_cs
    }%
%% Moreover, in order to avoid spurious                 %% 2010/03/14
%% \texttt{Label(s) may have changed} with 'hyperref', 
%% a single right quote must be \emph{read} as active 
%% by a `\newlabel' if and only if it has been active when 
%% `\@currentlabelname' was formed.\footnote{This uses 
%%      \cs{@onelevelsanitize}, therefore &\protect doesn't 
%%      change the behaviour of ``active" characters.} 
%% as `\active'. We use `\protected@write' as this cares for 
%% `\nofiles'. `\@auxout' may be `\@partaux' for `\include'.
    \newcommand*{\niceverb_aux_cat}[2]{%                %% 2010/03/14
        \protected@write\@auxout{}{\string#1\string#2}}%
%% v0.5 restricts ``activating" to `\MakeActiveLet':
%     \renewcommand*{\MakeActive}[1]{%
%         \MakeActiveHere#1%
%         \niceverb_aux_cat\MakeActiveHere#1}%
    \renewcommand*{\MakeActiveLet}[2]{%
        \MakeActiveLetHere#1#2%
%         \niceverb_aux_cat\MakeActiveHere#1}%
        \protected@write\@auxout{}{%
            \string\MakeActiveLetHere\string#1\string#2}}% 
    \renewcommand*{\MakeNormal}[1]{%
        \MakeNormalHere#1%
        \niceverb_aux_cat\MakeNormalHere#1}%
  }{}%
}
%% % todo doesn't 'babel' have the same problem? 2010/03/12
%% ==== 'hyper-xr'     ==== %% 2010/03/21
%% With the 'hyper-xr' package creating links into external documents, 
%% preceding `\externaldocument{<file>}' with 
%% `\MakeActiveLet\&\CmdSyntaxVerb' may be needed. 
%% I do not want to redefine something here right now as %% typo 2010/11/09 
%% I have too little experience with this situation.
%% 
%% ==== Listings and Moving ==== %% 2014/03/26f.
%% \label{sec:listmv}
%% Working on v0.6, in testing I discovered a problem with 
%% the \emph{listing environments}. The present documentation 
%% uses code listings with 'makedoc', which build on the 
%% 'moreverb' package and eventually call \LaTeX's 
%% `\@noligs' macro.\footnote{\ctanpkgref{moreverb}
%%     is used, and its listing environments use \cs{@verbatim} 
%%     from the \ctanpkgref{verbatim} package, then 
%%     \cs{verbatim@font} calls \cs{@noligs}~...}
%% The problem also appears with the `{verbatim}' environment 
%% from the \LaTeX\ kernel ('latex.ltx') as well as from the
%% \ctanpkgref{verbatim} package---with anything that calls 
%% \LaTeX's `\@noligs'. The latter assigns special meangings 
%% to the active characters listed in the `\verbatim@nolig@list', 
%% three of them need a different meaning with 'niceverb'.
%% When a page break happens after such an environment has been 
%% entered (this may well be when the environment falls to the 
%% beginning of the next page), these settings are used in 
%% \LaTeX's `\@outputpage' for running the `\write's of the page 
%% as well as for page headers. And this happens quite often 
%% in a package documentation!
%%
%% The problem was reported by Walter Schmidt with respect to 
%% math primes as `latex/3104' in 1999. I cannot reproduce    %% rm. to 2015/11/09
%% it, and I see two reasons in recent `latex.ltx' code 
%% why it cannot happen anymore. However, one remedy in `latex.ltx'
%% is activating `\active@math@prime' in `\@resetactivechars' 
%% of `\@outputpage'. 
%% But this is bad for 'niceverb''s single right quote. 
%% We override the `\active@math@prime' functionality and
%% verbatim `\@noligs' by appending 
%% some protection of the characters collected
%% in `\verbatim@nolig@list' 
%% % local restorement |\useNiceVerbHere| of our syntax.
%% to `\@resetactivechars'.
%% This solves the problem for `\write's at `\shipout'.
%% |\do_protect_noligs| is used for this purpose;
%% actually it is applied in |\useNiceVerb|
%% (\secref{allonoff}):{\sloppy\par}
\newcommand*{\do_protect_noligs}[1]{%                   %% 2014/03/28
    \MakeActiveLetHere#1\relax}          %% `Here' missing 2015/11/09
%% |\nvResetPages| can be used to restore \LaTeX's 
%% `\@resetactivechars'. I don't add it to `\noNiceVerb'
%% because it could corrupt `\write's, so should be used with care.
%% % Actually I think that our new version of `\@resetactivechars'
%% % is better than \LaTeX's, I think I can recommend to use it 
%% % always and even to modify `latex.ltx' accordingly.
%% % TODO!? math headings? without 'niceverb' restore right 
%% % single quote for math prime after `\shipout'.
\AtBeginDocument{%
    \newlet\latex_reset_actives\@resetactivechars}
\newcommand*{\nvResetPages}{%
    \let\@resetactivechars\latex_reset_actives}
%% |\NiceVerbMove{<text>}| with v0.6 is for ``moving" arguments so that 
%% 'niceverb' syntax operates \emph{locally} at the destination,
%% I think of table of contents and page headers.
%% It is automatically used by 'niceverb''s variant of \LaTeX's 
%% sectioning commands (\secref{rqsf}); while with `\markboth', `\markright', 
%% `\addcontentsline' etc. you must it include yourself (currently, TODO?).
%% This is meant as a remedy against \LaTeX's and \ctanpkgref{verbatim}'s 
%% `\@noligs' with respect to page headers. However, 
%% another purpose is that you could switch off the 'niceverb'
%% syntax at the beginning of your document (by `\noNiceVerb'), 
%% though certain entries to the table of contents can use 
%% 'niceverb' syntax without affecting other entries
%% (where some active characters may have different meanings, 
%%  perhaps from a different package).
\newcommand*{\NiceVerbMove}[1]{%
%% What goes to `.aux' files must not have underscores:
    {\NiceVerbGeneral\niceverb_rqsf_kind#1}}
\NewSelfProtectedCommand{\NiceVerbGeneral}{%
%% %... TODO only 2 applications of `\NewSelfProtectedCommand'!?
%% %
%% % Here is |\useNiceVerbHere|:
% \newcommand*{\useNiceVerbHere}{%                      %% 2014/03/28
    \let\MakeActiveLet\MakeActiveLetHere \useNiceVerbI}
% \newcommand*{\NiceVerbGeneral}{%
%     \nvSelfProtect\NiceVerbGeneral\useNiceVerbHere}
%%
%% ==== Turning off and on altogether ====
%% \label{sec:allonoff}
%% These commands are new with v0.3. 
%%
%% |\noNiceVerb| \emph{disables} all 'niceverb' features. 
\newcommand*{\noNiceVerb}  {\MakeNormal\`%
                            \MakeNormal\&%
                            \MakeNormal\<%
                            \MakeNormal\#%
                            \nvRightQuoteNormal
                            \MakeNormal\|%
                  \let\@sect\niceverb_before_sect}      %% 2014/03/27
%% |\useNiceVerb| \emph{activates} all the 'niceverb' features 
%% (apart from ``auto mode"). With v0.6, it is divided 
%% into two parts for `\NiceVerbMove' in \secref{listmv}:
\newcommand*{\useNiceVerbI}{\MakeActiveLet\`\LQverb
%% TODO to be changed with 'wiki.sty' v0.2
                            \MakeActiveLet\&\CmdSyntaxVerb
                            \MakeActiveLet\<\MetaVar
                            \MakeActiveLet\#\HashVerb
                            \nvRightQuoteSansSerif
                            \MakeActiveLet\|\nvCmdBox}
\newcommand*{\useNiceVerb} {\useNiceVerbI               %% 2014/03/27
                            \let\@sect\niceverb_sect
    \g@addto@macro\@resetactivechars{%
%                           \useNiceVerbHere            %% 2014/03/28
    \let\do\do_protect_noligs \verbatim@nolig@list      %% 2014/03/28
}}
%% 
%%
%%  === Minor Final Things         ===
%% ==== Activating the 'niceverb' Syntax ====
%% 'niceverb' features are activated at `\begin{document}' 
%% so (some) other packages can be loaded \emph{after} 'niceverb'. 
%% For v0.3, we do this after possible settings for 
%% compatibility with 'hyperref'.
\AtBeginDocument{\useNiceVerb}
%%
%% ==== Leave Package Mode               ====
\PopLetterCat\_                                         %% 2012/08/27
\endinput
%%
%%==== VERSION HISTORY ====

v0.1   2009/02/21   very first, sent to CTAN
v0.2   2009/04/04   ...NoVerbList: \subsubsection, \AddToMacro, 
       2009/04/05   \SimpleVerb makes more other than iii
       2009/04/06   just uses \dospecials
       2009/04/08   debugging code for rq/sf, +\relax
       2009/04/09   +\verb@eol@error, prepared for new doc method, 
                    removed spurious \makeat..., -\relax (ligature), 
       2009/04/10   ('-trick
       2009/04/11   \@ after \SimpleVerb
       2009/04/14   noted TODO below
       2009/04/15   change v0.1 to 2009/02/21
v0.30  2010/02/27   short, more explained, \AssignCatCodeTo,
                    use \MakeActive for re-activating, \MakeNormal
       2010/02/28   fixed @ and _ with & by moving \begin_min_verb;
                    replaced \lq by `; Capitals in Titles
       2010/03/05   \SimpleVerb -> \NVerb; 
                    use \MakeActive + \MakeNormal; \rq -> ';
                    renamed some sections; \lq_verb -> \LQverb, 
                    \niceverb_meta -> \MetaVar, 
                    \param_verb -> \HashVerb
       2010/03/06   removed \MakeAlign; removed @ and _ todo below;
                    \NVerb makes ` and ' other; 
                    \nvAllowRQSF allows ' in column titles,
       2010/03/08   \LQverb and & work in column titles, 
                    \RQverb works with \noindent; 
                    bookmark substitutions
       2010/03/09   extended notes on 'hyperref' (in)compatibility;
                    \MakeLetter\@ in \CmdSyntaxVerb only;
                    |...| implemented as \prepareCmdBox etc.!
       2010/03/10   \colorbox example, \thinspace; ltxguide!;
                    removed todo; ..._exec -> \DoRQsansserif; 
                    minor doc changes in ``Nasty"
       2010/03/11   doc changes in ``Escape Character ..." and 
                    ``Ampersand"
       2010/03/12   \niceverb_aux_cat, \MakeActiveHere etc., 
                    \IfTypesetting, \noNiceVerb, \useNiceVerb,
                    corr. bracing mistake in \MakeNormal!
       2010/03/14   0.31 -> 0.3; \HardNVerb, \GenCmdBox, 
                    \prepareCmdBox -> \nvCmdBox 
       2010/03/15   \endcell; \cmdboxitem; remark on \sfcode`/
       2010/03/16   corr. -> \endline; 
                    advice on \cs{par}, \cs{if...}, \cs{fi};
                    redefined \ignorespaces for RQ feature
       2010/03/17   corr. `\fututelet', corr. \cs PDF substitution
       2010/03/18   |\niceverbNoVerbList|, |\AddToMacro| etc.;
                    corr. \AddToMacro; 
                    \lastskip-fix of \niceverb_ignore, 
                    another fix of \niceverb_noindent
       2010/03/19   another fix of \niceverb_ignore: \spacefactor
       2010/03/20   ... again: \niceverb_spacefactor

NOT DISTRIBUTED, just stored saved as separate version

v0.31  2010/03/20   right quote feauture: letters get \sfcode=1001
                    `column title' -> `page headers', \ctanpkgref

NOT DISTRIBUTED, just stored as separate version

v0.32  2010/03/21   taking best things from v0.30 and v0.31
       2010/03/23   removed \relax from \IfTypesetting
SENT TO CTAN

v0.4   2010/03/27   restoring `_' with "auto mode" safer
       2010/03/28   \AddToNoVerbList
       2010/03/29   note above, renamed v0.4
SENT TO CTAN

v0.41  2010/04/03   v0.33 -> v0.4 
       2010/04/05   corrected \AutoCmdInput list
SENT TO CTAN as part of NICETEXT release r0.41

v0.41a 2010/11/09   typo corrected
v0.42  2010/12/30   corr. `\ ' emulation in auto mode
       2010/12/31   \MetaVar in ...maybe_meta...
       2011/01/19   `...' fix
       2011/01/24   \ctanpkgref moves to texlinks.sty
       2011/01/26   update (C)
with nicetext RELEASE r0.42
v0.43  2011/05/09   \gt, \lt
       2011/05/27   \cs uses \@backslashchar
       2011/06/20   \MakeActiveLetHere in \nice_maybe_meta_verb !!!
       2011/06/27   2011/05/27 undone
       2011/08/20   `r0.42', `v0.43'
with nicetext RELEASE r0.43
v0.44  2011/09/09   \AddQuotes, \DontAddQuotes
with nicetext RELEASE r0.44
v0.45  2011/11/05   mod. \niceverb_collect_egroup/\VerticalCmdBox, 
                    tried \output problem without avail
       2011/12/05   clarified "r0.44"
with nicetext RELEASE r0.5 

v0.5   2012/08/27   using 'catcodes', \providecommand\CatCode, 
                    rm. \AssignCatCodeTo, \private_letters 
       2012/08/28   fixed \private_letters; 
                    rewording for filling lines
       2012/09/27   corrections about \MakeActive...
with nicetext RELEASE r0.6

v0.6   2012/11/27   \[d]qtd only \provide'd 
v0.61  2014/03/18   doc.: rm. TODO on private letters hook,
                    folding history tighter, 
                    RM CODE COMMENTED OUT IN 2011;
                    \VerticalCmdBox gets \pagebreak[2]
       2014/03/19   doc.: strange replaced, restructured, 
                    Command-Highlighting Boxes -> Boxes 
                    Highlighting ...;
                    opt. arg. for \NVerb etc. replaces 
                    \niceverb_egroup, \cs/\cstx enhanced, 
                    reimpl.s with \SetNiceVerbSaveBox, 
                    \nice_maybe_meta_verb -> \NiceMaybeMetaVerb
       2014/03/20   reworking robustness -- doc., ...; doc. on 
                    `Shared ...', \qtdnverb
       2014/03/21   "debugging": \noexpand vs. \protect
       2014/03/22   ... continued; mod. \MakeNormal
       2014/03/23   ..., hiding ...
       2014/03/24   TODO on left quotes, doc. test there, 
                    rm. babel-TODO
       2014/03/25   doc. about left quotes shorter, rm. earlier page
                    breaks, doc. problems with right quotes; \newlet;
                    dealing with \active@math@prime
       2014/03/26   corr. test for right single quote, more about
                    \active@math@prime, corr. \CmdSyntaxVerb
       2014/03/27   different treatment of \active@math@prime ...
                    main work for sec:listmv and independent 
                    switching for rqsf, \NewSelfProtectedCommand
                    (3 applications); doc. corr., TODO; 
                    \typeout test
       2014/03/28   test section; [TODO?]; \nvShowProtectedEdef, 
                    \MetaVar: protection and hyperref version; 
                    remark \NVerb; [\NiceVerbHere]; \protect test
                    with RQ removed; \do_protect_noligs fixed 
                    and used
       2014/07/16   \BuildCsSyntax with hyperref
       2014/07/17   remarks on \BuildCsSyntax and removing useless 
                    braces there (hours of trying better)
       2015/02/23   doc.: \PDFstring -> \pdfstring
       2015/04/07   doc.: page headings -> page headers
       2015/11/09   bugfixes \nvRightQuoteNormal and 
                    \do_protect_noligs; doc. typo fix