import Miranda 2.066 from upstream

1 files changed, 88 insertions, 0 deletions

diff --git a/miralib/manual/29.m b/miralib/manual/29.m
new file mode 100644
index 0000000..9479de6
--- /dev/null
+++ b/miralib/manual/29.m
@@ -0,0 +1,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".
+