Glasgow Literate Programming User’s Guide

The GRASP Team Contact: Will Partain (partain@dcs.glasgow.ac.uk)

September 1992

Contents

1 Literate programming, Glasgow style 5

1.1 Objectives of our Glasgow system . . . . . . . . . . . . . . . . . . . . . . . . . 6 1.1.1 Programs/documents in an on-line form . . . . . . . . . . . . . . . . . 6 1.1.2 Programming on a medium scale . . . . . . . . . . . . . . . . . . . . . 6 1.1.3 Programming language independence . . . . . . . . . . . . . . . . . . . 7 1.1.4 Program code written exactly as in illiterate programs . . . . . . . . . 7 1.1.5 Use of ASCII-based files, “declarative” markup . . . . . . . . . . . . . 7 1.1.6 Use of hierarchical structure . . . . . . . . . . . . . . . . . . . . . . . . 7 1.1.7 “Separate compilation” for large programs/documents . . . . . . . . . 8 1.1.8 Using one file in several ways . . . . . . . . . . . . . . . . . . . . . . . 8

1.2 NON-Objectives of our system . . . . . . . . . . . . . . . . . . . . . . . . . . 9 1.2.1 Not to reinvent LaTEX (or any other extensible notation) . . . . . . . . 9 1.2.2 An un-emphasis on code-reordering . . . . . . . . . . . . . . . . . . . . 9

1.3 Other features of our Glasgow system . . . . . . . . . . . . . . . . . . . . . . 9 1.3.1 Sectioning support for large documents . . . . . . . . . . . . . . . . . 9 1.3.2 Automatic indexing of your code . . . . . . . . . . . . . . . . . . . . . 10 1.3.3 Indexing by hand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.3.4 Automatic cross-referencing of your code . . . . . . . . . . . . . . . . 10 1.3.5 Shortcut notations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 1.3.6 The great “LaTEX to ASCII” problem solved! . . . . . . . . . . . . . . 11 1.4 Shortcomings of our system . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.4.1 Limits because of the Texinfo intermediate representation . . . . . . . 11 1.4.2 Node namespace is not “neat” . . . . . . . . . . . . . . . . . . . . . . 11 1.4.3 A clunky implementation . . . . . . . . . . . . . . . . . . . . . . . . . 11

2 A LaTEX-like document markup language (tutorial-ish) 11 2.1 A micro-tutorial on our LaTEX-like conventions . . . . . . . . . . . . . . . . . 13 2.2 Sectioning commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

2.2.1 The \section<n> command . . . . . . . . . . . . . . . . . . . . . . . . 14 2.2.2 How to use \section<n> . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2.3 The \sectiontype and \sectionref commands . . . . . . . . . . . . 16 2.2.4 GNU Info node specifications with \section<n> . . . . . . . . . . . . 16

2.3 Including program code in your document . . . . . . . . . . . . . . . . . . . . 17 2.3.1 The usual ways to put code in a documents . . . . . . . . . . . . . . . 17 2.3.2 Code ribbons: the fancy stuff . . . . . . . . . . . . . . . . . . . . . . . 18 2.3.3 Code reordering with \insertribbon . . . . . . . . . . . . . . . . . . 19 2.3.4 Stuff that looks like code but isn’t . . . . . . . . . . . . . . . . . . . . 19 2.3.5 Magic things you can put in your code . . . . . . . . . . . . . . . . . . 19

2.4 Cross-referencing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.5 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 2.6 Some complete examples [NOT FINISHED] . . . . . . . . . . . . . . . . . . . 22

2.6.1 A simple example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.6.2 A typical example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.6.3 A hairy example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

2.7 Helpful short-cut notations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 2.7.1 Referring to code things in your text . . . . . . . . . . . . . . . . . . . 22 2.7.2 Using different “fonts” in your text . . . . . . . . . . . . . . . . . . . . 22

3 LaTEX-like markup commands: reference 22

4 Language-specific processing 32 4.1 Rules for unknown or unsupported languages . . . . . . . . . . . . . . . . . . 32 4.2 Language-specific rules for Haskell . . . . . . . . . . . . . . . . . . . . . . . . 32 4.3 Language-specific rules for perl . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.4 Language-specific rules for C . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 4.5 Language-specific rules for FORTRAN . . . . . . . . . . . . . . . . . . . . . . . . 32

5 A checklist of good literate habits 32

6 Caveats: bugs and foibles 33

7 Programs to process literate documents 34

8 Using your processed literate documents 39

9 APRIL91 PROPOSALS 39

9.1 New ideas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 9.1.1 Make the commands look less like LaTEX . . . . . . . . . . . . . . . . . 39 9.1.2 Multiple indexes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 9.1.3 Better Haskell indexing . . . . . . . . . . . . . . . . . . . . . . . . . . 40 9.1.4 Revisions to the sectioning commands . . . . . . . . . . . . . . . . . . 40 9.1.5 A “BNF grammar” environment . . . . . . . . . . . . . . . . . . . . . 41 9.1.6 Fake “C pre-processing” . . . . . . . . . . . . . . . . . . . . . . . . . . 41 9.1.7 Invisible code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 9.1.8 Plain text in your code . . . . . . . . . . . . . . . . . . . . . . . . . . 43 9.1.9 Using many “fonts” in text . . . . . . . . . . . . . . . . . . . . . . . . 43 9.1.10 Formatting code-ish things in text . . . . . . . . . . . . . . . . . . . . 43 9.1.11 Interface with plain LaTEX papers . . . . . . . . . . . . . . . . . . . . . 44 9.1.12 A literate Para mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 9.1.13 A lit2lit program (to help implement a Para system) . . . . . . . . 45 9.1.14 Generating LaTEX documents especially for xtex . . . . . . . . . . . . 45 9.1.15 A free-text “index” . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 9.1.16 Other “magic” Info nodes... . . . . . . . . . . . . . . . . . . . . . . . . 45 9.1.17 Revise the way options are fed to lit2* programs . . . . . . . . . . . 46 9.1.18 Mixing code in “Bird tracks” with other code . . . . . . . . . . . . . . 46

9.1.19 Decouple code reading and printing styles . . . . . . . . . . . . . . . . 46 9.2 Old ideas that still haven’t gone anywhere . . . . . . . . . . . . . . . . . . . . 46

9.2.1 \owner{⟨name⟩} . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

9.2.2 Burying test cases in your document . . . . . . . . . . . . . . . . . . . 47 9.2.3 Recording changes to your documents . . . . . . . . . . . . . . . . . . 47

10 SEPT92 THOUGHTS 47

11 Standalone installation of Glasgow literate programming 48 This guide introduces a suite of programs for literate programming. They support documentation as a natural part of programming; a program’s organization focusses on understanding by humans.

If you installing this system as a standalone entity, please see section 11, near the end.

This document begins with a few words about literate programming, the objectives of this system, and the Neat Stuff that this system is supposed to do for you (i.e., cheap, tasteless self-promotion). See section 1.

The real goods come next, most notably:

• an alleged “tutorial” on the LaTEX-like markup language in which documents/programs are written (section 2);

• a “reference manual” about the same markup language; this tends to be what you consult once you are using the system (section 3);

• the programs/tools to mangle your documents/programs into useful forms (section 7).

There are other sections, too, in greater-or-less states of usefulness.

It would be a good idea to understand the rudiments of GNU Info files before reading much further—type info info at your favourite Unix prompt. Or you could just ignore all mention of Info files...

YOUR SUGGESTIONS FOR IMPROVING THIS SYSTEM ARE MOST WELCOME.

DISCLAIMER: “Literate programming” is not my(WDP)/our area of expertise. This system has been developed mainly to suit our needs and has evolved on a grease-the-squeaky-wheel principle. However, we wouldn’t bother to document it if we didn’t think there was something to it!

APRIL91 PROPOSALS: I am thinking about some changes to the system, NOT YET IM-PLEMENTED. Discussion about most (all?) of them is gathered together in section 9. (You can find all discussion of proposed changes by grepping for “APRIL91”.)

SEPT92 THOUGHTS: Still haven’t really worked on this system. I have typed a few further thoughts at the obvious place. I have fixed one or two bugs, and I have incorporated Adriaan Joubert’s (adriaan@dcs.qmw.ac.uk) stuff for “literate Fortran,” for which I am most grateful. (See, it really is easy to extend :-)

For more information about “real” literate programming, the bibliography of literate programming in the (approx: ToDo) March 1991 SIGPLAN Notices may be of use.

1 Literate programming, Glasgow style

Literate programming is a style that tries to maximise humans’ understanding of programs by full-scale use the tools of the description trade (typesetting, indexing, etc.) to say what a program does and how it works. The power of literate programming is in the synergy between writing code and documentation in a unified framework.

So, for example, in Knuth’s original WEB system [ToDo: add reference(s)] “code” and “text” may be intermingled as much as you like, the pieces of “code” may appear in any order (even though it’s only glorified Pascal), and quite substantial cross-referencing and indexing (not to mention TEX-based typesetting) is built in. Programs are just documents for people to read and enjoy which happen to have machine-manipulable code “buried” in them.

1.1 Objectives of our Glasgow system

With our Glasgow system, your “program” is a LaTEX-like document, with the compilable/executable code marked off by a \begin{code} ... \end{code} pair (or equivalent shortcut notation). From there, your “program” may be (a) compiled/interpreted [by extracting the embedded code and feeding it to a “normal” compiler/interpreter]; (b) turned into a beautiful typeset document to be smeared onto dead trees, or (c) turned into an on-line viewable/jump-aroundable document.

Here are the specific (distinctive?) objectives of the Glasgow system.

1.1.1 Programs/documents in an on-line form

The people-oriented documents produced by literate-programming systems are usually on paper (this system provides those, too). For working programmers, their good properties are largely overshadowed by one fact: paper documents go stale quickly. Also, large programs turn into not-so-navigable large piles of dead trees. Surely we can do better!

Note our emphasis on presenting work-in-progress, as opposed to a system that emphasises the presentation of the final perfect programming gem.

Our goal is that these on-line documents should be the medium of choice for programmers’ daily reference. (APRIL91: See the note about “literate Para mode” in section 9.1.12.)

Our choice for an on-line format is the GNU Info format, a primitive ASCII-only sort-of hypertext system. The main reason for this choice is to let the GNU people do as much of our programming for us as possible! The program info can display Info files on just about any kind of terminal; xinfo works with the X Window System; the ubiquitous GNU Emacs has an ever-improving Info mode.

1.1.2 Programming on a medium scale

We aren’t really interested in programming-in-the-small (one person, a few hundred lines of code), and we don’t know about programming in the large (hundreds of programmers, millions of lines of code); our target audience is five-person projects working on programs the size of, say, a Haskell compiler :-)

1.1.3 Programming language independence

The system may be used for literate programming with any programming language. However, the quality of the indexing, typesetting, etc., support will vary, depending on whether that language is “supported” or not. Fortunately, the current implementation, while clunky (see section 1.4.3, makes it easy to add better support for a given programming language.

See section 1.2.2 for a related comment about code re-ordering.

1.1.4 Program code written exactly as in illiterate programs

You put executable/compilable code into your literate programs by inserting it in a \begin{code}/\end{code} environment (or the “Bird-track” equivalent); for example:

\begin{code}
main _= [ AppendChan stdout "Hello, world!\n" ]
\end{code}

The principle is: you can write code inside a \begin{code}/\end{code} environment exactly as you would in an illiterate program in the same language.

This brings up a dichotomy that pervades literate programs: everything in the program is either code (stuff in a code environment, or equivalent) or text (everything else).

1.1.5 Use of ASCII-based files, “declarative” markup

ASCII-based files (as opposed to some weird binary “internal format”): so you can read the files directly and e-mail them to your friends.

Insisting on ASCII files means some kind of markup commands buried in the text.

We want the markup to be “declarative,” that is, to say “what you want” rather than “how to produce what you want.” Section numbering, generation of a table of contents, much indexing work, cross referencing, creating of the Info “node” structure, etc., etc., is done automagically.

Our starting-point choice for a “declarative” markup notation was LaTEX, because that’s what we know (and so do a lot of other people). You could make the case that GNU’s Texinfo format would’ve been better, esp. given some of our other objectives. Or: you could argue that we should’ve chosen a completely different notation, because some people look at our literate files and think they are LaTEX, which they are not.

The most important parts of our LaTEX-like notation are introduced in section 2, and the whole mess is exhaustively described in section 3.

1.1.6 Use of hierarchical structure

That is: programs/documents divided into sections, subsections within sections, subsubsections...

Hierarchy is a very powerful structuring tool, but its utility for wading around a large sea of code is not apparent. APRIL91: See the comments about a “literate Para mode” in section 9.1.12.

See also section 1.3.1.

1.1.7 “Separate compilation” for large programs/documents

This really follows from the size of project we’re trying to support; it’s just too slow to have to slurp in the whole program text and do anything... (It’s pretty slow as it is :-)

Separate compilation of the embedded code: Use the normal mechanisms of your programming language. For example, if you have a literate C file, foo.lc, then you would extract the code into foo.c (command: lit2pgm foo.lc) and compile as normal (gcc -c foo.c).

“Separate compilation” of the (LaTEX and (Tex)info) document-generating tasks: this is harder and quite a lot of work has to be done at “link time”. What happens: the initial “separate compilations” of all the individual files in a program/document (e.g., lit2texi -c foo.lc or lit2latex -c foo.lc) produce intermediate files (*.itxi and *.itex files, respectively). These are then consulted when a “link” is done (e.g., lit2latex root.lit, where root.lit \inputs the other files).

(It’s complicated: use Makefiles!)

1.1.8 Using one file in several ways

Say you’re writing a Haskell compiler :-), which includes the source code for a typechecker. On the one hand, you want this to be included in “the book” (document) that is the whole compiler. However, you may also want to have a “typechecker document” that is itself selfcontained (if only because the “book” is so big). Going further: perhaps one module of your typechecker is so amazing that you want to publish it as a paper.

You could make copies of files, edit them, etc., but that’s tacky, and against a most deeply-held principle of literate programming: that you are looking at the source code for the program being described.

As it stands, this system lets you put \begin{onlystandalone} and \end{onlystandalone}

around pieces of your files that only apply in the “do this as a standalone document” case;

similarly, \begin{onlypartofdoc} and \end{onlypartofdoc} for stuff that only applies in

the “the glorious whole” case.

APRIL91: I am fairly convinced I got this wrong and believe that this stuff would be much better handled with a pseudo-“C pre-preprocessor” (one that does not look inside code blocks [see deeply-held principle above; section 1.1.4]); see section 9.1.6.

1.2 NON-Objectives of our system

1.2.1 Not to reinvent LaTEX (or any other extensible notation)

Just as with Texinfo, our markup notation has a fixed set of commands. We don’t have a \define command that let’s you define new macros in terms of old ones. This is for simplicity, I suppose.

APRIL91: see the note about fake “C pre-processing” in section 9.1.6.

1.2.2 An un-emphasis on code-reordering

Some programming languages have a narrow-minded idea about what order the pieces of a program must be presented (e.g., COBOL: identification division, then file division, then data division [how many of you knew this :-]), and some literate-programming systems provide lots of machinery to get around this orderly intransigence.

We write in Haskell, which is relatively open-minded about the order in which functions, etc., are presented. Re-splicing together code from dispersed program fragments doesn’t buy you much—and we think the same is true for most modern or semi-modern programming languages. Therefore, this system has only primitive support for reordering code.

1.3 Other features of our Glasgow system

1.3.1 Sectioning support for large documents

The main thing we’ve done here is change the sectioning commands (vs LaTEX) so it’s easy to re-arrange chunks of the hierarchy. Also, a default Info “node” structure is worked out, based on the sectioning information. (Veteran Texinfo hackers will appreciate the joys of not typing error-prone @menus.)

Sectioning in an individual file should always begins at \section; such files should then glued together in a “root file” with \input commands interspersed with \upsection and \downsection commands. lit2latex/lit2texi combine your files, putting appropriate real-LaTEX/Texinfo sectioning commands (\part, \chapter, etc.) in the right places.

A side-effect of diverging from LaTEX sectioning is that we can support deeper nesting of sectioning commands.

It’s also neat to be able to change your mind about whether you want to start with (LaTEXspeak...) parts, chapters, sections, or whatever...

Please see section 2.2 for further details about this whole mess.

1.3.2 Automatic indexing of your code

An attempt is made to index all the “interesting things” in the code parts of your program. The success of this enterprise depends on the degree to which the language you are using is supported.

In a paper manifestation, you’ll get nice neat indexes, like we’re used to. In an on-line manifestation, you would like to use the information to “point and jump” (our Info-based implementation does this, perhaps clumsily).

APRIL91: See section 9.1.2 for latest thoughts about indexing. Also, I’ve put some comment about free-text retrieval in section 9.1.15.

1.3.3 Indexing by hand

Indexing your text (vs your code) is not automatic. You do it by hand with \index{<stuff>} commands. The format of the \index commands is a simplified (?) form of makeindex commands. Section 2.5 gives the details.

1.3.4 Automatic cross-referencing of your code

Your code may also be automatically cross-referenced; again, it’s based on finding “interesting things” in your code; furthermore, it depends on distinguishing between “definitions” and “uses”, because the main purpose of cross-referencing is to let you move quickly from a “use” (e.g., of a function) to its “definition”.

APRIL91: Sometimes you would really like to be able to go from a definition to all of its uses. Perhaps this should be an option.

Cross-referencing is automatically OFF when producing LaTEX documents (we found it mainly cluttered) and ON when producing Info files (which lets you jump to the definitions through a node’s menu).

1.3.5 Shortcut notations

Within non-code parts of documents, code snippets may be included between ‘at’ signs; e.g., @f x y = y@—appropriate formatting, indexing, etc., will be done.

APRIL91 COMMENT: I need to clarify the proper use of these @s. I also need to figure what to do when @s are not the right thing! (I think Texinfo has an over-proliferation of commands for marking off this and that in the text.) See section 9.1.10.

For the ordinary text to be shown in a typewriter font (much used in user’s guides, for example), you may use the \tr{<text>} command; the only restriction on <text> is that braces must be balanced. The same trick for “plain” (roman) font is \pl{<text>}. [APRIL91: See section 9.1.9 for further thoughts about fonts in your text.]

APRIL91: See also: section 9.1.5.

1.3.6 The great “LaTEX to ASCII” problem solved!

(Well, not quite...) A literate program looks an awful lot like a LaTEX document. If you convert the program to an Info file, then run the info2ascii script [which I haven’t written yet :-] over it, you’ll have a quite-reasonable all-ASCII nicely-formatted version of your LaTEX-ish input.

1.4 Shortcomings of our system

1.4.1 Limits because of the Texinfo intermediate representation

We produce our on-line viewable GNU Info files by going through their Texinfo format. If something cannot be represented easily in Texinfo (which doesn’t do things not easily representable in character-only ASCII), it ain’t in our system. This leads to the following very notable shortcomings:

1. No graphics, pictures, or sound.

2. No fancy mathematical stuff of the sort TEX/LaTEX is so good at. Note: we would like to provide enough basic mathematical stuff so you aren’t hamstrung by this restriction.

1.4.2 Node namespace is not “neat”

For all practical purposes, it’s your problem to make sure that you don’t get nodename clashes. This is really uncool.

APRIL91: Some ideas for partial alleviation of making-up-nodenames weariness, see section 9.1.4.

Barring that, a good discipline for making up unique nodenames would be helpful (I haven’t found one yet).

1.4.3 A clunky implementation

The principle has been: do as little work as possible. (What do you expect from the proponents of lazy functional programming?)

The implementation is the Perl Script From Hell, with a supporting cast of the Flex Program From Hell, and a whole bunch of exceedingly useful programs written by other people, mainly the GNU Info/Texinfo-related programs and tgrind (by Van Jacobsen). [We can pass along the source to all of these programs.]

2 A LaTEX-like document markup language (tutorial-ish)

Here is a simple silly literate Haskell program:

\documentstyle[literate]{report}
\rootsectiontype{\part}
\begin{document}
Here is my \Haskell{} program to send a message to my friends:
\begin{code}
main _= [ AppendChan stdout (message ++ " to " ++ my_friends) ]
\end{code}
\section[message]{The Message}
\begin{code}
message = "Hello"
\end{code}
\subsection{Comments about the message and its implementation}
\begin{enumerate}
\item
The message is given as a top-level pattern binding.
\item
The @message@ binding does not violate the monomorphic restriction;
its type is \tr{[Char]}, which is not overloaded.
\end{enumerate}
\section[friends]{My friends}
\begin{code}
my_friends = ( \ y -> "Bob and Joe" ) 3
\end{code}
\printindex
\end{document}

Here are some things to see in this example (don’t worry if it doesn’t make sense first time):

• The compilable program (the parts between \begin{code}s and \end{code}s) is simply contained in marked-off parts of your document, and the code therein is completely ordinary (no special programming notation).

Such code is one “kind of stuff” in your literate program; text is the other.

• The overall document is arranged hierarchically (\section, \subsection, etc.) and looks an awful lot like a LaTEX document.

• There is quite a bit about what makes up your document (sections, code, enumerated lists) and very little about how your document should be formatted (e.g., “skip 2 lines”). This is “declarative” markup.

• Your program code will be indexed automatically; the \printindex command is how you say where you want the index included.

• You can refer to things-in-your-code in the text parts of your document, by enclosing the reference in @’s, as in @message@. The reference will be suitably indexed.

• The sectioning commands (e.g., \section) are odd (if you are used to LaTEX). Most important, a sectioning command gives a relative position in the hierarchy; this means that commands like \rootsectiontype can be used to adjust the absolute sectioning in the final document. In this example, the topmost section would be a LaTEX \chapter by default, but it’s been changed to be a \part.

• More not-LaTEX trivia: the optional argument to \section serves both as a label name (for \ref, etc.) and as a node name for GNU Info files.

The following sections describe the more interesting parts of our LaTEX-like notation, illustrated in the example above. (Before that is a micro-tutorial on LaTEX conventions, in section 2.1.)

• As the example above showed, the sectioning commands diverge quite significantly from LaTEX. Section 2.2 gives the full details about sectioning.

• The example shows how program code is included in a document in the simplest way: just begin \begin{code} and \end{code} around it. Section 2.3 describes the more involved uses of this feature.

• Section 2.4 and Section 2.5 describe how to take full advantage of the cross-referencing and indexing facilities in your literate programs.

• Section 2.6 is supposed to include several complete examples of literate programs but IT IS NOT FINISHED YET.

Remember: Section 3 is (supposed to be) a complete reference document about the LaTEX-like commands you may safely use.

2.1 A micro-tutorial on our LaTEX-like conventions

LaTEX is a document preparation system (described in a book of almost that name, by Leslie Lamport), and its notation is the basis of that used in this literate programming system. Unsurprisingly, one thing you can do with your literate programs is turn them into real LaTEX documents (for typesetting), using the program lit2latex.

A few things to know about our literate-programming markup notation:

• Backslash (\) is the starts-a-command character. Therefore, \item and \/ are commands, but dog and (+) are just plain text.

• Mandatory arguments to a command are given inside curly braces. So, we would use \foo{bar} to pass one argument to the command \foo; we would use \bar{hey1}{hey2} to pass two arguments to the command \bar.

• Optional arguments to a command are given in square brackets and come before mandatory arguments. So, for example, \help[everyone]{lunch} passes one optional and one mandatory argument to the command \help.

• \foo is a command called “foo”, while \begin{foo} ⟨text in-between⟩ \end{foo} is an environment called “foo” with ⟨text in-between⟩ being inside that environment.

• The above isn’t everything you need to know.

2.2 Sectioning commands

[APRIL91: After you read this, you may want to see some proposed changes in section 9.1.4.]

2.2.1 The \section<n> command

There is really just one sectioning command:

\section<n>[Info-node-name]{Section heading}

where <n> is a positive integer, the sectioning depth. For example, you might have:

\documentstyle[literate]{book}
\rootsectiontype{\chapter}
\begin{document}
\section1[Node-1]{The top}
\section2[Node-2]{The next level}
\section3[Node-3]{The bottom level}
\section3[Node-4]{More on the bottom level}
\section2[Node-5]{Second part of the middle level}
\section3[Node-6]{Bottom level, next section}
\section3[Node-7]{Last section on bottom level}
\end{document}

As a convenience, the following synonyms are supported:

\section           \section1
\subsection        \section2
\subsubsection     \section3
\subsubsubsection  \section4

Saying \rootsectiontype{\chapter} causes \section1, \section2, and \section3 to be

translated into the LaTEX/Texinfo commands \chapter, \section, and \subsection, respectively. This system supports deeper section nesting than LaTEX (12 levels vs. 7).

If you want a section heading but don’t want anything to appear in the table of contents, put a * after the command name (just like LaTEX); for example:

\subsection*[\pageref]{\pl{\pageref{<label-or-node-name>}}}

If you want something that looks like a section heading but really isn’t (no table-of-contents entry, no Info node), you probably want the \heading{<title>} command.

[Support your local creaky implementation: you must put sectioning commands on lines of their own.]

In making an Info file, the hierarchy of \section<n> commands will be turned into a corresponding hierarchy of Info nodes. With info, you navigate along one level of the hierarchy with Next- and Prev-node links; you move up the hierarchy with Up-node links; and you move down the hierarchy (e.g., from a \section<n> to its \section<n+1>s) by choosing from an (automatically-generated) Info menu.

2.2.2 How to use \section<n>

The presumption is that every file in a literate document will begin its sectioning with a \section (equivalently, \section1) and further sectioning will reflect a reasonable hierarchical structure within the file. You usually know this when you are typing in a particular file.

What you often do not know is how the file fits into the larger document, and it is most annoying (as happens sometimes with LaTEX) to have to rename all \chapters to \sections, or some such. The information on how things go together is usually in a “root file,” which sticks things together with \input, \downsection and \upsection; this example is typical:

 \section[Desugar_match]{@match@: compiling out pattern-matching}
 \downsection
 % each of the following files would start with a \section
 \input{Match.lhs}
 \input{DeTwiddle.lhs}
 \input{MatchCon.lhs}
 \input{MatchLit.lhs}
 \upsection

The \upsections and \downsections determine what actual LaTEX/Texinfo sectioning command is generated for a particular \section<n> command. Unfortunately, the desired LaTEX/Texinfo sectioning command for the top section in your hierarchy depends on the kind of document you are producing. For example, should it be a \part or a \chapter? The solution here is to let you choose, with the \rootsectiontype{\foo} command. It says that \section1s at the “top level” should be typeset as LaTEX/Texinfo \foo’s. The defaults based on the \documentstyle should usually be adequate:

\documentstyle  \rootsectiontype
article         \section
report          \chapter
book            \chapter

For a report, a useful variant might be \rootsectiontype{\part}.

2.2.3 The \sectiontype and \sectionref commands

Another annoying thing with LaTEX sectioning is to type Section~\ref{foo} only to have foo turn out to be a “chapter” (not a “section”). In this system, you can type \sectiontype{Node-name} and the type of the sectioning command at node Node-name (e.g., “chapter,” “section”) will be inserted [any unit below sections will be called “section”]. To have the inserted text be

capitalised, use \Sectiontype{Node-name}.
For the common idiom, \sectiontype{Node-name}~\ref{Node-name}, you may use \sectionref{Node-name}

(similarly for \Sectionref). [I use this all the time. –WDP]

2.2.4 GNU Info node specifications with \section<n>

[APRIL91: Don’t overlook the new ideas in section 9.1.4.]

When making an on-line Info document from a literate program, the text between two sectioning commands is turned into an Info node. Moreover, the sectioning commands are used to determine how the nodes should be linked together—almost always in the hierarchical structure implied by the sectioning. However, you can tweak the process as much as you wish (almost no-one ever wishes...).

Each \section<n> command may have an optional “node specification”, with which you may specify the name of the Info node and how it should be linked to other nodes. For common practice, I recommend giving a (unique) node name and enjoying the default links; for example:

\section[Foo-Sem]{Foo Semantics}

Besides serving as the node name, Foo-Sem will also be a LaTEX \label and may be \ref’d or \pageref’d: for example, you could say, “The semantics are given in section˜ \ref{Foo Sem}”. (This is more likely to work than introducing a \label of your own and \ref’ing that.)

Node names must not contain commas (and other unpleasant characters I don’t want to think about) and spaces are probably asking for trouble.

The next example shows the general form for a node specification, in which you want to specify all of a node’s links by hand:^{1}

1Ignore the rest of this section unless you enjoy pain—it presumes some familiarity with Texinfo/Info specifics; see info info and/or info texinfo.

\section1[This-Node,Next-Node,Prev-Node,Up-Node]{Bar Semantics}

A ? may be given for any of the four node-names; then the default is used:

1. The default node-name is the section number.

2. The default next-node is the one associated with the next same-level sectioning command (i.e., the next \section<n> command if this is a \section<n> command.

3. Analogously for the default previous-node…

4. The default up-node is the last-seen next-level-up sectioning command, e.g., if at a

     \section<n>, then the last \section<n-1> command seen.

Any text before the first \section command goes in node Top, which has node specification

“Top,,,(dir)”.
The recommended form \section[Foo-Sem]{Foo Semantics} is just short for \section1[Foo-Sem,?,?,?]{Foo Semantics}.

Additional Info nodes that are unrelated to sectioning commands may be added with the \node command. [Note: not well tested.]

If you want a LaTEX-style sectioning command (e.g., to specify a table-of-contents entry), use

onlyinfo and onlylatex environments.

2.3 Including program code in your document

Central to literate programming is having program code in your document that can be directly extracted and compiled/executed.

2.3.1 The usual ways to put code in a documents

The most straightforward way to do this is to put all the code in a file in one or more \begin{code} ... \end{code} environments—the code can then be extracted (in the order it appears in the text) and fed to your favourite compiler/interpreter/whatever.

An equivalent notation preferred by some is “Bird tracks”, so-called because it started with Richard Bird (and because Cordy calls them that); lines starting with a > are extracted; for example:

>main _= [AppendChan stdout "hello, world\n"]

is equivalent to:

\begin{code}
main _= [AppendChan stdout "hello, world\n"]
\end{code}

A block of Bird-tracked code lines must have a blank line before and after (not having one usually indicates a typo).

Comment: ToDo: Simon wants to know how code looks in (a) a LaTEX’d document and (b) an Info’d document.

2.3.2 Code ribbons: the fancy stuff

Both of the above are shorthand notation for messier stuff going on underneath... Strictly speaking, the code in a particular document is made up of one or more ribbons of code. For example,

A common thing to say to the world is ``Hello, world!''
\begin{code}[hello-goodbye]
void HELLO() { printf("HELLO, WORLD!\n"); }
\end{code}
However, you might want to be less exuberant:
\begin{code}[wimp]
void hello() { printf("hello, world!\n"); }
\end{code}
And perhaps you are trying to tune out, not tune in.
\begin{code}[hello-goodbye]
void goodbye() { printf("Good-bye, cruel world...\n"); }
\end{code}

As always, code to be extracted goes inside a \begin{code}...\end{code}; the optional argument after \begin{code} is the name of the code-ribbon to which the program-text belongs. The example above has two ribbons, hello-goodbye and wimp. You can extract any coderibbon(s) you wish [see lit2pgm’s -r option]; the disjoint pieces of a particular ribbon (e.g., hello-goodbye above) are catenated together in the order seen.

Usually, this ribbon-business is just a bother, so there is the good ol’ default ribbon, main. For example, the way-you-normally-write-things:

\begin{code}
void adieu() { printf("Adieu, cruel world...\n"); }
\end{code}

is actually short for:

\begin{code}[main]
void adieu() { printf("Adieu, cruel world...\n"); }
\end{code}

Unsurprisingly, main is the default code-ribbon when one is in the ribbon-extraction business. Similarly, code included with > signs in the leftmost column (“Bird tracks”) is just tacked onto the main ribbon, too:

>void
>adieu()
>{ printf("Adieu, cruel world...\n"); }

2.3.3 Code reordering with \insertribbon

If you are feeling particularly notorious, one piece of code may be appended to several ribbons (a comma-separated list of ribbon names, please—spaces are significant except for beside the commas):

\begin{code}[ribbon1, ribbon2, ribbon3]
void adieu() { printf("Bon soir, cru\\'el world...\n"); }
\end{code}

To get the effect of WEB-like parameterless macros, one ribbon may use \insertribbon to include a copy of another one, as in:

\begin{code}
void adieu()
    \insertribbon{message}
\end{code}
\begin{code}[message]
{ printf("Adieu, cruel world...\n"); }
\end{code}

ToDo: CHANGE \insertribbon SO IT’S OUTSIDE OF code ENVIRONMENT.

I don’t recommend \insertribbon. You can make a terrible mess with it. I haven’t tested it for months.

2.3.4 Stuff that looks like code but isn’t

If you want to include alternate versions of code (for illustrative purposes, presumably), to be typeset as code but not subject to extraction by lit2pgm, put the extra versions in pseudocode environments.

2.3.5 Magic things you can put in your code

Generally speaking, you enter your program code inside a code environment exactly as you would otherwise (the principle discussed in section 1.1.4), and it will appear in your documents as shown (nicely typeset, we hope). There are two magic things that you can put in your code that do not appear in your document (directly):

Index entries: Code is automagically indexed, but you may wish additional index entries of your own choosing.

Hidden comments: You will sometimes want comments in your actual code that you do not want printed. An example: you might want to record next to each code block the names of the the test files used to exercise it. This is really boring information to all but the most dedicated reader.

In both cases, the information could be provided outside the code environment (i.e., without any special construct), but it could quite easily get lost (code blocks can be big, even if they shouldn’t be :-).

In all cases, these annotations are in a form recognised as a comment by the compiler/whatever for that language. Please see section 4 for the exact form used for the language you are interested in. A Haskell example of both magic bits might be:

\begin{code}
main _= [AppendChan stdout "Hello, world...?\n"]
--idx:: world, state of
--hide:: use testfile093.hs
\end{code}

[APRIL91: Yell if you really dislike (or like) these two forms of “magic things in code”.]

2.4 Cross-referencing

For cross-referencing, the normal thing is to use node-names on sectioning commands as labels,

and to \ref{<label>} and \pageref{<label>} them, as is the LaTEX custom. \pagerefs

are discouraged, as there is no concept of page numbers in Info files.

Similarly, if you heave in a \label{<some text>}, the Info side of things will assume that <some text> is just another label for the current node [NOT IMPLEMENTED (ToDo)].

APRIL91: Cross-referencing is normally used to help you move from a use of a code-thing to its definition. There should probably be an option to let you get cross-referencing that will also let you move from a definition to all of its uses.

2.5 Indexing

[APRIL91: changes are envisaged; see section 9.1.2.]

Indexing is assumed to work with the program makeindex, so you should put a a \printindex command where you want the index to appear (almost always just before \end{document}). (A LaTEX \makeindex command is supplied automagically before \begin{document}.)

Roughly speaking, code portions of your document are automatically indexed, and then you index the text portion manually, with \index commands.

\index{<entry text>} is the basic indexing command and offers a simplified makeindex interface.

• If you want just plain simple “foo” to appear in the index, use \index{foo}.

• If you want subitems in an index entry, separate them with !s [useful].

• If you want separate text for sorting and printing an index entry, put the two texts in that order, separated by an unescaped @.

• To put a ! or @ in your index entry, escape it with a backslash \.

• All other (semi-normal) characters work as is.

I don’t encourage trying to have index entries pop out in different fonts—it doesn’t work in plain Info files. You can write devious LaTEX/makeindex code on your own...

Code-stuff in text (stuff inside @...@) is indexed automatically, just like “real code”. What actually happens depends on the support for your programming language—section 4 gives all the language-specific indexing idiosyncracies. The default bare-bones mechanism is that whitespace-free code-in-text over three characters long (e.g., @typecheck@) will generate an index entry. To suppress automatic indexing of a piece of code-in-text, put a \noindex immediately following, as in @typecheck@\noindex.

As mentioned in section 2.3.5, you can add index entries for your code by inserting speciallyformatted comments (this depends on how well your programming language is supported). For example, for Haskell, you might use [NB: NOT IMPLEMENTED YET (ToDo?)]:

f x y z = (y z) x
-- the next line is a comment that will cause an index entry
-- equivalent to: \index{foo-bar-baz}
--#idx::foo-bar-baz

For a chunk of code, a mini-index pointing to the definitions of the things it refers to (one possible definition of “things:” top-level functions) will be produced right after the code. (For the Info file, as part of the menu for that node.)

Comment: The Info part is done; I’m still thinking about what should be done for LaTEX. [APRIL91:

this is one of the things contemplated in section 9.1.2.]

At least some provision has been made for “stop lists” for the automagical indexing (I’m not sure how well it works...). You put words/strings that are normally picked up by the indexing into a file, then tell the system this is your “stop list file” (-s option, I think), meaning “Don’t index these things—I’m not interested.”

2.6 Some complete examples [NOT FINISHED]

NOT FINISHED YET. Some day...

Meanwhile, you will find some reasonable not-over-huge examples in the literate/tests directory in the source.

2.6.1 A simple example

2.6.2 A typical example

2.6.3 A hairy example

2.7 Helpful short-cut notations

APRIL91: There is discussion about these sorts of things scattered through the “new ideas” in section 9.1.

2.7.1 Referring to code things in your text

In the text part of a literate program, one often wishes to refer to things in the code (e.g., function names) or have code expressions in the running text, and so forth. One would like this code-in-text to be typeset just like the real-code-parts (currently verbatim, but that could change). To mark off code-in-text, surround it with ‘at’ signs: as in @code in text@; to put an ‘at’ sign in in-line code, you’ve got to put in two ‘ats’: @x @@ (y, z)@. Line-breaks are prevented inside “attified” code-text.

Because things inside ‘at’ signs are so often just what you want to be indexed, the rule is: if the at-signed thing contains no whitespace, an index entry is generated. (How to prevent indexing and how to do fancier things about indexing and cross-referencing are given section 2.5.)

APRIL91: see comments in section 9.1.8.

2.7.2 Using different “fonts” in your text

[APRIL91: Be sure to see section 9.1.9.]

The \tr{<text>} command sets <text> in typewriter font, with no need for escape characters or anything—provided the braces nest properly.

The same trick using a “plain” (roman) font is \pl{<text>}, to produce ⟨text⟩.

3 LaTEX-like markup commands: reference

This section assumes you are familiar with the tutorial-ish material in section 2. It also assumes some familiarity with LaTEX, in that I may say say, “It works as in LaTEX”.

The lists below catalog the environments (\begin{...}/\end{...} things) and commands (backslashed \things) of our Glasgow literate-programming notation. [For this clunky implementation, the \begin{...} and \end{...} delimiters should be on lines by themselves, beginning in the leftmost column.]

Occasional mention is made of the main programs used to process literate files: lit2pgm, which extracts the code from a file; lit2latex, which creates real LaTEX source from a file; and lit2texi, which creates Texinfo source from a file (from which Info files can be made

with makeinfo).

Little things first:

• In text, you should use the TEX style of double quotes: ``foo''.

• In text, backslashed magic characters, e.g., \& \_\# \$, will produce the self-same de-backslashed magic characters in the output.

• Accents on characters (e.g., \'e) are fine; they are tossed from Info files.

• You may safely use the italic correction \/.

• At least the font-fiddling declarations \sc and \tt will work; they are heartily unrecommended. APRIL91: see the comments in section 9.1.9. Also, make them commands, not declarations?

Commands and environments (in alphabetical order):

\appendix

Section numbering after this command is for appendices. (Has no effect on Info files. ToDo: it probably should.)

\author{⟨text⟩}

Please see under \maketitle.

center environment

As for LaTEX. [APRIL91: Not implemented (and not sure how to do it easily on the Texinfo side), but I need to do something because Simon keeps using it.]

\centerline{⟨text⟩}

As for LaTEX.

\caption{⟨text⟩}

As for LaTEX; likely to be unsatisfactory for Info files because the latter doesn’t do figures.

\clearpage and \cleardoublepage

As in LaTEX; no effect on Info files.

code environment

See section 2.3. Also, don’t forget the pseudocode environment. You cannot nest other environments inside code environments.

comment environment

Text in a comment environment will be output (perhaps with extra indentation, smaller font, etc.) if a \suppresscomments command hasn’t yet been encountered. [NB: \suppresscomments doesn’t work with lit2texi.] A comment environment cannot include another comment environment.

\date{⟨text⟩}

As for LaTEX; please see under \maketitle for exact details.

\define{⟨command⟩}{⟨replacement⟩}

Ultra-simple macro substitution, NOT LIKE LaTEX. The text for <command> will be replaced with <replacement>; no nesting, no funny characters, nothing fancy. Don’t \define the same <command> twice, for example. Intended for customising documents; please see the note

under \input.

Defaults are provided for \Haskell, \LaTeX, \TeX and \ldots. More defaults on request. APRIL91: see section 9.1.6 for what I would REALLY like to do about “defining”.

description environment

As in LaTEX.

display environment

Similar to verbatim (line-breaks are obeyed) but formatted in the prevailing font (not necessarily typewriter). There is a flushdisplay environment as well. You can’t nest one display environment inside another.

\documentstyle[⟨style-options⟩]{⟨doc-type⟩}

You do not have to the literate LaTEX style option; e.g., \documentstyle[literate]{report},

but it is probably a good idea so people don’t think you’re writing real LaTEX. \documentstyle has two magical actions: (1) the type of document (report, article, etc.) determines the default value for \rootsectiontype, and (2) it indicates that a standalone document is being generated (not just a part of one). [APRIL91: bear in mind that this standalone business is in jeopardy.]

{\em ⟨text⟩}

The \em (emphasize) declaration works just as in LaTEX. APRIL91: make it a command, not a declaration, i.e., \em{⟨text⟩}?

enumerate environment

As in LaTEX.

figure environment

Goes straight through for LaTEX; ignored for Info files, meaning that whatever is inside won’t “float.” (Remember: we don’t really do figures; see section 1.4.1.)

flushdisplay environment

Same as the display environment, except it is not indented relative to the left margin. You can’t nest one flushdisplay environment inside another.

flushverbatim environment

Same as the verbatim environment except that text is not indented relative to the left margin. You can’t nest other environments inside a flushverbatim environment; see the note in section 3.

\footnote{⟨text⟩}

Footnotes work! NB: with makeinfo, you may choose one of two ways of doing footnotes in an Info file. By default, they will be at the bottom of the node (style BN), as opposed to in a node of their own (style MN). [ToDo: update the makeinfo info]

\heading{⟨title⟩}

A pseudo-sectioning command that formats title as if it were a section heading (no numbering or any of that rot), but it doesn’t put anything in the table of contents, no Info node, no anything weird.

\index{⟨entry⟩}

Roughly as for LaTEX with makeindex. Don’t try anything too weird: for example, \index{<mumble>} inside a footnote doesn’t work. Warning: full-blown makeindex-style indexing has been “simplified”: please see section 2.5 for the full gory (but wonderful!) details.

\input{⟨filename⟩}

Be sure these are on lines by themselves and start in column 1. The argument should be the full filename—no implied suffix. Files will be searched for along the LITINPUTS path, specified by an environment variable of the same name. The default path includes only your current working directory.

\inputs are only followed at link time; if that’s not what you want, either give the appropriate command-line flag (-n) or use \inputnow.

APRIL91: see section 9.1.6 for some thoughts about how inputting may be changed.

\inputnow{⟨filename⟩}

These are \inputs that are followed always, no matter what. Otherwise, they are the same.

APRIL91: \inputnow may go away at any second.

\insertribbon{⟨ribbon-name⟩}

Used to insert the text of one code-ribbon into another; see section 2.3. Must share a line with nothing but whitespace. Not recommended.

ToDo: needs to be made to work outside of code environments, rather than inside them.

DOES NOT WORK WITH lit2pgm -q! (which is what we often use.)

itemize environment

As in LaTEX. British spelling (“itemise”) also accepted.

\label

Free-standing \labels [supposedly] work as expected in LaTEX; in Info files, a \label is taken as just another name for the node the \label is in. Determining which node it’s in doesn’t take account of \inputs—it’s the one it “appears” to be in—which may not be what you want. You really should use node-names as labels (see section 2.2.4)...

Labels (and, therefore, nodenames) shouldn’t have weird characters in them. Such labels (nodenames) will be studiously ignored.

\listoffigures and \listoftables

As for LaTEX; has no effect on Info files, which don’t do lists of figures or tables.

\makeindex

Not necessary even for LaTEX—one is inserted automagically just before \begin{document}; has no effect on lit2texi.

\maketitle

Will work as in LaTEX for simple cases, using values provided by \author{<author-stuff>},

\title{<title-stuff>}, and \date{<date-stuff>}. The \\ line-breaker works. You die if

you try anything weird.

For better or worse, if you use the -g option (to “grab” a subtree of text for printing), then it does matter if the \maketitle is in the pre-amble (before \begin{document}) or not. Please see section 7 for the sorry details.

menu environment

In producing an Info file, text in a menu environment is copied verbatim to create an Info menu. You must provide something that Texinfo can grok. This whole mess might be used in conjunction with \suppressmenu [if \suppressmenu were implemented yet].

APRIL91: this should probably be nuked if the rawtexinfo environment comes online.

\menuentry{⟨tag⟩}{⟨description⟩}

Requests that an extra menu entry be put at the beginning of this section’s menu.

\node{⟨node-spec⟩}

(Ignored for LaTEX.) Makes an extra node in the Texinfo file; the <node-spec> is copied straight through to the output, so it’s your problem to include something sensible.

APRIL91: nuked if rawtexinfo environment comes in?

\pounds⟨something-like-a-number⟩

The \pounds must be followed by: zero or more whitespace characters, a digit or a question mark, zero or more digits/question-marks/commas/full-stops/the-letters-K-or-M, and a digit/question-mark/the-letter-K-or-M. The Ks or Ms may be in lower-case. The mind boggles.

onlyinfo environment

Only the Texinfo/Info extraction program(s) pay attention to stuff inside. Don’t put code in here!

APRIL91: this stuff is in jeopardy of disappearing.

onlylatex environment

Only the LaTEX extraction program(s) pay attention to stuff inside. Don’t put code in here!

APRIL91: this stuff is in jeopardy of disappearing.

onlypartofdoc environment

The extraction programs pay attention to stuff inside only if they believe this is just a piece of a document (i.e., “separate compilation” is going on). As always, don’t put code in here! See the \standaloneornot command for a shortcut.

APRIL91: this stuff is in jeopardy of disappearing.

onlystandalone environment

The extraction programs pay attention to stuff inside only if they believe that a standalone document is in the works (i.e., a \documentstyle command has been seen or the -S flag given). As always, don’t put code in here! See the \standaloneornot command for a shortcut.

APRIL91: this stuff is in jeopardy of disappearing.

\pageref{⟨label-or-node-name⟩}

In making LaTEX documents, works as usual. In making Info files, treated as a \ref (there is no concept of “page” in an Info document).

\pl

Plain text, set in a roman font; equivalent to \mbox{\rm #1}, except that the argument can include any old printable ASCII characters, including properly-nested braces (escaping them is irrelevant). If you want to do something weird, do it another way. Note that linebreaks within the \pl are prevented.

The equivalent typewriter thing is \tr.

APRIL91: see possible changes in section 9.1.9.

\printindex

Should be just before \end{document}. In Info mode, generates a node ‘Index’ at the same sectioning depth as your top-level sectioning commands.

APRIL91: see possible changes in section 9.1.2.

pseudocode environment

Format the same way as in a code environment, but the enclosed stuff is not subject to extraction by lit2pgm.

Other environments do not nest inside a pseudocode environment.

quotation environment

As in LaTEX.

rawlatex environment

If lit2latexing, copies the body of the environment straight through. Otherwise, discard it.

One trick you may need: because of the feeble implementation, the system may still try to “follow” an \input inside a rawlatex environment (which it shouldn’t). The solution is to “hide” the \input so it isn’t first on a line:

\begin{rawlatex}
\begin{figure}
{}\input{weird-fig.ps}

\caption{Weird Figure}
\end{figure}
\end{rawlatex}

\ref{⟨label-or-node-name⟩}

As for LaTEX.

\rootsectiontype{⟨real-sectioning-command⟩}

Please see section 2.2.

\sectiontype{⟨nodename⟩}

Please see section 2.2.3.

\sectionref{⟨nodename⟩}

Please see section 2.2.3.

\standaloneornot{⟨ifso⟩}{⟨ifnot⟩}

If doing standalone-document processing (i.e., a \documentstyle seen or -S flag given), use text <ifso>; otherwise, use text <ifnot>. Keep this on one line by itself, OK?; for longer things, use the onlystandalone and onlypartofdoc environments.

APRIL91: this stuff is in SEVERE jeopardy of being nuked; see section 9.1.6.

\suppresscomments

Best put in the preamble of your overall document (i.e., before \begin{document}). Causes text in all subsequent comment environments to be ignored. NB: only works in producing LaTEX documents. (ToDo: fix this)

table environment

Goes straight through for LaTEX; ignored for Info files, meaning that whatever is inside won’t “float.”

\tableofcontents

As for LaTEX; adds extra stuff to the top-level menu in an Info file.

tabular environment

Same format as LaTEX, but anything magical beyond &, \\, and \hline will probably get you in trouble.

Other environments don’t nest inside a tabular environment.

\title{⟨text⟩}

Please see under \maketitle.

\tr

Set in typewriter font; equivalent to \mbox{\tt #1}, except that the argument can include any old printable ASCII characters, including properly-nested braces (escaping them is irrelevant). If you want to do something weird, do it another way. Note that linebreaks within the \tr are prevented.

The equivalent non-typewriter thing is \pl.

APRIL91: see section 9.1.9 for further comment on this stuff.

verbatim environment

As in LaTEX—line-breaks are obeyed and everything is in typewriter font. See also: the

flushverbatim and display environments.

You can’t nest other environments inside verbatim environments. A trick (hack) you can use to put a verbatim environment inside another is to indent the inner one by one space, as in:

 \begin{verbatim}
  ...
  \begin{verbatim}
  ...
  \end{verbatim}
  ...
 \end{verbatim}

4 Language-specific processing

This section describes the processing of code in documents that is done in a language-specific way. This is mainly to do with indexing, typesetting, and similar matters. First, however, we give the default rules used when the programming language used is unsupported or unknown.

4.1 Rules for unknown or unsupported languages

[Not finished yet.] No hidden comments or explicit index entries in code.

4.2 Language-specific rules for Haskell

[This section is not finished yet.] An explicit code index entry comment is of the form: --idx::<whatever>, on a line of its own. A hidden comment is of the form: --hide::<whatever>, on a line of its own.

4.3 Language-specific rules for perl

[This section is not finished yet.] An explicit code index entry comment is of the form: #idx::<whatever>, on a line of its own. A hidden comment is of the form: #hide::<whatever>, on a line of its own.

4.4 Language-specific rules for C

[This section is not finished yet.]

4.5 Language-specific rules for FORTRAN

[This section is not finished yet.] The FORTRAN-specific support was provided by Adriaan Joubert (adriaan@dcs.qmw.ac.uk).

5 A checklist of good literate habits

[Suggestions welcome. Haven’t worked on this in a while.] • Express your ideas in a way amenable to plain ASCII representation, as well as that of

full-blown TEX typesetting. For example, serious TEX math-mode stuff is not really on (even if you can get it past lit2latex). If you find this constraint a big problem, you may well be using the wrong tool for the job.

• If you test your document first as an Info file (i.e., use lit2texi to process it), once that is right then it is very likely that the LaTEX side of things (using lit2latex) will come out right as well. The reverse is not true.

• Follow the convention that the sectioning in every file begins with a \section. For details on how to do sectioning, please see section 2.2.2.

• Arrange your document so that your Info nodes come out no more than two screenfuls’ long. Very long nodes obviate the whole point of Info documents.

• It’s hard to make up good sets of Info node names. First, they must be unique! Second, it’s best if the uniqueness is in the first few characters, so that nodename completion may be used to most advantage.

6 Caveats: bugs and foibles

As mentioned in section 1.4.3, the initial implementation of this literate-programming system is delicate at best.

1. Environment-commands should be on lines of their own, and preferably start in column 1; the latter is especially important for verbatim environments.

2. The line numbers reported with errors stand a fair chance of being wrong or even laughably irrelevant. LaTEX doesn’t report errors in terms of their original source anyway at all... (urgh)

3. \Define-itions (incl. the built-in ones for Haskell, LaTEX, etc.) are expanded inside \tr and friends.

4. You can get confused \items (in enumerations, etc.) if you have:

\item[... stuff here... ]   ...................... ]
 right bracket on the same line -------------------^

The solution (and it’s better style anyway) is to put \items on lines of their own. This is a vestige of the implementation...

5. Don’t put \index commands inside footnotes. There are probably some other related restrictions... (ToDo)

6. Tabs in code will be expanded to spaces. This matters only if you have tabs in string constants, or some such (which you shouldn’t, because it’s hard for the reader of your code to see what you’ve done; use \t or the equivalent).

7. If you use the cross-referencing (-D, I think), you have the annoying feature of crossreferencing to things very near by, even on the same page. I don’t know how to stop this.

7 Programs to process literate documents

In this incarnation, the programs lit2pgm, lit2latex, and lit2texi (to extract program, LaTEX, or GNU Texinfo fodder) are just three ways of invoking one killer perl script, lit2stuff.

[Actually, this same script may be invoked as mkdependlit, to build a set of make dependencies for a literate document, as lit2text, to extract just the non-code text (perhaps for spell-checking), or as lit2changelog, which is the (mainly unimplemented) interface to the changelog-slurping code. I ignore these details herein.]

APRIL91: there are starting to be enough options that getopt-style one-letter names aren’t enough/too obtuse. Some revision may be in order there... See section 9.1.17.

For all three programs, their invocation takes the form lit2<whatever> [options] [input-file]. Usually, output is to a file determined from the input-file’s suffix (e.g., a .hs file from a .lhs file); if no input file is provided or life becomes confused, output is to the standard output. You can control input and output explicitly with the -i and -o options.

Known file suffixes and what they mean:

.lit a literate-document file with no code in it (e.g., this one)
.lhs literate Haskell source
.lprl literate Perl source
.llex literate Lex source
.lc  literate C source
.lh literate C header source
.ltex literate TEX macros
.lf  literate FORTRAN

The suffixes .itex and .itxi indicate the intermediate files from “separate compilation” (to LaTEX and Texinfo, respectively) of parts of a larger document.

In ordinary life, given a literate C program foo in file foo.lc, one would hope that the following simple invocations would suffice:

lit2pgm foo.lc
gcc -o foo foo.c
lit2latex foo.lc
latex foo.tex
lit2texi foo.lc
makeinfo foo.texi
# (and if you really want to make things right, use the script...

postmakeinfo foo.info
# as well)

What follows are the options to control these programs (and to complicate your life [and mine, too]). Not all command-line options make sense for all three programs; they are so noted. Options may be glopped together in the best getopt(3) style.

-A ⟨pgm-name⟩ option

(For hackers only.) Assume the program was invoked as <pgm-name>. must be the first option given. Still has to be either lit2pgm, lit2texi, or lit2latex.

-c option

(Not lit2pgm.) Produce Texinfo or LaTEX output (as appropriate) but don’t try to “link” together with other parts of the same document. Think of the -c option to a C compiler...

-d option

Print debugging information. I will be monumentally surprised if this is of any use to you!

-D option

(lit2latex only.) Print cross-references to code definitions in the text.

APRIL91: this option stands some chance of being renamed if the pseudo-C-preprocessor comes in; see section 9.1.6.

-f ⟨nodename-suffix⟩ option

(lit2texi only.) Append the string <nodename-suffix> to every nodename in a file. This can be useful if you’re trying to avoid nodename clashes between nodes in different parts of a big document (two of which might, for example, have nodes named “Introduction”).

APRIL91: A feeble solution; see section 1.4.2.

-g ⟨node-name⟩ option

(lit2latex only.) Grab the sub-tree of text for which node <node-name> is the root. Used when you want to print a whole chapter or section or something, rather than just one Info node.

At this time, this option is only suitable for printing drafts.

What is actually done: the output LaTEX-file consists of the pre-amble (really: everything before the first \section command—not quite what you want), the subtree you asked for, and \end{document}. Your section will be numbered 1 no matter what.

-H ⟨dir1⟩:⟨dir2⟩ option

(For hackers only.) Used by villanous people to override the hardwired directories (<dir1> for platform-specific files and <dir2> for platform-independent perl libraries) where the literateprogramming system finds its stuff. Also see the -A flag.

-i ⟨input-file⟩ option

Specify a specific input file. If not specified with -i, then the first non-option command-line argument; if no such thing, then standard input. You may also specify standard input as the “input file” with -i -.

-I ⟨directories⟩ option

Add (colon-separated) <directories> to the front of the default path used to follow \input commands (just . at the moment). Only give one -I option; I cannot promise what will happen if you give more than one.

Slight magic: the . in the path means: first, look in the directory where the file doing the \input’ing is; if not there, look in the current working directory. (This is usually what you want.)

-L option

(lit2texi only.) Alternate style of node linking—puts in more defaults for “next” and “previous” nodes. If a node doesn’t have a “next” [“previous”] at its level (e.g., it’s the last section in a chapter), then its “next” [“previous”] node will be the physically-next [-previous] one, regardless of sectioning level. (The default is for such nodes to have no next [previous] node.)

[I like the -L node-linking scheme but makeinfo issues warnings about it. APRIL91: newer version of some Info readers achieve the same effect using additional moving-around-the-tree commands.]

-l ⟨language⟩ option

(Not lit2pgm.) Assume that any code in the input file is written in ⟨language⟩ and process accordingly (automatic indexing, etc.). The ⟨language⟩ is normally intuited from the inputfile suffix (e.g., .lhs suggests Haskell code). The -x, -p, and -t options may be used to tweak cross-referencing, page-breaking, and typesetting of code, respectively.

-n option

Follow \input commands.

-N ⟨info-filename⟩ option

(lit2texi only.) Arrange for the Info file to be called <infofilename>. By default, for input file foo.xxx, the Info file will be called foo.info. For a multi-file document, the Info filename will be derived from the name of the first file encountered.

-o ⟨output-file⟩ option

Specify a specific output file. If not specified with -o, then it’s determined by puzzling over the input file’s suffix (see the -i <input-file> option). When in doubt, it reverts to the standard output. You may also specify standard output as the “output file” with -o -.

(For hackers only.) If the first character to the -o argument is a |, then the output is piped through the shell command(s) that presumably follow.

-O option

(lit2texi and lit2latex only.) At the beginning of each section, list the owner of the source file from which it was extracted.

[APRIL91: There is some doubt just how this option would work; see section 9.2.1.]

-p ⟨pagebreak-hints⟩ option

(lit2latex only.) The (language-specific) code for typesetting the code in the document is passed the ⟨pagebreak-hints⟩ to further control how it is determined where pagebreaks are allowed. This is because it is not always obvious where to do pagebreaks in long stretches of code.

These hints, if any, will be mentioned in the documentation of language-specific processing (Section 4).

[NOT IMPLEMENTED FOR ANY LANGUAGE]

-q option

(lit2pgm only.) Take quick shortcut. This will work if you are only using ribbon main (i.e., the usual recommended practice).

Should be much faster than the plain lit2pgm. The -q option will be the default in the Glorious new Haskell compiler.

-r ⟨ribbons-to-get⟩ option

(lit2pgm only.) Extract code-ribbons <ribbons-to-get> (comma-separated), instead of the default ribbon, main. An artifact of the implementation is that -r '' gets you main; use -r junkName to extract nothing.

-s ⟨stop-list-file⟩ option

(lit2texi and lit2latex only.) The file ⟨stop-list-file⟩ provides extra information for the automatic code-indexing about words that should not be indexed. One hacker’s dross is another’s gold.

[I’m not sure this is used for any language yet. ToDo: check]

-S option

(Not lit2pgm.) Process the input as if it is a standalone document. It is so processed if a \documentstyle command is seen, -S option or not.

APRIL91: in jeopardy of going away; see section 9.1.6.

-t ⟨typesetting-hints⟩ option

The (language-specific) routines for typesetting (really: outputting) the code in the document is passed the ⟨typesetting-hints⟩ to further control how typesetting is done.

These (comma-separated) hints, if any, will be mentioned in the documentation of languagespecific processing (Section 4). Available hints:

-t tgrind: Typeset code blocks by passing them through the tgrind program.

-t ruled: Put lines (rules) above and below blocks of code. (The default may vary with other outputting options.)

-t unruled: Do not put lines (rules) above and below blocks of code.

-t bird: Format all code (but not pseudocode) with Bird-tracks in the first column. By default, only code input with Bird-tracks is so formatted.

-t nobird: Format all code without Bird-tracks.

-v option

Be verbose. This is really a debugging thing, too.

-x ⟨xref-hints⟩ option

The (language-specific) code for indexing and/or cross-referencing the code in the document is passed the ⟨xref-hints⟩ to further control how things are done.

A general one you can use is -x noindex, to turn off code indexing.

These hints, if any, will be mentioned in the documentation of language-specific processing (Section 4).

An example might be using -l cpp -x extra:make on the configuration files for jmake. These files have both C pre-processor and make things worthy of indexing/cross-referencing, and these options would ensure that the code was put through the appropriate routines for both languages.

8 Using your processed literate documents

This section not written yet.

It’s supposed to be about all the neat ways to use your LaTEX- and Info-ised programs/documents.

9 APRIL91 PROPOSALS

9.1 New ideas

These ideas have piled up over the past six months. NONE OF THEM ARE IMPLE-MENTED. And some are TINY little things (and some are BIG).

JULY91: I have fleshed out the section 9.1.12 and section 9.1.13 comments, as these directions piqued the interest of some fellow GRASPers.

9.1.1 Make the commands look less like LaTEX

The biggest practical problem that has arisen among the (few) users of the literate programming stuff is that they think they’re writing LaTEX files and are surprised/disappointed when LaTEX fails to grok their files. We have been too successful in making the notation “LaTEX-like!”

One way to make the notation less LaTEX-like while maintaining the notation’s familiarity is to switch to mixed-case names, used in a consistent manner; for example:

CURRENTLY               WOULD BECOME ...
\documentstyle          \documentStyle
\printindex             \printIndex
\begin{flushleft}  \begin{flushLeft}

Command/environment names that are one word (e.g., \begin{enumerate}) would be unchanged.

Alternatively, we could make the literate-system case-insensitive where command names are concerned and merely make it our convention to use mixed-case names.

9.1.2 Multiple indexes

Having one index for a pretty-big program is a dubious proposition; you get a huge index. I think you need multiple indexes—in the case of a compiler, you might then have a separate index for: parser, typechecker, syntactic desugarer, optimiser, etc.

Let’s assume you index all the pieces of a compiler (as above) as self-contained units. PROB-LEM: it is the uses of functions, etc., that cross such boundaries that you would MOST like to have your attention drawn to.

That problem aside, I think this is the basic solution:

\defineindex{⟨index-tag-string⟩}: Says that ⟨index-tag-string⟩ is “legal” hereafter. Requiring/encouraging these \defineindex will help to catch typos.

\index[⟨index-tag-string⟩]{⟨entry⟩}: The \index command has an optional ⟨index-tag-string⟩ with which this ⟨entry⟩ should be tagged. The default tag string is main (unless reset

     with \setindex...; below).

\printindex[⟨index-tag-strings⟩]: Print an index here, made up from all the entries that have one of the ⟨index-tag-strings⟩. The default tag string is (same caveats...) main.

\setcurrentindex{⟨index-tag-string⟩}: Set the default tag string for \index commands in text.

I think you could use the mechanism above to come close to Texinfo’s idea about multiple indexes.

9.1.3 Better Haskell indexing

(The idea probably carries over to other languages.) Stick the whole literate-program Haskell source into an “interesting-thing finder” (call it htags :-), getting back (source-location, indexentry) pairs. Then the only trick is to tack each index-entry onto the code block nearest to the reported source-location.

9.1.4 Revisions to the sectioning commands

The main thing that is a pain about the current sectioning (see section 2.2) is making up unique node names all the time. I propose the following “system” for the optional arg to \section<n>; shown by example:

\section{⟨title⟩}: (As currently.) A default node name, made from the section number. No \label created.

\section[]{⟨title⟩}: No node name, no node, no \label. Not recommended :-)

\section[⟨the-usual⟩]{⟨title⟩}: (As currently.) Arguably, the stuff to let you specific next/prev/up explicitly should be dropped (to partly de-Info-ise the notation).

\section[˝ ]{⟨title⟩}: (The new one.) The node name should be the same as the ⟨title⟩ (“ditto”). No \label would be generated. Some massaging would be required to remove nodename-hostile characters from the title (e.g., colons).

9.1.5 A “BNF grammar” environment

This would work like the verbatim program used with the Haskell report; you could say:

\begin{grammar}
exp -> aexp
    |  exp aexp
    |  exp_1 op exp_2
    |  @-@ aexp
    |  @\@ apat_1 ... apat_n [gd] @->@ exp
    |  @if@ exp_1 @then@ exp_2 @else@ exp_3
    |  exp @where@ @{@ decls @}@
    |  @case@ exp @of@ @{@ alts @}@
    |  exp @::@ [context @=>@] atype
\end{grammar}

and respectable BNF-looking stuff would appear in your output. Index entries for the definitions of nonterminals would be generated; possibly a [noindex] option to suppress that.

I’d also like to do something for inference rules, but I’m fairly baffled about what that might be. (They can be mightily complicated, and it’s not clear that a plain-ASCII form is possible.)

9.1.6 Fake “C pre-processing”

Change things so that literate documents are first put through a “fake C pre-processor” (this section assumes you know what a C pre-processor does). Notes:

1. The relevant commands would start with ## (to avoid confusion w/ the real thing);

     hence, ##if, ##endif, ##define, ##include, etc.

2. (Very important.) This pseudo-C-preprocessor does NOTHING inside:

• Code environments (and the Bird-track equivalent).

• Verbatim environments.

• \tr and \pl commands (and any friends they may have).

• rawlatex environments (next section).

3. All of the current dubious only<this-or-that> environments and so on would go away; what you currently write as:

\begin{onlystandalone}
\documentstyle[11pt,literate]{article}
\begin{document}
\title{Glasgow Literate Programming\\ User's Guide}
\date{April 1991}
\maketitle
\begin{onlylatex}
\tableofcontents
\end{onlylatex}
\clearpage
\end{onlystandalone}

would be re-written as:

##if defined(STANDALONE)
\documentstyle[11pt,literate]{article}
\begin{document}
\title{Glasgow Literate Programming\\ User's Guide}
\date{April 1991}
\maketitle
##if defined(MK_LATEX)
\tableofcontents
##endif /* MK_LATEX */
\clearpage
##endif /* STANDALONE */

4. ##include would take the place of the current bogosity \inputnow.

5. ##define would take over from the current emasculated \define and would emphasise the point that this literate notation is a fixed notation, lacking general macros.

6. Running this or that program would pre-##define certain symbols (e.g., MK LATEX), but I don’t know exactly which just yet.

7. Using ##defines and ##ifdef’ing easily generalises the “standalone/partofdoc” dichotomy (which badly needs generalising).

9.1.7 Invisible code

I am wondering if we shouldn’t have a code environment of the form:

\begin{invisiblecode}
main (int argc, char **argv)

{

    printf("Hello, Seaworld!\n");

}

\end{invisiblecode}

for code that should be extracted (lit2pgm) but that should not be displayed in lit2latex/lit2texi documents. This would probably be used when you want to include most, but not all, of a program’s code—in a paper for publication, for example.

My only fear is that it is too easily subject to abuse.

Perhaps the C-pre-processing stuff is a better idea... (section 9.1.6).

9.1.8 Plain text in your code

In Knuth’s WEB, you can refer to code-things in the text parts of the document/program and to text-things in your code. (As I recall, putting | around text switches it to whateveryou’re-not-doing-now (code or text)).

We have the first (the @...@ shorthand to refer to code things while in text), but not the second: what’s in a code environment is code just like you would see in an illiterate program in the same language.

I guess the right solution is to have specially-marked comments (again, language-dependent) that say, “Don’t treat this as just a comment in this programming language, but extract it and mangle/massage it as if it were literate-document text.”

A pain to implement. Not worth it?

9.1.9 Using many “fonts” in text

I find the \tr (“typewriter font”) and \pl (“plain font”) commands quite useful. (Yes, I know they go against the intensional markup principle (section 1.1.5), but they are so convenient...)

I’m inclined to make up notations for italics, small caps, and bold (and their ASCII-only “equivalents”) and then try to systematize their use. Hmmm....

I’ve found the Texinfo attempt to have a command for every different kind of thing you might want to talk about in a document to be too much and also unsatisfying.

9.1.10 Formatting code-ish things in text

Right now, the @...@ shortcut notation means: Format this and automagically index it as for the code parts of the document.

Strictly speaking then, I think the @...@ notation should only be used to refer to things that actually exist in the code parts of the document, and not for code snippets, fragments, and other things mentioned along the way.

For this latter task, perhaps a \code[<language>]{<text>} command is in order. This says: format this ⟨text⟩ as for ⟨language⟩, but don’t index it or pretend that it actually has anything to do with the real code in the program.

9.1.11 Interface with plain LaTEX papers

At least in our setting, it is likely we’ve written one or more papers about some interesting part of the literate program we’re writing. The paper is likely to be:

• relatively polished (so you’d like to re-use that effort);

• either a decent introduction to some part of the program, or a succinct synopsis of some part;

• in straight LaTEX, but using features quite beyond our literate markup, and including figures, etc.;

• not to be changed in any way.

At the least, I’d like to be able to include the paper in toto, and have pointers into it (refs to its labels).

More/better ideas welcome.

9.1.12 A literate Para mode

[See also section 9.1.13.]

The sad fact is that, at the moment, these literate programs/documents are typed in as just plain files and manipulated as such. They are only processed into LaTeX/Info documents after the fact (and only occasionally).

Para mode is a GNU emacs mode that (roughly...) lets you both edit Texinfo files and jump around in them like Info files, based on the node structure. Either edit-as-normal or navigate-as-Info.

I think there are possibilities for doing the same thing with these literate documents/programs. Then you’d get the benefits of navigation, following indexery, etc., as you create the files.

One major problem (?): the literate sectioning makes it quite easy to navigate within a file, but, for it to be worth it, you’d like the “literate Para mode” (in navigation mode) to be able to carry you to the right place when you, e.g., want to go “up” from the first \section in a file.

Implementation: my first cut would be: run something over all the literate files in a program to collect “Para-useful” information; save this somewhere—this is the moral equivalent of a TAGS file. Then the navigation commands, etc., would use the pseudo-TAGS info to do their thing. Because the info would get out of date as you hack on your program, you’d re-make the pseudo-TAGS stuff whenever you stepped out for coffee, lunch, or sleep.

9.1.13 A lit2lit program (to help implement a Para system)

[This might be a better way to implement a literate Para ...] Have a program that takes a set of .lit files, munges them to do all the usual cross-referencing, etc., etc., and then writes out versions of the original files with all the linking info, etc., etc., inserted as comments. Call the program lit2lit...

If you took the lit2lit output and re-ran it through one of the other programs, e.g., lit2latex, it would produce exactly the same output.

The purpose of the information stored in comments would be to provide an Emacs mode (or something) enough information to help you jump around in a large program or generally do useful stuff.

For example, it might insert links and things for something like Bob Weiner’s Hyperbole system.

I’m thinking that lit2lit would be re-run over a system’s sources every night by cron(1).

9.1.14 Generating LaTEX documents especially for xtex

Xtex is a (free) DVI previewer with some hypertext-ish features; in particular, if you click on a reference to a label, then it takes you to the page where that label is defined. By generating a “LaTEX” document with all the linking info explicit (in the form of labels and references to them), xtex would do almost all the jumping-around stuff that info and xinfo do for you. And you don’t lose the font information.

9.1.15 A free-text “index”

OK, even with all the automagical indexing, cross-referencing, etc., occasions will arise when you say, “Help! I need to look absolutely everywhere for ⟨foo⟩!” (Like you do with grep/tags, but preferably nicer—all the tricks of the free-text indexing trade.)

It would be great to have a “free text index” button or pseudo-node (an Info “node” that, when you jump to it, puts you in a free-text-search mode. Of course, the free-text-search should be able to plunk you down in the Info node you finally select).

I really don’t want to implement this myself :-)

9.1.16 Other “magic” Info nodes...

The “free text index” magic Info node makes me wish for other nodes-that-do-weird-things when you jump to them... You jump to it and... it starts up a PostScript previewer and shows me a picture... or sound... or my text editor so I can send a gripe to the maintainer of foo... and so on.

9.1.17 Revise the way options are fed to lit2* programs

Using getopt(3)-style one-letter options is getting messy—there are too many of them. Perhaps time for something more complicated...

9.1.18 Mixing code in “Bird tracks” with other code

When you put something in a code environment, e.g.,

\begin{code}
main _= [ AppendChan stdout "Hi, Mom!\n" ]
\end{code}

there is no doubt about what should be considered the “first column”. On the other hand, if you see a “Bird track” equivalent:

> main _= [ AppendChan stdout "Hi, Mom!\n" ]

obviously the initial > should be stripped, but what about the space following? This matters if the code is to be put through, e.g., a C pre-processor, which looks for #’s in column 1.

The solution I lean to is to have an option that says how much whitespace should be stripped off the front of Bird-track style code lines.

9.1.19 Decouple code reading and printing styles

Code may come in either in code environments or in Bird-tracks. At present, it is printed in the same style as it came. This should remain the default.

However, it would be nice to be able to say (with options), “OK, print all the code as if it were in Bird-track form” (or vice versa). This allows uniform presentation, while preserving programmers’ preference for typing in one style rather than the other.

9.2 Old ideas that still haven’t gone anywhere

These are ideas that have been around for a long time, HAVE NOT BEEN IMPLEMENTED, and no-one seems to have minded much.

9.2.1 \owner{⟨name⟩}

(Not lit2pgm.) Give the “name” that should be listed as the “owner” of a section. If no \owner command has been seen, then the owner of the source file in which the first piece of text in the section was found is used.

[I haven’t really decided how this should work.] 9.2.2 Burying test cases in your document

The idea is that you can say:

\begin{test}{foo}
<Weird stuff in here>
\end{test}

For this test foo, the <weird stuff in here> would somehow say how to run the test, what should be fed to standard input (etc.), and what results to expect on standard output, standard error, and perhaps certain output files.

The idea is to put the (simple?) test cases right next to the code that will be exercised.

The problem is: tests can do pretty arbitrary things, and I don’t see any neat way to encode that fact. Simply bunging full-blown shell scripts into the middle of your literate program hardly seems the solution. Hmmm.....

If we had them: test environments don’t nest.

See ????? (ToDo) for a note on using hidden comments to highlight test information.

9.2.3 Recording changes to your documents

Vaguely like the test case stuff, you might say:

\begin{change}
<who> & <when> & <tag> & <description of first change> \\
<who> & <when> & <tag> & <description of second change> \\
... and so on ...
\end{change}

This is intended to be like the ChangeLog stuff supported in Emacs (C-x 4 a). It really only makes sense to use it after software is no longer undergoing cataclysmic change (after it is released perhaps?).

Anyway, the idea is to record your change notes right next to where you make them. [The program(s) to extract these notes and to collate them in the manner of your choice are not written yet.]

These change environments don’t nest.

10 SEPT92 THOUGHTS

These are further ruminations, having had another year to watch how people do and do not use this system.

Death to ‘ribbons’ and code re-ordering: No-one uses it, and it’s pretty clunky in this system, both conceptually and implementationally.

Suppressable ‘detail’: Be able to mark sections as ‘detail’, as well as to be able to put \begin{detail}/\end{detail} around arbitrary stuff. Obviously, you then want to format with/without the details in.

A minimally-extensible notation? Texinfo now supports setting and testing of variables, and the using the values thereof.

Support “all non-code is raw XXX”: Something like: given a flag -r latex, then all non-code would be taken to be pure LaTEX and wouldn’t be mangled at all.

Another likely possibility: a -r verbatim, to support the dubious verbatim script that’s popular in some circles.

Stop automagic indexing of code-in-text: I’m not sure it’s useful.

Throw out tree-grabbing (-g <node> option): Too hacky, not used, probably inadequate.

11 Standalone installation of Glasgow literate programming

NOT DONE PROPERLY YET.

Here are some short notes; they should work on a Sun4:

1. If you don’t have perl, go get it.

2. If you don’t have makeindex (normally with the TeX distribution) and/or tgrind, go get them, if you wish. You can easily get by without them, especially tgrind.

3. Customise for your local configuration, by creating a suitable mkworld/site.jm file. We supply a site.dist file that you can copy and work from.

Setting PerlCmd correctly is vital.

All the Haskell-compiler stuff isn’t important for the literate-programming system.

Setting TgrindHelperCmd is important if you’re going to try the tgrind-ing stuff.

Setting the things for installation (near the end) is vital. You will almost certainly need to set InstRootDir, and perhaps some others. If you don’t set anything, the literate-programming system will be installed (on a Sun4) in...

/usr/local/bin/sun4  things for the user to invoke (lit2mumble)
/usr/local/lib/literate/sun4 machine-specific support stuff
/usr/local/lib/literate  machine-independent support stuff

4. OK, you should be ready to go! From the top of the distribution...

% cd lit2xxx-X.YY
% ./STARTUP-literate >& startup.log

Everything should proceed to an obviously-successful conclusion (check the log to see...).

5. Test the system enough to see that it’s not totally broken. Invoke lit2pgm, lit2latex, or lit2texi directly from the literate/ directory, on some small test file of your choice, even something as simple as...:

\section[test]{Test section}
This is a small test.

Then try, perhaps:

% literate/lit2latex -v -c test.lit

6. If things seem basically happy, you can safely install the system.

% cd literate
% make -n install   # trial run, just to see if it looks "right"
% make install      # for real!

7. To make the documentation (some pre-built stuff is in the distrib):

% cd literate
% make literate.dvi # or ...
% make literate.info    # or ...
% make docs             # to do both

In the unlikely event you wanted to install it, continue with:

% make install-docs

8. You can now either delete the source or just clean up:

% make clean

9. Save a copy of your configuration file mkworld/site.jm for next time.

If you have problems, please report them to me, partain@dcs.glasgow.ac.uk.

Index

-A ⟨pgm-name⟩ option, 35 \appendix, 23 \author, 23

-c option, 35 \caption, 24 center environment, 23 \centerline, 23 \cleardoublepage, 24 \clearpage, 24 code (vs text), 7, 12 code environment, 24 code index entries, extra, 20 code ribbons, 18 command, 23 comment environment, 24 comments, hidden, 20

-D option, 35 -d option, 35 \date, 24 \define, 24 description environment, 24 display environment, 25 \documentstyle, 25

\em, 25 enumerate environment, 25 environment, 23

-f ⟨nodename-suffix⟩ option, 35 figure environment, 25 flushdisplay environment, 25 flushverbatim environment, 25 \footnote, 26

-g ⟨node-name⟩ option, 35

-H ⟨dir1⟩:⟨dir2⟩ option, 36 \heading, 26 hidden comments, 20

-I ⟨directories⟩ option, 36 -i ⟨input-file⟩ option, 36 \index, 26 index entries, extra ones in code, 20 \input, 26 \inputnow, 26 \insertribbon, 26 itemize environment, 27

-L option, 36

-l ⟨language⟩ option, 36

\label, 27

LaTeX-like markup language, 11 \listoffigures, 27 \listoftables, 27 lit2text, 34

\makeindex, 20, 27 makeindex, 20 \maketitle, 27 menu environment, 27 \menuentry, 27 mkdependlit, 34

-N ⟨info-filename⟩ option, 37 -n option, 37 \node, 28 node specification, 16 \noindex, 21

-O option, 37

-o ⟨output-file⟩ option, 37 onlyinfo environment, 28 onlylatex environment, 28 onlypartofdoc environment, 28 onlystandalone environment, 28 \owner, 46

-p ⟨pagebreak-hints⟩ option, 37 \pageref, 29 \pl, 29 \pounds, 28 \printindex, 20, 29 pseudocode environment, 29

-q option, 37

quotation environment, 29

-r ⟨ribbons-to-get⟩ option, 38 rawlatex environment, 29 \ref, 30 ribbons, code, 18 \rootsectiontype, 15, 30

-S option, 38 -s ⟨stop-list-file⟩ option, 38 sectioning, 14 \Sectionref, 16 \sectionref, 16, 30 \sectiontype, 16, 30 \standaloneornot, 30 \suppresscomments, 30

-t ⟨typesetting-hints⟩ option, 38 table environment, 30 \tableofcontents, 31 tabular environment, 31 text (vs code), 7, 12 \title, 31 \tr, 31

-v option, 38 verbatim environment, 31

-x ⟨xref-hints⟩ option, 39