path: root/Master/texmf-dist/source/latex/drac/drac-en.dtx

% \iffalse meta-comment
%-*- coding: iso-8859-15 -*-
% --------------------------------------------------------------------
% 
% Copyright (C) 2004, 2008 by Josselin Noirel et Yvon Henel 
% 
% Y. Henel dit « le TeXnicien de surface » 
% <le.texnicien.de.surface@wanadoo.fr>
%
% --------------------------------------------------------------------
% 
% This file may be distributed and/or modified under the conditions of
% the LaTeX Project Public License, either version 1.2 of this license
% or (at your option) any later version. The latest version of this
% license is in: 
%
%    <URL: http://www.latex-project.org/lppl.txt >
%
% and version 1.2 or later is part of all distributions of LaTeX
% version 1999/12/01 or later. 
%
% --------------------------------------------------------------------
% \fi
%
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\def\fileversion{v1}
%<package>\def\filedate{2008/08/14}
%<package>\def\fileinfo{fichier drac.sty par J. Noirel et Y. Henel}
%<package>\ProvidesPackage{drac}
%<package>   [\filedate\space\fileversion\space\fileinfo]
%
%<*driver>
\documentclass[a4paper]{ltxdoc}
\usepackage{drac}
\usepackage{url,array}        
\usepackage[latin1]{inputenc} 
\usepackage[T1]{fontenc}
\IfFileExists{lmodern.sty}{\usepackage{lmodern}}{}
\usepackage{ifpdf}
\usepackage{textcomp}
\usepackage{calc, xspace} % c'est pour moi (TdS) !
\let\cs=\relax
\DeclareRobustCommand*{\cs}[1]{{\normalfont\ttfamily\char`\\#1}}
\renewcommand*{\meta}[1]{{\normalfont\textlangle{\itshape #1\/}\textrangle}}
\newcommand*{\fctt}{{\normalfont\ttfamily fr.comp.text.tex}}
\makeatletter
\DoNotIndex{\@tempa,\@tempb,\@tempc,\csname,\endcsname,\noexpand,\def,^^A
  \edef,\ifx,\else,\endinput,\expandafter,\fi,\let,\newcommand,\relax,^^A
  \string,\@ifstar}
\makeatother
\usepackage[frenchb,english]{babel}
% comment out the following line to obtain the full code with explanations
\OnlyDescription
\EnableCrossrefs         
\CodelineIndex
\RecordChanges
\newcommand\BOP{\discretionary{}{}{}}
\begin{document}
\DocInput{drac-en.dtx}
\end{document}
%</driver>
% \fi
% \CheckSum{68}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v0}{2004/04/22}{Missed to be the 1st public version}
% \changes{v0.1}{2004/05/17}{Almost have been the 1st public version}
% \changes{v0.1}{2004/05/17}{Introduces \cs{ReDeclareRobActChar}}
% \changes{v1}{2008/08/14}{First public version}
% \GetFileInfo{drac.sty}
%
% \title{The \textsf{drac} package\thanks{This document corresponds to
%     the file \textsf{drac}~\fileversion, dated \filedate.}}
% \author{Josselin Noirel and Yvon Henel}
%
% \maketitle
% \begin{abstract}
%   This package provides \cs{DeclareRobustActChar} and
%   \cs{Re}\BOP|Declare|\BOP|Rob|\BOP|Act|\BOP|Char| macros.
%
%   One uses \cs{DeclareRobustActChar} as \cs{DeclareRobustCommand}
%   but the macro \cs{protect}s the active character when it appears
%   in a moving argument, see~\path{ltdefns.dtx} in
%   \path{/latex/base/}.
%
%   \cs{ReDeclareRobActChar} redefines the active character,
%   previously defined with \cs{DeclareRobustActChar}, the way
%   \cs{renewcommand} does for usual commands.
% \end{abstract}
% \begin{otherlanguage}{french}
% \begin{abstract}
%   Ce module définit \cs{DeclareRobustActChar} et
%   \cs{ReDeclareRobActChar}.
%
%   Vous devriez avoir obtenu, avec ce document, les fichiers
%   \path{drac-fr.dtx} et \path{drac-fr.pdf} qui donnent la version
%   française de cette documentation.
% \end{abstract}
% \end{otherlanguage}
%
% \tableofcontents
% 
% \section{Introduction}
% \begingroup\footnotesize{}
% 
% When the macro appeared on \fctt{} in the thread ``la question à
% 100~euros\footnote{The 100~euro question.}'', dated
% \oldstylenums{8}th april \oldstylenums{2004}, its name was
% \cs{DeclareRobustActiveCharacter} which had the advantage to be
% totally descriptive but one drawback viz.\ it was really long. To
% alleviate the pains of the typist but \emph{mainly} to avoid a
% complete mess in the index of this document, I have taken it upon
% myself to rename it \cs{DeclareRobustActChar}.
% 
% When reading the above mentioned thread, one can easily see that I
% ---{i\@. e\@.} Yvon Henel, \TeX nicien de surface--- just asked for
% code which was provided, very friendly and efficiently, by Josselin
% Noirel.  
% 
% I played a bit with Josselin's code but some months later life hit
% me hard which would not have been a surprise if I had really
% understood the classical wisdom I have been educated in during
% my younger days. But ``the light, which experience gives, is a
% lantern on the stern, which shines only on the waves behind us'' as
% wrote Samuel Taylor Coleridge. Thence when Josselin, who was rather
% busy as a student, sent me with an email in February
% \oldstylenums{2005} a second version where \cs{ReDeclareRobActChar}
% appeared I was in no state to benefit from it. 
% 
% Then time, the great healer, did fly\dots I'm back to the world and
% Josselin has left for other shores. 
% 
% The code exists and works. So instead of leaving it to rot somewhere
% on my hard disk and for I have spent somme hours to update my own
% packages I have decided to launch \texttt{drac} on the vast ocean of
% life. I just provide the wrapping and push the tiny thing on the
% nearest CTAN server. 
% 
% I do suppose that one understood that I can't promise to maintain
% the following code I hardly understand and that only because of the
% comments given by Josselin. So now is the time to let Josselin be
% at the helm\dots and the keyboard. 
% 
% \hspace*{\stretch{4}}Le \TeX nicien de surface\hspace*{\stretch{1}}
%
% \endgroup
% 
% \section{Usage}
% 
% This command has the usual syntax of the \cs{newcommand} and
% friends: it accepts a starred form depending on wether the active
% character accepts \cs{long} arguments (\emph{i.e.} an argument could
% contain a paragraph ending) or not; next comes the active character;
% an optionnal number of arguments, an optionnal argument which is the
% optionnal value of the first argument, and then the actual
% definition. Here are the valid syntaxes:
% ^^A
% \begin{list}{}{\ttfamily\leftmargin=\leftmargini}\item
% \cs{DeclareRobustActChar}\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{DeclareRobustActChar}\marg{active character}[\(n\)]\marg{definition}\par
% \cs{DeclareRobustActChar}\marg{active character}\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}[\(n\)]\marg{definition}\par
% \cs{DeclareRobustActChar}*\marg{active character}\marg{definition}
% \end{list}
% ^^A
% Then one will be able to use the active character in moving
% arguments (in the arguments of \cs{caption} for instance) and in
% other cases which demand robust commands
% (\cs{protected@edef},\cs{protected@write}, and so on).
% 
% Similarly \cs{ReDeclareRobActChar} has the same syntax than
% \cs{renewcommand} so here are the possible syntaxes:
% ^^A
% \begin{list}{}{\ttfamily\leftmargin=\leftmargini}\item
% \cs{ReDeclareRobActChar}\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{ReDeclareRobActChar}\marg{active character}[\(n\)]\marg{definition}\par
% \cs{ReDeclareRobActChar}\marg{active character}\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}[\(n\)]\%\\
% \ \ \oarg{default value of the first argument}\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}[\(n\)]\marg{definition}\par
% \cs{ReDeclareRobActChar}*\marg{active character}\marg{definition}
% \end{list}
% ^^A
% \StopEventually{\PrintChanges\PrintIndex}
%
% \section{The code}
% \begin{macro}{\DeclareRobustActChar}
%   We begin whith the definition of \cs{DeclareRobustActChar} (which
%   does not make a lot in fact).
% ^^A
%    \begin{macrocode}
% \iffalse
%<*package>
% \fi
\newcommand*{\DeclareRobustActChar}{
  \@ifstar{%
    \def\@tempc{\newcommand*}\@declarerobustactchar}{%
    \def\@tempc{\newcommand}\@declarerobustactchar}%
}
%    \end{macrocode}
% \end{macro}
% ^^A
% \begin{macro}{\ReDeclareRobActChar}
% And immediately we define \cs{ReDeclareRobActChar} (which, as the
% preceding one does not make a lot but slightly differently.)
% ^^A
%    \begin{macrocode}
\newcommand*{\ReDeclareRobActChar}{\@ifstar{%
    \def\@tempc{\renewcommand*}\@declarerobustactchar}{%
    \def\@tempc{\renewcommand}\@declarerobustactchar}%
}
%    \end{macrocode}
% ^^A
% \cs{@ifstar} checks the presence of a star and \cs{@tempc} is
% defined accordingly. \cs{@tempc} will in its time undertake the
% definition. Then \cs{@declarerobustactchar} is summoned.
% \end{macro}
% \begin{macro}{\@declarerobustactchar}
% Here comes the macro which does work:
% \cs{@declarerobustactchar}.  It takes an argument which is the
% active character (which is supposed to be \emph{already} active 
% when\cs{DeclareRobustActChar} is called in).
% ^^A
%    \begin{macrocode}
\newcommand*{\@declarerobustactchar}[1]{%
%    \end{macrocode}
% ^^A
% The present values of \cs{protect} and \cs{@typeset@protect} are
% preserved to be restored later.
% ^^A
%    \begin{macrocode}
  \let\@tempa=\protect
  \let\@tempb=\@typeset@protect
%    \end{macrocode}
% ^^A
% \cs{protect} and \cs{@typeset@protect} are defined as equivalent to 
% \cs{relax} for them not to `move' during the process of expansion in 
% \cs{edef}.  
% ^^A
%    \begin{macrocode}
  \let\protect=\relax
  \let\@typeset@protect\relax % Should be the case
%    \end{macrocode}
% ^^A
% The active character is defined. Caution: if the character is not
% active when one uses \cs{DeclareRobustActChar} there is a
% considerable risk of making \TeX{} growls about an `inaccessible'
% command. The \meta{active character} is defined as:
% ^^A
% \begin{flushleft}\begin{tabular}{@{}l@{}l@{}}
% \meta{active character} $\stackrel{\mathrm{def}}{\equiv}$ \hskip0pt &
% \cs{ifx}\cs{protect}\cs{@typeset@protect} \\
%    & \ttfamily\ \ \cs{expandafter}\cs{DRAC@real@\meta{active character}} \\
%    & \cs{else} \\
%    & \ttfamily\ \ \cs{protect}\meta{active character} \\
%    & \cs{fi} \\
% \end{tabular}\end{flushleft}
% ^^A
% The \cs{ifx} test enables us to know whether we are in the context
% of a moving argument or not. The result of the test is `true' if it
% is not the case; then \cs{DRAC@real@\meta{active character}} is
% executed: it is the effecting command which will contain in some
% time the \meta{definition} to which we were refering above.  When
% the test is `false', because we are in the context of a moving
% argument we simply \cs{protect} the \meta{active character} and put
% it back.  The \cs{expandafter} is there to make the chunk of code
% `\cs{else}\linebreak[0]\dots\linebreak[0]\cs{fi}' disappear.
% ^^A
%    \begin{macrocode}
  \edef#1{%
    \noexpand\ifx\protect\@typeset@protect
      \noexpand\expandafter
      \expandafter\noexpand
      \csname DRAC@real@\string#1\endcsname 
    \noexpand\else   
      \protect       
      \noexpand#1%
    \noexpand\fi
  }%
%    \end{macrocode}
% ^^A
% The initial values of \cs{protect} and \cs{@typeset@protect} are
% restored. 
% ^^A
%    \begin{macrocode}
  \let\protect=\@tempa
  \let\@typeset@protect=\@tempb
%    \end{macrocode}
% ^^A
% Now we define with \cs{newcommand} ---~by means of \cs{@tempc}, do
% you remember?~--- the effecting command \cs{DRAC@read@\meta{active
%     character}}. It is the use of \cs{newcommand} which enables us
% to protect the syntax. But one will note that it prevents, in
% particular, the redifinition of the command (in other words this
% package might still be improved).
% ^^A
%    \begin{macrocode}
  \expandafter\@tempc\csname DRAC@real@\string#1\endcsname
}
%    \end{macrocode}
% ^^A
% ``THE END''
% ^^A
%    \begin{macrocode}
\endinput
%    \end{macrocode}
% \end{macro}
% \iffalse
%</package>
% \fi
% ^^A
% \section{Bugs and restrictions}
% No known bugs at present. The restrictions are numerous: this
% package has no pretence.
% 
% It can \emph{a priori} work with commands as well but we advise you to
% use \cs{DeclareRobustCommand} instead in such a case.
% \Finale
\endinput
%%% Local Variables: 
%%% mode: doctex
%%% TeX-master: t
%%% fill-column: 70
%%% End: