% 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...
%%%%
%%%%
%%%% These TeX macros were documented with the documentation system
%%%% MAKEPROG and automatically converted to the current form.
%%%% If you have MAKEPROG available you may transform it back to
%%%% the original input: Remove every occurence of three percents
%%%% and one optional blank from the beginning of a line and remove
%%%% every line which starts with four percents. The following lex
%%%% program will do this:
%%%%
%%%% %%
%%%%
%%%% ^%%%\ ? ;
%%%% ^%%%%.*\n ;
%%%%
%%%% MAKEPROG may be obtained over the net from the Bitnet-Listserver
%%%% LISTSERV@DHDURZ1 (filelist WEBWARE), from tuglib@science.utah.edu,
%%%% or via ftp from june.cs.washington.edu.
%%%%
%%%%
%%% \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}