% This is PROGLTX.DOC                      as of 25 May 90
%---------------------------------------------------------
% (c) 1989,1990 by J.Schrod. copy conditions see below

%
% Macro package for the documentation of programs
% LaTeX style option
% MAKEPROG is needed
%

%
% DATE     PERSON  REMARK
% 92-01-15 rlb           add newsloppy environment (based on comment by
%                   Frank Mittlebach. Don't force a \newpage in
%                   Chapters, Just put a bigger space there.
% 89-11-18 js         repaired the handling of `|' (verbatim and \index).
% 89-10-05 js       first version (for TeX89)
%

% author's current address:
%
%       Detig$\,\cdot\,$Schrod \TeX{}sys
%       Joachim Schrod
%       Kranichweg 1
%
%       D-6074 R\"odermark-Urberach
%       FR Germany
%
%       Tel. (+6074) 1617
%       Bitnet: XITIJSCH@DDATHD21



% documented with itself...
\documentstyle[progltx]{article}


%
%
% local macros
%

\let\mc=\small         % for names like GNU

\def\WEB{{\tt WEB\/}}
\def\GNU{{\mc GNU}}

%
%


\begin{document}


\title{
   Documenting programs in a \WEB{} style\\
   The {\tt progltx\/} style option
   }
\author{\sc Joachim Schrod}

\maketitle


\chap Introduction.

\WEB{} systems allow the documentation of programs by supporting the
separation in program fragments which can be collected and rearranged
afterwards.  This allows {\it top-down\/} programming as well as the
{\it bottom-up\/} design of programs.  Each program fragment can be
documented, usually with \TeX{}\@.  A disadvantadge is that \WEB{}
actually exists only for a few programming languages (Pascal, C,
Modula-2).  Besides, building up \WEB{} systems for ``exotic''
programming languages like \TeX{} is very difficult.

This macro package was built to allow good documentation for programs
in languages for which \WEB{} doesn't exist.  It separates a program
text in sections that can be documented.  All sections, collected
sequentially, will result in the complete program.  In every section
begin and end of the program part are marked with |\beginprog| and
|\endprog|, this program part will be formatted as it is input
(``verbatim'').

Originally these macros were written for the usage with Plain \TeX{}
resp.\ on top of the \WEB{} macro package |webmac.tex|. But often the
requirement has been told to me that a \LaTeX{} version would be
useful, too---well, here it is. But even with \LaTeX{} I have decided
that still |\beginprog| and |\endprog| must be used for the markup of
the program parts, not |\begin{prog}| or |\end{prog}| which would be
more ``\LaTeX{}-like.'' The reason behind this is that I didn't want
to maintain two versions of the {\mc MAKEPROG\/} processor---but {\mc
MAKEPROG\/} wants to see the non-\LaTeX{}-like macros. But everybody
is encouraged to change it by themselves (it is {\it very\/} easy).

The user of these macros may use the usual sectioning macros of
\LaTeX{} for structuring his documentation. Additionally we provide a
|progdoc|-compatible (i.e.\ \WEB{}-like) markup with the two macros
|\chap| and |\sect|.

In the documentation part of a section text pieces, e.g.\ names of
variables, can be inserted verbatim to demonstrate the connection to
the program text.  These parts are included in vertical bars
(`{\tt\vbar}') This makes this style option extremely useful if your
identifiers (or your file names) include characters which would be
special characters for \TeX{} otherwise.  (One example of these
program languages is \TeX{} itself, but just enclose the macro names
in vertical bars and {\tt \vbar|\relax|\vbar}.)

The macros |\makevertother| and |\makevertactive| are available to
activate and deactivate the special behaviour of the vertical bar but
these macros should be needed seldom because the usual cases as the
usage within |verbatim| and |tabular| environments or |\index| macros
etc.\ are handled.

If a vertical bar must be used in the original fashion you can use two
command sequences: |\origvert| holds the meaning of the vertical bar
at the time this macro file was read in and |\vbar| is the character
with the {\mc ASCII\/} code of the vertical bar (i.e.~|"EC|) in the
current font.

The new notion of |\verb| must not be used within parameters of
macros, e.g.\ in the argument of |\section| etc.---it will result in
an error message by \TeX{}\@.  Furthermore within the preamble of a
|tabular|, an |array| environment, or the |\multicolumn| command the
vertical bar has the same meaning as before.  (That means within
|@{|\ldots|}| it is an ordinary character and otherwise it specifies a
vertical rule between the columns.

This macro package does not offer the automatic creation of an index
because it is not known which syntactical tokens the language has that
should be mentioned in an index. But of course all \LaTeX{} stuff like
|\index|, |\tableofcontents|, etc.\ may be used.


\sect This program is free software; you can redistribute it and/or
modify it under the terms of the \GNU{} General Public License as
published by the Free Software Foundation; either version~1, or (at your
option) any later version.

This program is distributed in the hope that it will be useful, but
{\bf without any warranty\/}; without even the implied warranty of
{\bf merchantability\/} or {\bf fitness for a particular purpose}.  See
the \GNU{} General Public License for more details.

You should have received a copy of the \GNU{} General Public License
along with this program; if not, write to the Free Software Foundation,
Inc., 675~Mass Ave, Cambridge, MA~02139, USA.


\sect We have to realize three parts:  (1)~the formatting of rather
small verbatim texts in a line, (2)~the formatting of larger parts of
program and (3)~the document structuring elements for the separation
of the sections.

\begin{sloppypar}
Before we start we declare some shorthands for category codes. By
declaring the underscore~`(|_|)' as a letter we can use it in our
macros names. (I agree with D.~Knuth that
|\identifier_several_words_long| is more readable than
|\IdentifierSeveralWordsLong| and in every case better than
|\p@@@s|.) But as we have to restore the category codes at the end
of this macro file we store its former value in the control
sequence |\uscode|. This method is better than the usage of a
group because not all macros have to be defined global this way.
\end{sloppypar}

\beginprog
\chardef\escape=0
\chardef\open=1
\chardef\close=2
\chardef\letter=11
\chardef\other=12
%\chardef\active=13              % is defined in Plain already

\chardef\uscode=\catcode`\_

\catcode`\_=\letter
\endprog




\chap Local Verbatim Formatting.

The main point of every verbatim formatting is the switching of the
character codes of all characters that have a special \TeX{} meaning.
This can be done with the control sequence |\dospecials| that applies
the control sequence |\do| to all special characters.  Additionally,
every line is regarded as a paragraph without indentation.  Between
two paragraphs, i.e.\ between two lines, no extra space is set.
Finally all blanks and tabular characters shall be obeyed and the
inter word space after sentence terminators shall not be enlarged.
The activation of the tabular characters with |\obeytabs| is
equivalent to |\obeyspaces| in {\tt plain.tex}.

\begin{sl}
As a matter of fact, I would like to use the character set with the
extended {\mc ASCII} (like in\/ \WEB{}) for setting the verbatim texts
in monospace. But then I must code many\/ |\@getfont|'s\,\dots
\end{sl}

\beginprog
%\font\tentex=cmtex10           % typewriter extended ASCII 10pt
%\let\ttex=\tentex              % only with base size 10pt
\def\ttex{\tt}                  % as a substitute

\def\setup_verbatim{%
   \def\do##1{\catcode`##1\other}\dospecials
   \parskip\z@skip \parindent\z@
   \catcode`\`\active \@noligs
   \obeylines \@vobeyspaces \obeytabs \frenchspacing
   \ttex
   }

\let\tab=\space
\begingroup
   \catcode`\^^I=\active%       % Attention: no tabs!
   \gdef\obeytabs{\catcode`\^^I=\active\def^^I{\tab}}
   \global\let^^I=\tab%    % if an active tab appears in a \write
\endgroup
\endprog


\sect After having saved the old meaning of `{\tt\vbar}' in
|\origvert| and after declaring |\vbar| as a synonym for the character
that has the code of a vertical bar in the actual font, the vertical
bar can be made active.  Then we call |\setup_verbatim|.  But the
newline characters shall not be processed, they shall be regarded like
blank space.  This can be reached by defining |\par| as |\space|.

The next vertical bar in the input closes the group which becomes an
(unbreakable) |\hbox| then.  The old meanings of the special
characters and of the vertical bar are restored and \TeX{} is in
normal (horizontal) mode again.

\beginprog
\let\origvert=|
\chardef\vbar=`\|

\def\makebaractive{\catcode`\|\active}
\def\makebarother{\catcode`\|\other}
\makebaractive

\def|{%
   \leavevmode
   \hbox\bgroup
      \let\par\space \setup_verbatim
      \let|\egroup
   }
\endprog


\sect A problem with this definition of the vertical bar is that
the bar is not a normal character any more but there exists situations
where the \LaTeX{} macros assumes this:
%
\begin{itemize}

\item In a |verbatim| environment a vertical bar must be typeset if it
occurs in the input.

\item In a |tabular| or an |array| environment a vertical bar is used
to denote rules between columns in the table. These environments must
be started with a parameter which is a ``preamble,'' the same preamble
construction is used to specify the format of multi-column entries.

\item In an output of an index entry the vertical bar must not result
in an error message. Usually index entries are typeset in a seperate
\TeX{} run where |idverb| is not used as a style option and the
vertical bar is therefore useful. This is no problem in section
headings or captions etc. Because they take their argument as a
parameter in every case the vertical bar can never be used there. But
|\origvert| resp.\ |\vbar| may be used there.

\end{itemize}
%
In the next sections we handle each of these problems.


\sect Before we start a |verbatim| environment we just redefine the
vertical bar as an ordinary character. Because this is within the
environment grouping the end of the environment will reestablish the
special meaning.

\beginprog
\let\@@verbatim=\@verbatim
\def\@verbatim{%
   \makebarother
   \@@verbatim
   }
\endprog


\sect Special care is needed in the |tabular| and the |array|
environment.  Both environments are begun by one macro (|\@tabarray|),
we redefine it so that the bar can be used in the preamble
specification.  The same problem occurs in |\multicolumn|, it is
solved the same way.  After the preamble construction (with
|\@mkpream|) the special meaning of the bar can be switched on
again---this allows the usage of the new meaning in the body of a
table.

Of course this mean that the ``verbatim identifier'' facility can
not be used within a preamble of a table. Furthermore it can not
be used within the |\multicolumn| statement, neither in the
preamble part (the second parameter) nor within the text part (the
third parameter).

\beginprog
\let\@@tabarray=\@tabarray
\def\@tabarray{%
   \makebarother
   \@@tabarray
   }

\def\multicolumn#1{%
   \multispan{#1}%
   \begingroup
      \makebarother
      \restof_multicolumn
   }
\def\restof_multicolumn#1#2{%
      \@mkpream{#1}%
      \def\@sharp{#2}%
      \let\protect\relax
      \let\@startpbox\@@startpbox  \let\@endpbox\@@endpbox
      \@arstrut \@preamble
   \endgroup
   \ignorespaces
   }

\let\@@mkpream=\@mkpream
\def\@mkpream#1{%
   \@@mkpream{#1}%
   \makebaractive
   }
\endprog


\sect Before an index entry is scanned almost all special characters
are transformed into ordinary characters. The only exceptions are the
opening and the closing brace because they are needed to delimit the
argument. This transformation is done with |\@sanitize|, this macro
must be called within a group. We just append the transformation of
the vertical bar.

\beginprog
\begingroup
   \def\@makeother{\noexpand\@makeother\noexpand}
   \xdef\@sanitize{\@sanitize\@makeother\|}
\endgroup
\endprog




\chap Fragments in Verbatim.

We need macros to format the program fragments without any
linebreaking.  Such a text area shall start with the macro
|\beginprog| and end with |\endprog|, i.e.\ as a kind of a
|prog|-environment.  The macro |\endprog| must stand at the very
beginning of a line and must be followed by white space (blank, tab or
newline character).  After |\beginprog| as well as after
|\endprog| the rest of the line is ignored.

Two demands must be regarded:  There should be no length restrictions
for the processed text, and the tabular characters should be expanded
so that this macro works on PC's and on VAXes etc., too.


\sect The implementation method is quite simple:  We read the next
line, test, wether the end is reached (by comparing with the end line)
and otherwise set the line actually read.  Every character is
inspected and tabular characters are expanded.

The verbatim text is started with |\begin_verbatim| which will be
either called by |\beginprog| or by |\beginverbatim|. These macros
will also define the contents of the end line.

Whether a line is set or whether the end of the processed area is
reached is indicated by the switch |\if@print|.  At the beginning of
the |\begin_verbatim| macro most settings are done with
|\setup_verbatim| (the vertical bar must be handled separately)
and the rest of the line is ignored.  As everything is done within
a group, the end of the verbatim text can be processed by simply
closing this group.

For the user it looks as if |\endprog| or |\endverbatim|
terminates the processing, but it just serves for the
identification of the end, the true processing is done with the
internal macro |\end_verbatim|.

\beginprog
\newif\if@print

\def\begin_verbatim{%
   \endgraf
   \bigbreak
   \begingroup
      \setup_verbatim \makebarother
      \@printtrue
      \ignore_rest_line
   }
\let\end_verbatim=\endgroup             % internal command !
\endprog


\sect {\sloppy 
 The first line is ignored, all the other lines are identified with
|\set_next_line| and processed with |\do_set|.  This separation in
identification and processing allows that the line end character is
active in the definition only for a short time.
 \par}

When a line is to be formatted, we first check with |\check_print|
wether it contains the end line, otherwise it is printed with
|\print_char|.  The printing must be done for every character
individually because we want to check for tabular characters; the
exact algorithm is described below.  Here we just have to note that
|\print_char| is used with two parameters of which the second one is
finished with the token |\end_line|.  The first parameter is the first
character of the line, the second parameter is the rest of the line.
If the line is empty, the argument of |\do_set| is empty, too; so the
activation of |\print_char| must be finished with two |\end_line|.
Then the first |\end_line| is the first argument for |\print_char| and
the second argument is empty.  But if the line did contain something,
the second |\end_line| is evaluated, for this case it is defined as
|\relax|.

At last we call |\set_next_line| again to format the next line.  If
the end is reached, i.e.\ if the sample line was found,
|\set_next_line| will be redefined as |\relax|.  This can be done
because the original meaning is restored while closing the group
with |\end_verbatim|.

\beginprog
\begingroup
   \obeylines%  % ^^M is active! ==> every line must end with %
   \gdef\ignore_rest_line#1^^M{\set_next_line}%
   \gdef\set_next_line#1^^M{\do_set{#1}}%
\endgroup

\def\do_set#1{%
   \endgraf
   \check_print{#1}%
   \if@print  \indent \print_char#1\end_line\end_line
   \else  \let\set_next_line\end_verbatim
   \fi
   \set_next_line
   }
\let\end_line=\relax
\endprog


\sect {\sloppy
 Before we look at the problem of formatting a line, we declare
|\check_print| that checks the end of the verbatim mode.  We have to
do two things:  we must split everything in front of the first blank
or tabular character and compare for identity with |\endprog|.  The
splitting is easy because the line which is our first argument
contains blanks and tabulators as active characters.  First we call
|\cut_at_tab| that demands a tabular character as separator for its
two pramenters so that everything in the line in front of the first
tabulator is part of the first parameter.  If there is no tabular
character in the line, we append one so that the second parameter is
empty.  The same trick is used to separate the part in front of the
first blank character from the resulting first part.
 \par}

The check is done with |\do_check|.  We use a separate macro here so
that we can indent it (in the following definition blanks are active!)

\beginprog
\begingroup
\obeyspaces\obeytabs
\gdef\check_print#1{\cut_at_tab#1^^I\end_line}
\gdef\cut_at_tab#1^^I#2\end_line{\check_first_part#1 \end_line}% blank !
\gdef\check_first_part#1 #2\end_line{\do_check{#1}}
\endgroup
\endprog


\sect
\begin{sloppypar}
|\do_check| compares the line with a sample line that is
available in |\end_verbatim_line|.  This macro will be defined later.
\end{sloppypar}

\beginprog
\def\do_check#1{%
   \def\@line{#1}%
   \ifx \@line\end_verbatim_line  \@printfalse
   \fi
   }
\endprog


\sect Now we can set a line:  we start with the first character,
followed by the rest of the line.  Each character is counted in
|\char_count|.  At the beginning of a line |\char_count| is~0, this
is reset at the end of the line.

\beginprog
\newcount\char_count  \char_count\z@

\def\print_char#1#2\end_line{%
   \print_first_char{#1}%
   \print_rest_of_line{#2}%
   }
\endprog


\sect For each character that is set |\char_count| is incremented.
If a character is a tabulator, we set with |\print_tab| the fitting
amount of blank characters, otherwise the character itself.  We must
compare the character that is stored in |\@char| with a macro of which
the ``first-level'' expansion is an active tabulator.  For this case
we declare |\@tab|.

\beginprog
{\obeytabs\gdef\@tab{^^I}}

\def\print_first_char#1{%
   \def\@char{#1}%
   \advance \char_count\@ne
   \ifx \@char\@tab  \print_tab
   \else  \@char
   \fi
   }
\endprog


\sect If we want to fill the line with blank spaces up to the next
column with a number that can be divided by~8, we must be able to
compute the column number modulo~8, but \TeX{} has no modulo operator.
So we define the macro |\mod_viii| that computes its argument modulo~8
and returns the result in the counter |\count_mod_viii|.  For the
computation we need the temporary counter |\count@|.

\beginprog
\newcount\count_mod_viii
\def\mod_viii#1{%
   \count@ #1\relax  \count_mod_viii\count@
   \divide \count@ 8\relax
   \multiply \count@ 8\relax
   \advance \count_mod_viii -\count@
   }
\endprog


\sect Now we can declare |\print_tab|.  We must remember that
|\char_count| was incremented already, if we set only one blank
character the counter keeps untouched.

\beginprog
\def\print_tab{%
   \loop  \space \mod_viii\char_count
      \ifnum \count_mod_viii>\z@
         \advance \char_count\@ne
   \repeat
   }
\endprog


\sect If the rest of the line is empty, we are ready.  |\char_count|
is reset to~0 for the next line.

Inside the |\else| part of |\ifx| |\print_char| should not be used
directly because this costs too much storage of \TeX{}\@.  Instead we
set a control sequence |\next| that is processed afterwards, depending
on the result of the comparison.  (This tail recursion will be
discovered by \TeX{} and handled appropriately.) If there is still
something to set, we use |\print_char| again, otherwise a
syntactically similar macro that expands to |\relax|.

\beginprog
\def\print_rest_of_line#1{%
   \def\@line{#1}%
   \ifx \@line\empty  \char_count\z@
      \def\next##1\end_line{\relax}%
   \else  \let\next\print_char
   \fi
   \next#1\end_line
   }
\endprog


\sect {\sloppy
Now we are ready to define the two ``user accessible'' macros
|\beginprog| and |\beginverbatim|. They must define the prototyp end
line |\end_verbatim_line| which will be compared against every line
in the verbatim text. During the definition of
|\end_verbatim_line| it must be cared for that the escape character~`|\|'
is a printable character:  A comparison with |\ifx| demands identical
category codes.  As a temporary escape character we use the slash.
\par}

\beginprog
{\catcode`\/=\escape            % / is temporary escape char 
   \catcode`\\=\other
   /gdef/beginprog{%
      /gdef/end_verbatim_line{\endprog}%
      /begin_verbatim
      }
   /gdef/beginverbatim{%
      /gdef/end_verbatim_line{\endverbatim}%
      /begin_verbatim
      }
}                                % here \endgroup can't be used
\endprog




\chap Document Structuring.

In addition to the normal \LaTeX{} structuring markups we will
provide a markup for a layout of the document that is like in
\WEB{}.  This can be done easily. All sections are numbered, the
number of the next section is stored in the counter |section|.  We
distinguish between main sections which start a group of sections
and between normal sections within a group.

The main sections are started with the macro |\chap|. It has one
parameter, the title of the section group. This parameter must be
terminated by a dot.  We start a new page, typeset the title in
bold face and separate it from the section text with a |\medskip|.
This text, the documentation part of the section, is formatted
without paragraph indentation.

If the \WEB{}-like macros are used every section number should be
output with a following dot. We want to establish this when we use the
|\chap| or the |\sect| macro the first time. Furthermore the new page
at the begin of a main section should not be started at the first
|\chap| because a title may precede it (and the title should not
be on a seperate page unless explicitely requested). Instead a
skip of (approximately) 2~pica should be set. To achieve
both goals a macro |\chap_intro| is defined that defines |\thesection|
appropriately, skips the 2~pica, and redefines itself to
|\newpage|---we then just have to call |\chap_intro| at the beginning
of |\chap|. The same applies to |\sect_intro|.

\beginprog
\newskip\pre_sect_skip  \pre_sect_skip=2pc plus 1pc minus 6pt

\def\chap_intro{%
   \gdef\thesection{\arabic{section}.}%
   \gdef\chap_intro{\bigbreak}%
   \addvspace{\pre_sect_skip}%
   }

\def\sect_intro{%
   \gdef\thesection{\arabic{section}.}%
   \global\let\sect_intro\relax
   }
\endprog


\sect Now we will have a look at the {\it wonderful\/} internal
interface of \LaTeX{}\@. With ``wonderful'' I mean that I'm always
full of wonder why it was designed in this way. E.g., if anybody
can explain to me why the coding of the non-indentation of the first
line in the following paragraph was combined with the coding of
the skip which will come in front of the section---I will be thankful
for the rest of my life. Such different things should be kept
different, i.e., the suppression of the indentation should not be
hidden in the sign of a skip! The same comment applies to the combined
coding of the skip below the section heading resp.\ to the right
of a run-in heading.

\begin{quote} \it
I want the following layout: no indentation in the following
paragraph\/ {\rm but no} space in front of the section heading.
How do I code a value of\/ $\sl -0 pt$?
\end{quote}
%
Well, a work-around is to use a value of $\rm -1\,sp$ because the
reader will not see this distance---but in my opinions this is no
good programming style. In this special case I have luck, too:
the skip is not set anyway, either it is discarded by the preceding
|\newpage| or it is not added by |\addvspace| because of the preceding
|\pre_sect_skip|.

\beginprog
\def\chap#1.{%
   \chap_intro
   \@startsection{section}{1}%
      {\z@}%
      {\m@ne sp}%
      {\medskipamount}%
      {\normalsize\bf}%
      {#1.}%
   }
\endprog


\sect Normal sections are started with |\sect|.  This macro has no
parameter.  Between two paragraphs we skip |\pre_sect_skip|.
Between the section number and the text one quad of space is set.
We have to take care for empty documentation parts where the
program part (i.e.\ |\beginprog|) will follow immediately. Then
the program part should begin on a new line and not behind the
section number. So we provide |\null| as an empty documentation
part in every case.

Now again the design of |\@startsection| comes in hand: \LaTeX{}
always leaves a quad after the section number (by the way,
this is not mentioned in the documentation---you have to look
in the macros to figure this out). Because our section header
consists only of the number we have to code a value of $\rm
-0\,pt$\,\dots

\begin{quote}
Again: {\it non-orthogonal design is bad design}.
\end{quote}

\beginprog
\def\sect{%
   \sect_intro
   \@startsection{section}{1}%
      {\z@}%
      {\pre_sect_skip}%
      {\m@ne sp}%
      {\normalsize\bf}%
      {\null}%
   }
\endprog

\sect Finally, the |newsloppy| environment. As pointed out by
Frank Mittelbach, {\LaTeX}'s |\sloppy| environment is just a
little too sloppy. The tolerence value with which it allows {\TeX} to
break at is considered infinite. Using a value just short of this
improves output considerably.

\beginprog
    \newcount\pl_tolerance \pl_tolerance = 9999
    \newenvironment{newsloppy}%
       {\begingroup\tolerance\pl_tolerance}%
       {\endgroup}       
\endprog

\sect We are finished and just have to restore the category code.

\beginprog
\catcode`\_=\uscode

\endinput
\endprog





\end{document}