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 lit-install, 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 Highlights.

The real goods come next, most notably:
   * an alleged "tutorial" on the LaTeX-like markup language in which
     documents/programs are written (section notation-tut);

   * a "reference manual" about the same markup language; this tends to
     be what you consult once you are using the system (section
     Command_reference);

   * the programs/tools to mangle your documents/programs into useful
     forms (section Programs-and-options). 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 IMPLEMENTED.  Discussion about most (all?) of them is gathered
together in section april91-proposals.  (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.

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.

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.

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 literate-para-mode.)

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.

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 :-)

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 clunky-implementation, makes it easy to add better
support for a given programming language.

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

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).

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 notation-tut, and the whole mess is exhaustively
described in section Command_reference.

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
literate-para-mode.

See also section sectioning-large-documents.

"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!)

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
self-contained (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 code-verissimilitude]); see section
pseudo-C-preprocessor.

NON-Objectives of our system
----------------------------

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
pseudo-C-preprocessor.

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.

Other features of our Glasgow system
------------------------------------

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 `@menu's.)

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 (LaTeX-speak...) parts, chapters, sections, or whatever...

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

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 multiple-indexes for latest thoughts about
indexing.  Also, I've put some comment about free-text retrieval in
section free-text-index.

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
Indexing gives the details.

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).

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
code-in-text-formatting.

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
diff-fonts-in-text for further thoughts about fonts in your
text.]

APRIL91: See also: section BNF-grammars.

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.

Shortcomings of our system
--------------------------

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.

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 revised-sectioning.

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

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.]

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 micro-latex.)
   * As the example above showed, the sectioning commands diverge quite
     significantly from LaTeX.  Section Sectioning 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 code-in-doc describes the more involved uses of
     this feature.

   * Section Cross_references and Section Indexing
     describe how to take full advantage of the cross-referencing and
     indexing facilities in your literate programs.

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

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

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.

Sectioning commands
-------------------

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

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.

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 `\chapter's to `\section's, 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 `\upsection's and `\downsection's 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 `\section1's 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}'.

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]

GNU Info node specifications with `\section<n>'
...............................................

[APRIL91: Don't overlook the new ideas in section
revised-sectioning.]

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)
     \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.

---------- Footnotes ----------

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

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.

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. ------------------------------

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 code-ribbon(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"); }

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.

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.

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 code-verissimilitude), 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
Language_specific 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".]

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. `\pageref's 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.

Indexing
--------

[APRIL91: changes are envisaged; see section multiple-indexes.]

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 Language_specific 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 magic-things-in-code, you can add index
entries for your code by inserting specially-formatted 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
multiple-indexes.]

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."

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.

A simple example
................

A typical example
.................

A hairy example
...............

Helpful short-cut notations
---------------------------

APRIL91: There is discussion about these sorts of things scattered
through the "new ideas" in section april91-new-ideas.

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
Indexing.)

APRIL91: see comments in section text-in-code.

Using different "fonts" in your text
....................................

[APRIL91: Be sure to see section diff-fonts-in-text.]

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>.

LaTeX-like markup commands: reference
=====================================

This section assumes you are familiar with the tutorial-ish material in
section notation-tut.  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 diff-fonts-in-text. 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 code-in-doc.  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 `...'.  More
defaults on request.

APRIL91: see section pseudo-C-preprocessor 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 texinfo-limits.)

 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 verbatim_environment.

 \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 Indexing 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.

`\input's 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 pseudo-C-preprocessor for some thoughts
about how inputting may be changed.

 \inputnow{<filename>}

These are `\input's 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
code-in-doc.  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 `\label's [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
`\input's -- 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 Node_specifications)...

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
Programs-and-options 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 diff-fonts-in-text.

 \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 multiple-indexes.

 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 Sectioning.

 \sectiontype{<nodename>}

Please see section sectiontype-and-ref.

 \sectionref{<nodename>}

Please see section sectiontype-and-ref.

 \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
pseudo-C-preprocessor.

 \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 diff-fonts-in-text 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}

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.

Rules for unknown or unsupported languages
------------------------------------------

[Not finished yet.]

No hidden comments or explicit index entries in code.

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.

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.

Language-specific rules for `C'
-------------------------------

[This section is not finished yet.]

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).

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 How_to_section.

   * 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.

Caveats: bugs and foibles
=========================

As mentioned in section clunky-implementation, 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 cross-referencing to things very near by, even
     on the same page.  I don't know how to stop this.

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 revised-pgm-options.

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
pseudo-C-preprocessor.

 -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 clumsy-node-namespace.

 -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 literate-programming
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 input-file 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 recording-who-to-blame.]

 -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 Language_specific).

[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
pseudo-C-preprocessor.

 -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 language-specific processing (Section
Language_specific).  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 Language_specific).

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.

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.

APRIL91 PROPOSALS
=================

New ideas
---------

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

JULY91: I have fleshed out the section literate-para-mode and
section lit2lit comments, as these directions piqued the
interest of some fellow GRASPers.

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.

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.  PROBLEM: 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.

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, index-entry)
pairs.  Then the only trick is to tack each index-entry onto the code
block nearest to the reported source-location.

Revisions to the sectioning commands
....................................

The main thing that is a pain about the current sectioning (see section
Sectioning) 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).

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.)

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).

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
pseudo-C-preprocessor).

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 whatever-you'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?

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 ASCII-declarative-markup), 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.

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.

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.

A literate Para mode
....................

[See also section lit2lit.]

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.

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)'.

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.*

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 :-)

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.

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...

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.

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.

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.

\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.]

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.

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.

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.

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.