> || Literate scripts (an alternative comment convention)
The standard comment convention for Miranda scripts is that anything
rightwards from a pair of vertical bars to the end of a line is taken to
be comment and ignored by the compiler, thus
||This is a comment
Everything else in the script is taken to be formal program text. An
inverted style of commenting is also available in Miranda, permitting
the construction of a "literate script" (the name is taken from
Professor Donald Knuth's idea of "literate programming"). In a literate
script EVERYTHING is assumed to be comment, except for lines marked with
the formalising symbol '>' in column 1. For example the following lines
> fac 0 = 1
> fac (n+1) = (n+1)*fac n
would be taken as formal program text - and could be preceded and/or
followed by some narrative explaining what the factorial function is and
why we define it in this way.
To minimise the danger that you will accidentally omit the '>" from one
line of your formal text without the compiler noticing that something is
wrong, the following additional rule applies to Miranda literate scripts
- whenever a group of lines of formal program text is preceded or
followed by some lines of "narrative", the two types of text must be
separated by at least one blank line. You will see that this has been
done for the definition of factorial given above. (Definition - a
"blank line" is one containing only white space.)
Within the formal sections of a literate script the standard comment
convention still works. For example
> result = sum [fac n | n <- [1..50]] ||NB this is a large number!
The compiler takes a decision on which comment convention applies by
looking at the first line of a script. If this has a '>' in column 1,
then it is a literate script, otherwise the compiler assumes it is a
conventional script. Typically the first line of a literate script will
just be a comment, eg
> ||This is a literate script
In fact this manual section is a legal Miranda script, defining `fac'
and `result' (see first line).
An alternative convention is based on the name of the file - if this
ends in `.lit.m' then it is assumed to be a literate script,
independently of the form of the first line. This makes it possible to
have literate scripts which begin in `narrative' mode.
As an aid to maintaining good layout in literate scripts, a simple text
formatting program, called `just' (short for justify), is supplied with
the Miranda system. This leaves untouched the formal sections of the
script and formats the narrative parts to specified width (default 72).
If you use `vi' to edit your scripts note that the `just' program can be
called from within the editor by saying, e.g.
:1,$!just
[Warning - do NOT use `just' on non-literate scripts, it will make a
mess of them!]
There is a UNIX manual page for `just' which gives details of its
behaviour - to see the manual page from within Miranda say `!man just'.
Note that `just' is a general purpose text formatting tool, and is not
in any way Miranda-specific.
As an additional aid to the use of document preparation tools in
conjunction with Miranda scripts, the Miranda compiler will recognise
underlined keywords. This applies both to reserved words, such as `div'
and `mod' and to directives such as `%export' (underlining of the
initial `%' is optional). The style of underlining accepted is
`backspace-underline-character' as generated by nroff/troff. It will
also recognise the underlined symbols > and < as being equivalent to >=,
<= respectively. This works in both literate scripts and scripts using
the standard comment convention.
Note on %insert and literate scripts
An %insert directive in a literate script will be effective provided it
occurs in a line beginning with `>' (otherwise it is a comment and will
be ignored). The inserted text may itself use either the standard or
the literate comment convention (decided by the name of the file and
whether or not its first line begins with '>').
Similarly, text %inserted into a non-literate script may use either the
standard or the literate comment convention (again decided by the name
of the file and the form of its first line).
Using LaTeX with Miranda literate scripts
Because of the `.lit.m' convention it is possible for a file to be both
a Miranda script and a LaTeX source file. In such a case the sections
of formal Miranda text (recognised by the Miranda compiler by the `>' in
column 1) will be surrounded by the LaTeX commands
\begin{verbatim}
\end{verbatim}
A similar arrangement can be made for troff.
This works fine - but you may wish to do even better, and have reserved
words in the Miranda text underlined in your printed document. The
program `mtotex' takes a `.m' file containing an ordinary Miranda
literate script, and creates a `.tex' file of the same name, in which
various LaTeX commands have been inserted, including to underline
reserved words in program text. See UNIX manual page for `mtotex' for
details. Note that the `.tex' file created by mtotex is not itself a
legal Miranda script.
Acknowledgements
The '>' inverse-comment convention (and the "blank line" rule) are due
to Richard Bird and Philip Wadler of Oxford University Programming
Research Group, and were first used in their language "Orwell". The
`mtotex' program was supplied by John Cupitt of the University of Kent.