> || 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.
[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 &lt; 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

 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.

 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.