% idverb.doc				  as of 22 Jan 90
%---------------------------------------------------------
% (c) 1989,1990 by J.Schrod. copy conditions see below

%
% Macro package for writing verbatim texts (e.g. identifiers) in
%	a WEB like fashion, i.e. as |identifier|.
% LaTeX style option
% MAKEPROG is needed
%

%
% DATE	   PERSON  REMARK
% 90-01-22 js      errors in documentation.
% 89-11-18 js	   complete exchange: use the first part of progltx
%		   renamed to idverb, rewritten with MAKEPROG.
% 88-07    js	   first version
%		   (idtt.sty, with no special handling of LaTeX stuff)


%%%%
%%%%
%%%% 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 via ftp from ftp.th-darmstadt.de
%%%% (directory pub/tex/src-webware) and from the Bitnet-Listserver
%%%% LISTSERV@DHDURZ1 (filelist WEBWARE).
%%%%    If you only want to print out the documentation you may fetch
%%%% the archive print-makeprog.tar.Z from ftp.th-darmstadt.de (directory
%%%% pub/tex/latex). It contains *all* used styles -- but beware, they
%%%% may not be documented...
%%%%
%%%%
%%% \documentstyle[progltx,a4-9]{article}


%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%% %
%%% % local macros
%%% %

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

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

%%% %
%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%


%%% \begin{document}


%%% \title{
%%%    Writing identifiers in a \WEB{} style\\
%%%    The {\tt idverb\/} style option
%%%    }
%%% \author{\sc Joachim Schrod}

%%% \maketitle


%%% \chap Introduction.


%%% This \LaTeX{} style option allows to write identifiers in a WEB like
%%% style, i.e.\ as {\tt \vbar identifier\vbar}.  The identifiers are
%%% typeset verbatim in the monospace type face.  This makes this style
%%% option extremely useful if you must write about \TeX{} stuff and you
%%% have to incorporate examples \TeX{} command sequences very often
%%% within the running text:  Just enclose them in vertical bars and {\tt
%%% \vbar|\relax|\vbar}.

%%% The macros |\makebarother| and |\makebaractive| 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.


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


%%% \sect This file was built as an extract of an other style option,
%%% |progltx|. Therefore there may be parts within the macros which are
%%% not needed anyway. But I prefer to let them be part of it because the
%%% maintainance in the future will be easier for me.




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




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

%%% \beginprog
\catcode`\_=\uscode

\endinput
%%% \endprog





%%% \end{document}