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

`