path: root/macros/latex/contrib/ltxnew/ltxnew.dtx

% \iffalse meta-comment
% ltxnew : provides the \new \renew and \provide prefixes for checking definitions
%          [2011/03/02 v1.3]
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either
% version 1.3 of this license or (at your option) any later
% version. The latest version of this license is in
%    http://www.latex-project.org/lppl.txt
%
% This work consists of the main source file keycommand.dtx
% and the derived files
%    ltxnew.sty, ltxnew.pdf, ltxnew.ins,
%
% Unpacking:
%    (a) If ltxnew.ins is present:
%           etex ltxnew.ins
%    (b) Without ltxnew.ins:
%           etex ltxnew.dtx
%    (c) If you insist on using LaTeX
%           latex \let\install=y\input{ltxnew.dtx}
%        (quote the arguments according to the demands of your shell)
%
% Documentation:
%           (pdf)latex ltxnew.dtx
% Copyright (C) 2009-2010 by Florent Chervet <florent.chervet@free.fr>
%<*ignore>
\begingroup
  \def\x{LaTeX2e}%
\expandafter\endgroup
\ifcase 0\ifx\install y1\fi\expandafter
         \ifx\csname processbatchFile\endcsname\relax\else1\fi
         \ifx\fmtname\x\else 1\fi\relax
\else\csname fi\endcsname
%</ignore>
%<*install>
\input docstrip.tex
\Msg{************************************************************************}
\Msg{* Installation}
\Msg{* Package: ltxnew 2011/03/02 v1.3 provides the \string\new \string\renew and \string\provide prefixes for checking definitions}
\Msg{************************************************************************}

\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax
\preamble

This is a generated file.

ltxnew : provides the \string\new \string\renew and \string\provide prefixes for checking definitions.

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License, either
version 1.3 of this license or (at your option) any later
version. The latest version of this license is in
   http://www.latex-project.org/lppl.txt

This work consists of the main source file ltxnew.dtx
and the derived files
   ltxnew.sty, ltxnew.pdf, ltxnew.ins,

ltxnew : provides the \string\new \string\renew and \string\provide prefixes for checking definitions
Copyright (C) 2009-2010 by Florent Chervet <florent.chervet@free.fr>

\endpreamble
\let\MetaPrefix\DoubleperCent

\generate{%
  \file{ltxnew.ins}{\from{ltxnew.dtx}{install}}%
  \file{ltxnew.sty}{\from{ltxnew.dtx}{package}}%
}

\obeyspaces
\Msg{************************************************************************}
\Msg{*}
\Msg{* To finish the installation you have to move the following}
\Msg{* file into a directory searched by TeX:}
\Msg{*}
\Msg{*     ltxnew.sty}
\Msg{*}
\Msg{* To produce the documentation run the file `ltxnew.dtx'}
\Msg{* through LaTeX.}
\Msg{*}
\Msg{* Happy TeXing!}
\Msg{*}
\Msg{************************************************************************}

\endbatchfile
%</install>
%<*ignore>
\fi
%</ignore>
%<*driver>
\edef\thisfile{\jobname}
\def\thisversion{1.3}
\def\thisinfo{provides the \cs{new} \cs{renew} and \cs{provide} prefixes for checking definitions.}
\let\loadclass\LoadClass
\def\LoadClass#1{\loadclass[abstracton]{scrartcl}\let\scrmaketitle\maketitle\AtEndOfClass{\let\maketitle\scrmaketitle}}
\PassOptionsToPackage{svgnames}{xcolor}
\documentclass[a4paper,oneside]{ltxdoc}
\usepackage[latin9]{inputenc}
\usepackage[american]{babel}
\usepackage{etex,holtxdoc,etoolbox,geometry,tocloft,fancyhdr,xcolor,xspace,needspace,titlesec}
\usepackage{bbding,framed,float,multirow,enumitem,txfonts}\CodelineNumbered
\usepackage{bookmark}
\usepackage{embedfile}
\usepackage{ltxnew}
\usepackage{interfaces}
\embedfile{\thisfile.dtx}
\geometry{top=1.5cm,headheight=1cm,headsep=.3cm,bottom=2.5cm,left=4cm,right=2cm}
\hypersetup{%
  pdftitle={The ltxnew package},
  pdfsubject={An e-TeX package for more useful tools for LaTeX package writers},
  pdfauthor={Florent CHERVET},
  colorlinks,linkcolor=reflink,urlcolor=refurl,
  pdfstartview={FitH},
  pdfkeywords={tex, e-tex, latex, package, definitions, macros, ltxnew, newcommand, renewcommand, providecomand, new, renew, provide},
  bookmarksopen=true,bookmarksopenlevel=2}
\begin{document}
   \DocInput{\thisfile.dtx}
\end{document}
%</driver>
% \fi
%
% \CheckSum{709}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \DoNotIndex{\begin,\CodelineIndex,\CodelineNumbered,\def,\DisableCrossrefs}
% \DoNotIndex{\DocInput,\documentclass,\EnableCrossrefs,\end,\GetFileInfo}
% \DoNotIndex{\NeedsTeXFormat,\OnlyDescription,\RecordChanges,\usepackage}
% \DoNotIndex{\ProvidesClass,\ProvidesPackage,\ProvidesFile,\RequirePackage}
% \DoNotIndex{\filename,\fileversion,\filedate,\let}
% \DoNotIndex{\@listctr,\@nameuse,\csname,\else,\endcsname,\expandafter}
% \DoNotIndex{\gdef,\global,\if,\item,\newcommand,\nobibliography}
% \DoNotIndex{\par,\providecommand,\relax,\renewcommand,\renewenvironment}
% \DoNotIndex{\stepcounter,\usecounter,\nocite,\fi}
% \DoNotIndex{\@fileswfalse,\@gobble,\@ifstar,\@unexpandable@protect}
% \DoNotIndex{\AtBeginDocument,\AtEndDocument}
% \DoNotIndex{\frenchspacing,\MessageBreak,\newif,\PackageWarningNoLine}
% \DoNotIndex{\protect,\string,\xdef,\ifx,\texttt,\@biblabel,\bibitem}
% \DoNotIndex{\z@,\wd,\wheremsg,\vrule,\voidb@x,\verb,\bibitem}
% \DoNotIndex{\FrameCommand,\MakeFramed,\FrameRestore,\hskip,\hfil,\hfill,\hsize,\hspace,\hss,\hbox,\hb@xt@,\endMakeFramed,\escapechar}
% \DoNotIndex{\do,\date,\if@tempswa,\@tempdima,\@tempboxa,\@tempswatrue,\@tempswafalse,\ifdefined,\ifhmode,\ifmmode,\cr}
% \DoNotIndex{\box,\author,\advance,\multiply,\Command,\outer,\next,\leavevmode,\kern,\title,\toks@,\trcg@where,\tt}
% \DoNotIndex{\the,\width,\star,\space,\section,\subsection,\textasteriskcentered,\textwidth}
% \DoNotIndex{\",\:,\@empty,\@for,\@gtempa,\@latex@error,\@namedef,\@nameuse,\@tempa,\@testopt,\@width,\\,\m@ne,\makeatletter,\makeatother}
% \DoNotIndex{\maketitle,\parindent,\setbox,\kernel@ifnextchar}
%
% \makeatletter
% \lastlinefit999
% \newcommand\macrocodecolor{\color{macrocode}}\definecolor{macrocode}{rgb}{0.18,0.00,0.45}
% \newcommand\reflinkcolor{\color{reflink}}\definecolor{reflink}{rgb}{0.49,0.00,0.00}
% \newcommand\refurlcolor{\color{refurl}}\definecolor{refurl}{rgb}{0.00,0.00,1.00}
% \def\ThisPackage{\Xpackage{\thisfile}}\def\thispackage{\xpackage{\thisfile}}
% \newrobustcmd*\FC[1][\color{copper}]{{#1\usefont{T1}{fts}xn FC}}
% \definecolor{copper}{rgb}{0.67,0.33,0.00}
% \pagesetup{
%   rules,
%   head/left=\thispackage\ -- \thisinfo,
%   foot/font=\color{gray!70}\scriptsize,
%   foot/left=\thispackage\quad\copyright\oldstylenums{2009}-\oldstylenums{2011}\,\lower.3ex\hbox{\NibRight}\,\FC,
%   foot/right=\oldstylenums{\thepage} / \oldstylenums{\pageref{LastPage}},
% }
% \pagestyle{fancy}
% \pagesetup[plain]{
%   foot/font=\color{gray!70}\scriptsize,
%   foot/right=\oldstylenums{\thepage} / \oldstylenums{\pageref{LastPage}},
%   foot/left=\thispackage\quad\copyright\oldstylenums{2009}-\oldstylenums{2011}\,\lower.3ex\hbox{\NibRight}\,\FC\quad\xemail{florent.chervet at free.fr},
%  }
% \floatplacement{table}{H}
%
% \catcode`\§\active\def§{\par\nobreak\vskip-\parskip}
% \newlength\saveparskip\saveparskip.4\baselineskip
% \newcommand\restoreparskip{\parskip\saveparskip}
% \parindent\z@\parskip\saveparskip\topsep\z@\partopsep\z@
% \g@addto@macro\macro@font{\macrocodecolor\let\AltMacroFont\macro@font}
% \def\smex{\leavevmode\hb@xt@2em{\hfil$\longrightarrow$\hfil}}
% \newrobustcmd*\xspaceverb{\ifnum\catcode`\ =\active\else \expandafter\xspace \fi}
% \newrobustcmd*\grabcs{\leavevmode\hbox\bgroup\bgroup\makeatletter\aftergroup\endgrabcs}
% \new\mathchardef\cs@sf=1900
% \def\endgrabcs {\egroup \spacefactor\cs@sf \xspaceverb}
% \renewcommand*\cs{\cs@ensurespace \texorpdfstring{\grabcs\cs@} \cs@pdf}
% \newcommand*\cs@ensurespace{\ifhmode \ifdim\lastskip>\z@ \ifnum\spacefactor<\cs@sf \unskip\spacefactor\cs@sf \space \fi\fi\fi }
% \newcommand*\cs@pdf[1]{\@backslashchar\if\@backslashchar\string#1 \else\string#1\fi}
% \newrobustcmd\cs@[2][]{\begingroup\escapechar\m@ne\def\x ##1{\endgroup\cs@hyperlink{##1}{\textt{#1{\@backslashchar##1}}}}\expandafter\x\expandafter{\string#2}\egroup}
% \newrobustcmd*\cs@hyperlink [2]{\ifcsname @declcs.\detokenize{#1}\endcsname \hyperref{}{declcs}{#1}{#2}\else #2\fi}
% \csundef{@declcs.begin}
% \newcommand\texorpdf [2]{\texorpdfstring{#1{#2}}{#2}}
% \newcommand\textt[1]{\texorpdf\texttt{#1}}
% \def\csred{\cs[\color{red}]}
% \def\CSif\bgroup\ignorespaces#1{\bgroup\ignorespaces\ifx#1\unskip\else \CS{#1}\fi}
% \def\CSbf#1{\textbf{\CS{#1}}}
% \def\Repeat#1#2{\ifnum\numexpr#1\relax>0\relax #2\relax\Repeat{#1-1}{#2}\fi}
% \def\Xpackage{\@dblarg\X@package}
%  \def\X@package[#1]#2{%
%     \xpackage{#2\footnote{\noindent\xpackage{#2}: \href{http://www.ctan.org/tex-archive/macros/latex/contrib/#1}{\nolinkurl{CTAN:macros/latex/contrib/#1}}}}}
% \sectionformat\section[hang]{font=\large\bfseries,label=\arabic{section}.,bookmark={color=MidnightBlue}}
% \sectionformat\subsection[hang]{font=\bfseries,label=\arabic{section}.\arabic{subsection},bookmark={bold,color=black!70}}
%
%
% \deffootnote{1em}{0pt}{\rlap{\textsuperscript{\thefootnotemark}}\kern1em}
% % \makeatother
%
% \title{\mdseries The {\bfseries \Xpackage{ltxnew}}\kern.6em package}
% \author{\footnotesize \FC}
% \date{\small March 03, 2011 -- \hyperref[\thisversion]{version \thisversion}}
% \subtitle{\thisinfo}
%
% \maketitle
%
% \deffootnote{1em}{0pt}{\rlap{\thefootnotemark.}\kern1em}
% \MakeShortVerb{\+}
%
% \begin{abstract}\parindent0pt\noindent\parskip\medskipamount\small
%
% \xpackage{ltxnew} provides \CSbf{new} \CSbf{renew} and \CSbf{provide}: three expandable prefixes
% for use with |\def|, |\gdef|, |\edef|, |\xdef|, |\countdef|, |\dimendef|, |\skipdef|, |\muskipdef|,
% |\box|, |\toksdef|, |\chardef|, |\mathchardef|, |\marks|, |\count|,
% |\dimen|, |\skip|, |\muskip|, |\savebox|, |\toks| and the |\glob|\Repeat3\textasteriskcentered\
% and |\loc|\Repeat3\textasteriskcentered\ variants of the \xpackage{etex} package.
%
% For example:§
% \quad|\new\def\macro| will do {\it something like:} |\newcommand\macro{} \def\macro|§
% \quad|\new\let\macro| will do {\it something like:} |\newcommand\macro{} \let\macro|
%
% ...But in fact |\new| does a little more than that... (see \nameref{Using New}).
%
% You may use |\new| or |\renew| for declaring macros, counters, dimensions, skips, muskips,
% boxes, tokens and \eTeX's marks. Even with |\let|, |\new| can be used. Moreover, |\renew| can be used
% to redefine macros that were previously defined as |\outer|.
%
% \xpackage{ltxnew} is designed to work with an \eTeX{} distribution of \LaTeX{}. It relies on the \LaTeX{} macro
% |\@ifdefinable|, and requires the \Xpackage[etex-pkg]{etex} package and no other package.
%
% \end{abstract}\vskip-\baselineskip
% \makeatletter\begingroup\let\@thefnmark\@empty\let\@makefntext\@firstofone
% \footnotetext{\noindent
% This documentation is produced with the +DocStrip+ utility.
% \begin{tabbing}
% \qquad\=\smex\=To get the documentation, \= run (thrice):\quad\= \texttt{pdflatex ltxnew.dtx} \\
% \>\>for the index:\>\>\texttt{makeindex -s gind.ist ltxnew.idx} \\
% \>\smex\>To get the package, \> run:\>        \texttt{etex ltxnew.dtx}
% \end{tabbing}§
%  The \xext{dtx} file is embedded into this pdf file thank to \xpackage{embedfile} by H. Oberdiek.}
% \endgroup\makeatother
%
% \bigskip
%  \tocsetup{
%   title=Contents\quad\leaders\hrule height3.4pt depth-3pt\hfill\null,
%   title/bottom=8pt,
%   section/skip=5pt plus2pt minus4pt,
%   section/dotsep=3mu,
%   subsection/dotsep=3mu,
%   twocolumns,
%   multicols/afterend=\noindent\hrulefill\null,
%  }
%  
% \tableofcontents
%
% \section{Introduction}
%
% \sectionformat\subsection{bookmark={bold*=false}}
% \subsection{Motivation}
%
% \LaTeX{} provides |\newcommand| for defining new commands. However, comparing to |\def|
% the syntax is limited because we cannot use delimited arguments in such a command.
% The advantage of |\newcommand| (apart the optional argument\footnote{optional arguments are
% implemented in a much flexible way by \xpackage{xargs} by Manuel P\'egouri\'e-Gonnard.})
% is that the control sequence is first checked for availability (its meaning ought to be
% |undefined| or |\relax| before the definition).
%
% \Xpackage{etoolbox} enhance this matter with \hologo{eTeX} |\newrobustcmd|, |\renewrobustcmd| and |\providerobustcmd|.
%
% Moreover, \LaTeX{} does not provide an automatic check of control sequences when defining
% tokens (|\newtoks|), dimensions (|\newdimen|), skips (|\newskip|), etc. etc.

% The only exceptions are:§
% \begin{itemize}\itemsep=0pt
% \item |\newlength| \\
%     but there is no |\renewlength| command... because
%     the name |\renewlength| sounds bad: it would have meant \textit{``I know the control sequence I wish
%     to define as a length has been defined before, as a macro may be, or a box or a token or
%     whatever, and I wish to redefine this control sequence to be a length (\textup{ie} a skip)}.
%     So it doesn't really make sense...
% \item |\newcounter| \\
%     but |\newcounter{name}| does not define |name| but |\c@name| instead, as a counter.
% \item |\newsavebox|
% \item |\newfont|
% \end{itemize}\restoreparskip
%
% \bfseries All those |\new|\Repeat{3}{\textasteriskcentered}\ stuff define control sequences globally,
% \emph{excepting} |\newfont|.  The reason could to be found in the background\footnote{in fact, a new font
% is defined as a control sequence, just like a macro, whereas skips, dimens, tokens etc. are numbered
% and then, defining a new one require an allocation.}.
%
% \mdseries
% But it's a matter of fact : \emph{fonts} are local to \LaTeX{} while \emph{length} (\emph{ie.\,skips})
% are global...
%
% Thank to the \xpackage{etex} package that provides a method for the local allocation of new quantity
% \xpackage{ltxnew} puts the state of the affairs in a better order. \xpackage{ltxnew} provides a way
% to define new control sequences, or redefine them, just by
% beginning the definition with a (expandable) prefix : |\new| or |\renew|.
%
% \subsection{What \cs{new} means...}
%
% Such a short and easy word as \texttt{new} ought to be defined !
%
% \bfseries \CS{new} means:§\mdseries
% \begin{itemize}[label=--,topsep=0pt,itemsep=0pt]
% \item Check if the control sequence to define is available (\emph{ie} means |undefined| or |\relax|)
% \item If that's OK: go on (with a side effect if the package \xpackage{tracing} is loaded)
% \item If not : throw an error, and if in |scrollmode| or |nonstopmode| or |batchmode| do not overwrite
%       the last meaning.
% \end{itemize}
%
% That is really what means |\new|. No more, no less.
% \Needspace{5\baselineskip}
%
% \subsection{What \cs{renew} means}
%
% \bfseries \CS{renew} means:§\mdseries\nobreak
% \begin{itemize}[label=--,topsep=0pt,itemsep=0pt,beginpenalty=10000]
% \item Check if the control sequence to redefine already has a meaning (different from |undefined| and also from |\relax|)
% \item If that's OK : go on (with a side effect if the package \xpackage{tracing} is loaded)
% \item If not : throw an error. But if in |srollmode|, |nonstopmode| or |batchmode| \textbf{do define} the control sequence.
% \end{itemize}
%
% \subsection{What \cs{provide} means}
%
% \bfseries \CS{provide} means:§\mdseries
% \begin{itemize}[label=--,topsep=0pt,itemsep=0pt]
% \item Check if the control sequence to define already has a meaning (different from |undefined| and also from |\relax|)
% \item If that's OK : go on (with a side effect if the package \xpackage{tracing} is loaded)
% \item If not : silently do nothing.
% \end{itemize}
%
% \subsection{Using \cs{new}}
% \label{Using New}
%
% |\new| acts as a (expandable) prefix with the following syntax:§
% \DeleteShortVerb{\|}\catcode`\|\active\let|\textbar\def\tvs{\textcolor{green}{\textvisiblespace}}\def\cblue{\color{blue}}
% \begin{framed}\begin{centering}\begin{tabular}{clll}
%                   & \cs\new                                & \tvs                                                                          \\
% \cblue possibly   &                                        & (\csred\long\tvs|\csred\global\tvs|\csred\protected\tvs|\csred\outer\tvs) & optional (zero or more) \\
% \cblue in a macro & \multirow{-2}*{\cblue $\Biggl\lbrace$} & \textsc{<definition word>}                                                    & required: see below     \\
%                   &                                        & \textit{control sequence}                                                     & required
% \end{tabular}\end{centering}\end{framed}
% {\noindent \small \tvs\space denote optional spaces, ignored by the \cs\new-prefixes-scanner.}
%
% \MakeShortVerb{\|}
%
% \bigbreak
% The \textsc{<definition word>} may be one of the following:§\parskip=0pt
% \def\intert[#1]#2{\multicolumn{1}{#1}{\it #2}}\let\up\upshape
% \begin{table}\centering\begin{tabular}{|>{\emph}l<{:}|*{4}{>{\CSif\bgroup}l<{\egroup}}|}\hline\hline
% General            & let                   &                           &                                                 & \cr
% Macros             & def                   & gdef                      & edef                                            & xdef                \cr\hline\hline
% \intert[|c|]{Type} & \intert[|c]{def-word} & \intert[c]{always global} & \intert[c]{local (unless \up\small\CS{global})} & \intert[c|]{global}\cr\hline
% Counters           & countdef              & count                     & loccount                                        & globcount           \cr
% Dimensions         & dimendef              & dimen                     & locdimen                                        & globdimen           \cr
% Skip               & skipdef               & skip or \CS{length}       & locskip                                         & globskip            \cr
% Muskip             & muskipdef             & muskip                    & locmuskip                                       & globmuskip          \cr
% Box                & box                   & savebox                   & locbox                                          & globbox            \cr
% Tokens             & toksdef               & toks                      & loctoks                                         & globtoks            \cr
% Fonts              & font                  &                           &                                                 & \cr
% Marks              & marks                 &                           & locmarks\footnotemark                           & globmarks           \cr
% Characters         & chardef               &                           &                                                 & \cr
% Math characters    & mathchardef           &                           &                                                 & \cr
% Write              &                       & write                     &                                                 & \cr
% Read               &                       & read                      &                                                 & \cr\hline\hline
% \end{tabular}
% \caption{List of definition-words that may be used with \CS{new} \CS{renew} and \CS{provide}}
% \end{table}
% \footnotetext{The use of \CS{locmarks} is left to the appreciation of the user...}
%
% \vskip-\baselineskip\minisec{Examples:}
% \begin{tabular}{ccc}
% |\new\countdef\mycount|        & is the same as & |\new\loccount\mycount|\cr
% |\new\global\countdef\mycount| & is the same as & |\new\globcount\mycount|\cr
% |\new\count\mycount|           & is the same as & |\newcount\mycount| \cr
%                                &                & (with control sequence checking) \cr
% |\new\write\fileout|           & is the same as & |\newwrite\fileout| \cr
%                                &                & (with control sequence checking) \cr
% \end{tabular}\medbreak
%
% Therefore: (all of the following are global excepting |\newfont|):\par\nobreak
% \begin{tabular}{l@{\quad}>{\small}c@{\quad}l@{\quad}>{\small}c@{\quad}l}
%  |\new\count|   & is an improved version of & |\newcount|   & close. to & |\new\global\countdef|  \\
%  |\new\dimen|   & is an improved version of & |\newdimen|   & close. to & |\new\global\dimendef|  \\
%  |\new\skip|    & is an improved version of & |\newskip|    & close. to & |\new\global\skipdef|   \\
%  |\new\skip|    & is also the same as       & |\newlength|  &           &                         \\
%  |\new\muskip|  & is an improved version of & |\newmuskip|  & close. to & |\new\global\muskipdef| \\
%  |\new\savebox| & is the same as            & |\newsavebox| & close. to & |\new\global\box|       \\
%  |\new\toks|    & is an improved version of & |\newtoks|    & close. to & |\new\global\toksdef|   \\
%  |\new\font|    & is the same as            & |\newfont|    &           \\
%  |\new\marks|   & is an improved version of & |\newmarks|   & equiv. to & |\new\global\locmarks|
% \end{tabular}
%
%
% \bigskip
% The |\loc|\Repeat3\textasteriskcentered\space and |\glob|\Repeat3\textasteriskcentered\space words and also |\newmarks|
% are defined by \Xpackage[etex-pkg]{etex}.
%
% Please note that there is no {\bfseries |\new\command|} and there will most probably never be.
%
% \subsection{Using \cs{renew} and \cs{provide}}
%
% \cs\renew and \cs\provide share the same syntax as \cs\new.
%
% \StopEventually{
% }
%
% \begin{center}\vskip6pt$\star$\hskip4em\lower12pt\hbox{$\star$}\hskip4em$\star$\vadjust{\vskip12pt}\end{center}
%
% \section{Implementation} \label{Implementation}
% \sectionformat\subsection{bookmark=}
%
% \subsection{Identification}
%
% This package is intended to use with \LaTeX{} so we don't check if it is loaded twice.
%
%    \begin{macrocode}
%<*package>
\NeedsTeXFormat{LaTeX2e}% LaTeX 2.09 can't be used (nor non-LaTeX)
   [2005/12/01]% LaTeX must be 2005/12/01 or younger (see kvsetkeys.dtx).
\ProvidesPackage{ltxnew}
   [2011/03/02 v1.3 provides the new and renew prefixes for checking definitions]
%    \end{macrocode}
% \iffalse
%<package>
% \fi
%
% \subsection{Requirements}
%
% \thispackage\ requires \Xpackage{etex} for local allocation of counters, tokens, skips etc.
%
%    \begin{macrocode}
\RequirePackage{etex}
%    \end{macrocode}
% \iffalse
%<package>
% \fi
%
% \subsection{Helper macro}
%
% \begin{macro}{\ltxn@expandonce}
% |\ltxn@expandonce| is the copy of the |\expandonce| macro from \Xpackage{etoolbox}.
% As long as this is the only macro from \xpackage{etoolbox} we use here, we avoid loading this package.
% \iffalse
%<package>% \ltxn@expandonce is the copy of \expandonce from etoolbox.sty
% \fi
%    \begin{macrocode}
\def\ltxn@expandonce#1{\unexpanded\expandafter{#1}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{The prefixes scanner}
%
% The prefixes scanner is very simple in fact! All the job is based of |\futurelet|: |\futurelet|
% reads the next token but does not remove it from the input string. We then just have to test
% it with |\ifx| to conditionally append it into the prefix buffer: |\ltxn@prfx|. Otherwise,
% we expand the prefix once and try again. Namely:
%
% \quad|\futurelet\x\testmacro|\quad\smex\quad if |\testmacro| ``returned false'' then:§
% \quad|\expandafter\futurelet\expandafter\x\expandafter\testmacro|
%
% easy easy easy...
%
% If it happens that the expanded prefix is the same before and after expansion, then it means that was
% a primitive. The only primitives allowed between |\new| and |\def| are:§
% \begin{centering}\begin{tabular}{*{4}{m{2.5cm}}}
% |\long| & |\global| & |\protected| & |\outer| \\
% |\expandafter| & |\noexpand| & \hfil \textit{and} & |\relax|
% \end{tabular}\end{centering}
%
% \begin{macro}{\ltxn@prefix}
% This is the prefix scanner. We open a group at the very beginning for all definitions
% will be local until the final definition:
% \iffalse
%<package>
%<package>% This is the entry point of the prefixes scanner:
%<package>% The whole job is done by \futurelet
% \fi
%    \begin{macrocode}
\def\ltxn@prefix{\begingroup
   \newif\ifglobal
   \let\ltxn@prfx\@empty
   \let\ltxn@rubbish\relax
   \futurelet\x\ltxn@@prefix}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ltxn@@prefix}
% This is the test macro: it is very long because there are many many |\ifx|... and as many fees!
% \iffalse
%<package>% Here is the test macro: testing each prefix token one after another:
%<package>% It consists in a long list of \ifx
% \fi\fi
%    \begin{macrocode}
\def\ltxn@@prefix{%
   \let\ltxn@next@addto\ltxn@next@prefix
   \ifx\x\@sptoken         \let\next\ltxn@space@prefix%%1
   \else                   \let\next\ltxn@addto@prfx
      \ifx\x\long          \def\z{\long}%%2
      \else\ifx\x\protected\def\z{\protected}%%3
      \else\ifx\x\global   \let\z\@empty\globaltrue%%4
      \else\ifx\x\outer    \def\z{\outer}%%5
      \else
         \ifx\x\expandafter \def\z{\expandafter}%%6
         \else\ifx\x\noexpand    \def\z{\noexpand}%%7
         \else\ifx\x\relax       \def\z{\relax}%%8
         \else
                  \def\ltxn@next@addto{\expandafter\ltxn@def\noexpand}%
            \ifx\x\let              \def\z{\let}%%9
                                    \let\ltxn@cancel\ltxn@cancel@let
            \else                   \let\ltxn@cancel\ltxn@cancel@def
               \ifx\x\def           \edef\z{\ifglobal\global\fi\def}%%10
               \else\ifx\x\edef     \edef\z{\ifglobal\global\fi\edef}%%11
               \else\ifx\x\gdef     \def\z{\gdef}%%12
               \else\ifx\x\xdef     \def\z{\xdef}%%13
               \else                \let\ltxn@cancel\ltxn@cancel@new
                  \ifx\x\count       \def\z{\newcount}%%14
                  \else\ifx\x\countdef%%15
                     \ifglobal\def\z{\globcount}\else\def\z{\loccount}\fi
                  \else\ifx\x\loccount%%16
                     \ifglobal\def\z{\globcount}\else\def\z{\loccount}\fi
                  \else\ifx\x\globcount   \def\z{\globcount}%%17
                  \else\ifx\x\dimen       \def\z{\newdimen}%%18
                  \else\ifx\x\dimendef%%19
                     \ifglobal\def\z{\globdimen}\else\def\z{\locdimen}\fi
                  \else\ifx\x\locdimen%%20
                     \ifglobal\def\z{\globdimen}\else\def\z{\locdimen}\fi
                  \else\ifx\x\globdimen   \def\z{\globdimen}%%21
                  \else\ifx\x\skip        \def\z{\newskip}%%22
                  \else\ifx\x\skipdef%%23
                     \ifglobal\def\z{\globskip}\else\def\z{\locskip}\fi
                  \else\ifx\x\locskip%%24
                     \ifglobal\def\z{\globskip}\else\def\z{\locskip}\fi
                  \else\ifx\x\globskip    \def\z{\globskip}%%25
                  \else\ifx\x\muskip      \def\z{\newmuskip}%%26
                  \else\ifx\x\muskipdef%%27
                     \ifglobal\def\z{\globmuskip}\else\def\z{\locmuskip}\fi
                  \else\ifx\x\locmuskip%%28
                     \ifglobal\def\z{\globmuskip}\else\def\z{\locmuskip}\fi
                  \else\ifx\x\globmuskip  \def\z{\globmuskip}%%29
                  \else\ifx\x\savebox     \def\z{\newsavebox}%%30
                  \else\ifx\x\box%%31
                     \ifglobal\def\z{\globbox}\else\def\z{\locbox}\fi
                  \else\ifx\x\locbox%%§32
                     \ifglobal\def\z{\globbox}\else\def\z{\locbox}\fi
                  \else\ifx\x\globbox     \def\z{\globbox}%%33
                  \else\ifx\x\toksdef%%34
                     \ifglobal\def\z{\globtoks}\else\def\z{\loctoks}\fi
                  \else\ifx\x\toks        \def\z{\newtoks}%%35
                  \else\ifx\x\loctoks%%36
                     \ifglobal\def\z{\globtoks}\else\def\z{\loctoks}\fi
                  \else\ifx\x\globtoks    \def\z{\globtoks}%%37
                  \else\ifx\x\locmarks%%38
                     \ifglobal\def\z{\globmarks}\else\def\z{\locmarks}\fi
                  \else\ifx\x\marks       \def\z{\newmarks}%%39   %\newmarks=\globmarks
                  \else\ifx\x\globmarks   \def\z{\globmarks}%%40
                  \else\ifx\x\font        \def\z{\font}%%41
                  \else\ifx\x\write       \def\z{\newwrite}%%42
                  \else\ifx\x\read        \def\z{\newread}%%43
                  \else\ifx\x\char        \def\z{\chardef}%%44
                  \else\ifx\x\chardef     \def\z{\chardef}%%45
                  \else\ifx\x\mathchar    \def\z{\mathchardef}%%46
                  \else\ifx\x\mathchardef \def\z{\mathchardef}%%47
                  \else\ifx\x\protect     \ltxn@error@prefix%%48
                  \else
                     \let\ltxn@next@addto\ltxn@next@prefix
                     \ifx\y\x\ltxn@error@prefix
                     \else\let\y\x
                     \fi
                     \let\next\ltxn@expand@prefix
                  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
                  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
                  \fi\fi\fi\fi\fi\fi\fi\fi\fi\fi\fi
               \fi\fi\fi\fi\fi\fi\fi\fi
            \fi
         \fi\fi\fi
      \fi\fi\fi\fi% so many fees...
   \fi\next}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\def\ltxn@next@prefix{\futurelet\x\ltxn@@prefix}
\def\ltxn@expand@prefix{%
   \expandafter\futurelet\expandafter\x\expandafter\ltxn@@prefix}
\def\ltxn@addto@prfx#1{\let\y\@undefined
   \expandafter\expandafter\expandafter\def
      \expandafter\expandafter\expandafter\ltxn@prfx
         \expandafter\expandafter\expandafter{\expandafter\ltxn@prfx\z}%
%   \edef\ltxn@prfx{\ltxn@expandonce\ltxn@prfx\ltxn@expandonce\z}%
   \ltxn@next@addto}
\expandafter\def\expandafter\ltxn@space@prefix\space{\ltxn@next@prefix}
\def\ltxn@error@prefix{\@latex@error{A \string\def\space
   (or \string\countdef\space or\string\toksdef\space etc.)\MessageBreak
   was expected after \string\new\MessageBreak
   I found a \meaning\x!\MessageBreak
   see ltxnew documentation for more information}\@ehd}
%    \end{macrocode}
%
% \subsection{The cancel macros}
%
% \begin{macro}{\ltx@cancel}
% These are the macros used in case we have to cancel definition (nonstopmode)
% \iffalse
%<package>
%<package>% These are the macros used in case we have to cancel definition (nonstopmode)
%<package>% #1 is always the control sequence not to redefine
% \fi
%    \begin{macrocode}
\def\ltxn@cancel@let{\afterassignment\endgroup\let\ltxn@rubbish}
\def\ltxn@cancel@def{\afterassignment\endgroup\def\ltxn@rubbish}
\def\ltxn@cancel@new{\endgroup}
%    \end{macrocode}
% \end{macro}
%
% \subsection{The defining macros}
%
% \begin{macro}{\ltxn@new}
% |\ltxn@new| defines the new control sequence, or cancels definition depending on the result
% of |\@ifdefinable|. |\ltxn@new| does all the jobs: it is called by both |\ltxn@renew| and |\ltxn@provide|:
% \iffalse
%<package>
%<package>% new: Do define or cancel, depending on the result of \@ifdefinable
% \fi
%    \begin{macrocode}
\def\ltxn@new#1{%
   \let\next\ltxn@cancel
   \ifdefined#1\unless\ifx#1\relax\def#1{new:error}\fi\fi
   \expandafter\@ifdefinable\noexpand#1{%
      \expandafter\let\noexpand#1=\relax
      \edef\next{\endgroup\ltxn@expandonce\ltxn@prfx#1}}%
   \next}

%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ltxn@renew}
% |\ltxn@renew| throws an error if the control sequence is undefined or if its meaning is |\relax|.
% In case of |nonstopmode| the control sequence is redefined, however.
%
% To handle the case where the control sequence was an outer macro, we ``stringify'' its name first,
% in order not to give the control sequence itself as an argument for the error message.
% \iffalse
%<package>
%<package>% renew: Throws an error in case the control sequence is unknown or \relax
% \fi
%    \begin{macrocode}
\def\ltxn@renew#1{%
   \edef\ltxn@name{\string#1}%
   \ifdefined#1\ifx#1\relax\ltxn@error{renew: \ltxn@name\space undefined}\fi
   \else       \ltxn@error{renew: \ltxn@name\space undefined}%
   \fi
   \let#1=\relax
   \def\next{\ltxn@new#1}%
   \next}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ltxn@provide}
% |\ltxn@provide| never throws an error, but define the control sequence only if it is undefined or |\relax|
% (\emph{ie}\, if it is |definable|):
%
% To handle the case where the control sequence was an outer macro, we ``stringify'' its name first,
% in order not to put the control sequence itself in the definition of |\next|. It's admittedly tricky
% here, because if the control sequence is already defined, |\provide| will cancel out the new definition,
% however, as a borderline effect, |\ltxn@new| should have been called with this very control sequence as an argument,
% if it had been definable. Even if this |\iffalse|-call (not expanded) is prepared
% into |\ifx|...|\fi| conditional, the |\outer| control sequence is there, and \TeX{} (not \LaTeX{})
% will throw an error: \texttt{Forbidden control sequence found...}.
% \iffalse
%<package>
%<package>% provide: Never throw an error but conditionally defines the control sequence
% \fi
%    \begin{macrocode}
\def\ltxn@provide#1{%
   \let\next\ltxn@cancel
   \edef\ltxn@name{\string#1}%
   \ifdefined#1\ifx#1\relax \ltxn@provide@new\fi
   \else \ltxn@provide@new
   \fi
   \next}
\def\ltxn@provide@new{%
   \edef\next{\noexpand\ltxn@new\csname\expandafter\@gobble\ltxn@name\endcsname}}
%    \end{macrocode}
% \end{macro}
%
% \subsection{The prefixes: \cs{new}, \cs{renew} and \cs{provide}}
%
%  \begin{macro}{\new}
% |\new|: the entry point: just let the definition macro to be |\ltxn@new| and start scanning prefixes.
% \iffalse
%<package>
%<package>% \new: the entry point:
%<package>%       just let the definition macro to be \ltxn@new and start scanning prefixes.
% \fi
%    \begin{macrocode}
\protected\def\new{\let\ltxn@def\ltxn@new\ltxn@prefix}
%    \end{macrocode}
%  \end{macro}
%
%  \begin{macro}{\renew}
% |\renew|: the entry point: just let the definition macro to be |\ltxn@renew| and start scanning prefixes.
% \iffalse
%<package>
%<package>% \renew: the entry point:
%<package>%         just let the definition macro to be \ltxn@renew and start scanning prefixes.
% \fi
%    \begin{macrocode}
\protected\def\renew{\let\ltxn@def\ltxn@renew\ltxn@prefix}
%    \end{macrocode}
%  \end{macro}
%
% \begin{macro}{\provide}
% |\provide|: the entry point: just let the definition macro to be |\ltxn@provide| and start scanning prefixes.
% \iffalse
%<package>
%<package>% \provide: the entry point:
%<package>%           just let the definition macro to be |\ltxn@provide| and start scanning prefixes.
% \fi
%    \begin{macrocode}
\protected\def\provide{\let\ltxn@def\ltxn@provide\ltxn@prefix}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ltxn@error}
% In case of redefinition, throws an |\ehc|-type error:
% \iffalse
%<package>
%<package>% In case of redefinition, throws an |\ehc|-type error:
% \fi
%    \begin{macrocode}
\def\ltxn@error#1{\@latex@error{#1}\@ehc}
%    \end{macrocode}
% \tracingnone
%  \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \begin{History}
%
%   \begin{Version}{2011/03/02 v1.3}\HistLabel{1.3}
%   \item
%       \cs\chardef and \cs\mathchardef added as allowed definition words.
%   \end{Version}
%
%   \begin{Version}{2010/04/17 v1.2}\HistLabel{1.2}
%   \item \cs\provide and \cs\renew added an undesirable blank space.
%   \end{Version}
%
%   \begin{Version}{2009/10/11 v1.1}\HistLabel{1.1}
%   \item
%     Correction of \texttt{.sty} header.
%   \end{Version}
%
%   \begin{Version}{2009/07/22 v1.0}\HistLabel{1.0}
%   \item
%     First version.
%   \end{Version}
%
% \end{History}
%
% \begin{thebibliography}{9}
%
% \bibitem{etex}
%   \textit{The \xpackage{etex} package}; \\
%   David Carlisle and Peter Breitenlohner \\
%   1998/03/26 v2.0;
%   \CTAN{macros/latex/contrib/etex-pkg/}.
%
% \end{thebibliography}
%
% \PrintIndex
%
% \label{LastPage}
% \Finale