From piet@cs.ruu.nl Thu Oct 10 20:05:48 1991 From: piet@cs.ruu.nl (Piet van Oostrum) Newsgroups: comp.text.tex Subject: Typesetting programs with (La)TeX (update) Date: 9 Oct 91 14:38:42 GMT Reply-To: piet@cs.ruu.nl (Piet van Oostrum) Organization: Dept of Computer Science, Utrecht University, The Netherlands 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 mail-server@cs.ruu.nl 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 , 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 bitftp@pucc.bitnet. 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 krommes@princeton.edu | 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 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 (heitkoet@gorbi.informatik.uni-dortmund.de), 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' gvr@cs.brown.edu +1 (401) 863-7693 uunet!brunix!gvr gvr@browncs.bitnet 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 (heitkoet@gorbi.informatik.uni-dortmund.de). ------------------------------------------------------------------------ 3. C2latex ------------------------------------------------------------------------ From: ramsdell@celebes.mitre.org (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 '.tex' with 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 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 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: dorai@tone.rice.edu (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. * (heitkoet@gorbi.informatik.uni-dortmund.de). (distributed under GNU copyleft) ------------------------------------------------------------------------ 10. Sundry. ------------------------------------------------------------------------ From: rosenber@ra.abo.fi (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 rosenber@ra.abo.fi. 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 jones@herky.cs.uiowa.edu ------------------------------------------------------------------------ % manpage.sty % Rong Chen (rchen@cs.uiuc.edu) % 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: HHBODE@DOSUNI1.BITNET ------------------------------------------------------------------------ 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. /* ** */ 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: piet@cs.ruu.nl (*`Pete')