This is Info file literate.info, produced by Makeinfo-1.47 from the
input file literate.texi.
File: literate.info, Node: Top, Up: (dir)
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 *Note 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 *Note Highlights::.
The real goods come next, most notably:
* an alleged "tutorial" on the LaTeX-like markup language in which
documents/programs are written (section *Note notation-tut::);
* a "reference manual" about the same markup language; this tends to
be what you consult once you are using the system (section *Note
Command_reference::);
* the programs/tools to mangle your documents/programs into useful
forms (section *Note 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 *Note 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.
* Menu:
* Highlights:: Literate programming, Glasgow style.
* notation-tut:: A LaTeX-like document markup language (tutorial-ish).
* Command_reference:: LaTeX-like markup commands: reference.
* Language_specific:: Language-specific processing.
* Habits:: A checklist of good literate habits.
* Caveats:: Caveats: bugs and foibles.
* Programs-and-options:: Programs to process literate documents.
* Info_etc:: Using your processed literate documents.
* april91-proposals:: APRIL91 PROPOSALS.
* sept92-thoughts:: SEPT92 THOUGHTS.
* lit-install:: Standalone installation of Glasgow literate programming.
* Index:: Index.
File: literate.info, Node: Highlights, Next: notation-tut, Prev: Top, Up: Top
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.
* Menu:
* Glasgow-objectives:: Objectives of our Glasgow system.
* Glasgow-NON-objectives:: NON-Objectives of our system.
* Other-Glasgow-features:: Other features of our Glasgow system.
* Glasgow-NON-features:: Shortcomings of our system.
File: literate.info, Node: Glasgow-objectives, Next: Glasgow-NON-objectives, Prev: Highlights, Up: Highlights
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.
* Menu:
* on-line-form:: Programs/documents in an on-line form.
* medium-scale:: Programming on a medium scale.
* language-independence:: Programming language independence.
* code-verissimilitude:: Program code written exactly as in illiterate programs.
* ASCII-declarative-markup:: Use of ASCII-based files, "declarative" markup.
* hierarchical-structure:: Use of hierarchical structure.
* separate-compilation:: "Separate compilation" for large programs/documents.
* one-file-many-purposes:: Using one file in several ways.
File: literate.info, Node: on-line-form, Next: medium-scale, Prev: Glasgow-objectives, Up: Glasgow-objectives
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 *Note 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.
File: literate.info, Node: medium-scale, Next: language-independence, Prev: on-line-form, Up: Glasgow-objectives
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 :-)
File: literate.info, Node: language-independence, Next: code-verissimilitude, Prev: medium-scale, Up: Glasgow-objectives
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 *Note clunky-implementation::, makes it easy to add better
support for a given programming language.
See section *Note reordering-unemphasis:: for a related comment about
code re-ordering.
File: literate.info, Node: code-verissimilitude, Next: ASCII-declarative-markup, Prev: language-independence, Up: Glasgow-objectives
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).
File: literate.info, Node: ASCII-declarative-markup, Next: hierarchical-structure, Prev: code-verissimilitude, Up: Glasgow-objectives
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 *Note notation-tut::, and the whole mess is exhaustively
described in section *Note Command_reference::.
File: literate.info, Node: hierarchical-structure, Next: separate-compilation, Prev: ASCII-declarative-markup, Up: Glasgow-objectives
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 *Note
literate-para-mode::.
See also section *Note sectioning-large-documents::.
File: literate.info, Node: separate-compilation, Next: one-file-many-purposes, Prev: hierarchical-structure, Up: Glasgow-objectives
"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!)
File: literate.info, Node: one-file-many-purposes, Prev: separate-compilation, Up: Glasgow-objectives
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 *Note code-verissimilitude::]); see section *Note
pseudo-C-preprocessor::.
File: literate.info, Node: Glasgow-NON-objectives, Next: Other-Glasgow-features, Prev: Glasgow-objectives, Up: Highlights
NON-Objectives of our system
----------------------------
* Menu:
* not-reinvent-LaTeX:: Not to reinvent LaTeX (or any other extensible notation).
* reordering-unemphasis:: An un-emphasis on code-reordering.
File: literate.info, Node: not-reinvent-LaTeX, Next: reordering-unemphasis, Prev: Glasgow-NON-objectives, Up: Glasgow-NON-objectives
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 *Note
pseudo-C-preprocessor::.
File: literate.info, Node: reordering-unemphasis, Prev: not-reinvent-LaTeX, Up: Glasgow-NON-objectives
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.
File: literate.info, Node: Other-Glasgow-features, Next: Glasgow-NON-features, Prev: Glasgow-NON-objectives, Up: Highlights
Other features of our Glasgow system
------------------------------------
* Menu:
* sectioning-large-documents:: Sectioning support for large documents.
* automatic-indexing:: Automatic indexing of your code.
* manual-indexing:: Indexing by hand.
* automatic-cross-referencing:: Automatic cross-referencing of your code.
* shortcut-notations:: Shortcut notations.
* TeX-to-ASCII:: The great "LaTeX to ASCII" problem solved!.
File: literate.info, Node: sectioning-large-documents, Next: automatic-indexing, Prev: Other-Glasgow-features, Up: Other-Glasgow-features
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 *Note Sectioning:: for further details about this
whole mess.
File: literate.info, Node: automatic-indexing, Next: manual-indexing, Prev: sectioning-large-documents, Up: Other-Glasgow-features
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 *Note multiple-indexes:: for latest thoughts about
indexing. Also, I've put some comment about free-text retrieval in
section *Note free-text-index::.
File: literate.info, Node: manual-indexing, Next: automatic-cross-referencing, Prev: automatic-indexing, Up: Other-Glasgow-features
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 *Note
Indexing:: gives the details.
File: literate.info, Node: automatic-cross-referencing, Next: shortcut-notations, Prev: manual-indexing, Up: Other-Glasgow-features
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).
File: literate.info, Node: shortcut-notations, Next: TeX-to-ASCII, Prev: automatic-cross-referencing, Up: Other-Glasgow-features
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 *Note
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
*Note diff-fonts-in-text:: for further thoughts about fonts in your
text.]
APRIL91: See also: section *Note BNF-grammars::.
File: literate.info, Node: TeX-to-ASCII, Prev: shortcut-notations, Up: Other-Glasgow-features
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.
File: literate.info, Node: Glasgow-NON-features, Prev: Other-Glasgow-features, Up: Highlights
Shortcomings of our system
--------------------------
* Menu:
* texinfo-limits:: Limits because of the Texinfo intermediate representation.
* clumsy-node-namespace:: Node namespace is not "neat".
* clunky-implementation:: A clunky implementation.
File: literate.info, Node: texinfo-limits, Next: clumsy-node-namespace, Prev: Glasgow-NON-features, Up: Glasgow-NON-features
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.
File: literate.info, Node: clumsy-node-namespace, Next: clunky-implementation, Prev: texinfo-limits, Up: Glasgow-NON-features
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 *Note revised-sectioning::.
Barring that, a good discipline for making up unique nodenames would be
helpful (I haven't found one yet).
File: literate.info, Node: clunky-implementation, Prev: clumsy-node-namespace, Up: Glasgow-NON-features
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.]
File: literate.info, Node: notation-tut, Next: Command_reference, Prev: Highlights, Up: Top
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 *Note micro-latex::.)
* As the example above showed, the sectioning commands diverge quite
significantly from LaTeX. Section *Note 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 *Note code-in-doc:: describes the more involved uses of
this feature.
* Section *Note Cross_references:: and Section *Note Indexing::
describe how to take full advantage of the cross-referencing and
indexing facilities in your literate programs.
* Section *Note Examples:: is supposed to include several complete
examples of literate programs but IT IS NOT FINISHED YET.
Remember: Section *Note Command_reference:: is (supposed to be) a
complete reference document about the LaTeX-like commands you may
safely use.
* Menu:
* micro-latex:: A micro-tutorial on our LaTeX-like conventions.
* Sectioning:: Sectioning commands.
* code-in-doc:: Including program code in your document.
* Cross_references:: Cross-referencing.
* Indexing:: Indexing.
* Examples:: Some complete examples [NOT FINISHED].
* Shortcuts:: Helpful short-cut notations.
File: literate.info, Node: micro-latex, Next: Sectioning, Prev: notation-tut, Up: notation-tut
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.
File: literate.info, Node: Sectioning, Next: code-in-doc, Prev: micro-latex, Up: notation-tut
Sectioning commands
-------------------
[APRIL91: After you read this, you may want to see some proposed
changes in section *Note revised-sectioning::.]
* Menu:
* section<n>:: The `\section<n>' command.
* How_to_section:: How to use `\section<n>'.
* sectiontype-and-ref:: The `\sectiontype' and `\sectionref' commands.
* Node_specifications:: GNU Info node specifications with `\section<n>'.
File: literate.info, Node: section<n>, Next: How_to_section, Prev: Sectioning, Up: 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.
File: literate.info, Node: How_to_section, Next: sectiontype-and-ref, Prev: section<n>, Up: Sectioning
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}'.
File: literate.info, Node: sectiontype-and-ref, Next: Node_specifications, Prev: How_to_section, Up: Sectioning
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]
File: literate.info, Node: Node_specifications, Prev: sectiontype-and-ref, Up: Sectioning
GNU Info node specifications with `\section<n>'
...............................................
[APRIL91: Don't overlook the new ideas in section *Note
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'.
File: literate.info, Node: code-in-doc, Next: Cross_references, Prev: Sectioning, Up: notation-tut
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.
* Menu:
* usual-code-in-doc:: The usual ways to put code in a documents.
* ribbons-details:: Code ribbons: the fancy stuff.
* reordering-with-insertribbon:: Code reordering with `\insertribbon'.
* pseudocode:: Stuff that looks like code but isn't.
* magic-things-in-code:: Magic things you can put in your code.
File: literate.info, Node: usual-code-in-doc, Next: ribbons-details, Prev: code-in-doc, Up: code-in-doc
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. ------------------------------
File: literate.info, Node: ribbons-details, Next: reordering-with-insertribbon, Prev: usual-code-in-doc, Up: code-in-doc
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"); }
File: literate.info, Node: reordering-with-insertribbon, Next: pseudocode, Prev: ribbons-details, Up: code-in-doc
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.
File: literate.info, Node: pseudocode, Next: magic-things-in-code, Prev: reordering-with-insertribbon, Up: code-in-doc
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.
File: literate.info, Node: magic-things-in-code, Prev: pseudocode, Up: code-in-doc
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 *Note 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 *Note
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".]
File: literate.info, Node: Cross_references, Next: Indexing, Prev: code-in-doc, Up: notation-tut
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.
File: literate.info, Node: Indexing, Next: Examples, Prev: Cross_references, Up: notation-tut
Indexing
--------
[APRIL91: changes are envisaged; see section *Note 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 *Note 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 *Note 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 *Note
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."
File: literate.info, Node: Examples, Next: Shortcuts, Prev: Indexing, Up: notation-tut
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.
* Menu:
* Simple_example:: A simple example.
* Typical_example:: A typical example.
* Hairy_example:: A hairy example.
File: literate.info, Node: Simple_example, Next: Typical_example, Prev: Examples, Up: Examples
A simple example
................
File: literate.info, Node: Typical_example, Next: Hairy_example, Prev: Simple_example, Up: Examples
A typical example
.................
File: literate.info, Node: Hairy_example, Prev: Typical_example, Up: Examples
A hairy example
...............
File: literate.info, Node: Shortcuts, Prev: Examples, Up: notation-tut
Helpful short-cut notations
---------------------------
APRIL91: There is discussion about these sorts of things scattered
through the "new ideas" in section *Note april91-new-ideas::.
* Menu:
* code-in-text:: Referring to code things in your text.
* fonts-in-text:: Using different "fonts" in your text.
File: literate.info, Node: code-in-text, Next: fonts-in-text, Prev: Shortcuts, Up: Shortcuts
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
*Note Indexing::.)
APRIL91: see comments in section *Note text-in-code::.
File: literate.info, Node: fonts-in-text, Prev: code-in-text, Up: Shortcuts
Using different "fonts" in your text
....................................
[APRIL91: Be sure to see section *Note 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>.
File: literate.info, Node: Command_reference, Next: Language_specific, Prev: notation-tut, Up: Top
LaTeX-like markup commands: reference
=====================================
This section assumes you are familiar with the tutorial-ish material in
section *Note 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 *Note diff-fonts-in-text::. Also, make them commands, not
declarations?
Commands and environments (in alphabetical order):
* Menu:
* \appendix:: \appendix.
* \author:: \author{<text>}.
* center_environment:: center environment.
* \centerline:: \centerline{<text>}.
* \caption:: \caption{<text>}.
* \clearpage-etc:: \clearpage and \cleardoublepage.
* code_environment:: code environment.
* comment_environment:: comment environment.
* \date:: \date{<text>}.
* \define:: \define{<command>}{<replacement>}.
* description_environment:: description environment.
* display_environment:: display environment.
* \documentstyle:: \documentstyle[<style-options>]{<doc-type>}.
* \em:: {\em <text>}.
* enumerate_environment:: enumerate environment.
* figure_environment:: figure environment.
* flushdisplay_environment:: flushdisplay environment.
* flushverbatim_environment:: flushverbatim environment.
* \footnote:: \footnote{<text>}.
* \heading:: \heading{<title>}.
* \index:: \index{<entry>}.
* \input:: \input{<filename>}.
* \inputnow:: \inputnow{<filename>}.
* \insertribbon:: \insertribbon{<ribbon-name>}.
* itemize_environment:: itemize environment.
* \label:: \label.
* \listoffigures-etc:: \listoffigures and \listoftables.
* \makeindex:: \makeindex.
* \maketitle:: \maketitle.
* menu_environment:: menu environment.
* \menuentry:: \menuentry{<tag>}{<description>}.
* \node:: \node{<node-spec>}.
* \pounds:: \pounds<something-like-a-number>.
* onlyinfo_environment:: onlyinfo environment.
* onlylatex_environment:: onlylatex environment.
* onlypartofdoc_environment:: onlypartofdoc environment.
* onlystandalone_environment:: onlystandalone environment.
* \pageref:: \pageref{<label-or-node-name>}.
* \pl:: \pl.
* \printindex:: \printindex.
* pseudocode_environment:: pseudocode environment.
* quotation_environment:: quotation environment.
* rawlatex_environment:: rawlatex environment.
* \ref:: \ref{<label-or-node-name>}.
* \rootsectiontype:: \rootsectiontype{<real-sectioning-command>}.
* \sectiontype:: \sectiontype{<nodename>}.
* \sectionref:: \sectionref{<nodename>}.
* \standaloneornot:: \standaloneornot{<ifso>}{<ifnot>}.
* \suppresscomments:: \suppresscomments.
* table_environment:: table environment.
* \tableofcontents:: \tableofcontents.
* tabular_environment:: tabular environment.
* \title:: \title{<text>}.
* \tr:: \tr.
* verbatim_environment:: verbatim environment.
File: literate.info, Node: \appendix, Next: \author, Prev: Command_reference, Up: Command_reference
\appendix
Section numbering after this command is for appendices. (Has no effect
on Info files. ToDo: it probably should.)
File: literate.info, Node: \author, Next: center_environment, Prev: \appendix, Up: Command_reference
\author{<text>}
Please see under `\maketitle'.
File: literate.info, Node: center_environment, Next: \centerline, Prev: \author, Up: Command_reference
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.]
File: literate.info, Node: \centerline, Next: \caption, Prev: center_environment, Up: Command_reference
\centerline{<text>}
As for LaTeX.
File: literate.info, Node: \caption, Next: \clearpage-etc, Prev: \centerline, Up: Command_reference
\caption{<text>}
As for LaTeX; likely to be unsatisfactory for Info files because the
latter doesn't do figures.
File: literate.info, Node: \clearpage-etc, Next: code_environment, Prev: \caption, Up: Command_reference
\clearpage and \cleardoublepage
As in LaTeX; no effect on Info files.
File: literate.info, Node: code_environment, Next: comment_environment, Prev: \clearpage-etc, Up: Command_reference
code environment
See section *Note code-in-doc::. Also, don't forget the `pseudocode'
environment.
You cannot nest other environments inside code environments.
File: literate.info, Node: comment_environment, Next: \date, Prev: code_environment, Up: Command_reference
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.
File: literate.info, Node: \date, Next: \define, Prev: comment_environment, Up: Command_reference
\date{<text>}
As for LaTeX; please see under `\maketitle' for exact details.
File: literate.info, Node: \define, Next: description_environment, Prev: \date, Up: Command_reference
\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 *Note pseudo-C-preprocessor:: for what I would
REALLY like to do about "defining".
File: literate.info, Node: description_environment, Next: display_environment, Prev: \define, Up: Command_reference
description environment
As in LaTeX.
File: literate.info, Node: display_environment, Next: \documentstyle, Prev: description_environment, Up: Command_reference
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.
File: literate.info, Node: \documentstyle, Next: \em, Prev: display_environment, Up: Command_reference
\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.]
File: literate.info, Node: \em, Next: enumerate_environment, Prev: \documentstyle, Up: Command_reference
{\em <text>}
The \em (emphasize) declaration works just as in LaTeX.
APRIL91: make it a command, not a declaration, i.e., \em{<text>}?
File: literate.info, Node: enumerate_environment, Next: figure_environment, Prev: \em, Up: Command_reference
enumerate environment
As in LaTeX.
File: literate.info, Node: figure_environment, Next: flushdisplay_environment, Prev: enumerate_environment, Up: Command_reference
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 *Note texinfo-limits::.)
File: literate.info, Node: flushdisplay_environment, Next: flushverbatim_environment, Prev: figure_environment, Up: Command_reference
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.
File: literate.info, Node: flushverbatim_environment, Next: \footnote, Prev: flushdisplay_environment, Up: Command_reference
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 *Note verbatim_environment::.
File: literate.info, Node: \footnote, Next: \heading, Prev: flushverbatim_environment, Up: Command_reference
\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]
File: literate.info, Node: \heading, Next: \index, Prev: \footnote, Up: Command_reference
\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.
File: literate.info, Node: \index, Next: \input, Prev: \heading, Up: Command_reference
\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 *Note Indexing:: for the full gory (but wonderful!)
details.
File: literate.info, Node: \input, Next: \inputnow, Prev: \index, Up: Command_reference
\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 *Note pseudo-C-preprocessor:: for some thoughts
about how inputting may be changed.
File: literate.info, Node: \inputnow, Next: \insertribbon, Prev: \input, Up: Command_reference
\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.
File: literate.info, Node: \insertribbon, Next: itemize_environment, Prev: \inputnow, Up: Command_reference
\insertribbon{<ribbon-name>}
Used to insert the text of one code-ribbon into another; see section
*Note 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.)
File: literate.info, Node: itemize_environment, Next: \label, Prev: \insertribbon, Up: Command_reference
itemize environment
As in LaTeX. British spelling ("itemise") also accepted.
File: literate.info, Node: \label, Next: \listoffigures-etc, Prev: itemize_environment, Up: Command_reference
\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 *Note Node_specifications::)...
Labels (and, therefore, nodenames) shouldn't have weird characters in
them. Such labels (nodenames) will be studiously ignored.
File: literate.info, Node: \listoffigures-etc, Next: \makeindex, Prev: \label, Up: Command_reference
\listoffigures and \listoftables
As for LaTeX; has no effect on Info files, which don't do lists of
figures or tables.
File: literate.info, Node: \makeindex, Next: \maketitle, Prev: \listoffigures-etc, Up: Command_reference
\makeindex
Not necessary even for LaTeX -- one is inserted automagically just
before `\begin{document}'; has no effect on `lit2texi'.
File: literate.info, Node: \maketitle, Next: menu_environment, Prev: \makeindex, Up: Command_reference
\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 *Note
Programs-and-options:: for the sorry details.
File: literate.info, Node: menu_environment, Next: \menuentry, Prev: \maketitle, Up: Command_reference
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.
File: literate.info, Node: \menuentry, Next: \node, Prev: menu_environment, Up: Command_reference
\menuentry{<tag>}{<description>}
Requests that an extra menu entry be put at the *beginning* of this
section's menu.
File: literate.info, Node: \node, Next: \pounds, Prev: \menuentry, Up: Command_reference
\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?
File: literate.info, Node: \pounds, Next: onlyinfo_environment, Prev: \node, Up: Command_reference
\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.
File: literate.info, Node: onlyinfo_environment, Next: onlylatex_environment, Prev: \pounds, Up: Command_reference
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.
File: literate.info, Node: onlylatex_environment, Next: onlypartofdoc_environment, Prev: onlyinfo_environment, Up: Command_reference
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.
File: literate.info, Node: onlypartofdoc_environment, Next: onlystandalone_environment, Prev: onlylatex_environment, Up: Command_reference
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.
File: literate.info, Node: onlystandalone_environment, Next: \pageref, Prev: onlypartofdoc_environment, Up: Command_reference
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.
File: literate.info, Node: \pageref, Next: \pl, Prev: onlystandalone_environment, Up: Command_reference
\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).
File: literate.info, Node: \pl, Next: \printindex, Prev: \pageref, Up: Command_reference
\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 *Note diff-fonts-in-text::.
File: literate.info, Node: \printindex, Next: pseudocode_environment, Prev: \pl, Up: Command_reference
\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 *Note multiple-indexes::.
File: literate.info, Node: pseudocode_environment, Next: quotation_environment, Prev: \printindex, Up: Command_reference
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.
File: literate.info, Node: quotation_environment, Next: rawlatex_environment, Prev: pseudocode_environment, Up: Command_reference
quotation environment
As in LaTeX.
File: literate.info, Node: rawlatex_environment, Next: \ref, Prev: quotation_environment, Up: Command_reference
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}
File: literate.info, Node: \ref, Next: \rootsectiontype, Prev: rawlatex_environment, Up: Command_reference
\ref{<label-or-node-name>}
As for LaTeX.
File: literate.info, Node: \rootsectiontype, Next: \sectiontype, Prev: \ref, Up: Command_reference
\rootsectiontype{<real-sectioning-command>}
Please see section *Note Sectioning::.
File: literate.info, Node: \sectiontype, Next: \sectionref, Prev: \rootsectiontype, Up: Command_reference
\sectiontype{<nodename>}
Please see section *Note sectiontype-and-ref::.
File: literate.info, Node: \sectionref, Next: \standaloneornot, Prev: \sectiontype, Up: Command_reference
\sectionref{<nodename>}
Please see section *Note sectiontype-and-ref::.
File: literate.info, Node: \standaloneornot, Next: \suppresscomments, Prev: \sectionref, Up: Command_reference
\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
*Note pseudo-C-preprocessor::.
File: literate.info, Node: \suppresscomments, Next: table_environment, Prev: \standaloneornot, Up: Command_reference
\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)
File: literate.info, Node: table_environment, Next: \tableofcontents, Prev: \suppresscomments, Up: Command_reference
table environment
Goes straight through for LaTeX; ignored for Info files, meaning that
whatever is inside won't "float."
File: literate.info, Node: \tableofcontents, Next: tabular_environment, Prev: table_environment, Up: Command_reference
\tableofcontents
As for LaTeX; adds extra stuff to the top-level menu in an Info file.
File: literate.info, Node: tabular_environment, Next: \title, Prev: \tableofcontents, Up: Command_reference
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.
File: literate.info, Node: \title, Next: \tr, Prev: tabular_environment, Up: Command_reference
\title{<text>}
Please see under `\maketitle'.
File: literate.info, Node: \tr, Next: verbatim_environment, Prev: \title, Up: Command_reference
\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 *Note diff-fonts-in-text:: for further comment on
this stuff.
File: literate.info, Node: verbatim_environment, Prev: \tr, Up: Command_reference
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}
File: literate.info, Node: Language_specific, Next: Habits, Prev: Command_reference, Up: Top
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.
* Menu:
* Default_rules:: Rules for unknown or unsupported languages.
* Haskell_rules:: Language-specific rules for Haskell.
* Perl_rules:: Language-specific rules for `perl'.
* C_rules:: Language-specific rules for `C'.
* Fortran_rules:: Language-specific rules for `FORTRAN'.
File: literate.info, Node: Default_rules, Next: Haskell_rules, Prev: Language_specific, Up: Language_specific
Rules for unknown or unsupported languages
------------------------------------------
[Not finished yet.]
No hidden comments or explicit index entries in code.
File: literate.info, Node: Haskell_rules, Next: Perl_rules, Prev: Default_rules, Up: Language_specific
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.
File: literate.info, Node: Perl_rules, Next: C_rules, Prev: Haskell_rules, Up: Language_specific
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.
File: literate.info, Node: C_rules, Next: Fortran_rules, Prev: Perl_rules, Up: Language_specific
Language-specific rules for `C'
-------------------------------
[This section is not finished yet.]
File: literate.info, Node: Fortran_rules, Prev: C_rules, Up: Language_specific
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).
File: literate.info, Node: Habits, Next: Caveats, Prev: Language_specific, Up: Top
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 *Note 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.
File: literate.info, Node: Caveats, Next: Programs-and-options, Prev: Habits, Up: Top
Caveats: bugs and foibles
=========================
As mentioned in section *Note 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.
File: literate.info, Node: Programs-and-options, Next: Info_etc, Prev: Caveats, Up: Top
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 *Note 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.
* Menu:
* A_option:: -A <pgm-name> option.
* c_option:: -c option.
* d_option:: -d option.
* capital_D_option:: -D option.
* f_option:: -f <nodename-suffix> option.
* g_option:: -g <node-name> option.
* H_option:: -H <dir1>:<dir2> option.
* i_option:: -i <input-file> option.
* capital_I_option:: -I <directories> option.
* capital_L_option:: -L option.
* l_option:: -l <language> option.
* n_option:: -n option.
* capital_N_option:: -N <info-filename> option.
* o_option:: -o <output-file> option.
* capital_O_option:: -O option.
* p_option:: -p <pagebreak-hints> option.
* q_option:: -q option.
* r_option:: -r <ribbons-to-get> option.
* s_option:: -s <stop-list-file> option.
* capital_S_option:: -S option.
* t_option:: -t <typesetting-hints> option.
* v_option:: -v option.
* x_option:: -x <xref-hints> option.
File: literate.info, Node: A_option, Next: c_option, Prev: Programs-and-options, Up: Programs-and-options
-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'.
File: literate.info, Node: c_option, Next: d_option, Prev: A_option, Up: Programs-and-options
-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...
File: literate.info, Node: d_option, Next: capital_D_option, Prev: c_option, Up: Programs-and-options
-d option
Print debugging information. I will be monumentally surprised if this
is of any use to you!
File: literate.info, Node: capital_D_option, Next: f_option, Prev: d_option, Up: Programs-and-options
-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 *Note
pseudo-C-preprocessor::.
File: literate.info, Node: f_option, Next: g_option, Prev: capital_D_option, Up: Programs-and-options
-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 *Note clumsy-node-namespace::.
File: literate.info, Node: g_option, Next: H_option, Prev: f_option, Up: Programs-and-options
-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.
File: literate.info, Node: H_option, Next: i_option, Prev: g_option, Up: Programs-and-options
-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.
File: literate.info, Node: i_option, Next: capital_I_option, Prev: H_option, Up: Programs-and-options
-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 -'.
File: literate.info, Node: capital_I_option, Next: capital_L_option, Prev: i_option, Up: Programs-and-options
-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.)
File: literate.info, Node: capital_L_option, Next: l_option, Prev: capital_I_option, Up: Programs-and-options
-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.]
File: literate.info, Node: l_option, Next: n_option, Prev: capital_L_option, Up: Programs-and-options
-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.
File: literate.info, Node: n_option, Next: capital_N_option, Prev: l_option, Up: Programs-and-options
-n option
Follow `\input' commands.
File: literate.info, Node: capital_N_option, Next: o_option, Prev: n_option, Up: Programs-and-options
-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.
File: literate.info, Node: o_option, Next: capital_O_option, Prev: capital_N_option, Up: Programs-and-options
-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.
File: literate.info, Node: capital_O_option, Next: p_option, Prev: o_option, Up: Programs-and-options
-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 *Note recording-who-to-blame::.]
File: literate.info, Node: p_option, Next: q_option, Prev: capital_O_option, Up: Programs-and-options
-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 *Note Language_specific::).
[NOT IMPLEMENTED FOR ANY LANGUAGE]
File: literate.info, Node: q_option, Next: r_option, Prev: p_option, Up: Programs-and-options
-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.
File: literate.info, Node: r_option, Next: s_option, Prev: q_option, Up: Programs-and-options
-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.
File: literate.info, Node: s_option, Next: capital_S_option, Prev: r_option, Up: Programs-and-options
-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]
File: literate.info, Node: capital_S_option, Next: t_option, Prev: s_option, Up: Programs-and-options
-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 *Note
pseudo-C-preprocessor::.
File: literate.info, Node: t_option, Next: v_option, Prev: capital_S_option, Up: Programs-and-options
-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 *Note
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.
File: literate.info, Node: v_option, Next: x_option, Prev: t_option, Up: Programs-and-options
-v option
Be verbose. This is really a debugging thing, too.
File: literate.info, Node: x_option, Prev: v_option, Up: Programs-and-options
-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 *Note 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.
File: literate.info, Node: Info_etc, Next: april91-proposals, Prev: Programs-and-options, Up: Top
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.
File: literate.info, Node: april91-proposals, Next: sept92-thoughts, Prev: Info_etc, Up: Top
APRIL91 PROPOSALS
=================
* Menu:
* april91-new-ideas:: New ideas.
* april91-old-ideas:: Old ideas that still haven't gone anywhere.
File: literate.info, Node: april91-new-ideas, Next: april91-old-ideas, Prev: april91-proposals, Up: 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 *Note literate-para-mode:: and
section *Note lit2lit:: comments, as these directions piqued the
interest of some fellow GRASPers.
* Menu:
* delatexify-commands:: Make the commands look less like LaTeX.
* multiple-indexes:: Multiple indexes.
* better-Haskell-indexing:: Better Haskell indexing.
* revised-sectioning:: Revisions to the sectioning commands.
* BNF-grammars:: A "BNF grammar" environment.
* pseudo-C-preprocessor:: Fake "C pre-processing".
* invisible-code:: Invisible code.
* text-in-code:: Plain text in your code.
* diff-fonts-in-text:: Using many "fonts" in text.
* code-in-text-formatting:: Formatting code-ish things in text.
* interface-with-papers:: Interface with plain LaTeX papers.
* literate-para-mode:: A literate Para mode.
* lit2lit:: A `lit2lit' program (to help implement a Para system).
* xtex-options:: Generating LaTeX documents especially for `xtex'.
* free-text-index:: A free-text "index".
* magic-Info-nodes:: Other "magic" Info nodes....
* revised-pgm-options:: Revise the way options are fed to `lit2*' programs.
* mixing-Bird-code-and-other:: Mixing code in "Bird tracks" with other code.
* code-reading-and-printing:: Decouple code reading and printing styles.
File: literate.info, Node: delatexify-commands, Next: multiple-indexes, Prev: april91-new-ideas, Up: april91-new-ideas
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.
File: literate.info, Node: multiple-indexes, Next: better-Haskell-indexing, Prev: delatexify-commands, Up: april91-new-ideas
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.
File: literate.info, Node: better-Haskell-indexing, Next: revised-sectioning, Prev: multiple-indexes, Up: april91-new-ideas
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.
File: literate.info, Node: revised-sectioning, Next: BNF-grammars, Prev: better-Haskell-indexing, Up: april91-new-ideas
Revisions to the sectioning commands
....................................
The main thing that is a pain about the current sectioning (see section
*Note 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).
File: literate.info, Node: BNF-grammars, Next: pseudo-C-preprocessor, Prev: revised-sectioning, Up: april91-new-ideas
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.)
File: literate.info, Node: pseudo-C-preprocessor, Next: invisible-code, Prev: BNF-grammars, Up: april91-new-ideas
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).
File: literate.info, Node: invisible-code, Next: text-in-code, Prev: pseudo-C-preprocessor, Up: april91-new-ideas
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 *Note
pseudo-C-preprocessor::).
File: literate.info, Node: text-in-code, Next: diff-fonts-in-text, Prev: invisible-code, Up: april91-new-ideas
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?
File: literate.info, Node: diff-fonts-in-text, Next: code-in-text-formatting, Prev: text-in-code, Up: april91-new-ideas
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 *Note 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.
File: literate.info, Node: code-in-text-formatting, Next: interface-with-papers, Prev: diff-fonts-in-text, Up: april91-new-ideas
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.
File: literate.info, Node: interface-with-papers, Next: literate-para-mode, Prev: code-in-text-formatting, Up: april91-new-ideas
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.
File: literate.info, Node: literate-para-mode, Next: lit2lit, Prev: interface-with-papers, Up: april91-new-ideas
A literate Para mode
....................
[See also section *Note 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.
File: literate.info, Node: lit2lit, Next: xtex-options, Prev: literate-para-mode, Up: april91-new-ideas
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)'.
File: literate.info, Node: xtex-options, Next: free-text-index, Prev: lit2lit, Up: april91-new-ideas
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.*
File: literate.info, Node: free-text-index, Next: magic-Info-nodes, Prev: xtex-options, Up: april91-new-ideas
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 :-)
File: literate.info, Node: magic-Info-nodes, Next: revised-pgm-options, Prev: free-text-index, Up: april91-new-ideas
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.
File: literate.info, Node: revised-pgm-options, Next: mixing-Bird-code-and-other, Prev: magic-Info-nodes, Up: april91-new-ideas
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...
File: literate.info, Node: mixing-Bird-code-and-other, Next: code-reading-and-printing, Prev: revised-pgm-options, Up: april91-new-ideas
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.
File: literate.info, Node: code-reading-and-printing, Prev: mixing-Bird-code-and-other, Up: april91-new-ideas
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.
File: literate.info, Node: april91-old-ideas, Prev: april91-new-ideas, Up: april91-proposals
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.
* Menu:
* recording-who-to-blame:: \owner{<name>}.
* test-burying:: Burying test cases in your document.
* recording-changes:: Recording changes to your documents.
File: literate.info, Node: recording-who-to-blame, Next: test-burying, Prev: april91-old-ideas, Up: april91-old-ideas
\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.]
File: literate.info, Node: test-burying, Next: recording-changes, Prev: recording-who-to-blame, Up: april91-old-ideas
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.
File: literate.info, Node: recording-changes, Prev: test-burying, Up: april91-old-ideas
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.
File: literate.info, Node: sept92-thoughts, Next: lit-install, Prev: april91-proposals, Up: Top
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.
File: literate.info, Node: lit-install, Next: Index, Prev: sept92-thoughts, Up: Top
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.
File: literate.info, Node: Index, Prev: lit-install, Up: Top
Index
=====
* Menu:
* -D option: capital_D_option.
* -A <pgm-name> option: A_option.
* \appendix: \appendix.
* \author: \author.
* -c option: c_option.
* \caption: \caption.
* center environment: center_environment.
* \centerline: \centerline.
* \cleardoublepage: \clearpage-etc.
* \clearpage: \clearpage-etc.
* code (vs text): code-verissimilitude.
* code (vs text)_2: notation-tut.
* code environment: code_environment.
* code index entries, extra: magic-things-in-code.
* code ribbons: ribbons-details.
* command: Command_reference.
* comment environment: comment_environment.
* comments, hidden: magic-things-in-code.
* -d option: d_option.
* \date: \date.
* \define: \define.
* description environment: description_environment.
* display environment: display_environment.
* \documentstyle: \documentstyle.
* \em: \em.
* enumerate environment: enumerate_environment.
* environment: Command_reference.
* -f <nodename-suffix> option: f_option.
* figure environment: figure_environment.
* flushdisplay environment: flushdisplay_environment.
* flushverbatim environment: flushverbatim_environment.
* \footnote: \footnote.
* -g <node-name> option: g_option.
* -H <dir1>:<dir2> option: H_option.
* \heading: \heading.
* hidden comments: magic-things-in-code.
* -I <directories> option: capital_I_option.
* -i <input-file> option: i_option.
* index entries, extra ones in code: magic-things-in-code.
* \index: \index.
* \input: \input.
* \inputnow: \inputnow.
* \insertribbon: \insertribbon.
* itemize environment: itemize_environment.
* -L option: capital_L_option.
* -l <language> option: l_option.
* \label: \label.
* LaTeX-like markup language: notation-tut.
* \listoffigures: \listoffigures-etc.
* \listoftables: \listoffigures-etc.
* lit2text: Programs-and-options.
* makeindex: Indexing.
* \makeindex: Indexing.
* \makeindex_2: \makeindex.
* \maketitle: \maketitle.
* menu environment: menu_environment.
* \menuentry: \menuentry.
* mkdependlit: Programs-and-options.
* -N <info-filename> option: capital_N_option.
* -n option: n_option.
* node specification: Node_specifications.
* \node: \node.
* \noindex: Indexing.
* -O option: capital_O_option.
* -o <output-file> option: o_option.
* onlyinfo environment: onlyinfo_environment.
* onlylatex environment: onlylatex_environment.
* onlypartofdoc environment: onlypartofdoc_environment.
* onlystandalone environment: onlystandalone_environment.
* \owner: recording-who-to-blame.
* -p <pagebreak-hints> option: p_option.
* \pageref: \pageref.
* \pl: \pl.
* \pounds: \pounds.
* \printindex: Indexing.
* \printindex_2: \printindex.
* pseudocode environment: pseudocode_environment.
* -q option: q_option.
* quotation environment: quotation_environment.
* -r <ribbons-to-get> option: r_option.
* rawlatex environment: rawlatex_environment.
* \ref: \ref.
* ribbons, code: ribbons-details.
* \rootsectiontype: How_to_section.
* \rootsectiontype_2: \rootsectiontype.
* -S option: capital_S_option.
* -s <stop-list-file> option: s_option.
* sectioning: Sectioning.
* \Sectionref: sectiontype-and-ref.
* \sectionref: \sectionref.
* \sectionref_2: sectiontype-and-ref.
* \sectiontype: \sectiontype.
* \sectiontype_2: sectiontype-and-ref.
* \standaloneornot: \standaloneornot.
* \suppresscomments: \suppresscomments.
* -t <typesetting-hints> option: t_option.
* table environment: table_environment.
* \tableofcontents: \tableofcontents.
* tabular environment: tabular_environment.
* text (vs code): code-verissimilitude.
* text (vs code)_2: notation-tut.
* \title: \title.
* \tr: \tr.
* -v option: v_option.
* verbatim environment: verbatim_environment.
* -x <xref-hints> option: x_option.
Tag Table:
Node: Top96
Node: Highlights3235
Node: Glasgow-objectives4426
Node: on-line-form5734
Node: medium-scale7013
Node: language-independence7502
Node: code-verissimilitude8172
Node: ASCII-declarative-markup9013
Node: hierarchical-structure10364
Node: separate-compilation10933
Node: one-file-many-purposes12171
Node: Glasgow-NON-objectives13594
Node: not-reinvent-LaTeX13939
Node: reordering-unemphasis14489
Node: Other-Glasgow-features15348
Node: sectioning-large-documents15959
Node: automatic-indexing17191
Node: manual-indexing17991
Node: automatic-cross-referencing18401
Node: shortcut-notations19278
Node: TeX-to-ASCII20306
Node: Glasgow-NON-features20788
Node: texinfo-limits21148
Node: clumsy-node-namespace21925
Node: clunky-implementation22467
Node: notation-tut23069
Node: micro-latex27347
Node: Sectioning28813
Node: section<n>29328
Node: How_to_section31469
Node: sectiontype-and-ref33368
Node: Node_specifications34176
Node: code-in-doc36990
Node: usual-code-in-doc37673
Node: ribbons-details38777
Node: reordering-with-insertribbon40734
Node: pseudocode41737
Node: magic-things-in-code42151
Node: Cross_references43836
Node: Indexing44658
Node: Examples47802
Node: Simple_example48246
Node: Typical_example48383
Node: Hairy_example48527
Node: Shortcuts48644
Node: code-in-text49033
Node: fonts-in-text50082
Node: Command_reference50530
Node: \appendix55179
Node: \author55413
Node: center_environment55571
Node: \centerline55858
Node: \caption56006
Node: \clearpage-etc56229
Node: code_environment56414
Node: comment_environment56702
Node: \date57125
Node: \define57310
Node: description_environment57944
Node: display_environment58107
Node: \documentstyle58478
Node: \em59121
Node: enumerate_environment59372
Node: figure_environment59526
Node: flushdisplay_environment59866
Node: flushverbatim_environment60186
Node: \footnote60569
Node: \heading60958
Node: \index61279
Node: \input61677
Node: \inputnow62348
Node: \insertribbon62616
Node: itemize_environment63072
Node: \label63265
Node: \listoffigures-etc63905
Node: \makeindex64135
Node: \maketitle64384
Node: menu_environment64981
Node: \menuentry65456
Node: \node65681
Node: \pounds66025
Node: onlyinfo_environment66437
Node: onlylatex_environment66736
Node: onlypartofdoc_environment67047
Node: onlystandalone_environment67517
Node: \pageref68012
Node: \pl68296
Node: \printindex68822
Node: pseudocode_environment69162
Node: quotation_environment69495
Node: rawlatex_environment69670
Node: \ref70275
Node: \rootsectiontype70433
Node: \sectiontype70625
Node: \sectionref70814
Node: \standaloneornot71002
Node: \suppresscomments71520
Node: table_environment71882
Node: \tableofcontents72131
Node: tabular_environment72347
Node: \title72654
Node: \tr72805
Node: verbatim_environment73347
Node: Language_specific73903
Node: Default_rules74638
Node: Haskell_rules74918
Node: Perl_rules75313
Node: C_rules75698
Node: Fortran_rules75904
Node: Habits76190
Node: Caveats77578
Node: Programs-and-options79262
Node: A_option82659
Node: c_option82960
Node: d_option83257
Node: capital_D_option83472
Node: f_option83810
Node: g_option84290
Node: H_option84930
Node: i_option85315
Node: capital_I_option85668
Node: capital_L_option86231
Node: l_option86947
Node: n_option87442
Node: capital_N_option87590
Node: o_option87991
Node: capital_O_option88570
Node: p_option88934
Node: q_option89524
Node: r_option89894
Node: s_option90246
Node: capital_S_option90648
Node: t_option90998
Node: v_option91990
Node: x_option92156
Node: Info_etc92917
Node: april91-proposals93232
Node: april91-new-ideas93480
Node: delatexify-commands95184
Node: multiple-indexes96273
Node: better-Haskell-indexing97769
Node: revised-sectioning98270
Node: BNF-grammars99339
Node: pseudo-C-preprocessor100331
Node: invisible-code102536
Node: text-in-code103304
Node: diff-fonts-in-text104187
Node: code-in-text-formatting104915
Node: interface-with-papers105714
Node: literate-para-mode106544
Node: lit2lit108098
Node: xtex-options109171
Node: free-text-index109809
Node: magic-Info-nodes110535
Node: revised-pgm-options111011
Node: mixing-Bird-code-and-other111387
Node: code-reading-and-printing112265
Node: april91-old-ideas112882
Node: recording-who-to-blame113373
Node: test-burying113804
Node: recording-changes114778
Node: sept92-thoughts115626
Node: lit-install116843
Node: Index119654
End Tag Table