summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/tex/latex/ifnextok
diff options
context:
space:
mode:
authorManuel Pégourié-Gonnard <mpg@elzevir.fr>2011-08-03 13:05:10 +0000
committerManuel Pégourié-Gonnard <mpg@elzevir.fr>2011-08-03 13:05:10 +0000
commitb92cdcac0a3665ba9f12d18a70d1879f1563560d (patch)
treed4887aed4f74032db69b03a7ea381825e57b6f60 /Master/texmf-dist/tex/latex/ifnextok
parentf53d41771bd380e3a5c63ff43cc0350764e62b13 (diff)
ifnextok v0.3
git-svn-id: svn://tug.org/texlive/trunk@23379 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/tex/latex/ifnextok')
-rw-r--r--Master/texmf-dist/tex/latex/ifnextok/ifnextok.sty502
1 files changed, 425 insertions, 77 deletions
diff --git a/Master/texmf-dist/tex/latex/ifnextok/ifnextok.sty b/Master/texmf-dist/tex/latex/ifnextok/ifnextok.sty
index 896c4e5e439..552b8b73ec9 100644
--- a/Master/texmf-dist/tex/latex/ifnextok/ifnextok.sty
+++ b/Master/texmf-dist/tex/latex/ifnextok/ifnextok.sty
@@ -1,5 +1,5 @@
\NeedsTeXFormat{LaTeX2e}[1994/12/01]
-\ProvidesPackage{ifnextok}[2011/05/23 v0.1 next token test (UL)]
+\ProvidesPackage{ifnextok}[2011/06/27 v0.3 test next token (UL)]
%% Copyright (C) 2011 Uwe Lueck,
%% http://www.contact-ednotes.sty.de.vu
@@ -16,12 +16,13 @@
%%
%% http://www.contact-ednotes.sty.de.vu
%%
-%% === Outline ===
+%% == Outline ==
%% The 'ifnextok' package deals with the behavior of
%% \LaTeX's internal `\@ifnextchar' to skip blank spaces.
%% This sometimes has surprising or for some users really
%% \emph{unwanted} effects, especially with brackets following
-%% `\\' where the user does \emph{not} intend to specify an
+%% `\\' when %% v0.1a: was `where'
+%% the user does \emph{not} intend to specify an
%% optional argument, rather wants that brackets are \emph{printed.}
%% The package offers commands and options for modifying this
%% behavior, maybe limited to certain parts of the
@@ -29,20 +30,31 @@
%% together with the presentation of the implementation.
%%
%% As after multiletter commands blank spaces are skipped anyway
-%% (\TeX book p.~46f.), the package makes a difference only
-%% for one-symbol commands such as |\\|, or for active characters
-%% such as the double quote with \ctanpkgref{german}`.sty'
-%% and \ctanpkgref{babel}.
+%% (\TeX book p.~46f.), the package makes a \emph{difference only
+%% for one-symbol commands} such as |\\|, or for %% \emph 2011/05/27
+%% \emph{active characters} such as the double quote with
+%% \ctanpkgref{german}`.sty' and \ctanpkgref{babel}.
+%% (v0.21: Or also optional arguments
+%% \emph{following mandatory ones}---``trailing" optional arguments
+%% mentioned by Lars Hellstr\"om and Bruno Le Floch on `LATEX-L'.
+%% v0.21a: Moreover, with ``starred" command versions having a
+%% first optional argument!) %% 2011/06/14
%%
-%% A little \strong{overview:}
+%% Similar things happen in \ctanpkgref{amsmath} and
+%% \ctanpkgref{mathtools}, and as of v0.21, %% v0.21a 2011/06/14
+%% we discuss relations to these packages.
+%%
+%% A little \strong{overview} of the package's commands and options:
+%% %% structured 2011/05/27
+%% === For Macro Writers ===
%% \begin{enumerate}
%% \item |\IfNextToken| is an alternative to `\@ifnextchar',
-%% not skipping spaces (Section~\ref{sec:main}).
+%% not skipping spaces (\secref{main}).
%% This macro is the \strong{low-level}
%% backbone of all other modifications of \LaTeX\ commands.
%% \item |\IfStarNextToken| is an alternative to `\@ifstar',
%% not skipping spaces, using `\IfNextToken' in lieu of
-%% `\@ifnextchar' (Section~\ref{sec:star}).
+%% `\@ifnextchar' (\secref{star}).
%% \item Some ``\strong{patching}" commands aim at modifying
%% existing (\LaTeX) macros without specifying the resulting
%% new definition explicitly
@@ -53,45 +65,104 @@
%% \item There are low-level commands
%% |\INTstore| and |\INTrestore|
%% for undoing modifications of existing macros
-%% (Section~\ref{sec:stored}).
-%% \item There are \strong{high-level} commands for modifying
-%% |\\| and selecting \LaTeX\ \strong{environments}
-%% to be affected (Section~\ref{sec:break}).
-%% Package \strong{options} execute some of them.
+%% (\secref{stored}).
%% \end{enumerate}
-%% (TODO: how command names are composed) %% 2011/05/23, v0.1
-%%
-%% === Caveats ===
-%% Only a few of the commands have been tested so far,
-%% and usage together with \ctanpkgref{amsmath}
-%% may require special care or fail altogether.
+%%
+%% === For End-Users ===
+%% % \item
+%% There are \strong{high-level} commands for modifying
+%% |\\| and selecting \LaTeX\ \strong{environments}
+%% to be affected (\secref{break}).
+%% Package \strong{options} execute some of them
+%% (\secref{options}), e.g., `[stdbreaks]'.
+%%
+%% === Intermediate ===
+%% |\MakeNotSkipping{<target>}{<on-space>}|
+%% described in \secref{genpatch} is somewhat ``intermediate."
+%% It acts on a document-level command <target> without
+%% any assumptions about its internals.
+%% On the other hand, choosing <on-space> for the new behavior
+%% of <target> in front of a space token may need some knowledge ...
+%%
+%% (TODO: how command names are composed) %% 2011/05/23, v0.1
%%
-%% Switching into ``don't-skip-spaces" mode
-%% \emph{two times} without switching back into normal mode
-%% in between won't work with this version (v0.1)
-%% of the package (TODO: permanent aliases).
-%% You will get the
-%% \[\texttt{Argument of <patching> has an extra }`}.'\]
-%% error. This also applies to commands that have been issued
-%% by package options.
+%% \pagebreak %% 2011/06/26
+%% == Caveats ==
+%% \begin{enumerate}
+%% \item Testing has not been very comprehensive so far.
+%% % \item
+%% Usage together with \textcolor{blue}{\ctanpkgref{amsmath}}
+%% may require special care or fail altogether.
+%% \item Switching into ``don't-skip-spaces" mode
+%% \emph{two times} without switching back into normal mode
+%% in between won't work with this version (v0.1--v0.3 TODO)
+%% of the package (TODO: permanent aliases).
+%% You will get the
+%% \[\texttt{Argument of <patching> has an extra }`}.'\]
+%% error. This also applies to commands that have been issued
+%% by package options.
+%% \item Implementation may change much.
+%% % , and certain auxiliary
+%% % commands may move to separate packages.
+%% (TODO 0.3)
+%% \end{enumerate}
%%
-%% === The Main Command \cs{IfNextToken} ===
+%% == For Making Macros == %% 2011/05/27
+%% \label{sec:mac}
+%% === The Main Command &\IfNextToken === %% & 2011/05/27
%% \label{sec:main}
-%% |IfNextToken<match>{<if>}{<else>}| is the obvious variant
+%% |\IfNextToken<match>{<if>}{<else>}| %% add. miss. `\' 2011/05/31
+%% is the obvious variant
%% of \LaTeX's internal `\@ifnextchar' executing <if>
-%% if actually the \emph{``very next"} token is <mathc>
+%% if actually the \emph{``very next"} token is
+%% <match> %% v0.1a: was `mathc'
%% and executing <else> otherwise. If <match> is \emph{not}
%% a \emph{space token} (\LaTeX's `\@sptoken') but
%% the next token \emph{is}, <else> is executed;
%% while `\@ifnextchar' tries matching the next token
%% after ensuing space tokens.
\newcommand{\IfNextToken}[3]{%
- \let\nextok@match=#1\def\nextok@if{#2}\def\nextok@else{#3}%
+ \let\nextok@match= #1%
+%% ... v0.21 adds \qtd{`= '} after Heiko Oberdiek's explanation
+%% on \texhaxpref{11-05-017590}{texhax}, %% 2011/06/14
+%% this allows `\@sptoken' as a possible `#1'.
+ \def\nextok@if{#2}\def\nextok@else{#3}%
\futurelet\@let@token\nextok@decide}
+%% ... apart from using different names, this is the same as
+%% `\new@ifnextchar' in `amsgen.sty' of the \ctanpkgref{amsmath}
+%% bundle:
+%% \begin{verbatim}
+%% \long\def\new@ifnextchar#1#2#3{%
+%% \let\reserved@d= #1%
+%% \def\reserved@a{#2}\def\reserved@b{#3}%
+%% \futurelet\@let@token\new@ifnch
+%% }
+%% \end{verbatim}
+%% ... and the behavior is essentially the same ...
\def\nextok@decide{%
\ifx\@let@token\nextok@match \expandafter\nextok@if
\else \expandafter\nextok@else
\fi}
+%% The analogue to our `\nextok@decide' in 'amsmath'/`amsgen.sty'
+%% is `\new@ifnch':
+%% \begin{verbatim}
+%% \def\new@ifnch{%
+%% \ifx\@let@token\reserved@d \let\reserved@b\reserved@a \fi
+%% \reserved@b
+%% }
+%% \end{verbatim}
+%% ... and these two macros ('ifnextok''s and 'amsmath''s)
+%% actually make the difference to Standard \LaTeX.
+%% The latter's `\@ifnch' tests for `\@sptoken' before
+%% looking for the actually wanted `char', 'ifnextok' and
+%% 'amsmath' don't. As to `\new@ifnch' vs.\ `\nextok@decide',
+%% the first has one token less than the latter, but one
+%% assignment more. What does this mean? TODO
+%%
+%% When I decided to create the 'ifnextok' package, I was not aware
+%% of the similarity to 'amsmath', and I am not sure what I would
+%% have done had I ...
+%%
%% |\NoNextSkipping| now switches into ``don't-skip-spaces"
%% mode ``altogether" (however ...):
\newcommand*{\NoNextSkipping}{\let\@ifnextchar\IfNextToken}
@@ -104,40 +175,77 @@
%% Actually, because `\NoNextSkipping' does not affect
%% `\kernel@ifnextchar', those of \LaTeX's commands using the latter
%% still will skip spaces (with package version v0.1).
+%%
+%% As opposed to 'amsmath', 'ifnextok' aims at more choices
+%% as to what document-level commands are affected by the
+%% modified `next' checking. Of course, 'amsmath' deals with
+%% breaks between math display lines, while the present package
+%% rather was motivated by experiences in the humanities.
%%
-%% === Patching Commands ===
+%% `\@sptoken' was discussed under \qtd{Some puzzling TeX} on
+%% texhax in 2011 (February/May/June), and the matter is discussed in
+%% \meta{The \TeX book} in Exercise~24.6 and on pp.~376f.
+%%
+%% === ``Bold" Patching Commands ===
%% \label{sec:patch}
+%% % The little auxilary |\@xp@xp@xp| (cf.~`\@xp' in `amsgen.sty'):
+%% % \providecommand*{\@xpxpxp}{\expandafter\expandafter\expandafter}
%% |\INTpatch<replacer><macro>| replaces
%% something in the definition of <macro> according to
%% the replacement macro <replacer>.
%% This seems to work with the macros I thought of.
%% It does \emph{not} work when
-%% (for replacing `\@ifnextchar')
+%% (for replacing `\@ifnextchar') %% mod. 2011/06/24:
%% (a)~there are \emph{more} `\@ifnextchar's in the
-%% macro to patch, or when (b)~an `\@ifnextchar'
+%% macro to patch (outside braces),
+%% or when (b)~the only `\@ifnextchar'
%% is inside a pair of braces.
\newcommand*{\INTpatch}[2]{%
\expandafter\expandafter\expandafter \def
\expandafter\expandafter\expandafter #2%
\expandafter\expandafter\expandafter {%
- \expandafter #1#2#1}}
+ \expandafter #1#2}} %% red. 2011/06/24
%% |\NextTestPatch<macro>| replaces
%% `\@ifnextchar' in the definition of <macro> by
%% `\IfNextToken'.
\newcommand*{\NextTestPatch}{\INTpatch\nextok@patch}
-\def\nextok@patch#1\@ifnextchar#2\nextok@patch{#1\IfNextToken#2}
+\def\nextok@patch#1\@ifnextchar{#1\IfNextToken} %% red. 2011/06/24
+%% Another application of `\INTpatch' is `\StarTestPatch' in \secref{star}.
%%
%% === Storing and Restoring ===
%% \label{sec:stored}
+%% % |\WCS@namemod@apply@cs{<mod>}<apply>{<cs>}|
+%% % applies the token <apply> to (the token) <cs> modified by <mod>:
+%% %\providecommand*\WCS@namemod@apply@cs[3]{%
+%% % \expandafter#2\csname#1#3\endcsname}
+%% % Note the order of the arguments in the replacement text.
+%% % It allows shorthands like the following
+%% % |\INT@save@nmod<apply>{<cs>}|
+%% % when one name modifyer is used for various purposes:
+%% % \newcommand*{\INT@save@nmod}{\WCS@namemod@apply@cs\INT@save}
%% |\INTstore<macro>| stores the meaning of the macro <macro>
%% in a special name space.
-\newcommand*{\INTstore}[1]{%
- \expandafter\let\csname\INT@name#1\endcsname#1}
-\newcommand*{\INT@name}{INTstore.\expandafter\@gobble\string}
+%% %\newcommand*{\INTstore}[1]{\INT@save@nmod\let#1#1}
+\newcommand*{\INTstore}[1]{%
+ \expandafter\let\csname\INT@save#1\endcsname#1}
+%% In order to apply `\MakeNotSkipping' even to
+%% active characters below (v0.2), nothing must be gobbled
+%% from `\string<token>':
+%% % `\INT@save<token>' is a \emph{``name modifier":}
+% \newcommand*{\INT@save}{INT.save\expandafter\@gobble\string}
+\newcommand*{\INT@save}{INT.save\string}
+%% % For restoring, we use another general auxiliary
+%% % \[|\WCS@namemod@copy@to@from{<mod>}<new>{<old>}|:\]
+%% %\providecommand*{\WCS@namemod@copy@to@from}[3]{%
+%% % \expandafter\let\expandafter#2\csname#1#3\endcsname}
+%% % \providecommand*{\WCS@namemod@copy@to@from}[2]{%
+%% % \def\WCS@apply{\let#2}%
+%% % \WCS@namemod@apply@cs#1\WCS@apply}
%% |\INTrestore<macro>| \emph{re}stores the meaning of <macro>
-%% that is expected to having been stored with `\INTstore':
+%% that is expected to have been stored with `\INTstore':
+%% %\newcommand*{\INTrestore}[1]{\WCS@namemod@copy@to@from\INT@save#1#1}
\newcommand*{\INTrestore}[1]{%
- \expandafter\let\expandafter#1\csname\INT@name#1\endcsname}
+ \expandafter\let\expandafter#1\csname\INT@save#1\endcsname}
%%
%% === The Star Test ===
%% \label{sec:star}
@@ -146,16 +254,17 @@
%% `\@ifnextchar'. So already `\@ifstar' needs to be modified.
%% We do not so much want to change `\@ifstar' altogether,
%% rather we will replace it at some places by a non-skipping
-%% variant |\IfStarNextToken|, using the patching command
-%% |\StarTestPatch<macro>|.
+%% variant |\IfStarNextToken|,\footnote{TODO or &\IfNextStar,
+%% cf.~&\IfNextSpace.}
+%% using the patching command |\StarTestPatch<macro>|.
%% (`\@ifstar' has an argument and therefore cannot be patched as
%% nicely as the line-break commands.)
\newcommand*{\IfStarNextToken}[1]{\IfNextToken*{\@firstoftwo{#1}}}
\newcommand*{\StarTestPatch}{\INTpatch\nextok@starpatch}
%% The macro to be patched may contain a \cs{par}
%% (`\@centercr' is an example), so we need `\long':
-\long\def\nextok@starpatch#1\@ifstar#2\nextok@starpatch{%
- #1\IfStarNextToken#2}
+%% %% red. 2011/06/24
+\long\def\nextok@starpatch#1\@ifstar{#1\IfStarNextToken}
%% |\StoreStarSkipping| stores the current meaning of
%% `\@ifstar' ...
%% % is executed before changing `\@ifstar' temporarily:
@@ -166,10 +275,163 @@
\newcommand*{\NoStarSkipping}{\let\@ifstar\IfStarNextToken}
%% This again seems to be so dangerous that it will not be
%% supported much with package version v0.1 (by a package option).
+%%
+%% On the other hand, 'amsmath' (`amsgen.sty') is not as scrupulous
+%% as we are and indeed redefines `\@ifstar' \emph{altogether},
+%% equivalent to our `\NoStarSkipping', except that the latter
+%% provides a method to restore. I.e., as soon as you have loaded
+%% `amsgen.sty' (invoked by any 'amsmath' package),
+%% you have decided that a star appearing after
+%% whitespace is printed as a star, rather than choosing the
+%% ``starred" version of the respective command.
+%% %% v0.21a 2011/06/14:
+%% What we actually find in `amsgen.sty' is
+%% \begingroup \hfuzz=33pt
+%% \begin{verbatim}
+%% \def\@ifstar#1#2{\new@ifnextchar *{\def\reserved@a*{#1}\reserved@a}{#2}}
+%% \end{verbatim}
+%% \endgroup \noindent
+%% The `\reserved@a' trick seems to be due to 'amsmath''s idea
+%% of implementing the conditional
+%% (see the code we are quoting in \secref{main}).
+%%
+%% === More General Patching with \cs{@sptoken} ===
+%% \label{sec:genpatch}
+%% This section deals with modifying macros by a more general
+%% technique than employed in \secref{patch}. We do not use any
+%% knowledge of internals of the target user command
+%% (a ``control symbol" like `\\' or an ``active character"),
+%% and the command may take arguments, as the active double quote
+%% does with 'german.sty' or 'babel'.
+%%
+%% ==== &\IfNextSpace ====
+%% |\IfNextSpace{<if>}{<else>}| is an auxiliary macro that
+%% executes <if> if the next token is a space token
+%% (\LaTeX's `\@sptoken'), otherwise it executes <else>:
+\newcommand*{\IfNextSpace}{\IfNextToken\@sptoken}
+%% This did not work with the v0.2 version of `\IfNextToken'
+%% that didn't have \qtd{`= '}, due to `\@sptoken' being an
+%% ``implicit space token," as Heiko Oberdiek pointed out
+%% on texhax. He also provided the remedy that actually was
+%% 'amsmath''s way ...
%%
-%% === ``Manual" Line Breaks ===
+%% v0.2 was:
+%% \begin{verbatim}
+%% \newcommand*{\IfNextSpace}[2]{%
+%% \def\nextok@if{#1}\def\nextok@else{#2}%
+%% \futurelet\@let@token\nextok@ifspace}
+%% \newcommand*{\nextok@ifspace}{%
+%% \ifx\@let@token\@sptoken \expandafter \nextok@if
+%% \else \expandafter \nextok@else
+%% \fi}
+%% \end{verbatim}
+%% ... not so bad from an efficiency point of view, but ...---%
+%% % Is `\IfNextSpace' useful? I don't know of a shorthand
+%% % like `\@ifnextcharleftbracket' for %% 2011/06/24 \qtd:
+%% % \qtd{&\@ifnextchar[} ... %% rm. 2011/06/26
+%%
+%% ==== &\MakeNotSkipping ====
+%% |\MakeNotSkipping{<target>}{<on-space>}| should modify `<target>'
+%% so that it acts in its usual way when no space token is ahead
+%% while executing <on-space> otherwise. E.g., <target> may be
+%% the active double quote |"| from 'babel', and on the left of a space
+%% token you want that the double quote just prints an ordinary
+%% double quote from the ligature
+%% \lq\verb+''+\rq\ %% \ 2011/06/03
+%% (the first pair of argument braces may be omitted):
+%% \[\verb+\MakeNotSkipping{"}{''}+\]
+%% ... while I don't really recommend this right now (v0.2f.).
+%% %% rm. 2011/06/27 useless:
+%% % For some unknown |\\|,
+%% % you may want to block searching for an optional argument by
+%% % \[`\MakeNotSkipping{\\}{\\\relax}'\]
+%%
+%% <target>, being on document level and probably appearing
+%% in moving arguments, must be robust, while `\IfNextSpace' is not.
+%% When <target> has been defined using `\DeclareRobustCommand'
+%% (`\\' from the `document' environment is an example),
+%% we would loose the original behavior of <target> if we used
+%% `\DeclareRobustCommand' ourselves.
+%%
+%% v0.21 was horribly flawed at this point; I had not tested
+%% all cases, I had not studied how \LaTeX's `\DeclareRobustCommand'
+%% handles control symbols (such as `\_', see `source.pdf'),
+%% and my implementation did not obey the warning in my
+%% ancompanying documentation ...
+%%
+%% % |\RobustDeferName<cs>| may move to a general package
+%% % about robust commands TODO:
+%% %\providecommand*{\RobustDeferName}[1]{\expandafter\@gobble\string#1 }
+%% When <target> is a single (active) character,
+%% it may have been robustified by making it expand
+%% to a robust control sequence token, such as `~'
+%% via `\nobreakspace{}'---we don't know,
+%% or don't try to find out now. We make it robust,
+%% accepting that this may just introduce an unnecessary extra
+%% macro. %% rest of paragraph was nonsense 2011/06/27
+\newcommand*{\INT@modified}[1]{%
+ \ifx\protect\@typeset@protect
+ \expandafter\expandafter\expandafter \IfNextSpace
+ \csname\INT@mod#1\expandafter\endcsname
+ \else
+ \protect#1%
+ \fi}
+%% `\INT@mod<cs>' is another \emph{``name modifier":}
+%% % `\WCS@namemod@apply@cs' from \secref{stored}
+%% % provides both arguments for `\IfNextSpace' associated with
+%% % #1 (TODO!?):
+%% % \edef\@tempa{\WCS@namemod@apply@cs\INT@mod\noexpand#1}%
+%% % \expandafter\expandafter\expandafter \IfNextSpace \@tempa}
+\newcommand*{\INT@mod}{INT@mod.\string}
+%% Here is the main command of the section.
+%% `\@tempa' will store the meaning of the command that <target>
+%% would call in typesetting mode after
+%% `\DeclareRobustCommand<target>'.
+%% `\@tempb' will store what <target> does in in typesetting
+%% mode, maybe that is just the meaning of <target>
+%% (kind of flag, like `\if@tempswa'):
+\newcommand*{\MakeNotSkipping}[2]{%
+ \expandafter \let \expandafter \@tempa
+ \csname\expandafter\@gobble\string#1 \endcsname
+ \let\@tempb#1%
+%% When #1 is a control word, and its name, extended by a space,
+%% is the name of a defined token, we \emph{lazily}
+%% (like \ctanpkgref{makerobust}, TODO) assume that
+%% its current meaning was assigned by `\DeclareRobustCommand'.
+%% One exception: if that token is the control space~`\ ',
+%% #1 is a single character (hopefully active, TODO check!?).
+ \ifx\@tempa\relax \else \ifx\@tempa\ \else
+ \let\@tempb\@tempa \fi \fi
+ \expandafter\let\csname\INT@save#1\endcsname\@tempb
+%% We have analyzed #1 and now may modify it:
+ \def#1{\INT@modified#1}%
+%% We do not know beforehand what <on-space> will contain,
+%% in any case it should \emph{not} be expanded right here,
+%% that's why we use the token register `\@toks':
+ \toks@{#2}%
+ \expandafter\edef\csname\INT@mod#1\endcsname{%
+ {\the\toks@}%
+ \expandafter\noexpand\csname\INT@save#1\endcsname}%
+}
+%% This still is experimental, and you must care not to apply
+%% the patch two times when it has not been undone in between.
+%% The main application may be a macro like |\\| that some
+%% (non-standard) environment defines; then you could redefine
+%% the environmont so that its start finally modifies that
+%% macro according to your wishes. In the latter situation,
+%% the end of the environment will undo your `\MakeNotSkipping';
+%%
+%% TODO: %% v0.2
+%% In the case of |"|, this might be a starting point
+%% for handling conventions about moving an ensuing
+%% punctuation mark to the left of the quotation mark.
+%% Moreover, getting something really useful would require
+%% dealing with `"' at the left of a bracket too.
+%%
+%% % \pagebreak %% 2011/06/26
+%% == ``Manual" Line Breaks ==
%% \label{sec:break}
-%% ==== Outline of Implementation ====
+%% === Outline of Implementation ===
%% In the first instance, the present package aims at rendering
%% |\\| a command that interpretes a left-hand square bracket
%% as a start of an optional argument only if the bracket is not
@@ -194,7 +456,7 @@
%% the second starts with `\@x<pivot>' and invokes the
%% left-hand-bracket test. Both of them need to be patched.
%%
-%% ==== ``Normal" Manual Line Breaks ====
+%% === ``Normal" Manual Line Breaks ===
%% \label{sec:newline}
%% If I had been aware of the difficulties of this part,
%% I probably would not have started writing this package,
@@ -204,21 +466,15 @@
%% version of the bracket test, and this patch suffices for the
%% optional-argument goal.
%%
-%% The `\@ifstar' call is in `\@normalcr'; the latter is invoked
-%% by the robust version of `\\'. However, \LaTeX\ defines
-%% `\@normalcr' by a `\let' referring to the result of
-%% `\DeclareRobustCommand\\' ...
+%% %% more accurately 2011/05/31:
+%% The `\@ifstar' call is in `\@normalcr' and its alias `\\ ';
+%% the latter is invoked by `\\' according to `\DeclareRobustCommand\\'.
%%
-%% Things seem to be easier when |\\| calls `\@normalcr'
-%% instead of `\\ ' (the latter is the effect of
-%% `\DeclareRobustCommand'),
-%% we are \textcolor{blue}{\strong{interchanging}}
-%% the roles of `\\ ' and `\@normalcr'
-%% (\textcolor{blue}{\strong{caution!}}).
+%% Things seem to be easier when `\\ ' \emph{expands} to `\@normalcr'
+%% instead of being an \emph{alias} of it
+%% (\strong{\textcolor{blue}{CAUTION!}}).
%% Then we just need to control `\@normalcr':
-\def\\{\x@protect\\\protect\@normalcr}
-%% (Another \strong{Caveat:} I do not understand `\x@protect'.) %% v0.1
-%%
+\@namedef{\@backslashchar\space}{\@normalcr}
%% |\StoreNewlineSkipping| \emph{stores} the skipping behavior of |\\|
%% outside special environments:
\newcommand*{\StoreNewlineSkipping}{%
@@ -232,7 +488,7 @@
\newcommand*{\NoNewlineSkipping}{%
\StarTestPatch\@normalcr \NextTestPatch\@xnewline}
%%
-%% ==== Manual Line Breaks in \LaTeX\ Environments ====
+%% === Manual Line Breaks in \LaTeX\ Environments ===
%% \label{sec:envs}
%% The macros in the present section should modify \LaTeX's |\\|
%% in environments (<env> being one of:)
@@ -240,7 +496,12 @@
%% These \emph{environment names} are the expected
%% \emph{arguments} of those macros.
%% However, argument |center| also affects the
-%% |flushleft| and |flushright| environments,
+%% %% 2011/05/27 v0.11a verse:
+%% |flushleft|, |flushright|, and
+%% |verse| environments,\footnote{`verse'
+%% is provided by \LaTeX's standard \ctanpkgref{classes} only,
+%% while `flushleft' and `flushright' belong to the \LaTeX\
+%% kernel.}
%% and |array| and |tabular| should also affect
%% their enhanced variants from other \LaTeX\ packages.
%% When this internal structure of \LaTeX\ changes,
@@ -270,38 +531,72 @@
\INTactOnEnv\StarTestPatch\NextTestPatch}
%% % \NotSkippingCRs{center}
%% \begin{center}
+%% % \MakeNotSkipping\\{\\\relax}
+%% % \show\\
%% Do these commands work?\\ [\,Or do they not?\,]
%% \end{center}
+%%
+%% %% 2011/05/27 v0.11a:
+%% By contrast, the environments |quotation| and |quote|
+%% from \LaTeX's standard \ctanpkgref{classes} use the
+%% ``normal" newline command essentially provided by
+%% `\@normalcr'.
+%% === 'amsmath' and 'mathtools' ===
+%% Just discussing related functionality in
+%% the \ctanpkgref{amsmath} and \ctanpkgref{mathtools}
+%% packages, without any own code:
+%% %% modifications v0.21a 2011/06/14:
+%%
+%% 'amsmath' modifies the star (|*|) test all over the document
+%% (see our \secref{star}), while providing own
+%% (not skipping) versions of |\\| rather in math displays
+%% and math environments only. This applies quite obviously
+%% to the `{cases}' and `{matrix}' environments.
+%% I am not sure about 'amsmath''s use of `\displaybreak',
+%% (cf.~`amstex.sty' and the `\intertext' command) and `\math@cr'.
%%
-%% === Package Options ===
+%% 'mathtools' modifies 'amsmath''s line breaking behavior
+%% in turn on its options `[allowspaces]' and `[disallowspaces]',
+%% referring to some strange behavior of 'amsmath'.
+%% Still I don't understand what is going on entirely,
+%% and my impression is that nobody else has understood these
+%% things entirely so far. 'mathtools' is not the first
+%% package suppressing space skipping with `\\', 'amsmath' has done
+%% this already; the question is where, where not, and why ...
+%% 'mathtools''s `[disallowspaces]' just seems to provide
+%% a more straightforward policy ... TODO
+%% % Again, please see the 'mathtools' documentation for more details.
+%% %% <- rm. 2011/06/14
+%%
+%% == Package Options ==
%% \label{sec:options}
-%% ==== Behavior \emph{without} Options ====
+%% === Behavior \emph{without} Options ===
%% If the package is called without any option,
%% it only defines `\IfNextToken', `\IfStarNextToken'
%% and the other package-writer or user commands,
%% without actually changing behavior of any \LaTeX\ command.
%%
-%% ==== Option `newline' ====
+%% === Option `newline' ===
%% Package option |newline| stores and disables space skipping for
-%% |\\| in ``normal" mode according to Section~\ref{sec:newline}:
+%% |\\| in ``normal" mode according to \secref{newline}:
\DeclareOption{newline}{\StoreNewlineSkipping\NoNewlineSkipping}
%%
-%% ==== Environments ====
+%% === Environments ===
%% The next package options are just the environment names
-%% according to Section~\ref{sec:envs}
+%% according to \secref{envs}
%% (|center|, |tab|, |array|, |tabular|).
%% Option |<env>| stores and disables the skipping behavior
%% of |\\| in <env> environments.
%% We abuse the our temporary macro `\nextok@match' from
-%% Section~\ref{sec:main}:
+%% \secref{main}:
\def\nextok@match#1{%
\DeclareOption{#1}{\StoreSkippingCRs{#1}\NotSkippingCRs{#1}}}
\nextok@match{center}
\nextok@match{tab}
\nextok@match{array}
\nextok@match{tabular}
-%% ==== ``All Options" ====
-%% Package Option |all| has the same effect as
+%% === ``All Options" or ``Standard Options" ===
+%% Package Options |all| and (v0.11:\@) |stdbreaks| have the same effect as
%% using the `newline' option and the environment package options
%% `center', `tab', `array', and `tabular' at once.
\def\nextok@match#1{\csname ds@#1\endcsname}
@@ -309,12 +604,65 @@
\DeclareOption{all}{%
\nextok@match{newline} \nextok@match{center}
\nextok@match{tab} \nextok@match{array} \nextok@match{tabular}}
+%% Behavior of option |all| may \emph{change} in the future of the package,
+%% while option |stdbreaks| should rather \emph{keep} its present behavior.
+\DeclareOption{stdbreaks}{\nextok@match{all}} %% v0.11
%%
%%
-%% === Processing Options and Leaving the Package ===
+%% == Processing Options and Leaving the Package ==
\ProcessOptions
\endinput
%%
-%% === VERSION HISTORY ===
-
+%% == Acknowledgments == %% v0.2 2011/05/27
+%% While I experienced the problem myself some years ago with
+%% a critical edition, I finally decided to do this work
+%% after postings by Susan Dittmar (March 2011) %% 017128
+%% and Philipp Stephani (December 2010) %% 106431
+%% on the \texhaxref{}{'texhax'} mailing list.
+%% The latter pointed to \ctanpkgref{mathtools}.
+%%
+%% Moreover, the space skipping matter was discussed on the
+%% `LATEX-L' mailing list (\qtd{xparse and space skipping})
+%% in mid of May 2011, and the present
+%% package may be considered a contribution to that discussion
+%% (saying something like: keep the simple standard for beginners,
+%% offer something advanced for advanced users if you think
+%% some of them want it ... maybe just as `contrib').
+%% Bruno Le Floch (May~11) and Frank Mittelbach (May~15)
+%% made me aware of the similar functionality in 'amsmath'.
+%% Wordings in describing 'ifnextok' may resemble wordings
+%% in that `LATEX-L' very much. Only for v0.21, I actually
+%% read these `LATEX-L' postings, rather than only their
+%% subject lines.
+%%
+%% See sections~\ref{sec:main} and~\ref{sec:genpatch} for
+%% Heiko Oberdiek's contribution. %% 2011/06/24
+%%
+%% == VERSION HISTORY ==
v0.1 2011/05/23 very first
+v0.11 2011/05/23 typo `mathc' fixed, where/when
+ 2011/05/27 &, more structure, option [stdbreaks]
+ 2011/05/27 doc. mentions `verse', `quotation', `quote';
+ ack.s
+v0.2 2011/05/30 \IfNextSpace, \MakeNotSkipping
+ 2011/05/31 using \@normalcr differently;
+ corrected \IfNextSpace
+v0.21 2011/06/02 reworked \IfNextToken and \IfNextSpace
+ after Heiko Oberdiek, regarding amsmath;
+ documentation discusses amsmath and mathtools
+ and refers to LATEX-L
+ 2011/06/03 ... \ , \rq\ ; corr. version string
+v0.21a 2011/06/14 quoting \@ifstar from amsmath, extended comments
+ on amsmath and mathtools, starred versions,
+ Heiko Oberdiek for sec:main
+ TO CTAN
+v0.22 2011/06/24 ack's extended; reduced sec:patch; sec:genpatch:
+ horribly fragile robustification fixed
+ 2011/06/25 re-implementations in sec:patch using \WCS...
+ 2011/06/26 was named v0.3, renamed v0.22
+ JUST STORED
+v0.3 2011/06/26 sec:stored as v0.11;
+ sec:genpatch code similar to v0.2;
+ different sectioning; \pagebreak's
+ 2011/06/27 \INT@modified streamlined, rm. useless \\ example
+ and wrong description of \INT@modified