% This file is part of the CTAN package named ifis-macros.
% 
%   ifis-macros-doc.tex: instructions for three macro packages:
%      ifisinteger.tex, ifisdimension.tex, and ifisglue.tex;
%   and the componentwise test macros in gluecomp.tex:
%      \ifnatwd, \ifstretch, and \ifshrink
%      
%
%   Copyright (C) 2024,2025  Udo Wermuth (author)
%
%   This program is free software: you can redistribute it and/or modify
%   it under the terms of the GNU General Public License as published by
%   the Free Software Foundation, either version 3 of the License, or
%   (at your option) any later version.
%
%   This program is distributed in the hope that it will be useful,
%   but WITHOUT ANY WARRANTY; without even the implied warranty of
%   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%   GNU General Public License for more details.
%
%   You should have received a copy of the GNU General Public License
%   along with this program.  If not, see <http://www.gnu.org/licenses/>.

\outer\def\beginsection#1\par{\vskip 0pt plus 3\baselineskip\penalty-250
  \vskip 0pt plus -3\baselineskip\bigskip\vskip\parskip
  \message{#1}\leftline{\bf#1}\nobreak\smallskip\noindent}
% %%%
% %%% verbatim macros (from manmac.tex)
% %%%
\newskip\ttglue {\tt\global\ttglue=0.5em plus 0.25em minus 0.15em }
\def\ttverbatim{\begingroup \frenchspacing
  \catcode`\\=12 \catcode`\{=12 \catcode`\}=12 \catcode`\$=12 \catcode`\&=12
  \catcode`\#=12 \catcode`\%=12 \catcode`\~=12 \catcode`\_=12 \catcode`\^=12
  \obeyspaces \obeylines \tt}
\def\verbatimspace{\ifvmode\indent\fi\space}
{\obeyspaces \gdef\makespaceverbspace{\def {\verbatimspace}}}
\outer\def\verbatim{$$\ifdim\parskip>0pt
    \abovedisplayskip=\parskip \abovedisplayshortskip=\parskip
    \belowdisplayskip=\parskip \belowdisplayshortskip=\parskip
  \else
    \abovedisplayskip=3pt \abovedisplayshortskip=3pt
    \belowdisplayskip=3pt \belowdisplayshortskip=3pt
  \fi
  \let\par=\endgraf \ttverbatim \makespaceverbspace \parskip=0pt
  \catcode`\§=0 \advance\leftskip by 10pt \ttfinish}
{\catcode`\§=0 §catcode`§\=12 % § is temporary escape character
  §obeylines % end of line is active
  §gdef§ttfinish#1^^M#2\endverbatim{§vbox{#2}§endgroup$$}}
\catcode`\|=\active
{\obeylines \gdef|{\ttverbatim \spaceskip\ttglue \let^^M=\  \let|=\endgroup}}

\def\noitem{\item{\phantom{0.}}}

% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\font\titlefont=cmssdc10 at 36pt
\font\subtitlefont=cmssdc10 at 17pt
%
\centerline{\titlefont ifis-macros}
\bigskip
\centerline{\subtitlefont Version 2.0, 25.02.2025}
\bigskip
\centerline{Macros for plain \TeX\ by Udo Wermuth}
\medskip
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\noindent
There are three main macros in the files {\tt ifisinteger.tex}, {\tt
ifisdimension.tex}, and {\tt ifisglue.tex}. The macro |\ifisint| tests
if a given input string represents a number for \TeX. The macro
|\ifisdim| does this for dimensions and |\ifisglue| for glue and muglue.

All macros generate errors but hide them from the terminal as they
work in |\batchmode|. There is one configuration parameter:
|\IIcurrentmode|. The default is |\errorstopmode|. Change this if you
call the macros in a different interaction mode so that they can
return to this mode.

For |\ifisglue| an application is included. The macros |\ifnatwd|,
|\ifstretch|, and |\ifshrink| test the corresponding component of two
glue or muglue specifications.



\beginsection 0. Installation

To use the macro |\ifisint| load via |\input ifisinteger.tex| the file
that contains the code. For |\ifisdim| use |\input ifisdimension.tex|
and for |\ifisglue \input ifisglue.tex|.

To use |\ifnatwd|, |\ifstretch|, or |\ifshrink| enter
|\input gluecomp.tex|.



\beginsection 1. File {\tt ifisinteger.tex}

The main macro is called |\ifisint| and must be used like an
|\if|-conditional except that its argument is delimited by |\Boolend|:
|\ifisint <argument>\Boolend <true branch>\else <false branch>\fi|.

The implemented algorithm has four steps:
\smallskip
\item{1.}1)~Remove signs with or without braces; add sentinel |W|.
\noitem  2)~Test that the input isn't now |"W|, etc.; otherwise
         return false.
\item{2.}Create a canonical form with a leading zero.
\item{3.}1)~Assign the input to a |\count| register inside an
         |\hbox|.
\noitem  2)~Test that the box width is the width of the sentinel.
\noitem  3)~Otherwise return false.
\item{4.}1)~Return true if the number isn't \TeX's maximum.
\noitem  2)~Otherwise test if the canonical form is \TeX's maximum.
         If yes, return true.
\noitem  3)~Otherwise return false.
\medskip

For more details see my article in TUGboat {\bf45}:1 (2024), 106--109.



\beginsection 2. File {\tt ifisdimension.tex}

The main macro is called |\ifisdim| and must be used like an
|\if|-conditional except that its argument is delimited by |\Boolend|:
|\ifisdim <argument>\Boolend <true branch>\else <false branch>\fi|.

The implemented algorithm has four steps:
\smallskip
\item{1.}1)~Remove signs with or without braces; add sentinel |mm|.
\noitem  2)~Exclude trivial non-numerics as done in |\ifisint|.
\noitem  3)~Otherwise return false.
\item{2.}1)~Get the integer part.
\noitem  2)~Get fraction and the unit.
\noitem  3)~Get the width of the unit.
\item{3.}1)~Assign the input to a |\dimen| register inside an
         |\hbox|.
\noitem  2)~Test that the box width is the width of the sentinel.
\noitem  3)~Otherwise return false.
\item{4.}1)~Return true if the dimension isn't \TeX's |\maxdimen|.
\noitem  2)~Otherwise test if the coerced sum of the integer part
         and the fraction expressed in the unit |sp| is |\maxdimen|.
\noitem  3)~If no, return false.
\noitem  4)~Otherwise return true.
\medskip

For more details see my article in TUGboat {\bf45}:1 (2024), 109--112.



\beginsection 3. File {\tt ifisglue.tex}

The main macro is called |\ifisglue| and must be used like an
|\if|-conditional except that its argument is delimited by |\Boolend|:
|\ifisglue <argument>\Boolend <true branch>\else <false branch>\fi|.

In contrast to integers and dimensions glue and muglue are specific
to \TeX. The macro |\ifisglue| accepts only alphabetic constants
without backslashes and shouldn't be used with the double-hat notation
involving the hexadecimal digit `f'. I assume no user enters glue
specifications with such constructions.

The implemented algorithm has four steps:
\smallskip
\item{1.}Convert the characters of the keywords to
         lowercase letters; use uppercase for `f'.
\item{2.}Split at keywords {\tt minus} and {\tt plus}
         and store the components in |\II@nw| (natural width),
         |\II@st| (stretchability), |\II@sh| (shrinkability).
\item{3.}1)~Replace in |\II@nw| {\tt mu} by {\tt pt}.
\noitem  2)~Replace in |\II@st| {\tt mu}, {\tt Fil},
         {\tt Fill}, and {\tt Filll} by {\tt pt}.
\noitem  3)~Do 2) for |\II@sh|.
\noitem  4)~Count replacements and absences; if the count equals 3, set
         |\ifIImugluetrue| as the input must be muglue.
\item{4.}1)~Check if |\II@nw| is a valid dimension.
\noitem  2)~If okay check |\II@st|.
\noitem  3)~If okay check |\II@sh|.
\noitem  4)~If okay perform the box-width test using |\skip| for glue
         and |\muskip| for muglue.
\noitem  5)~If okay return true; otherwise return false.
\medskip

For more details see my article in TUGboat {\bf46}:1 (2025), 145--147.



\beginsection 4. File {\tt gluecomp.tex}

This is an application of |\ifisglue|. It provides three macros
|\ifnatwd|, |\ifstretch|, and |\ifshrink| to test individual
components of two glue or muglue specifications. They must be used
with so-called \TeX\ split glue macros (Tsgm).

Usage: |\if<macro> <Tsgm1><relation><Tsgm2>\Boolend <true branch>\else
<false branch>\fi|, where |\if<macro>| is one of |\ifnatwd|,
|\ifstretch|, or |\ifshrink| and |<relation>| is one of |<|, |=|, or
|>|.

First create a Tsgm via |\makeTsgm <glue or muglue>!<control sequence>|. It
defines the |<control sequence>| and stores the data of |<glue or muglue>|.

Second test one component of two Tsgms. For example, after |\makeTsgm
3pt plus 1fil!\one| and |\makeTsgm 1pt plus 1.1fil!\two| the test
|\ifnatwd\one>\two\Boolend| executes the |<true branch>|; with the
relations |<| and |=| the |<false branch>| is chosen. Similar,
|\ifstretch\one<\two\Boolend| and |\ifshrink\one=\two\Boolend| are
true and other relations make the comparisons false.

\medskip

For more details see my article in TUGboat {\bf46}:1 (2025), 147--150.

\bye
