path: root/macros/latex/contrib/progkeys/programs.dtx

% \iffalse
%
% 'programs.dtx'
%
% Copyright (C) 1993,1994,1995 by Miguel Alabau.  All rights reserved.
%
% ENVIRONMENTS FOR EASILY TYPESETTING PROGRAMS
%
% **WARNING** If the file 'programs.ins' does not accompany the file
% 'programs.dtx', then you must strip this last file by hand.
% (1) Run 'latex docstrip' on 'programs.dtx' and indicate 'drv' as
%     suffix file and 'driver' as selector for extraction.
% (2) Run 'latex docstrip' on 'programs.dtx' and indicate 'sty' as
%     suffix file and 'style' as selector for extraction.
% (3) Run 'latex docstrip' on 'programs.dtx' and indicate 'ist' as
%     suffix file and 'index' as selector for extraction.
% Then, if you want to produce the documentation, proceed as follows:
%     latex programs.drv; latex programs.drv; latex programs.drv
%     makeindex -s programs.ist programs.idx
%     latex programs.drv
%
%<style>\NeedsTeXFormat{LaTeX2e}
%<style>\ProvidesPackage{programs}
%
% \fi
%
%
% \def\fileversion{v1.0}
% \def\filedate{95/04/01}
% \def\docdate {96/01/31}
%
%
% ^^A -*-LaTeX-*-
% 
%\catcode`\<=12

% \CheckSum{393}
%% \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{\@,\@@par,\@beginparpenalty,\@empty}
% \DoNotIndex{\@flushglue,\@gobble,\@input}
% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
% \DoNotIndex{\cal,\csname,\def,\documentstyle,\dospecials,\edef}
% \DoNotIndex{\documentclass}
% \DoNotIndex{\egroup}
% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
% \DoNotIndex{\ifcase}
% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
% \DoNotIndex{\strutbox}
% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
% \DoNotIndex{\nopagebreak}
% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
% \DoNotIndex{\[,\{,\},\]}
% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
% \DoNotIndex{\baselineskip,\begin,\tw@}
% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
% \DoNotIndex{\bfdefault}
%
% \DoNotIndex{\addtocounter,\baselinestretch,\em,\noindent}
% \DoNotIndex{\linewidth,\columnwidth,\newcounter,\newif,\newlength}
% \DoNotIndex{\normalsize,\refstepcounter,\rlap,\rule}
% \DoNotIndex{\@@tempa,\@@tempb,\@ifnextchar,\@nameuse}
%
% \title{The ``{\sf{}programs.sty}'' style file\thanks{%
%    This file has version number \fileversion{} dated \filedate{}.
%    The documentation was last revised on \docdate{}.}}
%
% \author{Miguel Alabau\\
%         {\small{}LaBRI, Universit\'e Bordeaux~I (France)}\\
%         {\small{\em{}e-mail\/}: {\tt{}Miguel.Alabau@labri.u-bordeaux.fr}}}
%
% \maketitle
%
% \begin{abstract}
%    This style file contains a set of definitions that allow a fairly
%    easy pretty-printing of programs.
%    In particular, text alignement is obtained by simply typing
%    {\tt{}space} characters.
%    Emphasized characters, mathematical symbols and commands are
%    directly taken into account.
% \end{abstract}%
%
% \newif\ifmulticols
% \makeatletter
% \ifhave@multicol\multicolstrue\else\multicolsfalse\fi
% \makeatother
%
% \begin{footnotesize}
%     \ifmulticols \begin{multicols}{2} \fi
%     \tableofcontents
%     \ifmulticols \end{multicols} \fi
% \end{footnotesize}
%
%
% \ifmulticols
% \begin{multicols}{2}[\section{Introduction}]
% \else \section{Introduction} \fi
%
% The \LaTeX\ \verb"verbatim" environment allows for easy typesetting
% of text. However it is sometimes convenient to type programs that
% involve some mathematics, some emphasized text or some boldfaced
% keywords.
% \LaTeX\ provides the \verb"tabbing" environment for freely
% typesetting programs. But a cumbersome aspect of this environment is
% the way tabs are specified: their presence makes the text to be
% obscured. 
% The file {\em{}programs.sty\/} provides different environments and
% commands for typesetting programs. Spaces are interpreted as in the
% \verb"verbatim" environment, avoiding the user to type \verb"\=" and
% \verb"\>" control characters.
% Accents, mathematical symbols, emphasized and boldface fonts can be
% used. Another useful feature is the capability 
% to number lines and to put labels on lines (and, of course, to refer
% to them).
%
% \ifnoprogsfile \relax\else
%
% For instance, you may type something like
% \InBodyLeftNumberLine
%
% \begin{verbatim}
% \begin{programf}
% function sqrt(x: integer): integer;
%          (* sqrt(x)  = $\sqrt{x}$ *)
% function pow(x,y: real): real;
%          (* pow(x,y) = $x^y$ *)
% \end{programf}
% \end{verbatim}
%
% \vspace{-\baselineskip}
% \noindent%
% which leads to the following output
%
% \begin{programf}
% function sqrt(x: integer): integer;
%          (* sqrt(x)  = $\sqrt{x}$ *)
% function pow(x,y: real): real;
%          (* pow(x,y) = $x^y$ *)
% \end{programf}
%
% \fi
%
% It is also possible to typeset the same program in a smaller font,
% enclosed within two horizontal lines, and with the lines unnumbered.
%
% \ifnoprogsfile \relax\else
%
% \begin{verbatim}
% \programsurround
% \begin{programt}*
% function sqrt(x: integer): integer;
%          (* sqrt(x)  = $\sqrt{x}$ *)
% function pow(x,y: real): real;
%          (* pow(x,y) = $x^y$ *)
% \end{programt}
% \end{verbatim}
%
% \vspace{-\baselineskip}
% \noindent%
% yielding to the following output:\\
%
% \programsurround
% \begin{programt}*
% function sqrt(x: integer): integer;
%          (* sqrt(x)  = $\sqrt{x}$ *)
% function pow(x,y: real): real;
%          (* pow(x,y) = $x^y$ *)
% \end{programt}
%
% \fi
%
% A set of other options is provided, together with two file inclusion
% capabilities.
%
% \ifmulticols\end{multicols}\fi
%
% ^^A **********************************************
% ^^A **          USERS's MANUAL                  **
% ^^A **********************************************
%
% \section{User's Manual}
%
% In this section, we describe the environments and commands provided by
% this style file (section~\ref{user:program-environments}).
% We indicate also three sets of control commands:
% 
% \begin{itemize}
%   \item{} Global commands, i.e. global switches for the
%     commands/environments of section~\ref{user:program-environments}
%     (section~\ref{user:global-commands}).
%   \item{} Commands whose scope is the next program only
%     (section~\ref{user:running-commands}).
%   \item{} Commands that are used {\em{}within\/} a program environment
%     (section~\ref{user:local-commands}).
% \end{itemize}
% 
% The user is provided with two {\em{}meta-commands\/} that allow to
% define new program environments for some other fonts, or to redefine
% existing program environments.
%
% This section terminates by indicating how to proceed for extracting
% the different archives from the file {\em{}programs.dtx}.
%
% \subsection{Environments for typesetting programs}
% \label{user:program-environments}
%
% The following environments are provided, every one of them
% corresponding to one of the \LaTeX\ predefined font sizes:
%
% \begin{center}
% \begin{tabular}{ll}
%     \hline
%     \multicolumn{1}{c}{environments} & \multicolumn{1}{c}{sizes}\\
%     \hline\hline
%     program   & normalsize \\
%     programl  & large \\
%     programL  & Large \\
%     programs  & small \\
%     programf  & footnotesize \\
%     programsc & scriptsize \\
%     programt  & tiny \\
%     \hline
% \end{tabular}
% \end{center}
%
% These environments are to be used like the \verb"verbatim"
% environment. However they work differently, since the usual \LaTeX\
% escapes are allowable from within the environment. For instance,
% math mode as well as emphasized characters may be used.
%
% By default, lines are numbered. If someone wants to type an
% unnumbered text, it is necessary to put a \verb"*" just after the
% beginning of the environment.
% \ifnoprogsfile \relax\else
% For instance:
%
% \begin{verbatim}
% \begin{programL}*
%     <unnumbered text>
% \end{programL}
% \end{verbatim}
% \fi
%
% Program indentation obey to the variable \verb"\ProgramIndent" (see
% section~\ref{user:global-commands}). However, it is possible, for
% one given environment, not to obey to the global indentation of
% programs. This is done by indicating another indentation between
% square braces just after entering the environment.
% \ifnoprogsfile \relax\else
% For instance, an unnumbered program indented 2cm from the left
% margin of the text is:
%
% \begin{verbatim}
% \begin{programL}[2cm]*
%     <unnumbered text>
% \end{programL}
% \end{verbatim}
% \fi
%
% There is also a set of inclusion commands similar to the
% \verb"\verbatimfile" (verbatim inclusion of a file) and
% \verb"\verbatimlisting" (verbatim inclusion of a file, with
% numbered lines) commands of the ``{\em{}verbatimfiles.sty\/}'' by
% Chris Rowley.
% Of course, the files input by these commands are subject to the same
% permisive syntax as for the environments above (math syntax,
% emphasized text, {\em{}etc.\/}).
%
% \begin{center}
% \begin{tabular}{lll}
%     \hline
%     \multicolumn{3}{c}{program inclusion commands} \\
%     \hline
%     \multicolumn{1}{c}{unnumbered programs}
%     & \multicolumn{1}{c}{numbered programs}
%     & \multicolumn{1}{c}{sizes}\\
%     \hline\hline
%     \verb"\"fprogram   & \verb"\"lprogram   & normalsize      \\
%     \verb"\"fprograml  & \verb"\"lprograml  & large           \\
%     \verb"\"fprogramL  & \verb"\"lProgramL  & Large           \\
%     \verb"\"fprograms  & \verb"\"lprograms  & small           \\
%     \verb"\"fprogramf  & \verb"\"lprogramf  & footnotesize    \\
%     \verb"\"fprogramsc & \verb"\"lprogramsc & scriptsize      \\
%     \verb"\"fprogramt  & \verb"\"lprogramt  & tiny            \\
%     \hline
% \end{tabular}
% \end{center}
%
% We describe in section~\ref{user:meta-commands} how to define new
% program environments.
%
% \subsection{Global commands}
% \label{user:global-commands}
%
% \DescribeMacro{\ProgramIndent}
% This command serves to control the default indentation of the
% programs.
% It is used as described below:
% \begin{verbatim}
%    \ProgramIndent{1cm}
% \end{verbatim}
% \vspace{-\baselineskip}
% and has the effect to make all the programs to be indented by
% default one centimeter from the left margin, unless this value is
% changed by another \verb"\ProgramIndent" command.
% Default is no indentation at all.
%
% \DescribeMacro{\programindent}
% This macro redefines the macro \verb+\ProgramIndent+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \DescribeMacro{\LeftMarginNumberLine}
% \DescribeMacro{\RightMarginNumberLine}
% \DescribeMacro{\BothMarginsNumberLine}
% \DescribeMacro{\InBodyLeftNumberLine}
% These four commands are self-explanatory.
% They allow the user to specify that line numbers must be put in
% either the left or the right margin, or in both margins, or that lines
% must appear inside the body of the text on the left of the program.
% These options may be put anywhere in the text, in the preamble as
% well as in the body.
% The effect of one of these commands stands until it is changed by
% another one of them.
% Of course, different commands may be put in several parts of the text,
% if the user wants its programs to be numbered differently.
% The default is for the lines to appear in the left margin of the
% text (\verb"\LeftMarginNumberLine"). 
%
% \DescribeMacro{\BothMarginNumberLine}
% This macro redefines the macro \verb+\BothMarginsNumberLine+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \DescribeMacro{\ttProgram}
% \DescribeMacro{\rmProgram}
% \DescribeMacro{\emProgram}
% Text of programs are usually typed with a teletype font (like in the
% \verb"verbatim" environment). The user has the ability to change
% this default font to one of the three predefined fonts: teletype,
% roman, italicized roman.
%
% \DescribeMacro{\ProgramDefaultFont}
% The command \verb"\ProgramDefaultFont" serves to reset the printing
% to the default font. 
%
% \subsection{Commands to be used before a program environment}
% \label{user:running-commands}
%
% \DescribeMacro{\ProgramSurround}
% Programs are usually typeset as they are.
% However a user can specify that the next program to be printed will
% be surrounded by two horizontal lines, as long as the width of the
% text.
% This is done by putting this command in the body of the text before
% the program appears. 
%
% \DescribeMacro{\programsurround}
% This macro redefines the macro \verb+\ProgramSurround+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \DescribeMacro{\SetProgramCounter}
% By default, program lines are counted from~$1$.
% It is possible to change the value of the first line number of the
% next program by issuing the following command before the program is
% included: 
%
% \begin{verbatim}
%     \SetProgramCounter{6}
% \end{verbatim}
%
% \vspace{-\baselineskip}
% In this example, the lines of the next program will start from~$6$.
%
% \DescribeMacro{\setprogramcounter}
% This macro redefines the macro \verb+\SetProgramCounter+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \DescribeMacro{\NoResetProgramCounter}
% If the user desires that the number of the first line of the next
% program is equal to the number of the last line of the last previous
% program, he must issue the command \verb"\NoResetProgramCounter"
% before the next program.
% This command has no effect if issued before the first program.
%
% \DescribeMacro{\noresetprogramcounter}
% This macro redefines the macro \verb+\NoResetProgramCounter+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \subsection{Commands to be used inside a program environment}
% \label{user:local-commands}
%
% \DescribeMacro{\UnnumLine}
% \label{user:unnumline}
% This command is to be used only {\em{}within\/} programs.
% It must appear at the end of a line and has the effect not to number
% the following line.
% It serves when the user wants to keep only one unique line number for
% long statements that span accross several lines.
%
% \DescribeMacro{\unnumline}
% This macro redefines the macro \verb+\UnnumLine+.
% It is present here for compatibility with previous versions of the
% {\em{}programs.sty\/} style.
%
% \subsection{Meta-Commands: how to define new program environments}
% \label{user:meta-commands}
%
% \DescribeMacro{\NewProgram}
% \DescribeMacro{\RenewProgram}
% \label{user:newprogram}
% The \verb"\NewProgram" command serves to define a new program
% environment.
% The \verb"\RenewProgram" command is to be used for redefining already
% defined program environments.
% These commands must be used as below:
% \begin{quote}
%     \verb"\NewProgram"\{{\em{}name\/}\}\{{\em{}font\_name\/}\} \\
%     \verb"\RenewProgram"\{{\em{}name\/}\}\{{\em{}font\_name\/}\}
% \end{quote}
%
% The command \verb"\NewProgram" defines one environment and two
% commands. Let us assume that the user issues the following command:
%
% \begin{verbatim}
%     \NewProgram{LittleProg}{smallsize}
% \end{verbatim}
%
% \vspace{-\baselineskip}%
% then an environment called \verb"LittleProg" will be generated for
% direct typesetting of programs, and two commands will be created:
% \verb"fLittleProg" and \verb"lLittleProg" for inclusion of
% unnumbered (resp. numbered) text.
%
% \DescribeMacro{\newprogram}
% \DescribeMacro{\renewprogram}
% These two macros are old names present here for compatibility with
% previous versions of the {\em{}programs.sty\/} style.
% \verb+\newprogram+ redefines \verb+\NewProgram+, and 
% \verb+\renewprogram+ redefines \verb+\RenewProgram+.
%
% \subsection{The Index File}
%
% In order for the processing of this file to be complete, an index
% format file is required. Let us assume that it is named
% \verb+programs.ist+, then the following command must be run and then
% another compilation of the current file:
%
%    \begin{macrocode}
%<index>
%<index>%% -----------------------------------------------------------
%<index>%% Assuming this file is named "programs.ist" (after being
%<index>%% generated from "programs.dtx" by running "latex docstrip"),
%<index>%% the following command will produce a well formated index:
%<index>%% 
%<index>%%                  makeindex -s programs.ist programs.idx
%<index>%% -----------------------------------------------------------
%<index>
%    \end{macrocode}
%
% Another possibility is to set the environment variable
% \verb+INDEXSTYLE+ to a directory name where the ``.ist'' files
% (index format files) may be found.
%
% A possible index file is given below\footnote{It can be generated by
% invoquing the compilation of ``docstrip'' with the ``index''
% option.}: 
%
%    \begin{macrocode}
%<index>actual '='
%<index>quote '!'
%<index>level '>'
%<index>preamble
%<index>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
%<index>postamble
%<index>"\n\n \\end{theindex}\n"
%<index>item_x1   "\\efill \n \\subitem "
%<index>item_x2   "\\efill \n \\subsubitem "
%<index>delim_0   "\\pfill "
%<index>delim_1   "\\pfill "
%<index>delim_2   "\\pfill "
%<index>% The next lines will produce some warnings when
%<index>% running Makeindex as they try to cover two different
%<index>% versions of the program:
%<index>lethead_prefix   "{\\bf\\hfil "
%<index>lethead_suffix   "\\hfil}\\nopagebreak\n"
%<index>lethead_flag       1
%<index>heading_prefix   "{\\bf\\hfil "
%<index>heading_suffix   "\\hfil}\\nopagebreak\n"
%<index>headings_flag       1
%    \end{macrocode}
%
% \subsection{The Driver File}
%
% There is also a driver file, called {\em{}programs.drv\/}, that is
% included in the distribution. 
% It is devoted to control the latex compilation of the documentation.
% Its code is given below.
%
%    \begin{macrocode}
%<*driver>
\newif\ifnoprogsfile
\openin1 programs.sty
\ifeof1 \noprogsfiletrue\else\noprogsfilefalse\fi\closein1
\ifnoprogsfile
    \typeout{*******************************************************}
    \typeout{To get a more complete documentation, you should}
    \typeout{copy the current file into 'programs.sty'}
    \typeout{*******************************************************}
\fi
\ifnoprogsfile
    \documentclass{ltxdoc}
\else
    \documentclass{ltxdoc}
    \usepackage{programs}
\fi
\MakePercentIgnore%
%
\setlength{\textwidth}{31pc}%
\setlength{\textheight}{54pc}%
\setlength{\parindent}{0pt}%
\setlength{\parskip}{2pt plus 1pt minus 1pt}%
\setlength{\oddsidemargin}{8pc}%
\setlength{\marginparwidth}{8pc}%
\setlength{\topmargin}{-2.5pc}%
\setlength{\headsep}{20pt}%
\setlength{\columnsep}{1.5pc}%
\setlength{\columnwidth}{18.75pc}%
%%
\setcounter{IndexColumns}{2}%
\EnableCrossrefs%
\RecordChanges
\CodelineIndex
%\OldMakeindex     % use if your MakeIndex is pre-v2.9%
\begin{document}%
    \DocInput{programs.dtx}
\end{document}
%</driver>
%    \end{macrocode}
%
% \subsection{Extracting the documents included in the file programs.dtx}
%
% There are three documents included in the {\em{}programs.dtx\/} file:
% the style file ({\em{}programs.sty}),
% the index style file for printing a cross-referenced document
% ({\em{}programs.ist}),
% and the driver file for printing the document: {\em{}programs.drv\/}.
%
% For file extraction it is necessary to use the \verb"docstrip"
% utility, which is part of the \verb"doc"
% distribution~\cite{art:doc}. 
% Normally, a file \verb"docstrip.tex" should exist on the \LaTeX\
% style files directory.
% Extraction is performed by typing:
%
% \begin{verbatim}
%    latex docstrip
% \end{verbatim}
%
% This is an interactive program, and the dialogue for generating the
% style file should be:
%
% \begin{verbatim}
%    **********************************************************
%    * This program converts documented macro-files into fast *
%    * loadable files by stripping off (nearly) all comments! *
%    **********************************************************
%    
%    ****************************************************
%    * First type the extension of your input file(s):  *
%    \infileext=doc
%    ****************************************************
%    
%    ****************************************************
%    * Now type the extension of your output file(s)  : *
%    \outfileext=sty
%    ****************************************************
%    
%    ****************************************************
%    * Now type the name(s) of option(s) to include   : *
%    \Options=style
%    ****************************************************
%    
%    ****************************************************
%    * Finally give the list of input file(s) without   *
%    * extension seperated by commas if necessary     : *
%    \filelist=programs
%    ****************************************************
% \end{verbatim}
%
% For generating the index file it suffices to rerun the
% \verb"docstrip" utility and to answer ``ist/index'' instead of
% ``sty/style'' int the above steps~2 and~3, and in another run to
% answer "drv/driver".
%
% \medskip
%
% The three files may be produced in a single pass, by simply latexing
% the file {\em{}programs.ins\/} which goes along with the file
% {\em{}programs.dtx\/}. 
%
% \medskip
%
% Generation of the documentation is then simply performed as follows:
%
% \begin{verbatim}
%    latex programs.drv
%    latex programs.drv
%    latex programs.drv
%    makeindex  -s programs.ist programs.idx
%    latex programs.drv
% \end{verbatim}
%
% \StopEventually{
%  \begin{thebibliography}{1}
%    \bibitem{book:KnuthA} {\sc D.E. Knuth}.
%      \newblock Computers \& Typesetting (The \TeX book).
%      \newblock Addison-Wesley, Vol. A, 1986.
%    \bibitem{lamport86}{\sc L. Lamport}.
%      \newblock {\em {\LaTeX}: a Document Preparation System}.
%      \newblock Addison-Wesley Publishing Company, 1986.
%    \bibitem{art:doc} {\sc F. Mittelbach}.
%      \newblock The {\tt doc}-option.
%      \newblock {\sl TUGboat}, Vol.~10(2), {\it pp}.~245--273, July
%        1989.
%    \bibitem{art:docstrip} {\sc F. Mittelbach, D. Duchier and
%         J. Braams}. 
%      \newblock {\tt docstrip.dtx}~.
%      \newblock The file is part of the DOC package.
%  \end{thebibliography}
% 
% } ^^A end \StopEventually
%
%    \begin{macrocode}
%<*style>
%    \end{macrocode}
%

% ^^A **********************************************
% ^^A **          TECHNICAL DESCRIPTION           **
% ^^A **********************************************

\typeout{Document style `programs.sty' <1993,1994,1995>}

% \section{Description of Macros}
%
% \begin{macro}{\AlreadyDefined@@Programs}
%    This macro can be tested by any style file to know if the file
%    ``{\sf{}programs.sty}'' has been input. But it allows a modular
%    programming style similar to the one used with the C~header
%    files. 
%    Hence, the first time the ``{\sf{}programs.sty}'' style file is
%    included all of its body will be included; the second time, the
%    body will not be included.
%    \begin{macrocode}
\expandafter\ifx\csname AlreadyDefined@@Programs\endcsname\relax%
\expandafter\def\csname AlreadyDefined@@Programs\endcsname{}%
\else\endinput\fi
%    \end{macrocode}
% \end{macro}%

% \subsection{Controlling program indentation}
%
% \begin{macro}{\ProgramIndent}
% \begin{macro}{\@@programindent}
%    \verb"\@@programindent" is the amount of program indentation for
%    the left margin of the text.
%    Initially, it is set to \verb"\z@"\ :
%    \begin{macrocode}
%<style>%% CONTROLLING PROGRAM INDENTATION
\newdimen\@@programindent
\@@programindent=\z@
%    \end{macrocode}
% \end{macro}
%
%    The \verb"\ProgramIndent" has the only effect to set the variable
%    of \verb"\@@programindent" to the value indicated by its
%    parameter: 
%    \begin{macrocode}
\def\ProgramIndent#1{\@@programindent=#1}
%    \end{macrocode}
% \end{macro}

% \subsection{Surrounding programs by rules}
%
% \begin{macro}{\ProgramSurround}
% \begin{macro}{\if@@surround}
%    By default, a program is printed as is, but it is possible to
%    indicate that it is going to be enclosed within two
%    \verb"\hrule":
%    \begin{macrocode}
%<style>%% SURROUNDING PROGRAMS BY RULES
\newif\if@@surround\@@surroundfalse
\def\ProgramSurround{\@@surroundtrue}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\@@progline}
% \begin{macro}{\@@noprogline}
% These two macros define the shape of the surrounding lines.
% The definition of \verb"\@@progline" is such that the surrounding
% lines lengths are always equal to the width of the current line
% (even if it is changed from one program to another).
%    \begin{macrocode}
\def\@@progline{\def\@@prgln{\rule{\linewidth}{0.1mm}}\@@prgln}
\def\@@noprogline{\rule{0pt}{0pt}}
%    \end{macrocode}
% \end{macro}
% \end{macro}

% \subsection{Line numbering}
%
% \begin{macro}{\@@defaultindent}
%    The purpose of this macro is to keep space enough for printing
%    the line numbers of the programs.
%    I have defined its length for make it easy printing long
%    programs (thousands of lines).
%    \begin{macrocode}
%<style>%% LINE NUMBERING
\newlength{\@@defaultindent}
\settowidth{\@@defaultindent}{{\tt{}12345}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\if@@resetlineno}
% \begin{macro}{\if@@unnumline}
% \begin{macro}{\if@@CurrentProgIsUnnumbered}
%    These three conditions serve to indicate the printing status of
%    the current program.
%    More precisely, \verb"\if@@resetlineno" is a boolean flag to
%    specify if line numbering must be reset for the next program.
%    It defaults to true.
%    \verb"\if@@unnumline" is a boolean flag to specify that the next
%    line to be printed is not to be numbered.
%    It defaults to false (i.e. every line is numbered, by default).
%    \verb"\if@@CurrentProgIsUnnumbered" is a global flag for the
%    program, that indicates if the program being printed is numbered
%    or not. 
%    It defaults to false (i.e. programs are numbered, by default).
%    \begin{macrocode}
\newif\if@@resetlineno \@@resetlinenotrue \newif\if@@unnumline
\@@unnumlinefalse
\newif\if@@CurrentProgIsUnnumbered \@@CurrentProgIsUnnumberedfalse
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}

% \begin{macro}{\NoResetProgramCounter}
%    This macro is provided to the user to specify that the first line
%    number of the next program must be equal to the last line number
%    of the previous program.
%    More precisely, lines for the next program will be numbered from
%    \verb"\@@lineno + 1".
%    \begin{macrocode}
\def\NoResetProgramCounter{\@@resetlinenofalse}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\UnnumLine}
%    As said in section~\ref{user:unnumline}, this macro must appear
%    at the end of a program line.
%    Its effect is to set on the boolean flag \verb"\@@unnumlinetrue"
%    to prevent the macro \verb"\@@xnewprog" from numbering the next line
%    of the program.
%    The ``\verb"\ "'' that appears ahead of the macro serves to make
%    the command valid even if issued on an empty line.
%    \begin{macrocode}
\def\UnnumLine{\ \@@unnumlinetrue}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{@@lineno}
% \begin{macro}{\SetProgramCounter}
%    This is the definition of a counter for the program lines.
%    Once the macro \verb"\SetProgramCounter" called, its effect is to
%    make lines starting from the value indicated as param \verb"#1".
%    Of course, if the user issues a \verb"\SetProgramCounter"
%    command, it is implicitly assumed that he wants the lines to be
%    numbered.
%    That is why the condition \verb"\if@@resetlineno" is set to
%    false.
%    \begin{macrocode}
\newcounter{@@lineno}\setcounter{@@lineno}{1}
\def\SetProgramCounter#1{\setcounter{@@lineno}{#1}\@@resetlinenofalse}
%    \end{macrocode}
% \end{macro}
% \end{macro}

% \begin{macro}{@@dummylineno}
%    This little trick is an internal line counter for the unnumbered
%    programs.
%    It is necessary for making it possible to put labels on
%    lines in unnumbered programs, and refer to them.
%    Internal numbering of unnumbered programs always begins at~$1$.
%    \begin{macrocode}
\newcounter{@@dummylineno}\setcounter{@@dummylineno}{1}
%    \end{macrocode}
% \end{macro}

% \begin{macro}{\LeftMarginNumberLine}
% \begin{macro}{\RightMarginNumberLine}
% \begin{macro}{\BothMarginsNumberLine}
% \begin{macro}{\InBodyLeftNumberLine}
% \begin{macro}{\@@PlaceOfNumbers}
%    The first four commands are provided to the user for
%    indicating line number placement.
%    They have the only effect to change the value of
%    \verb"\@@PlaceOfNumbers" which is an internal value whose purpose
%    is to define where the line numbers are to appear on the text.
%    It is used by the macro \verb"\@@xnewprog".
%    \begin{macrocode}
\def\LeftMarginNumberLine{\let\@@PlaceOfNumbers\@@LeftMarginNumberLine}
\def\RightMarginNumberLine{\let\@@PlaceOfNumbers\@@RightMarginNumberLine}
\def\BothMarginsNumberLine{\let\@@PlaceOfNumbers\@@BothMarginsNumberLine}
\def\InBodyLeftNumberLine{\let\@@PlaceOfNumbers\@@InBodyLeftNumberLine}
\def\@@LeftMarginNumberLine{0} \def\@@RightMarginNumberLine{1}
\def\@@BothMarginsNumberLine{2}
\def\@@InBodyLeftNumberLine{3}
%    \end{macrocode}
%
%    For more readability, a 
%    \begin{macrocode}
\LeftMarginNumberLine
%    \end{macrocode}
%    command is issued, in order to initialize
%    \verb"\@@PlaceOfNumbers".
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}

% \subsection{Program default fonts}
%
% \begin{macro}{\@@DefaultProgramFont}
%    Text of programs is usually typed with a teletype font (like in
%    the \verb"verbatim" environment).
%    Default font printing is controlled by this counter.
%    Its value is used in the macro \verb"\@@astyped" described
%    elsewhere in this document.
%    \begin{macrocode}
%<style>%% PROGRAM DEFAULT FONTS
\def\@@DefaultProgramFont{0}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ttProgram}
% \begin{macro}{\rmProgram}
% \begin{macro}{\emProgram}
% \begin{macro}{\ProgramDefaultFont}
%    These commands allow the user to change the default font of the
%    programs. This is performed by redefining the running macros
%    \verb"\@@astyped" and \verb"\@@program".
%    \begin{macrocode}
\def\ttProgram{\def\@@DefaultProgramFont{0}\def@@astyped\def@@program}
\def\rmProgram{\def\@@DefaultProgramFont{1}\def@@astyped\def@@program}
\def\emProgram{\def\@@DefaultProgramFont{2}\def@@astyped\def@@program}
\def\ProgramDefaultFont{\ttProgram}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}

% \subsection{The real environment}
%
% \begin{macro}{\@@vobeyspaces}
% \begin{macro}{\@@xobeysp}
%    We first begin by redefining the space character that will be
%    used in the \verb"@@astyped" environment.
%    It is important to let a space after the occurrence of
%    \verb"\let" below, since at this point space characters are
%    become active.
%    If \verb"\@@xobeysp" had been issued on a different line, a risk
%    would have existed to have space redefined to empty space.
%    \begin{macrocode}
%<style>%% THE REAL ENVIRONMENT
{\catcode`\ =\active\gdef\@@vobeyspaces{\catcode`\ \active\let \@@xobeysp}}
\def\@@xobeysp{\leavevmode\penalty10000\ }
%    \end{macrocode}
%  \end{macro}
%  \end{macro}
%
% \begin{macro}{\def@@astyped}
% \begin{macro}{\@@astyped}
% \begin{macro}{\end@@astyped}
%    Then, we define the \verb"@@astyped" environment by the means of
%    its two macros \verb"\@@astyped" and \verb"\end@@astyped".
%    It is very strongly related to the \verb"astyped"
%    environment~\cite{astyped88}. However, rather than directly using
%    the \verb"astyped" environment, I have prefered to make the
%    {\em{}programs.sty\/} style file independent.
%
%    \verb"\def@@astyped" causes the \verb"@@astyped" environment
%    to be defined. This is because we want a different
%    \verb"@@astyped" environment to be defined for every new
%    \verb"program" environment, because fonts may have changed, hence
%    spacing may differ from one environment to another one. 
%    \begin{macrocode}
\def\def@@astyped{%
    \def\@@astyped{%
        \partopsep\z@%
        \topsep\z@%
        \trivlist \item[]%
            \leftskip\@totalleftmargin%
            \rightskip\z@%
            \parindent\z@%
            \parfillskip\@flushglue%
            \parskip\z@%
            \@tempswafalse%
            \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par}%
            \obeylines%
            \ifcase\@@DefaultProgramFont \tt\or \rm\or \em\else \tt\fi
            \catcode``=13 \@noligs%
            \let\do\@makeother \do\ \do\^^K\do\^^A%
            \frenchspacing\@@vobeyspaces%
            \noindent\hspace{\parindent}%
            \if@@surround\@@progline\else\@@noprogline\fi%
            \nopagebreak%
            }
    \def\end@@astyped{%
            \nopagebreak%
            \noindent\hspace{\parindent}%
            \if@@surround\@@progline\else\@@noprogline\fi%
        \endtrivlist%
        }
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}

% \subsection{Meta-commands for defining new program environments}
%
% \begin{macro}{\NewProgram}
% \begin{macro}{\RenewProgram}
% \begin{macro}{\@@newprog}
%    The command \verb"\NewProgram" (resp. \verb"\RenewProgram") can
%    be used to define (resp. redefine) new program environments. The
%    first parameter is the name of a program environment to be
%    created, and the second one is the name of a size for the police
%    (e.g. {\em{}smallsize}, {\em{}tiny}, {\em{}etc}.).
%    See section~\ref{user:meta-commands} for an example.
%
%    I have defined \verb"\RenewProgram" same as \verb"\NewProgram"
%    because I am too lazzy, but it should test if the environment to
%    be redefined has been previously defined.
%    \begin{macrocode}
%<style>%% META-COMMANDS FOR DEFINING NEW PROGRAM ENVIRONMENTS
\def\NewProgram#1#2{\@@newprog{#1}{#2}}
\def\RenewProgram#1#2{\@@newprog{#1}{#2}}
\def\@@newprog#1#2{%
    \@namedef{#1}{%
        \begingroup\def\@@tempa{\@nameuse{#2}}%
        \def\@@tempb{\baselinestretch}\def\baselinestretch{1}%
        \@ifundefined{@@tempa}{\normalsize}{\@@tempa}%
        \def@@astyped\@@astyped%
        \@ifnextchar[{\@@xnewprog}{\@@xnewprog[\@@programindent]}%
    }%
    \@namedef{end#1}{%
        \everypar{}%
%    \end{macrocode}
%    The little trick below is necessary because \verb"\@@lineno" is
%    incremented by 1 at the beginning of every \verb"program"
%    environment (see \verb"\@@xnewprog" below). 
%    Hence, when \verb"\NoResetProgramCounter" is used, the line
%    numbers of the last line of the previous program and the first
%    line of the new program would be the same.
%    The condition below avoids this drawback.
%    \begin{macrocode}
        \if@@CurrentProgIsUnnumbered \relax%
        \else%
                \addtocounter{@@lineno}{1}%
        \fi%
        %
        \end@@astyped%
        \let\baselinestretch=\@@tempb\endgroup%
        \global\@@resetlinenotrue%
        \global\ProgramDefaultFont%
        \global\@@surroundfalse%
    }%
%    \end{macrocode}
%    At last, if actual value of parameter \verb+#1+ is \verb+FOO+, we
%    define two file inclusion commands: \verb+\fFOO+ and \verb+lFOO+
%    for inclusion of unnumbered and numbered programs
%    (see section~\ref{user:program-environments}).
%    \begin{macrocode}
    \@namedef{f#1}##1{\@nameuse{#1}*\par\input##1\@nameuse{end#1}}%
    \@namedef{l#1}##1{\@nameuse{#1}\par\input##1\@nameuse{end#1}}%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}

% \begin{macro}{\@@numlinelength}
% \begin{macro}{\@@xnewprog}
%    The macro \verb"\@@xnewprog" performs the printing of the lines.
%    \begin{macrocode}
\newlength{\@@numlinelength}
\def\@@xnewprog[#1]{%
%    \end{macrocode}
%    If the first character is the symbol \verb+*+ then no line
%    numbers are printed.
%    \begin{macrocode}
        \@ifstar{%
          \@@CurrentProgIsUnnumberedtrue
            \setcounter{@@dummylineno}{0}%
            \leavevmode%
            \everypar{%
                \refstepcounter{@@dummylineno}%
                \@@unnumlinefalse%
                \noindent\hspace{#1}}%
        }%
%    \end{macrocode}
%    Otherwise, this is the normal case:
%    \begin{macrocode}
        {%
          \@@CurrentProgIsUnnumberedfalse
          \if@@resetlineno%
                  \setcounter{@@lineno}{0}%
          \else%
                  \addtocounter{@@lineno}{-1}%
          \fi%
          \leavevmode%
          \everypar{%
              \if@@unnumline%
%    \end{macrocode}
%    I decided to make a default indentation on the left side of the
%    unnumbered program if the user has requested a numbering on the
%    left side of the page for the numbered programs.
%    This is to keep an homogeneous layout.
%    \begin{macrocode}
                  \ifx \@@PlaceOfNumbers\@@InBodyLeftNumberLine%
                      \hspace{\@@defaultindent}%
                      \rule{0pt}{0pt}%
                  \fi
%    \end{macrocode}
%    Otherwise, for numbered programs, we begin by incrementing the
%    line counter and making it possible a reference to the line
%    number to be done (see the {\em{}latex.tex\/}\footnote{This file
%    is part of the \LaTeX\ distribution.} file for explanations on
%    \verb"\refstepcounter"). 
%    \begin{macrocode}
              \else%
                  \refstepcounter{@@lineno}%
%    \end{macrocode}
%    Then, we look at the placement of the line numbers, which is
%    controlled by the variable \verb"\@@PlaceOfNumbers":
%    \begin{macrocode}
                  \ifx \@@PlaceOfNumbers\@@LeftMarginNumberLine%
                      \llap{{\rm\the@@lineno\ \ }}%
                  \else \ifx \@@PlaceOfNumbers\@@RightMarginNumberLine%
                      \noindent\hspace{\columnwidth}%
                      \rlap{{\rm\ \ \the@@lineno}}%
                      \noindent\hspace{-\columnwidth}%
                  \else \ifx \@@PlaceOfNumbers\@@BothMarginsNumberLine%
                      \noindent\hspace{\columnwidth}%
                      \rlap{{\rm\ \ \the@@lineno}}%
                      \noindent\hspace{-\columnwidth}%
                      \llap{{\rm\the@@lineno\ \ }}%
                  \else \ifx \@@PlaceOfNumbers\@@InBodyLeftNumberLine%
                      \hspace{\@@defaultindent}%
                      \rule{0pt}{0pt}%
                      \llap{{\rm\the@@lineno\ \ }}%
                  \else
%    \end{macrocode}
%    Otherwise (default case), numbers are printed on the left margin
%    of the page:
%    \begin{macrocode}
                       \llap{{\rm\the@@lineno\ \ }}%
                  \fi\fi\fi\fi
%    \end{macrocode}
%    Then we reset the boolean flag
%    {\makeatletter\verb"\@@unnumlinefalse"} in order 
%    to make the next line to be numbered (of course, this is useful
%    only if the program is numbered), and we indent the program
%    according to what was requested by the user.
%    \begin{macrocode}
              \fi\@@unnumlinefalse%
              \noindent\hspace{#1}%
        }%
    }%
}
%    \end{macrocode}
% \end{macro}
% \end{macro}

% \subsection{Predefined environments and commands}
%
% \begin{macro}{\def@@program}
% \begin{macro}{\ProgramDefaultFont}
%    This command serves to define the environments and commands
%    described in section~\ref{user:program-environments}.
% It is invoked by the \verb"\ProgramDefaultFont" command.
%    \begin{macrocode}
%<style>%% PREDEFINED ENVIRONMENTS AND COMMANDS
\def\def@@program{%
  \NewProgram{program}{normalsize}
  \NewProgram{programl}{large}
  \NewProgram{programL}{Large}
  \NewProgram{programs}{small}
  \NewProgram{programf}{footnotesize}
  \NewProgram{programsc}{scriptsize}
  \NewProgram{programt}{tiny}
}
%    \end{macrocode}
%    Then we terminate by instructing \LaTeX\ to switch to the default
%    font for typing programs (which, in the current implementation is
%    \verb+\tt+ in order to have a behaviour consistent with the
%    \verb+verbatim+ environment).
%    \begin{macrocode}
\ProgramDefaultFont
%    \end{macrocode}
% \end{macro}
% \end{macro}

% \subsection{Old macro names present here for compatibility reasons}
%
% \begin{macro}{\newprogram}
% \begin{macro}{\renewprogram}
% \begin{macro}{\noresetprogramcounter}
% \begin{macro}{\programindent}
% \begin{macro}{\programsurround}
% \begin{macro}{\setprogramcounter}
% \begin{macro}{\unnumline}
% \begin{macro}{\BothMarginNumberLine}
%    These macro names are simple redefinitions of macros defined
%    elsewhere in this document style.
%    They are present here because they had been defined in previous
%    versions of this style. 
%    \begin{macrocode}
%<style>%% OLD MACRO NAMES PRESENT HERE FOR COMPATIBILITY REASONS
\let\newprogram=\NewProgram \let\renewprogram=\RenewProgram
\let\noresetprogramcounter=\NoResetProgramCounter
\let\programindent=\ProgramIndent
\let\programsurround=\ProgramSurround
\let\setprogramcounter=\SetProgramCounter \let\unnumline=\UnnumLine
\let\BothMarginNumberLine=\BothMarginsNumberLine
%    \end{macrocode}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}
% \end{macro}

%    \begin{macrocode}
%</style>
%    \end{macrocode}

% ^^A The four commented lines below may be used to output an index on
% ^^A a page layout greater than the one used till now.
% ^^A -----
% ^^A \newpage
% ^^A \setlength{\oddsidemargin}{0pt}
% ^^A \setlength\textwidth{15cm}
% ^^A \normalsize
% ^^A -----
%
% \IndexPrologue{%
%       \section*{Index}%
%       \markboth{Index}{Index}%
%       {\it{}The italic numbers denote the pages where the
%       corresponding entry is described,
%       numbers underlined point to the definition,
%       all others indicate the places where it is used
%       (ie. the line numbers where it appears).
%       }}
% \Finale
% \newpage
% \PrintIndex \PrintChanges