path: root/support/makeprog/docu/mkprgdoc.tex

% mkprgdoc.tex					06 Oct 90
%------------------------------------------------------------
% (c) 1988-1990 by J.Schrod.

%
% documentation for the MAKEPROG system
% LaTeX
%

%
%		VERSION HISTORY
%
% DATE	   WHO REMARK
% 90-10-06 js  added hint to doc2tex and tex2doc.
%	       MAKEPROG will be available at tuglib.
% 90-09-21 js  new progdoc, progltx mentioned everywhere.
% 90-06-11 js  rewritten in LaTeX.
% 89-02-01 js  updated with comments of Klaus Guntermann.
% 88-12-05 js  first version (for ftp/Bitnet).

% author:
%	js:	Joachim Schrod <xitijsch@ddathd21.bitnet>
% contributors:
%	(-: place enough for your name! :-)




\documentstyle{article}


%\advance\textheight by \baselineskip


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

\makeatletter


% fonts

\let\mc=\small		      % medium caps for acronyms
\font\tentex=cmtex10          % typewriter extended ASCII 10pt
\let\ttex=\tentex


% short hands

\def\MAKEPROG{{\mc MAKEPROG}}
\def\CWEB{{\mc CWEB\/}}
\def\WEB{{\tt WEB\/}}
\def\TANGLE{{\tt TANGLE\/}}
\def\WEAVE{{\tt WEAVE\/}}
\def\TIE{{\tt TIE\/}}
\def\DVI{{\tt DVI\/}}
\def\spider{{\tt SpiderWEB\/}}


% footnotes on the titlepage without any marker

\def\titlenote#1{%
   \begingroup
      \def\@makefntext##1{\noindent ##1}%
      \footnotetext{%
         \interlinepenalty\@M
	 \ignorespaces #1%
	 }%
   \endgroup
   }


% |...| verbatim from progdoc.doc. look there for the explanations.

\catcode`\|=\active
\def|{%
   \leavevmode
   \hbox\bgroup
      \let\par\space \setupverb@tim
      \let|\egroup
   }
\def\setupverb@tim{%
   \let\do\@makeother \dospecials
   \parskip\z@skip \parindent\z@
   \obeylines \obeyspaces \frenchspacing
   \ttex
   }

% an inch symbol

\def\inch{{\tt "\/}}



\makeatother

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



\begin{document}



\title{The MAKEPROG System of Documentation}
\author{Joachim Schrod}

\date{October 1990}

%%%%% moved below after footnotes -- the titlenote should be on the
%%%%% bottom of the page
%
%\titlenote{
%   \copyright{} Copyright 1988--1990 by Joachim Schrod.
%   All rights reserved.
%   }

\maketitle



\section{Introduction}

In his article \cite{knuth:literate} {\sc D.~Knuth} has introduced
the concept of {\it Literate Programming}. This concept focused on
the following statement: ``Instead of imagining that our main task is
to instruct a {\sl computer\/} what to do, let us concentrate rather
on explaining to {\sl human beings\/} what we want a computer to
do.'' To support this for Pascal programs he has created the {\sl
\WEB{} system of structured documentation} \cite{knuth:web}, an
extension of Pascal.  In \WEB{} a program is splitted into sections,
each section contains a documentation and a program part (both parts
can be empty).%
   \footnote{%
      In fact there is a third part, the macro part, which is not
      important in this context.
      }
 Such a \WEB{} program is transformed by the \TANGLE{} processor into
a program source for the compiler and the \WEAVE{} processor produces
an output which can be fed into \TeX{} to get a fine looking
document.  Both \TANGLE{} and \WEAVE{} support the inclusion of
changefiles, with these files lines of text can be replaced by other
lines.

At the Technichal University of Darmstadt we have used this
concept---with \CWEB{} \cite{kg-js:cweb}---in many of our projects,
e.g.\ for our portable \DVI{} driver family. With the introduction of
\spider{} made by {\sc N.~Ramsey} \cite{ramsey:spider} a \WEB{}
generator became available which allows the generation of a new
\WEB{} system for a specific language. But even with \spider{} not
all languages may be supported because the lexical analysis is fixed
to languages with tokens separated by white space.  E.g.,
prettyprinting \TeX{} macros is a non-trivial task due to \TeX's
dynamic lexical analysis. Furthermore \spider{} does not run on as
many computer systems as \WEB{} does because it is implemented in
{\tt awk\/} that is not as widespread.%
   \footnote{%
      But please note that there exists {\tt gawk}, the {\tt awk\/}
      implementation of the GNU project, which is free software and
      may be ported to more systems.
      }
 (In my opinion this is one of the strongest drawbacks of \spider{},
it should be rewritten in \WEB{} urgently.) Or people do not have
enough time to generate a \WEB{} system even if they should do so if
they plan to work longer with this specific formal language.

\titlenote{\strut}
\titlenote{
   \copyright{} Copyright 1988--1990 by Joachim Schrod.
   All rights reserved.
   }

To close this gap I have developed the \MAKEPROG{} system. It allows
to document programs with \TeX{} in a \WEB{} like fashion, the
program parts of the documentation file can be extracted to yield the
program file. During the extraction process the documentation file
can be altered with a changefile. Multiple changefiles may be used
with the help of \TIE{}~\cite{kg-wr:tie}.

The \MAKEPROG{} system consists of two parts:  (1)~the \MAKEPROG{}
processor which does the extraction and (2)~the macro files |progdoc|
(for usage with Plain \TeX{}) or |progltx| (as an article style
option with \LaTeX{}) which make formatting facilities available. 
The \MAKEPROG{} processor is derived from \TANGLE{}, therefore there
should be no difficulties for any site running \WEB{} to install
\MAKEPROG{}.  The macros are implemented with \MAKEPROG{}, the files
|progdoc.doc| resp.\ |progltx.doc| are the ultimate sources.
|progdoc.tex| or |progltx.sty| is only delivered to allow the
printing of |progdoc.doc|.



\section{Distribution}

\MAKEPROG{} 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.

\MAKEPROG{} 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~\cite{gnu:license} for more details.

At the moment \MAKEPROG{} may be obtained from {\tt
LISTSERV@DHDURZ1\/} (filelist {\tt WEBWARE\/}) for the Bitnet folks,
from {\tt tuglib@science.utah.edu}, and it is included in the
BSD/UNIX distribution of Pierre MacKay (so it may be available via
anonymous ftp from {\tt june.cs.washington.edu}, too).

If you want to get a floppy (DOS format, 5.25\inch{}~HD, 3.5\inch{}
HD or~DD) with the \MAKEPROG{} system you may contact me. But please
note that you will have to pay a handling charge of DM~40. (``When we
speak of free software, we are referring to freedom, not
price.''~\cite{gnu:license}) On my distribution disk is \MAKEPROG{},
\TIE{}, and \WEB{}.



\section{How to Use MAKEPROG}

If you use \LaTeX{} you must include |progltx| as a document style
option, if you use Plain \TeX{} you must include the macro file with
|\input progdoc|. Afterwards you can structure your document into
sections and the sections into groups.  The first section of a group
starts with |\chap|, it corresponds to the starred section (`|@*|')
of a \WEB{} program.  |\chap| has one parameter, the title of the
section group.  The parameter is ended by a dot.  The dot is printed
by the macro.  Every other section starts with |\sect|.  These macros
produce a number in front of each section; this number is incremented
with each new section. Of course, in \LaTeX{} you may use the normal
\LaTeX{} sectioning markup if you prefer that one.

Within a section one or more program part(s) can be specified with the
macros |\beginprog| and |\endprog|.  Both macros must start at the
beginning of a line.  If |\beginprog| does not start at the beginning
of a line verbatim typesetting will be switched on but no extraction
to the program file will result afterwards.  After |\beginprog| the
rest of the line is ignored.  If |\endprog| does not start at the
beginning of a line or if it is not followed by white space (blanks,
tabs, or end of line) neither verbatim typesetting nor extracting will
stop.

Please note that even with \LaTeX{} |\beginprog| and |\endprog| must
be used for the markup of the program parts, instead of
|\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 \MAKEPROG{} processor---but \MAKEPROG{} wants to see the
non-\LaTeX{}-like macros. But everybody is encouraged to change it by
himself.

Outside of the program part---in the so called documentation
part---you can use the vertical bar to print small texts verbatim,
e.g.\ identifiers, macro names, etc.  A vertical bar starts the
verbatim mode, the next vertical bar stops it.

After you have finished writing your document you can print it with
\TeX{} and you can run the \MAKEPROG{} processor to extract all
program parts into a program file.  During the extraction \MAKEPROG{}
will recognize change files like \TANGLE{} does.



\section{Bells and Whistles}

Within the documentation part you can use |\origvert| to get an
original vertical bar. |\vbar| is the character with the {\mc ASCII}
representation of a vertical bar in the actual font.

If you use Plain \TeX{} and |progdoc| you may change the appearance
of the title page with the table of contents. This page is output as
the last page and it's layout is like in \WEB{}. Before the table of
contents the macro |\topofcontents| is executed. The default
definition of this macro supplies the title and glue on the top. The
header line above the table is typeset by |\HeaderToc|, each contents
line is typeset by |\tocline|. You can change the definitions within
|\topofcontents|. After the table the macro |\botofcontents| is
executed which usually just supplies glue, but may be redefined to
incorporate copyright notices etc.

\smallskip

If you document \TeX{} macros with \MAKEPROG{} and send them to
people who don't have \MAKEPROG{} and if you have {\mc LEX\/}
available, you may use |doc2tex| to transform the \MAKEPROG{} source
into a \TeX{} source. All documentation parts are turned into \TeX{}
comments and a paragraph is added which includes a hint to
\MAKEPROG{}. |tex2doc| converts such a file back to a \MAKEPROG{}
source.



\section{Problems and Errors}

The following deficiencies are known to me (some are not inherent
but there wasn't the time to do it until now):
 %
 \begin{itemize}

\item \MAKEPROG{} does not rearrange the code as \TANGLE{} does. 
This is the most important drawback.  The support of stepwise
refinement is one of \WEB{}'s main advantages.

\item \MAKEPROG{} does not prettyprint the program part because it
does not know anything about the target language and therefore
nothing about the lexical and syntactical structure of the program. 
Instead it just prints the program part verbatim.  But compared to
wide spread macros which set text verbatim it has the advantage
that you can print your program part if you have embedded tabs in it.
The macros will replace every tab with one to eight spaces according
to the current column.

\item \MAKEPROG{} does not produce any index.  This is impossible
because it does not know what an identifier looks like.  (This can
even change inmidst a program, cf.~\TeX!)

\item Because the documentation file is a \TeX{} file and \TeX{} does
not recognize change files the complete documentation (with a change
file) cannot be printed.  \TIE{} must be used to create a new master
file which can be printed afterwards.

\item The page breaking is not satisfying in all cases.  I still have
to fiddle with the penalties.

\item \MAKEPROG{} should insert the current date as a comment line in
front of the produced program file. The syntax of the comment line
(start and end of a comment) must be specifiable.

\end{itemize}

If you have found an error or if you have some remarks please contact
me. I~prefer electronic mail and I will acknowledge your mail within
a week. Send bug reports to:
%
 \begin{quote}
 Detig$\,\cdot\,$Schrod \TeX{}sys\\
 Joachim Schrod\\
 Kranichweg 1\\[.5\baselineskip]
 D-6074 R\"odermark-Urberach\\
 FR Germany\\[.5\baselineskip]
 Email: {\tt xitijsch@ddathd21.bitnet}
 \end{quote}



\section{Related Work}

Frank Mittelbach and Rainer Sch\"opf have presented |doc|
\cite{mittelbach:doc}, a \LaTeX{} style option for documenting
\LaTeX{} styles. An accompanying \LaTeX{} input file (|docstrip|)
strips these documents. Although their approach seems to be similar
to the one presented here, it should be noticed that there are
several important differences. 

At first |doc| was created for documenting \LaTeX{} macros, while
\MAKEPROG{} was created to support the documentation of {\it formal
representations which are processed by a computer}, e.g.\ programs.
Therefore |doc| was able to supply specific (semantic dependent) help
for automatic creation of an index and of marginal notes whereas
\MAKEPROG{} must refer the user to the standard features available in
\LaTeX{} or Plain \TeX{} because it has no knowledge about the
semantic structure of the program.

Furthermore \MAKEPROG{} supports the changefile mechanism which is
rarely needed for the documentation of \TeX{} macros because \TeX{}
is (almost) the same on all computer systems but programs in general
must be adapted to local circumstances, i.e., system dependent stuff
must be included.




\appendix



\section{Installation}

The first step is to install the \MAKEPROG{} processor.  Because it
is derived from \TANGLE{} this should be rather easy.  Just take your
local \TANGLE{} change file and you should have very few alterations
(perhaps much to delete).  You will need to put the \MAKEPROG{}
processor somewhere where your local command processor will find
it---perhaps you will even need a command script around it.  But this
will be the same as it was with \TANGLE{}. (To ease the installation
for many sites I have included changefiles for {\tt WEBtoC\/} and for
Turbo Pascal.)

You can test your new program by feeding |progdoc.doc| resp.\
|progltx.doc| through it. The output must be identical to
|progdoc.tex| resp.\ |progltx.sty|. Well, the main work is now done. 
You still have to put |progdoc.tex| and |progltx.sty| in directories
where \TeX{} will find them and then have much fun. (Don't
worry---be happy$\,\ldots$)




\bibliographystyle{plain}
\bibliography{web,gnu,tug}




\end{document}