% \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