Subject: Typesetting programs with (La)TeX (update)

From: [email-masked] (Piet van Oostrum)
Date: 9 Oct 91 14:38:42 GMT

Typesetting program texts with TeX and LaTeX.

This is a survey of methods to typeset program texts with TeX
and/or LaTeX, usually mixed with other text. The description consists
mostly of (edited) parts of the documentation of the packages, or messages
from their authors. I post this to get responses from people that know
other packages, or updated versions of these. Also I would like to receive
input about the availability (e.g. by FTP or mail server) of these
packages, other than the ones mentioned here.

PLEASE MAIL remarks to me, do not post them on the net. After two or three
weeks I will post an updated version. I might also submit it for
publication in TUGboat, but then I will have to TeXify it first.

----------------------------------------------------------------------
Note:
Several of the packages described below can be obtained from our
archive, either by ftp-ing from archive.cs.ruu.nl [131.211.80.5], in
directory TEX/TOOLS, or by sending a message to [email-masked]
containing the line:
send TEX/TOOLS/INDEX
or replacing INDEX with an appropriate file name.
If you are not familiar with the mail-server, use "send HELP" first.
----------------------------------------------------------------------

Contents:

1. Web and derivatives
1.1        Cweb
1.2        Fweb
1.3        Spiderweb
2. Tgrind
3. C2latex
4. C++2latex
5. Cprog macros
6. program environment
7. Scheme
8. Ada
9. Modula-2/Pascal
10. sundry

------------------------------------------------------------------------
1.1     Cweb
------------------------------------------------------------------------

ctangle, cweave - translate CWEB to C and/or TeX

The ctangle program converts a CWEB source document into a C
program that may be compiled in the usual way.  The output
file includes #line specifications so that debugging can be
done in terms of the CWEB source file.

The cweave program converts the same CWEB file into a TeX
file that may be formatted and printed in the usual way.  It
takes appropriate care of typographic details like page
layout and the use of indentation, italics, boldface,
etc.,and it supplies extensive cross-index information that
it gathers automatically.

CWEB allows you to prepare a single document containing all
the information that is needed both to produce a compilable
C program and to produce a well-formatted document
describing the program in as much detail as the writer may
desire.  The user of CWEB ought to be familiar with TeX as
well as C.

Don Knuth wrote WEB for TeX and Pascal. Silvio Levy designed
and developed CWEB by adapting the WEB conventions to C and
by recoding everything in CWEB.

Subject: Levy's Cweb system ported to MS-DOS and VAX/VMS

On the UK TeX Archive at Aston University, directory [tex-archive.web.cweb]
contains the sources for building Silvio Levy's CWEB system (a WEB suite
which uses C as the programming language, and TeX as the typesetting
language) under Unix; this includes a bootstrapping version of Ctangle
which permits one to get Cweave, etc., working.

Originally this was accompanied by a file VMS.CH which purported to
port Cweb onto VAX/VMS: however, Vax-C has been revised since Levy
released this, and further changes were necessary to get the system
working under VMS.  The original VMS.CH has threfore been deleted, and a
new subdirectory [tex-archive.web.cweb.vms] added to hold the files for
bootstrapping CWEB onto VMS, and the change files to make this Ctangle
and Cweave.

In addition, I have ported CWEB to MS-DOS (under Borland's Turbo-C V1.5).
This was a *major* undertaking, because of clashes between identifiers
used in ANSI-standard function prototypes in Borland's libraries and
constants defined in the .web files.  Other very extensive changes were
required to handle the large data structures, which exceed the 64kB
segment limit of the PC architecture.  However, it's all working
eventually, and the files required for bootstrapping it, and the change
files, will be found in [tex-archive.web.cweb.ms-dos].

For both of the above ports, the majority of the files of the Unix
distribution will also be required.

To get started, fetch the file [tex-archive.web.cweb]00readme.txt from
Aston, either by NIFTP (username PUBLIC, password PUBLIC), or by sending
mail to <[email-masked]>, with the body of the message
consisting of the two lines:
  FILES
  [tex-archive.web.cweb]00readme.txt

This file will tell you which other files will be required to be fetched
to have a working version of CWEB under Unix, VMS or MS-DOS.

                               Brian {Hamilton Kelly}

------------------------------------------------------------------------
1.2     Fweb
------------------------------------------------------------------------

		       The WEB System of Structured
		     Software Design and Documentation
		   for C, C++, Fortran, Ratfor, and TeX
				     
			       Release 1.22
			    September 21, 1991
				     
			      John A. Krommes
			   Princeton University

INTRODUCTION

  This message is for new users of the so-called FWEB processors, which
implement a version of Knuth's WEB system that supports multiple languages and
a variety of other useful features.  If you are already on the FWEB mailing
list, you should have already received announcements about version 1.22,
and there is nothing new in the following.  If you would like to be added
to the mailing list, please let me know.  (Please supply an Internet
address if possible.)

  The WEB system consists of EASY-TO-USE software tools that aid in
software design and documentation.  In fact, one can say that the
documentation IS the code, and vice versa.  The documentation facility is
fully integrated with TeX; book-quality documentation of both text and code
can be produced essentially automatically.  Knuth's fundamental philosophy
of rearrangable and pluggable modules of code fragments substantially
simplifies the translation of logical ideas into compilable code.  A fully
indexed, 150 page user manual based on Knuth's original brief memo is
included with this release.

  The most significant features that distinguish FWEB from its predecessors
are: 

	* SUPPORT for MULTIPLE LANGUAGES  

		Presently supported are C, C++, Fortran--77, Fortran--90,
		Ratfor (RATional FORtran), and (to a limited extent) TeX
		itself. 

	* A POWERFUL, C-LIKE MACRO PREPROCESSOR

		This is particularly useful for Fortran and Ratfor; it
		makes programming in those languages substantially less
		painful. 

	* A BUILT-IN RATFOR PROCESSOR

		Ratfor endows Fortran with a C-like syntax and certain
		useful commands such as `for' and `switch'.  If you must
		program in Fortran, try Ratfor.

In addition, many user-friendly features and options have been added to
this release.

  FWEB was originally released in 1989.  Since then, it has undergone
substantial development and testing on a variety of machines.  It is
written in ANSI C, so it is very portable.  An INCOMPLETE list of machines
and operating systems on which FWEB runs is

	[ansi]	(any system that has a fully ANSI C compiler)
	Apollo
	Cray-2
	DECstation
	IBM-PC	(executable files are supplied in addition to source code)
	NeXT
	Silicon Graphics Personal Iris
	Sun	(both gcc and cc compilers)
	VAX/VMS

FWEB is compiled on all machines in the above list except the Apollo before
each release.

OBTAINING VERSION 1.22

  Version 1.22 of the FWEB system is available via anonymous guest ftp from
Internet host

	lyman.pppl.gov

in public area

	/pub/fweb/v1.22/

Here is a sample ftp dialog.  (The precise commands may differ slightly on
your system.)

		ftp lyman.pppl.gov
	Name:	anonymous
	Password: guest
	ftp>	cd pub/fweb/v1.22
	ftp>	ls
	ftp>	get READ_ME.FWEB	(brief instructions)
[If you're a new user, you may initially want to skip the next two lines:]
	ftp>	type image
	ftp>	get TAR.v1.22.Z		(the entire release)
[If you get the TAR file, the next two lines are unnecessary:]
	ftp>	cd manual
	ftp>	get INSTALL_FWEB.tex	(detailed installation instructions)
	ftp>	quit

Follow the instructions in READ_ME.FWEB or, in much more detail, in
INSTALL_FWEB.tex.  The TAR file contains the complete release, except that
the executable files for the IBM-PC are not included in it.  You must
obtain those by separate get commands, e.g.,

	ftp>	cd boot/pc
	ftp>	mget *.exe

To unpack the TAR file, say in an empty subdirectory

	uncompress TAR.v1.22
	tar -xvf TAR.v1.22 *

After you've done this, obtain the user manual

	make -n fwebman

to see what will happen, then say ``make fwebman'' to really do it.

  If you can't use ftp, you may be able to use the intermediary of bitftp,
available through bitnet.  You type a valid ftp session into a file, then
send that file as a message to [email-masked].  You will get the files
you requested---e.g., TAR.v1.22.Z---back in the form of a message or
messages, possibly uuencoded if the file is large.  To obtain help on using
bitftp, send to the above address a message containing the single word
``help''.

NEW in VERSION 1.22

  Version 1.22 is essentially the non-beta version of v1.20--beta that was
made available in February 1991; it fixes a wide variety of bugs with that
earlier version, and adds a few new features.  A short list of the changes
and principal bug fixes can be found at the beginning of the detailed
installation guide INSTALL_FWEB.tex.  Note the following in particular [new
users will be most interested in point (1) about support for LaTeX]:

(1) This version is intended to run with LaTeX as well as with Plain TeX,
and it is recommended that you use LaTeX if you can.  However, this recent
enhancement has not been tested thoroughly.  If you run across macro
conflicts or other difficulties with using LaTeX in conjunction with
fweave, please let me know.  Note that fwebmac usurps LaTeX's \output
routine, so you won't be able to do fancy things with output unless you dig
into the details of fwebmac.  But simple LaTeX environments such as tables
are supposed to work.

(2) IBM--PC users should note that executable files are provided with this
release, so you don't need a C compiler to proceed.  That's the good news.
The bad news is that I haven't yet been able to squeeze this version down
enough so that the processors can do themselves.  To get a feeling for the
size of things, you should begin with small test programs and use the -s
command-line option to look at the memory allocation statistics.

(3) SYSTEM INSTALLERS SHOULD NOTE THAT THE BOOTSTRAPPING PROCEDURE HAS BEEN
GREATLY SIMPLIFIED.  All source files with the exception of one are now
common to all machines.  The exception is custom.web/custom.h.  For
bootstrapping, if a custom.h for your machine is not provided in the
relevant boot subdirectory, you should first copy a version of custom.h
into the web subdirectory, then edit that copy following the instructions
contained in the file.  Then compile and link as usual.  A short version of
the bootstrapping procedure is provided in READ_ME.FWEB; more details are
given in manual/INSTALL_FWEB.tex.

  I continue to be very interested in what changes you must make to get
FWEB running on your machine.  For example, you might have to do something
that's not covered in custom.h.  Unless you know better, always begin by
trying the ansi customization (in boot/unix/ansi/custom.h).  If your C
compiler isn't ANSI, complain to the vendor; standards are useful.  If your
compiler crashes, complain to the vendor and notify me.

  This version has benefited from the bug reports and suggestions of a
large number of patient beta-testers and manual readers of v1.20.  I am
very grateful to all of you.

OBTAINING HELP and REPORTING BUGS

  FWEB is an evolving project [supported by just one author, in (allegedly)
spare time] that benefits greatly from user feedback.  An attempt is made
to answer FWEB-related mail promptly---at least once a week, generally more
frequently.  Please feel ABSOLUTELY FREE to request help, advice, and new
features, and to report bugs or inconsistencies in the documentation.
Thanks very much for your help.

--- John Krommes
    September 21, 1991

  [email-masked]                         |  John A. Krommes
                                                |  Plasma Physics Laboratory
  ``princeton.edu'' is a synonym for            |  P.O. Box 451
  lyman.pppl.gov == 192.55.106.129              |  Princeton, NJ  08543

                                                |  Phone:  (609) 243--2606  

------------------------------------------------------------------------
1.3     Spiderweb
------------------------------------------------------------------------

% Copyright 1989 by Norman Ramsey, Odyssey Research Associates
% To be used for research purposes only
% For more information, see file COPYRIGHT in the parent directory

\documentstyle[11pt]{article}
\title{A note about a new implementation of {\tt WEB}}
\author{Norman Ramsey\\Odyssey Research Associates}
\date{July 4, 1988}
\setcounter{secnumdepth}{0}
\begin{document}
\maketitle

\begin{abstract}
Literate programming has received recent attention in the {\sl
Communications of the ACM}~\cite{bentley:lp,cvw:loom}. 
{\tt WEB} is a tool intended for literate programming, but 
until recently it was  useful only for writing PASCAL programs.
The author has developed a new tool, {\tt SPIDER}, which reads a
description of a programming language and writes a {\tt WEB} system
that can be used to write programs in that language.
{\tt SPIDER} has been used in the author's organization to build {\tt
WEB} systems for Ada, C, AWK, and other languages.
The author hopes that {\tt SPIDER} will enable people to write
literate programs in many more languages than they could before.
\end{abstract}

\section{Introduction}
Donald Knuth developed the {\tt WEB} system of structured documentation 
as part of the {\TeX} project~\cite{knuth:literate-programming}.
His implementation of {\tt WEB} combined PASCAL and {\TeX}.
  The {\tt WEB} idea suggests a way of combining {\em any}
programming language with {\em any} document formatting language,
but until recently there was no software support for writing in {\tt
WEB} anything but PASCAL programs.
In~1987, Silvio Levy rewrote the {\tt WEB} system in C for C,
while retaining {\TeX} as the formatting language~\cite{levy:cweb}.
I have has modified Levy's implementation by removing the parts
that  make C the target programming language, and I have
 added a third tool, {\tt SPIDER}, which complements {\tt WEAVE}
and {\tt TANGLE}.
{\tt SPIDER} reads a description of a programming language, and writes
source code for a {\tt WEAVE} and {\tt TANGLE} which support that
language. 
Using {\tt SPIDER}, a C~compiler, and an AWK~interpreter, an experienced
systems programmer can generate in a few hours a {\tt WEB} system for
an Algol-like language.

\section{Features of Spidery {\tt WEB}}
An exhaustive list of Spidery {\tt WEB}'s features would interest only
{\tt WEB} experts, 
but I do want to mention some features that I hope will encourage
people to use Spidery {\tt WEB}.
\begin{itemize}
\item
{\tt TANGLE} and {\tt WEAVE} can read from multiple files (this
feature is present in Levy's {\tt CWEB}), and
{\tt TANGLE} can write to multiple files.
Included files will be searched for on a path if not found in the
current directory.
These features make Spidery {\tt WEB} more usable on systems that have
{\tt make}.
\item
{\tt TANGLE} can expand macros with multiple parameters.
\item
The starred sections in Spidery {\tt WEB} can be organized
hierarchically (in three levels).
We have a UNIX tool that can extract different pieces of the hierarchy
from the output of {\tt WEAVE}, so that it is possible to take
excerpts from {\tt WEB} documents.
\item
{\tt TANGLE} writes {\tt \#line} directives, so you can debug at the
{\tt WEB} source level if your compiler respects the C~conventions for
{\tt\#line}.
\item
Many features of {\tt WEB} seem to exist only to compensate for
deficiencies in PASCAL, and most of those were dropped in {\tt CWEB}.
I have changed much of {\tt CWEB} in order to avoid being bound too
much by C conventions.
As a result, there are dozens of minor differences between Spidery
{\tt WEB} and original {\tt WEB}.
To give just one example, Spidery {\tt WEB} supports
octal and hexadecimal constants using {\tt WEB}-style
notation, not the C~notation used in {\tt CWEB}.
\end{itemize}

\section{Scope of {\tt SPIDER}}
{\tt SPIDER} can generate {\tt WEB} systems for a variety
of languages.
The author has written {\tt SPIDER} description files for C, AWK, Ada,
SSL (a language that describes attribute grammars to the
Cornell Synthesizer Generator), 
the Larch Shared Language (a language for describing equational
theories), 
and Dijkstra's language of guarded commands.
Debugging the grammar that {\tt WEAVE} uses to
prettyprint the language is the most time-consuming part of creating a
{\tt WEB} system for a new target language,
and {\tt SPIDER} makes it trivial to change that grammar.
To make a {\tt SPIDER} description file for an Algol-like language
that uses infix expression notation, an experienced systems programmer
should be able to adapt an existing {\tt SPIDER} description file very
quickly.

{\tt SPIDER}'s major limitations are lexical.
 All Spidery {\tt WEB}s
assume that spaces and tabs in the input are not significant, except
as separators;
this makes it impossible to construct Spidery {\tt WEB}s for languages
like Fortran and Miranda, where the position of text on a line is
significant.
The lexical structures of identifiers, string literals, and numeric
literals are fixed.

\section{Conclusions}
{\tt SPIDER} is a modest piece of engineering; it does not introduce
new ideas.
{\tt SPIDER}  does make it possible to create a new {\tt WEB} quickly,
and to tinker with it easily.
The author's group routinely uses Spidery {\tt WEB} to write programs
in Ada, C, and~SSL, and has been pleased with the result.
We have written in {\tt WEB} an application of eighteen thousand
lines, and
we are very pleased at how easy it has been to review and maintain
this code.
The author hopes that the availability of Spidery {\tt WEB} will
encourage other groups to try literate programming, and that they,
too, will be pleased with the results.

\begin{thebibliography}{Van~Wyk~9999}
\bibitem[Bentley~86]{bentley:lp}
Jon L. Bentley, ``Programming Pearls,''
{\sl Communications of the ACM} {\bf 29:5} (May~1986), 364--368, and
{\bf 29:6} (June~1986), 471--483.
\bibitem[Knuth~84]{knuth:literate-programming}
Donald E. Knuth, ``Literate Programming,'' {\sl The Computer Journal}
{\bf 27:2} (1984), 97--111.
\bibitem[Levy~87]{levy:cweb}
Silvio Levy, ``{\tt WEB} Adapted to C, Another Approach,''
 {\sl TUGBoat} {\bf 8:1} (1987), 12--13.
\bibitem[Van~Wyk~87]{cvw:loom}
Christopher J. Van~Wyk, ``Literate Programming,''
{\sl Communications of the ACM} {\bf 30:7} (July~1987), 593--599, and
{\bf 30:12} (December~1987), 1000--1010.
\end{thebibliography}

------------------------------------------------------------------------
2.      Tgrind
------------------------------------------------------------------------

From: Ken Yap <[email-masked]>

Several people have asked about including program source in TeX
documents. I believe the most general approach is to use a utility like
tgrind (TeX analog of vgrind). One specifies the language to be
processed (so that tgrind can detect keywords).  Tgrind converts tabs
into the appropriate spacing (generates things like \tab{24} for 3
tabs), boldens keywords, prints quoted strings in typewriter font,
prints comments in italics, and other nice things.  All these goodies
are customizable.  This requires an extra pass, but the preprocessing
is quite fast.

Tgrind is on the Unix TeX tape, in the directory TeXcontrib/van. It was
written by Van Jacobson of LBL. Unfortunately it is Unix specific, but
I think equivalents for other OS are no problem. Heck, just take your
favourite pretty-printer and generate TeX instead of prettified
output.

Ken

tgrind - grind nice program listings using TeX or LaTeX

Tgrind formats program sources in a nice style using TeX.
Comments are placed in italics, keywords in bold face and
strings in typewriter font.  Source file line numbers appear
in the right margin (every 10 lines).  The start of a
function is indicated by the function name in large type in
the right margin.

In regular mode tgrind processes its input file(s) and
passes them to TeX for formating and output.

In format mode (i.e., when the  flag is used), tgrind
processes its input file(s) and writes the result to
standard output.  This output can be saved for later
editting, inclusion in a larger document, etc.

Currently known are
     PASCAL, RATFOR, Modula-2, MODEL, C, ISP, Yacc,
     Prolog, Icon, TeX, CSH, and Bourne Shell .

Van Jacobson, Lawrence Berkeley Laboratory (based on
"vgrind" by Dave Presotto & William Joy of UC Berkeley).
------------------------------------
Jerry Leichter improved tgrind.  His version is available from
venus.ycc.yale.edu in [.TGRIND].

I've added some functionality to Jerry's version of tgrind and called
it lgrind, as it only really works with LaTeX (as does Jerry's).
Essentially, what I did was to add a facility for having fragments of
code in comments (a la WEB) and to improve the embedded mode, where
lgrind filters a LaTeX file with embedded chunks of code.

I was going to release lgrind by itself, but now it's going to be part
of Pretty!, a suite of prettyprinting programs by Joerg `joke'
Heitkoetter ([email-masked]), who writes:
   Pretty! currently consists of Modula2LaTeX (c.s.m.vol22i79-81), lgrind
   and C++2LaTeX, plus a library for writing indentation tools like the
   BSD indent (which might be rewritten by me for BSD4.4), plus low level
   stuff like expand/unexpand(1) tools, etc.
   I already made a proposal to FSF to call it "GNU Pretty!", we'll see...

/George
________________
George V. Reilly   `Georges Cinq'	[email-masked]  +1 (401) 863-7693
uunet!brunix!gvr   [email-masked]	Box 1910, Brown U, Prov, RI 02912
------------------------------------
I hope you got George V Reilly's addendum to your "Currently available
tools for program documentation" list, I hope to alpha release
"Pretty! -- Utilities for Typesetting Formal Languages" during the
next weeks...

It contains LAGRiND, which is based on Van Jacobsen's tgrind, Jerry
Leichter's update to tgrind, and some ideas developed by George's group at
Brown University. It will make *any* tgrind version obsolete, because
you can emulate the older versions with a switch.

Pretty! (the ! belongs the the logo) is a collection of tools of the
following kind:

	1. formatters (BSD indent)
	2. typesetters (LaGRiND, Modula2LaTeX, C++2LaTeX)
	3. low level utilities (expand/unexpand)

Pretty! was much inspired by suite's like Rich Murphey's GNU Graphics, and
Jef Poskanzer's PBM+. I hope Pretty! will be the a kind of clearing house
for this special usage of LaTeX/TeX usage. We'll see.

Thanx again and so long

      -joke

--
Joerg Heitkoetter
Systems Analysis Group
University of Dortmund, Germany
([email-masked]).

------------------------------------------------------------------------
3.      C2latex
------------------------------------------------------------------------

From: [email-masked] (John D. Ramsdell)
Subject: c2latex--Simple Support for Literate Programming in C

C2latex provides simple support for literate programming in C.  Given
a C source file in which the comments have been written in LaTeX,
c2latex converts the C source file into a LaTeX source file.  It can
be used to produce typeset listings of C programs and/or documentation
associated with the program.

The C source given to c2latex usually has the following form.  It
starts with a large comment containing LaTeX commands that start a
document along with any initial text.  Then there is a sequence of
comment and code pairs, with the comment explaining the code to
follow.  The source file is ended by a comment containing LaTeX
commands that finish the document.

C2latex produces LaTeX source by implementing a small number of rules.
A C comment that starts at the beginning of a line is copied
unmodified into the LaTeX source file.  Otherwise, non-blank lines are
surrounded by a pair of formatting commands (\begin{flushleft} and
\end{flushleft}), and the lines are separated by \\*.  Each non-blank
line is formatted using LaTeX's \verb command, except comments within
the line are formatted in an \mbox.

The c2latex program is written in ANSI C and can be processed by
c2latex to produce LaTeX source containing a typeset listing of
itself.  It has a copyright similar to those distributed with GNU
software.  c2latex is available from me as a shar file via electronic
mail.  If there is enough interest, I will request that the sources be
placed on a public server.

John

------------------------------------------------------------------------
4.      C++2latex
------------------------------------------------------------------------

The program c++2latex converts ANSI-C/C++ programs into LaTeX source.

It requires flex which can be found on various ftp sites,
 e.g. prep.ai.mit.edu. For those without flex and without the possibility
to get one, I can email the flex'ed program.

Please notice that this program is under GNU Copyleft.

     DESCRIPTION

c++2latex is a tool for generating LateX source from ANSI-C
or C++ programs.  It recogizes all keywords, strings, and
comments. These recognized parts can be set in different
fonts.  c++2latex can generate complete LaTeX files which
can directly passed through latex or parts of LaTeX files
which can be included in other files (either direct or by
the \input or \include commands).  The output filename is
searched in various steps. First, if the {-o,+output} flag
is given, the output is written to the file pointed to by
the value of this flag. If the {-t,+pipe} option is given,
the output is written to stdout. (It is an error to specify
both options together.) If none of this options but an input
pathname is given, the output is written to a file who's
name is the last component of the input pathname with the
substituted or else added suffix '.tex'. If the input is
read from stdin and none of the above options is given, the
output is written to '<program-name>.tex' with <program-
name> being the name of this program.

------------------------------------------------------------------------
5.      Cprog macros
------------------------------------------------------------------------

The cprog macros allow programs in C, C++, Pascal, and Modula-2 to be
included directly into TeX documents.  Program text is set in a Roman
font, comments in slanted, and strings in typewriter.  Operators such as
<= are optionally combined into single symbols like $\le$.  Keywords are
*not* emphasised---I find this ugly and distracting.  (By purest
coincidence it would also be very hard to do.)

These macros can be \input in plain TeX or used as a style file in LaTeX.
They provide a convenient alternative to tgrind, particularly for program
fragments embedded in documents.  Full instructions for use appear in the
macro package itself.

\'Eamonn McManus <[email-masked]>   <[email-masked]>

This allows C programs to be formatted directly by TeX.  It can be
invoked by \cprogfile{filename} or (in LaTeX) \begin{cprog} ...
\end{cprog} or (in plain TeX) \cprog ... \end{cprog}.  In LaTeX, the
alternative form \begin{cprog*} is allowed, where spaces in C strings
are printed using the `square u' character (like LaTeX {verbatim*}).
In plain TeX, you have to use \csname cprog*\endcsname for this (sorry).
If you are using \cprogfile, say \cprogttspacetrue beforehand if you
want this effect.

The formatting is (necessarily) simple.  C text is set in a normal Roman
font, comments in a slanted font, and strings in a typewriter font, with
spaces optionally made visible as the `square u' symbol.  Tabs are
expanded to four spaces (this does not look good when comments are
aligned to the right of program text).  Some pairs of input characters
appear as single output characters: << <= >> >= != -> are respectively
TeX's \ll \le \gg \ge \ne \rightarrow.  Say \cprogpairsfalse to disable
this.

You can escape to TeX within cprog text by defining an escape character.
The character @ is suitable for C and Pascal.  I have not tested other
characters so they may interact badly with their existing definitions here.
To define @ as the escape character, do \cprogescape@.  Then within text
you can do @ followed by TeX commands.  These commands will be in a TeX
group with the \catcodes of \{}% as normal.  The commands are terminated
by a newline, which is not considered part of the program text.

The fonts below can be changed to alter the setting of the various parts
of the program.  The \cprogbaselineskip parameter can be altered to
change the line spacing.  LaTeX's \baselinestretch is taken into account
too.  The indentation applied to the whole program is \cprogindent,
initially 0.  Before and after the program there are skips of
\beforecprogskip and \aftercprogskip; the default values are \parskip
and 0 respectively (since there will often be a \parskip after the
program anyway).

If the source text is Pascal or Modula-2, say \pascaltrue or \modulatrue
(respectively) before formatting it.  This makes (* *) be recognised for
comments instead of /* */.  Braces {} are also recognised for Pascal.
\pascalfalse or \modulafalse as appropriate restores the default of C.

This package works by making a large number of characters active.  Since
even spaces are active, it is possible to examine the next character in
a macro by making it a parameter, rather than using \futurelet as one
would normally do.  This is more convenient, but the coding does mean
that if the next character itself wants to examine a character it may
look at a token from the macro rather than the input text.  I think that
all cases that occur in practice have been looked after.

The macros could still do with some work.  For example, the big macro
defined with [] taking the place of {} could be recoded to use {} and so
be more legible.  The internal macros etc should have @ in their names,
and should be checked against LaTeX macros for clashes.

------------------------------------------------------------------------
6.      Program environment
------------------------------------------------------------------------
\documentstyle[program2]{article}
\oddsidemargin 10mm \evensidemargin 10mm
\marginparwidth 20mm \marginparsep 7pt
\topmargin 0mm \headheight 12pt \headsep 1cm \footheight 12pt \footskip 30pt
\textheight 220mm \textwidth 147mm \columnsep 10pt \columnseprule 0pt
\def\lijn{\rule{\textwidth}{1pt}}
\begin{document}
\title{How to layout a (Pascal-)program in \LaTeX}
\author{Rein Smedinga \\
{\small  department of computing science, p.o.box 800, 9700 AV Groningen }\\
{\small tel. 050--633937 (633939), email: \verb!rein @cs.rug.nl!}}
\maketitle
\def\framed#1{\framebox[\textwidth][l]{\vbox{#1}}}
\def\bep{\begin{program}\skipprog}%                   begin programtext
\def\eep{\end{program}\noindent}%                     end programtext

In \TeX\ or \LaTeX\ is it possible, but difficult, to create a nice layout
for programs. The easiest way is to use the \verb!verbatim! environment.
The layout is then copied from the input file. In most books a program
(e.g., a PASCAL-program) is displayed using boldface reserved words, 
using math-italic for statements and using teletype fonts for string
representations. Without extra equipment this can be done in \TeX\ as
well as in \LaTeX\ using a \verb!tabbing!-environment. 
Of course, each font choice
should be made explicitly, e.g., you must say \verb!{\bf begin}! to
create a boldface begin-symbol and \verb!$x:=x+1$! to denote an
assignment. Furthermore, the user is responsible for setting the tabs and
jumping to the right ones. This is far from being user-friendly.

The \verb!program!-environment tries to be of some help while displaying
program-texts. It contains a number of macros of the form \verb!\BEGIN!,
\verb!\PROCEDURE! and alike that not only put down a boldface begin-
or procedure-symbol but also sets and jumps to the right tabs. Using
the \verb!program! environment from the \verb!program2!-style file
also automatically puts the statements
in math-mode (you do not have to use \verb!$!-signs anymore).

------------------------------------------------------------------------
A similar style:

program.sty: a LaTeX style file for typesetting algorithms.
Copyright (C) 1991 Martin Ward

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.

This is the "program" style option which sets up the
program and programbox environments,
keywords for programs and a few goodies.
NOTE: Within the program environment:
(1) Newlines are significant.
(2) Each line is in math mode, so for example spaces in the input
    file are not significant.
(3) \\ within a line causes a linebreak in the output.

We also define a "programbox" environment which typesets a program in a box.
Useful for keeping a piece of code on one page or for typesetting small
programs in running text.
We also redefine \( and \) as \begin{programbox} and \end{programbox}.
The \tab and \untab commands are defined to have no effect while outside
a program environment, hence a single-line program can be typeset in
maths mode without the overhead associated with programbox.

------------------------------------------------------------------------
7.      Scheme
------------------------------------------------------------------------

From: John D. Ramsdell <[email-masked]>
Subject: SchemeTeX---Simple support for literate programming in Lisp.

SchemeTeX provides simple support for literate programming in any
dialect of Lisp on Unix.  Originally created for use with Scheme, it
defines a new source file format which may be used to produce LaTeX
code or Lisp code.  Roughly speaking, LaTeX formats Lisp code in a
verbatum-like environment, and it formats Lisp comments in an ordinary
environment.

SchemeTeX is available via anonymous FTP from linus (192.12.120.51) in
the shar file named "pub/schemeTeX.sh".  Included is an operating
system independent version for the T dialect of Lisp.

John

------
From: [email-masked] (Dorai Sitaram)
Subject: typesetting Scheme code

I wrote something called SLaTeX that allows listings of Scheme code in
LaTeX without restricting it to the usual monospace typewriter font
supported by other code typesetters.

I've placed the current version in the titan.rice.edu's anonymous ftp
area: get public/slatex.sh.

SLaTeX decides which tokens should be, say, boldfaced, italicized, or
sansserifed, pretty much along the style of the Little Lisper [1].
(The user can completely control this default decision process, so
much so that he can flip the fonts around, add new fonts, or even do
something silly like make everything come out in typewriter -- i.e.,
turn the program into a no-op.)

I'd been leery of distributing SLaTeX before because of the frequent
updating that it's undergone following the Rice Scheme-and-similar-
language users' lively demands for bells and whistles, e.g.,

o allowing arbitrarily positionable displays, boxed code, in-text code,
	and directly inputing actual Scheme files; 

o getting little pockets of LaTeX text or mathmode into the Scheme
	code, for readable Schemelike pseudocode (useful for
	expository papers and class handouts);

o making it learn automatically that a macro definition implies that
	keyword should henceforth be boldfaced, etc.

At any time, the ftp site will contain the most recent code.  The shar
file contains the Scheme source (Ch*z, but should carry over to other
Schemes with minor changes), a shellscript that piggybacks the
codesetter on to LaTeX, the requisite LaTeX style file, installation
instructions, a manual in LaTeX, a man page, and a copyleft.  The
first 2 sections in the manual suffice for most uses, with fine tuning
being described later.  (The code, as of now, contains more fine
tuning than documented -- I'll update the docs when I next get time.)

This is free(ly distributable) software, and hence no warranty, though
I'll be glad to field bug and other reports.

[1] D.P. Friedman and M. Felleisen, _The Little Lisper_, Science
Research Associates (3e), 1989, and The MIT Press, 1987.

------------------------------------------------------------------------
8.      Ada.
------------------------------------------------------------------------

See TUGboat 10#1, April 1989
    Sriram Sankar       APE -- A set of TeX macros to format Ada
                        programs

I have developed a set of macros to do exactly this for Ada programs.
To get more details on these macros, read the report in the April issue
of TUGBoat, or the Nov/Dec issue of Ada Letters (both in 1989).

The macros are available by anonymous ftp to anna.stanford.edu in the
pub directory (I think).  I can send them to you if you are willing
to cover the costs.

Sriram.

See also:
       GUTenberg'90
      May 15-18, 1990
University Paul Sabatier, Toulouse, FRANCE

Typesetting ADA programs           (P. Naudin, C. Quitte)

------------------------------------------------------------------------
9.      Modula-2/Pascal
------------------------------------------------------------------------

m2latex - a Modula-2 to LaTeX converter

m2latex is a tool for generating LaTeX sources  from  Pascal
or  Modula-2  It  recogizes  all keywords, strings, and com-
ments. These recognized parts can be  typeset  in  different
fonts.   m2latex can generate complete LaTeX files which can
pass directly through latex(1) or parts of LaTeX files which
can  be  included  in  other  files (either direct or by the
\input or \include commands).

The output filename is searched in various steps. First,  if
the {-o,+output} flag is given, the output is written to the
file pointed to by the value of this flag. If the {-p,+pipe}
option  is given, the output is written to stdout. (It is an
error to specify both options together.) If  none  of  these
options  but an input filename is given, the output is writ-
ten to a file who's name is the last component of the  input
filename with the added suffix '.tex'.

*  Copyright (C) 1991 Joerg Heitkoetter
*  Systems Analysis Group, University of Dortmund, Germany.
*  ([email-masked]).
(distributed under GNU copyleft)

------------------------------------------------------------------------
10.     Sundry.
------------------------------------------------------------------------

From: [email-masked] (Robin Rosenberg INF)
Subject: Re: Typesetting programming languages in LaTeX

About two years ago I wrote a program that converts programs to TeX.
The program sets keywords in boldface (or any font you select) using a
data file to find out which strings are keywords and how to skip
comments. I have data files for Modula-2, C, C++, Pascal, Occam, Beta,
and some more. The program is written in C (under VMS) and could well
be improved. However it does what I want it to do, it makes programs
_look_ nice in listing. As said it translates to TeX and not LaTex but that is no big deal to change I'd guess. 

If you need this program send a mail to [email-masked]. mail

Robin Rosenberg

------------------------------------------------------------------------
I have an SED script and Pascal environment for LaTeX that follows
the standard Algol 60 style for setting Pascal text.  The SED
script translates everything between \begin{pascal} and \end{pascal}
in various ways that the pascal environment understands.  The only
problem with the thing is that indenting must be in multiples of
4 spaces, but I've used it for a number of publications without
hearing any complaints about my awkward indenting style.

In any case, I strongly recommend the notion of environments for
language types, as opposed to the various grind programs.  It would
be nice to have a standard set of environment parameters to control
things like keyword font so language environments from different
sources could be at least somewhat interchangable.

      Doug Jones
      [email-masked]

------------------------------------------------------------------------
% manpage.sty

% Rong Chen ([email-masked])
% Department of Computer Science
% University of Illinois at Urbana-Champaign
% Urbana, IL 61801

% Copyright (c) 1990 by Rong Chen 
% Permission to copy all or part of this work is granted, provided
% that the copies are not made or distributed for resale, and that
% the copyright notice and this notice are retained.
% 
% THIS WORK IS PROVIDED ON AN "AS IS" BASIS.  THE AUTHOR PROVIDES NO
% WARRANTY WHATSOEVER, EITHER EXPRESS OR IMPLIED, REGARDING THE WORK,
% INCLUDING WARRANTIES WITH RESPECT TO ITS MERCHANTABILITY OR FITNESS
% FOR ANY PARTICULAR PURPOSE.

% This style option is designed to work with the report document style
% of LaTeX version 2.09.  Use \documentstyle[11pt,manpage]{report}
% 
% This LaTeX style file is similer to the UNIX troff man macros in format and
% is specially tuned for documenting the C++ library that the author wrote.
%
% The commands that are created in the style file are:
%
% \begin{manpage}{Title}{Module}{Version}  % see an example, all will be clear
% \end{manpage}                            % end of manpage environment
% \variable{#1}  (e.g., \variable{int foo}) % with \medskip added
% \variable*{#1} (e.g., \variable*{int bar})% no extra spacing
% \function{#1}  (e.g., \function{void demo(int dummy)}) % with \medskip added
% \function*{#1} (e.g., \function*{void demo(int dummy)})% no extra spacing
% \subtitle{#1}  (e.g., \subtitle{AUTHOR}) % fit in the same line if possible
% \subtitle*{#1} (e.g., \subtitle*{AUTHOR})% always break a newline
% "#1"           (e.g., "dummy_variable")  % argument is in italic&unbreakable
% \separator		% draw a thin line to seperate suntitle from the text
% \header{#1}{#2}{#3}	% in case you want to have a header and 
% \footer{#1}{#2}{#3}	% a footer outside of the manpage environment
% \dq			% print double quote character (")
%
% In the \function macro, data types and their dummy arguments are separated
% by a space. So if you have a function like "int f(const int n)", you should
% document it as \function{int f(const~int n)}.  The argument n is optional.
% In the \subtitle macro, two lines of text may be devided by "\\".
---------------------------------------------------------------------------
MAKEPROG
---------------------------------------------------------------------------
Another possibility, which comes very close to your suggestion, is
J. Schrod's MAKEPROG. With this you can write plain-TeX or LaTeX documents
with embedded program fragments (simply enclosed in \beginprog and
\endprog), that will be typeset just verbatim. MAKEPROG extracts the program
fragments from the source and joins them together (in linear order only).
All in all, MAKEPROG has less capabilities than WEB, but is not limited to a
given programming language. You can get it from the address above in the
directory /soft/tex/utilities. I wrote an enhancement to MAKEPROG, that
makes the layout of the documentation more WEB-like; if you are interested,
I will mail it to you.
 
Hans-Hermann Bode
Arbeitsgruppe Systemforschung, Universit\"at Osnabr\"uck
Tel.: (49)-541-9692545
e-mail: [email-masked]

------------------------------------------------------------------------
CNOWEB:
------------------------------------------------------------------------
There's another C to plain TeX system, cnoweb, available from
u.washington.edu in pub/tex/cnoweb.

c-NO_WEB (a c program pretty printer)
by Jim Fox, February 1987
version 1.1, August 10, 1989
version 1.2, October 30, 1989
             fixed spacing after ?, :, etc.
version 1.3, June 28, 1990
             added OOdent and IIdent, added \|typewriter|
version 1.4, January 4, 1991
             allow /* and */ in strings

-----------------------------------------------------------------

The TeX input file is a c source program.  It is assumed to have
this structure:

  /* comments ignored by c-no-web
     \input cnoweb
     \title{A one line title of the program (optional) }
     \synopsis{Synopsis of the program (optional) }
     \section{Name of the first section}
     rest of comments */

The rest of the file is normal c code.
Within the title a \\ may be used to separate lines.

Each major section begins with
  /* \section{name of the section}    .... */
The section names are printed boldface, marked for reference in
the page headline, and written to the table of contents.

Each minor section begins with
  /* \subsection{name of the subsection}    .... */
The subsection names are written to the table of contents.

A new page can be forced by
     /* \newpage */

Code and other text containing special characters may be
typed in text mode if it is bracked by *< ... >*
e.g. /* *<inactive c-code>* */
but this may not be used in a macro argument.

You can print in bold by enclosing text in double quotes: \"text".
You can print in typewriter by enclosing text in vertical bars: \|text|.
You can print in italics by enclosing text in single quotes: \'text'.

The file must end with \endc in a comment. e.g.,
     ... last c code statement ...
     /* \endc */
------------------------------------------------------------------------
-- 
Piet* van Oostrum, Dept of Computer Science, Utrecht University,
Padualaan 14, P.O. Box 80.089, 3508 TB Utrecht, The Netherlands.
Telephone: +31 30 531806   Uucp:   uunet!mcsun!ruuinf!piet
Telefax:   +31 30 513791   Internet:  [email-masked]   (*`Pete')