1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
|
> || _L_i_t_e_r_a_t_e_ _s_c_r_i_p_t_s_ _(_a_n_ _a_l_t_e_r_n_a_t_i_v_e_ _c_o_m_m_e_n_t_ _c_o_n_v_e_n_t_i_o_n_)
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).
There is a UNIX manual page for `just' which gives details of its
behaviour. 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 `_d_i_v'
and `_m_o_d' and to directives such as `_%_e_x_p_o_r_t' (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.
_U_s_i_n_g_ _L_a_T_e_X_ _w_i_t_h_ _M_i_r_a_n_d_a_ _l_i_t_e_r_a_t_e_ _s_c_r_i_p_t_s
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.
[The 1989 distribution included a program, mtotex, for using mira with
LaTeX, but this no longer works and has been removed - DT]
_A_c_k_n_o_w_l_e_d_g_e_m_e_n_t_s
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".
|
