The “programs.sty” style file^{∗}

Miguel Alabau

LaBRI, Université Bordeaux I (France)

e-mail: Miguel.Alabau@labri.u-bordeaux.fr

March 6, 1996

Abstract

This style file contains a set of definitions that allow a fairly easy prettyprinting of programs. In particular, text alignement is obtained by simply typing space characters. Emphasized characters, mathematical symbols and commands are directly taken into account.

Contents

1 Introduction 1

2 User’s Manual 2

2.1 Environments for typesetting

programs . . . . . . . . . . . . . 2 2.2 Global commands . . . . . . . . . 3 2.3 Commands to be used before a

program environment . . . . . . . 4 2.4 Commands to be used inside a

program environment . . . . . . . 4 2.5 Meta-Commands: how to define

new program environments … 4 2.6 The Index File . . . . . . . . . . 5 2.7 The Driver File . . . . . . . . . . 5 2.8 Extracting the documents in-

cluded in the file programs.dtx . 6

3 Description of Macros 7 3.1 Controlling program indentation 7 3.2 Surrounding programs by rules . 8 3.3 Line numbering . . . . . . . . . . 8 3.4 Program default fonts . . . . . . 9 3.5 The real environment . . . . . . . 9 3.6 Meta-commands for defining new

program environments . . . . . . 10 3.7 Predefined environments and

commands . . . . . . . . . . . . . 12 3.8 Old macro names present here for

compatibility reasons . . . . . . . 13

1 Introduction

The L^{A}TEX 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. L^{A}TEX provides the 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 programs.sty provides different environments and commands for typesetting programs. Spaces are interpreted as in the verbatim environment, avoiding the user to type \= and \> 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). For instance, you may type something like

\begin{programf}
function sqrt(x: integer): integer;
       (* sqrt(x)  = $\sqrt{x}$ *)
function pow(x,y: real): real;

∗This file has version number v1.0 dated 95/04/01. The documentation was last revised on 96/01/31.

          (* pow(x,y) = $x^y$ *)
 \end{programf}

which leads to the following output

    1 function sqrt(x: integer): integer;
    2  (* sqrt(x)  = \sqrt{x} *)
    3 function pow(x,y: real): real;
    4  (* pow(x,y) = x^{y} *)

5

It is also possible to typeset the same program in a smaller font, enclosed within two horizontal lines, and with the lines unnumbered.

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

yielding to the following output:

                                                                           function sqrt(x: integer): integer;
                                                                                    (* sqrt(x)  = \sqrt{x} *)
                                                                           function pow(x,y: real): real;
                                                                                    (* pow(x,y) = xy *)

A set of other options is provided, together with two file inclusion capabilities.

2 User’s Manual

In this section, we describe the environments and commands provided by this style file (section 2.1). We indicate also three sets of control commands:

• Global commands, i.e. global switches for the commands/environments of section 2.1 (section 2.2).

• Commands whose scope is the next program only (section 2.3).

• Commands that are used within a program environment (section 2.4).

The user is provided with two 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 programs.dtx.

2.1 Environments for typesetting programs

The following environments are provided, every one of them corresponding to one of the L^{A}TEX predefined font sizes:

environments  sizes
program  normalsize
programl  large
programL  Large
programs  small
programf  footnotesize
programsc  scriptsize
programt  tiny

These environments are to be used like the verbatim environment. However they work differently, since the usual L^{A}TEX 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 * just after the beginning of the environment. For instance:

 \begin{programL}*
     <unnumbered text>
 \end{programL}

Program indentation obey to the variable \ProgramIndent (see section 2.2). 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. For instance, an unnumbered program indented 2cm from the left margin of the text is:

 \begin{programL}[2cm]*
     <unnumbered text>
 \end{programL}

There is also a set of inclusion commands similar to the \verbatimfile (verbatim inclusion of a file) and \verbatimlisting (verbatim inclusion of a file, with numbered lines) commands of the “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, etc.).

program inclusion commands

unnumbered programs numbered programs  sizes
\fprogram  \lprogram  normalsize
\fprograml  \lprograml  large
\fprogramL  \lProgramL  Large
\fprograms  \lprograms  small
\fprogramf  \lprogramf  footnotesize
\fprogramsc  \lprogramsc  scriptsize
\fprogramt  \lprogramt  tiny

We describe in section 2.5 how to define new program environments.

2.2 Global commands

\ProgramIndent This command serves to control the default indentation of the programs. It is used as described below:

    \ProgramIndent{1cm}

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 \ProgramIndent command. Default is no indentation at all.

\programindent This macro redefines the macro \ProgramIndent. It is present here for compatibility

with previous versions of the programs.sty style.

\LeftMarginNumberLine These four commands are self-explanatory. They allow the user to specify that line

\RightMarginNumberLine
\BothMarginsNumberLine
\InBodyLeftNumberLine

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 (\LeftMarginNumberLine).

\BothMarginNumberLine This macro redefines the macro \BothMarginsNumberLine. It is present here for

compatibility with previous versions of the programs.sty style.

\ttProgram Text of programs are usually typed with a teletype font (like in the verbatim envi-

\rmProgram
\emProgram

ronment). The user has the ability to change this default font to one of the three predefined fonts: teletype, roman, italicized roman.

\ProgramDefaultFont The command \ProgramDefaultFont serves to reset the printing to the default font.

2.3 Commands to be used before a program environment

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

\programsurround This macro redefines the macro \ProgramSurround. It is present here for compatibility

with previous versions of the programs.sty style.

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

     \SetProgramCounter{6}

In this example, the lines of the next program will start from 6.

\setprogramcounter This macro redefines the macro \SetProgramCounter. It is present here for compat-

ibility with previous versions of the programs.sty style.

\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 \NoResetProgramCounter before the next program. This command has no effect if issued before the first program.

\noresetprogramcounter This macro redefines the macro \NoResetProgramCounter. It is present here for

compatibility with previous versions of the programs.sty style.

2.4 Commands to be used inside a program environment

\UnnumLine This command is to be used only 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.

\unnumline This macro redefines the macro \UnnumLine. It is present here for compatibility with previous versions of the programs.sty style.

2.5 Meta-Commands: how to define new program environments

\NewProgram The \NewProgram command serves to define a new program environment. The \RenewProgram \RenewProgram command is to be used for redefining already defined program en-

vironments. These commands must be used as below:

\NewProgram{name}{font name} \RenewProgram{name}{font name}

The command \NewProgram defines one environment and two commands. Let us assume that the user issues the following command:

     \NewProgram{LittleProg}{smallsize}

then an environment called LittleProg will be generated for direct typesetting of programs, and two commands will be created: fLittleProg and lLittleProg for inclusion of unnumbered (resp. numbered) text.

\newprogram These two macros are old names present here for compatibility with previous versions

\renewprogram of the programs.sty style. \newprogram redefines \NewProgram, and \renewprogram
redefines \RenewProgram.

2.6 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 programs.ist, then the following command must be run and then another compilation of the current file:

1 ⟨index⟩

 2 ⟨index⟩%% -----------------------------------------------------------
 3 ⟨index⟩%% Assuming this file is named "programs.ist" (after being
 4 ⟨index⟩%% generated from "programs.dtx" by running "latex docstrip"),
 5 ⟨index⟩%% the following command will produce a well formated index:

6 ⟨index⟩%%

 7 ⟨index⟩%%                  makeindex -s programs.ist programs.idx
 8 ⟨index⟩%% -----------------------------------------------------------

9 ⟨index⟩

Another possibility is to set the environment variable INDEXSTYLE to a directory name where the “.ist” files (index format files) may be found. A possible index file is given below^{1}:

10 ⟨index⟩actual '='

11 ⟨index⟩quote '!' 12 ⟨index⟩level '>' 13 ⟨index⟩preamble

14 ⟨index⟩"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n"
15 ⟨index⟩postamble
16 ⟨index⟩"\n\n \\end{theindex}\n"
17 ⟨index⟩item_x1   "\\efill \n \\subitem "
18 ⟨index⟩item_x2   "\\efill \n \\subsubitem "
19 ⟨index⟩delim_0   "\\pfill "
20 ⟨index⟩delim_1   "\\pfill "
21 ⟨index⟩delim_2   "\\pfill "
22 ⟨index⟩% The next lines will produce some warnings when
23 ⟨index⟩% running Makeindex as they try to cover two different
24 ⟨index⟩% versions of the program:
25 ⟨index⟩lethead_prefix   "{\\bf\\hfil "
26 ⟨index⟩lethead_suffix   "\\hfil}\\nopagebreak\n"
27 ⟨index⟩lethead_flag       1
28 ⟨index⟩heading_prefix   "{\\bf\\hfil "
29 ⟨index⟩heading_suffix   "\\hfil}\\nopagebreak\n"
30 ⟨index⟩headings_flag       1

2.7 The Driver File

There is also a driver file, called programs.drv, that is included in the distribution. It is devoted to control the latex compilation of the documentation. Its code is given below.

31 ⟨∗driver⟩

32 \newif\ifnoprogsfile
33 \openin1 programs.sty
34 \ifeof1 \noprogsfiletrue\else\noprogsfilefalse\fi\closein1
35 \ifnoprogsfile
36  \typeout{*******************************************************}
37  \typeout{To get a more complete documentation, you should}
38  \typeout{copy the current file into 'programs.sty'}
39  \typeout{*******************************************************}

1It can be generated by invoquing the compilation of “docstrip” with the “index” option.

40 \fi
41 \ifnoprogsfile
42  \documentclass{ltxdoc}
43 \else
44  \documentclass{ltxdoc}
45  \usepackage{programs}
46 \fi
47 \MakePercentIgnore%

48 %

49 \setlength{\textwidth}{31pc}%
50 \setlength{\textheight}{54pc}%
51 \setlength{\parindent}{0pt}%
52 \setlength{\parskip}{2pt plus 1pt minus 1pt}%
53 \setlength{\oddsidemargin}{8pc}%
54 \setlength{\marginparwidth}{8pc}%
55 \setlength{\topmargin}{-2.5pc}%
56 \setlength{\headsep}{20pt}%
57 \setlength{\columnsep}{1.5pc}%
58 \setlength{\columnwidth}{18.75pc}%
59 %%
60 \setcounter{IndexColumns}{2}%
61 \EnableCrossrefs%
62 \RecordChanges
63 \CodelineIndex
64 %\OldMakeindex     % use if your MakeIndex is pre-v2.9%
65 \begin{document}%
66  \DocInput{programs.dtx}
67 \end{document}

68 ⟨/driver⟩

2.8 Extracting the documents included in the file programs.dtx

There are three documents included in the programs.dtx file: the style file (programs.sty), the index style file for printing a cross-referenced document (programs.ist), and the driver file for printing the document: programs.drv. For file extraction it is necessary to use the docstrip utility, which is part of the doc distribution [3]. Normally, a file docstrip.tex should exist on the L^{A}TEX style files directory. Extraction is performed by typing:

    latex docstrip

This is an interactive program, and the dialogue for generating the style file should be:

    **********************************************************
    * 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
    ****************************************************

For generating the index file it suffices to rerun the 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”.

The three files may be produced in a single pass, by simply latexing the file programs.ins which goes along with the file programs.dtx.

Generation of the documentation is then simply performed as follows:

    latex programs.drv
    latex programs.drv
    latex programs.drv
    makeindex  -s programs.ist programs.idx
    latex programs.drv

69 ⟨∗style⟩

3 Description of Macros

\AlreadyDefined@@Programs This macro can be tested by any style file to know if the file “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 “programs.sty” style file is included all of its body will be included; the second time, the body will not be included.

70 \expandafter\ifx\csname AlreadyDefined@@Programs\endcsname\relax%
71 \expandafter\def\csname AlreadyDefined@@Programs\endcsname{}%
72 \else\endinput\fi

3.1 Controlling program indentation

\ProgramIndent \@@programindent \@@programindent is the amount of program indentation for the left margin of the text. Initially, it is set to \z@ :

73 ⟨style⟩%% CONTROLLING PROGRAM INDENTATION
74 \newdimen\@@programindent
75 \@@programindent=\z@

The \ProgramIndent has the only effect to set the variable of \@@programindent to the value indicated by its parameter:

76 \def\ProgramIndent#1{\@@programindent=#1}

3.2 Surrounding programs by rules

\ProgramSurround \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 \hrule:

77 ⟨style⟩%% SURROUNDING PROGRAMS BY RULES
78 \newif\if@@surround\@@surroundfalse
79 \def\ProgramSurround{\@@surroundtrue}

\@@progline \@@noprogline These two macros define the shape of the surrounding lines. The definition of \@@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).

80 \def\@@progline{\def\@@prgln{\rule{\linewidth}{0.1mm}}\@@prgln}
81 \def\@@noprogline{\rule{0pt}{0pt}}

3.3 Line numbering

\@@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).

82 ⟨style⟩%% LINE NUMBERING
83 \newlength{\@@defaultindent}
84 \settowidth{\@@defaultindent}{{\tt{}12345}}

\if@@resetlineno \if@@unnumline \if@@CurrentProgIsUnnumbered These three conditions serve to indicate the printing status of the current program. More precisely, \if@@resetlineno is a boolean flag to specify if line numbering must be reset for the next program. It defaults to true. \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). \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).

85 \newif\if@@resetlineno \@@resetlinenotrue \newif\if@@unnumline
86 \@@unnumlinefalse
87 \newif\if@@CurrentProgIsUnnumbered \@@CurrentProgIsUnnumberedfalse

\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 \@@lineno + 1.

88 \def\NoResetProgramCounter{\@@resetlinenofalse}

\UnnumLine As said in section 2.4, this macro must appear at the end of a program line. Its effect is to set on the boolean flag \@@unnumlinetrue to prevent the macro \@@xnewprog from numbering the next line of the program. The “\ ” that appears ahead of the macro serves to make the command valid even if issued on an empty line.

89 \def\UnnumLine{\ \@@unnumlinetrue}

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

90 \newcounter{@@lineno}\setcounter{@@lineno}{1}
91 \def\SetProgramCounter#1{\setcounter{@@lineno}{#1}\@@resetlinenofalse}

@@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.

92 \newcounter{@@dummylineno}\setcounter{@@dummylineno}{1}
\LeftMarginNumberLine \RightMarginNumberLine \BothMarginsNumberLine \InBodyLeftNumberLine \@@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 \@@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 \@@xnewprog.

93 \def\LeftMarginNumberLine{\let\@@PlaceOfNumbers\@@LeftMarginNumberLine}
94 \def\RightMarginNumberLine{\let\@@PlaceOfNumbers\@@RightMarginNumberLine}
95 \def\BothMarginsNumberLine{\let\@@PlaceOfNumbers\@@BothMarginsNumberLine}
96 \def\InBodyLeftNumberLine{\let\@@PlaceOfNumbers\@@InBodyLeftNumberLine}
97 \def\@@LeftMarginNumberLine{0} \def\@@RightMarginNumberLine{1}
98 \def\@@BothMarginsNumberLine{2}
99 \def\@@InBodyLeftNumberLine{3}

For more readability, a

100 \LeftMarginNumberLine

command is issued, in order to initialize \@@PlaceOfNumbers.

3.4 Program default fonts

\@@DefaultProgramFont Text of programs is usually typed with a teletype font (like in the verbatim environment). Default font printing is controlled by this counter. Its value is used in the macro \@@astyped described elsewhere in this document.

101 ⟨style⟩%% PROGRAM DEFAULT FONTS
102 \def\@@DefaultProgramFont{0}

\ttProgram \rmProgram \emProgram \ProgramDefaultFont These commands allow the user to change the default font of the programs. This is performed by redefining the running macros \@@astyped and \@@program.

103 \def\ttProgram{\def\@@DefaultProgramFont{0}\def@@astyped\def@@program}
104 \def\rmProgram{\def\@@DefaultProgramFont{1}\def@@astyped\def@@program}
105 \def\emProgram{\def\@@DefaultProgramFont{2}\def@@astyped\def@@program}
106 \def\ProgramDefaultFont{\ttProgram}

3.5 The real environment

\@@vobeyspaces \@@xobeysp We first begin by redefining the space character that will be used in the @@astyped environment. It is important to let a space after the occurrence of \let below, since at this point space characters are become active. If \@@xobeysp had been issued on a different line, a risk would have existed to have space redefined to empty space.

107 ⟨style⟩%% THE REAL ENVIRONMENT
108 {\catcode`\ =\active\gdef\@@vobeyspaces{\catcode`\ \active\let \@@xobeysp}}
109 \def\@@xobeysp{\leavevmode\penalty10000\ }

\def@@astyped \@@astyped \end@@astyped Then, we define the @@astyped environment by the means of its two macros \@@astyped and \end@@astyped. It is very strongly related to the astyped environment [?]. However, rather than directly using the astyped environment, I have prefered to make the programs.sty style file independent. \def@@astyped causes the @@astyped environment to be defined. This is because we want a different @@astyped environment to be defined for every new program environment, because fonts may have changed, hence spacing may differ from one environment to another one.

110 \def\def@@astyped{%
111  \def\@@astyped{%
112  \partopsep\z@%
113  \topsep\z@%
114  \trivlist \item[]%
115  \leftskip\@totalleftmargin%
116  \rightskip\z@%
117  \parindent\z@%
118  \parfillskip\@flushglue%
119  \parskip\z@%
120  \@tempswafalse%
121  \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par}%
122  \obeylines%
123  \ifcase\@@DefaultProgramFont \tt\or \rm\or \em\else \tt\fi
124  \catcode``=13 \@noligs%
125  \let\do\@makeother \do\ \do\^^K\do\^^A%
126  \frenchspacing\@@vobeyspaces%
127  \noindent\hspace{\parindent}%
128  \if@@surround\@@progline\else\@@noprogline\fi%
129  \nopagebreak%

130 }

131  \def\end@@astyped{%
132  \nopagebreak%
133  \noindent\hspace{\parindent}%
134  \if@@surround\@@progline\else\@@noprogline\fi%
135  \endtrivlist%

136 } 137 }

3.6 Meta-commands for defining new program environments

\NewProgram \RenewProgram \@@newprog The command \NewProgram (resp. \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. smallsize, tiny, etc.). See section 2.5 for an example. I have defined \RenewProgram same as \NewProgram because I am too lazzy, but it should test if the environment to be redefined has been previously defined.

138 ⟨style⟩%% META-COMMANDS FOR DEFINING NEW PROGRAM ENVIRONMENTS
139 \def\NewProgram#1#2{\@@newprog{#1}{#2}}
140 \def\RenewProgram#1#2{\@@newprog{#1}{#2}}
141 \def\@@newprog#1#2{%
142  \@namedef{#1}{%
143  \begingroup\def\@@tempa{\@nameuse{#2}}%
144  \def\@@tempb{\baselinestretch}\def\baselinestretch{1}%
145  \@ifundefined{@@tempa}{\normalsize}{\@@tempa}%
146  \def@@astyped\@@astyped%
147  \@ifnextchar[{\@@xnewprog}{\@@xnewprog[\@@programindent]}%

148 }%

149  \@namedef{end#1}{%
150  \everypar{}%

The little trick below is necessary because \@@lineno is incremented by 1 at the beginning of every program environment (see \@@xnewprog below). Hence, when \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.

151  \if@@CurrentProgIsUnnumbered \relax%
152  \else%
153  \addtocounter{@@lineno}{1}%
154  \fi%

155 %

156  \end@@astyped%
157  \let\baselinestretch=\@@tempb\endgroup%
158  \global\@@resetlinenotrue%
159  \global\ProgramDefaultFont%
160  \global\@@surroundfalse%

161 }%

At last, if actual value of parameter #1 is FOO, we define two file inclusion commands: \fFOO and lFOO for inclusion of unnumbered and numbered programs (see section 2.1).

162  \@namedef{f#1}##1{\@nameuse{#1}*\par\input##1\@nameuse{end#1}}%
163  \@namedef{l#1}##1{\@nameuse{#1}\par\input##1\@nameuse{end#1}}%

164 }

\@@numlinelength \@@xnewprog The macro \@@xnewprog performs the printing of the lines.
165 \newlength{\@@numlinelength}
166 \def\@@xnewprog[#1]{%

If the first character is the symbol * then no line numbers are printed.

167  \@ifstar{%
168  \@@CurrentProgIsUnnumberedtrue
169  \setcounter{@@dummylineno}{0}%
170  \leavevmode%
171  \everypar{%
172  \refstepcounter{@@dummylineno}%
173  \@@unnumlinefalse%
174  \noindent\hspace{#1}}%

175 }%

Otherwise, this is the normal case:

176 {%

177  \@@CurrentProgIsUnnumberedfalse
178  \if@@resetlineno%
179  \setcounter{@@lineno}{0}%
180  \else%
181  \addtocounter{@@lineno}{-1}%
182  \fi%
183  \leavevmode%
184  \everypar{%
185  \if@@unnumline%

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.

186  \ifx \@@PlaceOfNumbers\@@InBodyLeftNumberLine%
187  \hspace{\@@defaultindent}%
188  \rule{0pt}{0pt}%
189  \fi

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 latex.tex^{2} file for explanations on \refstepcounter).

2This file is part of the L^{A}TEX distribution.

190  \else%
191  \refstepcounter{@@lineno}%

Then, we look at the placement of the line numbers, which is controlled by the variable

 \@@PlaceOfNumbers:
192  \ifx \@@PlaceOfNumbers\@@LeftMarginNumberLine%
193  \llap{{\rm\the@@lineno\ \ }}%
194  \else \ifx \@@PlaceOfNumbers\@@RightMarginNumberLine%
195  \noindent\hspace{\columnwidth}%
196  \rlap{{\rm\ \ \the@@lineno}}%
197  \noindent\hspace{-\columnwidth}%
198  \else \ifx \@@PlaceOfNumbers\@@BothMarginsNumberLine%
199  \noindent\hspace{\columnwidth}%
200  \rlap{{\rm\ \ \the@@lineno}}%
201  \noindent\hspace{-\columnwidth}%
202  \llap{{\rm\the@@lineno\ \ }}%
203  \else \ifx \@@PlaceOfNumbers\@@InBodyLeftNumberLine%
204  \hspace{\@@defaultindent}%
205  \rule{0pt}{0pt}%
206  \llap{{\rm\the@@lineno\ \ }}%
207  \else

Otherwise (default case), numbers are printed on the left margin of the page:

208  \llap{{\rm\the@@lineno\ \ }}%
209  \fi\fi\fi\fi

Then we reset the boolean flag \@@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.

210  \fi\@@unnumlinefalse%
211  \noindent\hspace{#1}%

212 }% 213 }% 214 }

3.7 Predefined environments and commands

\def@@program \ProgramDefaultFont This command serves to define the environments and commands described in section 2.1. It is invoked by the \ProgramDefaultFont command.

215 ⟨style⟩%% PREDEFINED ENVIRONMENTS AND COMMANDS
216 \def\def@@program{%
217 \NewProgram{program}{normalsize}
218 \NewProgram{programl}{large}
219 \NewProgram{programL}{Large}
220 \NewProgram{programs}{small}
221 \NewProgram{programf}{footnotesize}
222 \NewProgram{programsc}{scriptsize}
223 \NewProgram{programt}{tiny}

224 }

Then we terminate by instructing L^{A}TEX to switch to the default font for typing programs (which, in the current implementation is \tt in order to have a behaviour consistent with the verbatim environment).

225 \ProgramDefaultFont

3.8 Old macro names present here for compatibility reasons

\newprogram \renewprogram \noresetprogramcounter \programindent \programsurround \setprogramcounter \unnumline \BothMarginNumberLine These macro names are simple redefinitions of macros defined elsewhere in this docu-

ment style. They are present here because they had been defined in previous versions of this style.

226 ⟨style⟩%% OLD MACRO NAMES PRESENT HERE FOR COMPATIBILITY REASONS
227 \let\newprogram=\NewProgram \let\renewprogram=\RenewProgram
228 \let\noresetprogramcounter=\NoResetProgramCounter
229 \let\programindent=\ProgramIndent
230 \let\programsurround=\ProgramSurround
231 \let\setprogramcounter=\SetProgramCounter \let\unnumline=\UnnumLine
232 \let\BothMarginNumberLine=\BothMarginsNumberLine

233 ⟨/style⟩

References

[1] D.E. Knuth. Computers & Typesetting (The TEXbook). Addison-Wesley, Vol. A, 1986.

[2] L. Lamport. L^{A}TEX: a Document Preparation System. Addison-Wesley Publishing Company, 1986.

[3] F. Mittelbach. The doc-option. TUGboat, Vol. 10(2), pp. 245–273, July 1989.

[4] F. Mittelbach, D. Duchier and J. Braams. docstrip.dtx . The file is part of the DOC package.

Index

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).

BothMarginNumberLine=  \subitem *+\BothMarginNumberLine+, \usage{3}, \main{226}
BothMarginsNumberLine=  \subitem *+\BothMarginsNumberLine+, \usage{3}, \main{93}, 232
CodelineIndex=  \subitem *+\CodelineIndex+, 63
columnsep=  \subitem *+\columnsep+, 57
DocInput=  \subitem *+\DocInput+, 66
emProgram=  \subitem *+\emProgram+, \usage{3}, \main{103}
EnableCrossrefs=  \subitem *+\EnableCrossrefs+, 61
headsep=  \subitem *+\headsep+, 56
ifnoprogsfile=  \subitem *+\ifnoprogsfile+, 32, 35, 41
InBodyLeftNumberLine=  \subitem *+\InBodyLeftNumberLine+, \usage{3}, \main{93}
LeftMarginNumberLine=  \subitem *+\LeftMarginNumberLine+, \usage{3}, \main{93}
MakePercentIgnore=  \subitem *+\MakePercentIgnore+, 47
marginparwidth=  \subitem *+\marginparwidth+, 54
NewProgram=  \subitem *+\NewProgram+, \usage{4}, \main{138}, 217--223, 227
newprogram=  \subitem *+\newprogram+, \usage{4}, \main{226}
noprogsfilefalse=  \subitem *+\noprogsfilefalse+, 34
noprogsfiletrue=  \subitem *+\noprogsfiletrue+, 34
NoResetProgramCounter=  \subitem *+\NoResetProgramCounter+, \usage{4}, \main{88}, 228
noresetprogramcounter=  \subitem *+\noresetprogramcounter+, \usage{4}, \main{226}

oddsidemargin=  \subitem *+\oddsidemargin+, 53
OldMakeindex=  \subitem *+\OldMakeindex+, 64
partopsep=  \subitem *+\partopsep+, 112
ProgramDefaultFont=  \subitem *+\ProgramDefaultFont+, \usage\{3\}, \main\{103\}, 159,\underline{215}
ProgramIndent=  \subitem *+\ProgramIndent+, \usage{3}, \main{73}, 229
programindent=  \subitem *+\programindent+, \usage{3}, \main{226}
ProgramSurround=  \subitem *+\ProgramSurround+, \usage{4}, \main{77}, 230
programsurround=  \subitem *+\programsurround+, \usage{4}, \main{226}
RecordChanges=  \subitem *+\RecordChanges+, 62
RenewProgram=  \subitem *+\RenewProgram+, \usage{4}, \main{138}, 227
renewprogram=  \subitem *+\renewprogram+, \usage{4}, \main{226}
RightMarginNumberLine=  \subitem *+\RightMarginNumberLine+, \usage{3}, \main{93}
rmProgram=  \subitem *+\rmProgram+, \usage{3}, \main{103}
SetProgramCounter=  \subitem *+\SetProgramCounter+, \usage{4}, \main{90}, 231
setprogramcounter=  \subitem *+\setprogramcounter+, \usage{4}, \main{226}
textheight=  \subitem *+\textheight+, 50
textwidth=  \subitem *+\textwidth+, 49
ttProgram=  \subitem *+\ttProgram+, \usage{3}, \main{103}
UnnumLine=  \subitem *+\UnnumLine+, \usage{4}, \main{89}, 231
unnumline=  \subitem *+\unnumline+, \usage{4}, \main{226}
usepackage=  \subitem *+\usepackage+, 45