import Miranda 2.066 from upstream

6 files changed, 605 insertions, 0 deletions

diff --git a/miralib/manual/27/1 b/miralib/manual/27/1
new file mode 100644
index 0000000..0b785fc
--- /dev/null
+++ b/miralib/manual/27/1
@@ -0,0 +1,19 @@
+_S_y_n_t_a_x_ _o_f_ _l_i_b_r_a_r_y_ _d_i_r_e_c_t_i_v_e_s
+
+libdir:= %_i_n_c_l_u_d_e env(;)            parts:= part part*
+         %_e_x_p_o_r_t parts(;)
+         %_f_r_e_e { sig }              part:= identifier
+                                           fileid
+env:= fileid binder? aliases?              +
+                                           -identifier
+binder:= { binding binding* }
+                                    fileid:= "pathname"
+binding:= var = exp(;)                       <pathname>
+          tform == type(;)
+                                    _N_o_t_e_s For the  definition  of  `sig'
+aliases:= alias alias*              (=signature),  `var', `exp', `tform'
+                                    and `type' see the main manual  page
+alias:= identifier/identifier       on  formal  syntax  of Miranda.  For
+        IDENTIFIER/IDENTIFIER       the definition of  `identifier'  and
+        -identifier                 `IDENTIFIER'  see lexical syntax.
+
diff --git a/miralib/manual/27/2 b/miralib/manual/27/2
new file mode 100644
index 0000000..c53c3f0
--- /dev/null
+++ b/miralib/manual/27/2
@@ -0,0 +1,44 @@
+_T_h_e_ _%_i_n_c_l_u_d_e_ _d_i_r_e_c_t_i_v_e_ _(_b_a_s_i_c_ _i_n_f_o_r_m_a_t_i_o_n_)
+
+Suppose the file "mylib.m" contains  some  Miranda  declarations  (which
+could be any kind of legal Miranda declaration, eg function definitions,
+type definitions etc).  To make these in scope in  another  script,  the
+latter will contain the directive
+	%_i_n_c_l_u_d_e "mylib"
+
+This  can  come  anywhere  in  the  script  (there  is  for  example  no
+requirement  that  %_i_n_c_l_u_d_e directives come at the front) but must be at
+top level - you may not  place  a  %_i_n_c_l_u_d_e  directive  inside  a  _w_h_e_r_e
+clause.  The subject of a %_i_n_c_l_u_d_e directive may itself contain %_i_n_c_l_u_d_e
+directives, and so on (to any reasonable depth).
+
+By  default,  the names `exported' from an included script are all those
+defined in it at top level, but  not  those  of  subsidiary  %_i_n_c_l_u_d_e's.
+This  can  be  modified by placing a `%_e_x_p_o_r_t' directive in the included
+script.  For a discussion of this and other ways of modifying the effect
+of  %_i_n_c_l_u_d_e  see  the  manual  section giving a detailed account of the
+library directives.
+
+If the filename in a _%_i_n_c_l_u_d_e directive is enclosed  in  angle  brackets
+instead  of  string quotes, this is understood to be a pathname relative
+to the miralib directory.  So for example putting in your script
+	%_i_n_c_l_u_d_e <ex/matrix>
+brings into scope the definitions exported from the  matrix  package  in
+the Miranda examples directory `ex'.  (*See note below.)
+
+Finally, note that that the relationship between includor  and  includee
+is unsymmetrical.  If file A %_i_n_c_l_u_d_e's file B, then the declarations of
+B are visible to A, but not vice versa.
+
+There is a simpler (purely textual) directive
+	%_i_n_s_e_r_t "file"
+which causes the contents of "file" to be substituted  for  the  %_i_n_s_e_r_t
+directive during lexical analysis.  This can occur anywhere in a Miranda
+script.  See manual section on compiler directives.
+
+------------------------------------------------------------------------
+(*) Note  to  system  administrators:  an  empty  directory  `local'  is
+provided  under the miralib directory, in which you can place additional
+libraries which you wish to make available to all Miranda users at  your
+site.
+
diff --git a/miralib/manual/27/3 b/miralib/manual/27/3
new file mode 100644
index 0000000..5891ed2
--- /dev/null
+++ b/miralib/manual/27/3
@@ -0,0 +1,286 @@
+_E_x_p_l_a_n_a_t_i_o_n_ _o_f_ _l_i_b_r_a_r_y_ _d_i_r_e_c_t_i_v_e_s
+
+The three directives  %_i_n_c_l_u_d_e  %_e_x_p_o_r_t  %_f_r_e_e  constitute  the  Miranda
+library  mechanism,  which  controls  the sharing of identifiers between
+separately compiled scripts.   The  %_f_r_e_e  directive  is  covered  in  a
+separate manual entry and will not be discussed further here.
+------------------------------------------------------------------------
+
+%_i_n_c_l_u_d_e "file"
+
+The presence of this directive, anywhere in a Miranda script, causes all
+the  identifiers  exported from the Miranda script "file" to be in scope
+in the containing script.  Note that "file" should  be  the  name  of  a
+Miranda source file (by convention these all have names ending in `.m').
+
+The following conventions apply to all filenames in library directives:
+ 1) A fileid can be an arbitrary UNIX pathname
+ 2) If the fileid given does not end in `.m' this is added.
+ 3)  If  the  fileid  is  surrounded by angle brackets instead of string
+quotes it is  assumed  to  be  a  pathname  relative  to  the  `miralib'
+directory,  otherwise it is taken to be relative to the directory of the
+script in which the directive occurs.  (Examples, "pig"  means  "pig.m",
+<stdenv> means "/usr/lib/miralib/stdenv.m")
+
+In addition (if you are using Berkeley UNIX or  a  derivative)  the  `~'
+convention  of  the  cshell  may be used to abbreviate home directories.
+That is `~' abbreviates your own home directory, and  ~jack  abbreviates
+jack's home directory, at the front of any pathname.
+
+The file mentioned in a  %_i_n_c_l_u_d_e  directive  must  contain  a  CORRECT,
+CLOSED  Miranda script.  (That is it must have no syntax or type errors,
+and no undefined names.) An attempt to %_i_n_c_l_u_d_e a  file  which  violates
+these  conditions  will be rejected by the compiler as a syntax error in
+the script containing the %_i_n_c_l_u_d_e statement.
+
+It is also illegal to %_i_n_c_l_u_d_e a script which causes nameclashes, either
+against  top-level identifiers of the including script or those of other
+%_i_n_c_l_u_d_e directives in the script.
+
+The effect of an %_i_n_c_l_u_d_e directive can be modified by following it with
+one  or  more  aliases  (which  are  used  to remove nameclashes between
+identifiers exported from the included script and those of the  current
+script  or  of  other  %_i_n_c_l_u_d_e  files).   There are two forms of alias,
+`new/old' which  renames  and  `-old'  which  suppresses  an  identifier
+altogether.
+
+For example suppose we wish to include the file "mike" but  it  contains
+two  identifiers,  f  and  g say, which clash with top-level bindings of
+these identifiers in the current script.  We  wish  to  use  the  "mike"
+definition  of  `f',  but  his  `g'  is  of  no interest.  The following
+directive could be used.
+
+%_i_n_c_l_u_d_e "mike" -g mike_f/f
+
+Any other identifiers exported from "mike", not  specifically  mentioned
+in the aliases, will be accepted unchanged.
+
+It is permitted to alias typenames, and constructors (say `NEW/OLD') but
+typenames and constructors cannot be  suppressed  by  a  `-name'  alias.
+Note  that  if you alias one or more of the constructors of an algebraic
+data type the behaviour of `_s_h_o_w'  on  objects  of  that  type  will  be
+modified in the appropriate way.
+
+A file which has been %included may itself contain %_i_n_c_l_u_d_e  directives,
+and  so  on, to any reasonable depth.  A (directly or indirectly) cyclic
+%_i_n_c_l_u_d_e is not permitted, however.
+
+The  `?identifier'  command  can  be  used to find the ultimate place of
+definition of an imported identifier.  When aliasing has taken place the
+`?identifier'  command  will give both the current and the original name
+of an  aliased  identifier.   If  your  installed  editor  is  `vi'  the
+`??identifier'  command  will  open  the  appropriate source file at the
+definition  of  the  identifier.   (There  is  also  a  command   `/find
+identifier'  which  is  like  `?identifier'  but will recognise an alias
+under its original name.)
+
+Every script behaves as though it contained the directive
+	%_i_n_c_l_u_d_e <stdenv>
+
+It is therefore illegal to %_i_n_c_l_u_d_e the standard environment explicitly,
+as  this  will  lead  to  huge number of name clashes (because it is now
+present twice).  As a consequence there is currently no way of  aliasing
+or  suppressing  the  names  in the standard environment.  (This will be
+fixed in the  future  by  providing  a  directive  for  suppressing  the
+implicit inclusion of <stdenv>.)
+------------------------------------------------------------------------
+
+%_e_x_p_o_r_t parts
+
+Any (correct, closed) Miranda script can be %included in another  script
+(there  is  no notion of a "module" as something with a different syntax
+from an ordinary script).  By default the names exported from  a  script
+are all those defined in it, at top level, but none of those acquired by
+a %_i_n_c_l_u_d_e of another file.  This behaviour can be modified  (either  to
+export  more  or  to  export less than the default) by placing a %_e_x_p_o_r_t
+directive in the script, specifying a list of `parts' to be exported  to
+an including file.
+
+The presence of a %_e_x_p_o_r_t directive in a script has  no  effect  on  its
+behaviour  when  it  is  the current script of a Miranda session - it is
+effective only when the script is %included in another.   A  script  may
+contain  at  most  one  %_e_x_p_o_r_t  directive.  This can be anywhere in the
+script, but to avoid nasty surprises it is advisable to  place  it  near
+the top.
+
+Each `part' listed in the export directive must be one of the following:
+ identifier (variable or typename)
+ fileid (in quotes, conventions as described above)
+ the symbol `+'
+ -identifier
+
+Notice  that  constructors need not (and cannot) be listed explicitly in
+an %_e_x_p_o_r_t  directive  -  if  you  export  an  algebraic  typename,  its
+constructors  are AUTOMATICALLY exported along with it.  The consequence
+of this is that you cannot use %_e_x_p_o_r_t to create an abstract data  type,
+by  "hiding information" about how an algebraic type was formed.  If you
+want to create an abstract data type you must use the _a_b_s_t_y_p_e  mechanism
+- see separate manual entry.
+
+If a fileid is present in the export list, this must be the  name  of  a
+file  which is %included in the exporting script, and the effect is that
+all the bindings acquired by that %_i_n_c_l_u_d_e  statement  (as  modified  by
+aliases  if  present)  are re-exported.  Allowing fileid's in the export
+list is merely a piece of shorthand, which can be used to avoid  writing
+out long lists of names.
+
+The symbol `+' is allowed in an export list as an abbreviation  for  all
+the top-level identifiers defined in the current script.
+
+The default %_e_x_p_o_r_t directive (i.e.  that which is assumed if no %_e_x_p_o_r_t
+statement is present) is therefore
+	%_e_x_p_o_r_t +
+This  will  export  all the top-level identifiers of the current script,
+but not those acquired by %_i_n_c_l_u_d_e directives.
+
+Finally, the notation `-identifier' is allowed  in  an  export  list  to
+indicate that this identifier NOT to be exported.  This is useful if you
+have used a fileid or the symbol `+' to abbreviate a list of names,  and
+wish to subtract some of these names from the final export list.
+
+An example - the following export statement exports  all  the  top-level
+identifiers of the current script, except `flooby'.
+	%_e_x_p_o_r_t + -flooby
+
+The order of appearance of  the  items  in  an  export  list  is  of  no
+significance,  and repetitions are ignored.  A negative occurrence of an
+identifier overrides any number of positive occurrences.
+
+It  is possible to find out what names are exported from a given Miranda
+script (or scripts) by calling, from UNIX, the command
+ `mira -exports files' (the extension `.m' will be added  to  each  file
+name if missing).  This will list (to stdout) for each file the exported
+names together with their types.
+------------------------------------------------------------------------
+
+_S_o_m_e_ _e_x_a_m_p_l_e_s
+
+(i) There are two scripts, called "liba.m" and "libb.m" say,  containing
+useful  definitions.   For  convenience  we  wish to combine them into a
+single larger library called say, "libc.m".  The following  text  inside
+the file "libc.m" will accomplish this.
+
+	%_e_x_p_o_r_t "liba" "libb"
+	%_i_n_c_l_u_d_e "liba"
+	%_i_n_c_l_u_d_e "libb"
+
+You  will  notice  that  when  "libc.m" is compiled, this does NOT cause
+recompilation  of  "liba.m"  and  "libb.m"  (see  section  on   separate
+compilation  -  the  compiler  is able to create an object code file for
+"libc.m", called "libc.x", by combining  "liba.x"  and  "libb.x"  in  an
+appropriate  way).   This  economy in recompilation effort is one reason
+why %_i_n_c_l_u_d_e is a better mechanism than the  simpler  textual  directive
+%_i_n_s_e_r_t (see section on compiler directives).
+
+We  could  if  we  wished  add  some  definitions  to "libc.m" - if the
+corresponding names are added to the %_e_x_p_o_r_t  statement  these  bindings
+will  then  be  exported  along  with those of the two sublibraries.  Of
+course if we don't add the names of the locally defined objects  to  the
+%_e_x_p_o_r_t  directive  they  will be `private definitions' of "libc.m", not
+visible to includors.
+
+Recall that if no  %_e_x_p_o_r_t  is  directive  is  present,  then  ONLY  the
+immediate  definitions  (if  any)  of  "libc.m"  will be exported.  So a
+script which contains only %_i_n_c_l_u_d_e directives and no %_e_x_p_o_r_t cannot  be
+usefully %included in another script (it is however perfectly acceptable
+as a current script).
+
+(ii) [More technical - omit on first reading]
+ Our second group of examples is chosen to bring out some  issues  which
+arise  when  exporting  types  between  scripts.   Suppose  we  have the
+following script, called "trees.m"
+	
+	tree * ::= NILT | NODE * (tree *) (tree *)
+	reflect :: tree *->tree *
+	reflect NILT = NILT
+	reflect (NODE a x y) = NODE a(reflect y)(reflect x)
+
+(a) If in another script we  write  `%_i_n_c_l_u_d_e  "trees"',  the  following
+bindings  will  be  imported  -  tree NILT NODE reflect.  Now suppose we
+modify the "trees.m" by placing in it the following directive - `%_e_x_p_o_r_t
+reflect'.  When the modified "trees.m" script is included in another, we
+will get the  following  error  message  from  the  compilation  of  the
+including script:
+
+	MISSING TYPENAME
+	the following type is needed but has no name in this scope:
+	'tree' of file "trees.m", needed by: reflect;
+	typecheck cannot proceed - compilation abandoned
+
+Explanation - it is illegal to export an identifier to a place where its
+type, or any part of its type, is unknown.  In this  situation  we  call
+reflect a `type-orphan' - it has lost one of its parents!
+
+(b)  Readoption  of a type-orphan (a more subtle example).  Assuming the
+"trees.m" script in  its  original  form  as  above,  we  construct  the
+following file "treelib.m"
+
+	%_e_x_p_o_r_t size
+	%_i_n_c_l_u_d_e "trees"
+	size :: tree *->num
+	size NILT = 0
+	size (NODE a x y) = 1+size x+size y
+
+If  we  %_i_n_c_l_u_d_e  the  above  script in another as it stands, we will of
+course get a missing typename diagnostic for `size' -  consider  however
+the following script
+
+	%_i_n_c_l_u_d_e "treelib"
+	%_i_n_c_l_u_d_e "trees"
+	... (etc)
+
+Everything  is  now  ok,  because  a  name  for size's missing parent is
+imported through another route (the  second  %_i_n_c_l_u_d_e  statement).   The
+Miranda  compiler  recognises  the  `tree'  type  imported by the second
+%_i_n_c_l_u_d_e as being the same one as that referred to  inside  "treelib.m",
+because  it  originates  (albeit  via  different  routes)  from the SAME
+SOURCEFILE.   A  `tree'  type  imported  from   a   different   original
+sourcefile,  even  if  it  had  the same constructor names with the same
+field types, would be recognised as a different type.
+
+[Note: the Miranda compiler is always able to recognise  when  the  same
+source  file  is  inherited  via  different  routes,  including in cases
+involving files with multiple pathnames due to the presence of (hard  or
+symblic) links.]
+
+[Further  note:  the lexical directive %_i_n_s_e_r_t (see compiler directives)
+should be regarded as making a _t_e_x_t_u_a_l_ _c_o_p_y of  the  material  from  the
+inserted  file  into  the file containing the %_i_n_s_e_r_t directive - if the
+text of a type definition (in ::= or abstype) is copied in this way, the
+compiler  will  regard  the %_i_n_s_e_r_t as having created a new type in each
+such case, not identical with that in the inserted file.]
+
+(c) Last example (typeclash).  Finally note that that it is illegal  for
+the  same  original  type  to be imported twice into the same scope even
+under different names.  Consider the following script
+
+	%_i_n_c_l_u_d_e "trees" shrub/tree Leaf/NILT Fork/NODE -reflect
+	%_i_n_c_l_u_d_e "trees"
+	... (etc)
+
+The first %_i_n_c_l_u_d_e taken on its own is perfectly ok - we  have  imported
+the `tree' type, and renamed everything in it by using aliases.  However
+we have also inherited the `tree' type under its original name, via  the
+second %_i_n_c_l_u_d_e.  The compiler will reject the script with the following
+message:
+
+	TYPECLASH - the following type is multiply named:
+	'tree' of file "trees.m", as: shrub,tree;
+	typecheck cannot proceed - compilation abandoned
+
+The rule that a type can have at most one name in a given scope  applies
+to both algebraic types and abstract types (it does not apply to synonym
+types, because these are not `real' types but mere  macro's  -  you  can
+have  any  number  of synonyms for `tree' in scope at the same time - as
+long as the underlying `real' type has a unique name).
+
+Typeclashes are illegal in Miranda in order to  preserve  the  following
+two  principles.  (i) In any given scope, each possible type must have a
+unique canonical form (obtained by expanding out synonyms, and  renaming
+generic  type  variables  in  a  standard  way).   (ii) Each object of a
+`printable type' must have,  in  any  given  scope,  a  unique  external
+representation  (ruling  out  multiply  named  constructors).  The first
+principle is necessary to the functioning of the typechecker, the second
+is demanded by the requirement that the function `_s_h_o_w' be referentially
+transparent.
+
diff --git a/miralib/manual/27/4 b/miralib/manual/27/4
new file mode 100644
index 0000000..f34bc3d
--- /dev/null
+++ b/miralib/manual/27/4
@@ -0,0 +1,116 @@
+_T_h_e_ _%_f_r_e_e_ _d_i_r_e_c_t_i_v_e_ _a_n_d_ _p_a_r_a_m_e_t_r_i_s_e_d_ _s_c_r_i_p_t_s
+
+It is permitted to construct a script containing definitions  which  are
+dependent  on information which will be supplied only when the script is
+made the subject of a %_i_n_c_l_u_d_e directive.  Such a script is said  to  be
+_p_a_r_a_m_e_t_r_i_s_e_d.   This  is  indicated  by  the presence in the script of a
+directive of the form
+
+	%_f_r_e_e { signature }
+
+where `signature' is a list of specifications  of  the  identifiers  for
+which  bindings will be provided at %_i_n_c_l_u_d_e time.  A script may contain
+at  most  one  %_f_r_e_e  directive,  which  must  therefore  give  all  the
+identifiers  on  which  the script is parametrised.  The %_f_r_e_e directive
+may appear anywhere in the script, but for  clarity  it  is  recommended
+that you place it at or near the top.
+
+For example a script (called "matrices"  say)  defining  the  notion  of
+matrix  sum  and  matrix  product,  for  matrices  of as-yet-unspecified
+element type, could be written as follows:-
+
+	%_e_x_p_o_r_t matmult matadd
+
+	%_f_r_e_e { elem :: _t_y_p_e
+		zero :: elem
+		mult, add :: elem->elem->elem
+	      }
+	
+	matrix == [[elem]]
+
+	matadd :: matrix->matrix->matrix
+	matadd xx yy = [[add a b|(a,b)<-zip2 x y]|(x,y)<-zip2 xx yy]
+
+	matmult :: matrix->matrix->matrix
+	matmult xx yy = outerprod innerprod xx (transpose yy)
+	innerprod x y = sum [mult a b|(a,b)<-zip2 x y]
+			_w_h_e_r_e
+			sum = foldr add zero
+	outerprod f xx yy = [[f x y|y<-yy]|x<-xx]
+
+Note that the identifiers declared under %_f_r_e_e may denote types as  well
+as  values.   When we write a %_i_n_c_l_u_d_e directive for the above script we
+must provide bindings for all of its free identifiers.  The bindings are
+given in braces following the pathname (and before the aliases, if any).
+Thus:-
+
+	%_i_n_c_l_u_d_e "matrices" {elem==num; zero=0; mult=*; add=+; }
+
+In  the  scope  of  the  script  containing  the  above  directive   the
+identifiers   `matmult'   and   `addmult'  will  be  available  at  type
+[[num]]->[[num]]->[[num]] and will behave as if  their  definitions  had
+been  written  using  0, (+), (*) in place of the identifiers zero, add,
+mult.
+
+The order in which the bindings are given is immaterial (it need not  be
+the  order in which the identifiers occurred in the %_f_r_e_e directive) but
+a binding must be given  for  each  free  identifier  of  the  %included
+script.   Note that the binding for a type is given using `==' and for a
+value using `='.  If the types of all the bindings (taken together)  are
+not  consistent  with the information given in the free directive of the
+%included script, or if any required binding is  missing,  the  compiler
+will reject the %_i_n_c_l_u_d_e directive as incorrect.
+
+The main advantage of a parametrised script is that  different  bindings
+may  be  given  for  its  free  identifiers on different occasions.  For
+example the  same  script  "matrices"  may  be  invoked  with  different
+bindings  to  provide a definition of matrix addition and multiplication
+over matrices with elements of type bool.  Thus:-
+
+	%_i_n_c_l_u_d_e "matrices" {elem==bool; zero=False; mult=&; add=\/; }
+
+It is even possible to %_i_n_c_l_u_d_e the same parametrised  script  twice  in
+the  same  scope  (presumably  with  different  bindings  for  the  free
+identifiers) but in this case it will be be necessary to alias apart the
+two  sets of exported identifiers to avoid a nameclash.  So we might add
+`b_matadd/matadd b_matmult/matmult' to the above directive  if  it  were
+being used in the same script as the previous one.
+
+_M_i_s_c_e_l_l_a_n_e_o_u_s_ _p_o_i_n_t_s
+
+By default the identifiers declared %_f_r_e_e in a parametrised  script  are
+not  exported  from  the  script.   As  always this can be overridden by
+explicitly listing them in an %_e_x_p_o_r_t directive.
+
+Free typenames of non-zero arity are declared in the following style.
+
+	%_f_r_e_e { stack * :: _t_y_p_e
+		table * ** :: _t_y_p_e
+		...
+	      }
+
+The corresponding bindings could be as follows
+
+	%_i_n_c_l_u_d_e ... {stack * == [*]; table * ** == [(*,**)]; ... }
+
+When a parametrised script exports a  locally  created  typename  (other
+than  a synonym type), each instantiation of the script by a %_i_n_c_l_u_d_e is
+deemed to create a NEW type (this is relevant to deciding whether or not
+two  types are the same for the purpose of readopting a type orphan, see
+previous manual section).  This is because the compiler assumes that  an
+abstract  or  algebraic  type  defined  in a parametrised script will in
+general have an internal structure that depends on the free identifiers.
+
+Finally  note  that  the  bindings  for  the  free  identifiers   of   a
+parametrised  script  must  always  be  given  EXPLICITLY.   For example
+suppose we wish to %_i_n_c_l_u_d_e the file  "matrices"  in  a  script  already
+containing  a  type  called  `elem'  over  which  we intend to do matrix
+multiplication.  We must write
+
+	%_i_n_c_l_u_d_e "matrices" {elem==elem; etc. }
+
+The binding `elem==elem' is not redundant, nor is it cyclic, because the
+two  `elem's  involved refer to two different scopes (on the left of the
+binding, that of the includee, and on  the  right  that  of  the  script
+containing the directive).
+
diff --git a/miralib/manual/27/5 b/miralib/manual/27/5
new file mode 100644
index 0000000..22e4753
--- /dev/null
+++ b/miralib/manual/27/5
@@ -0,0 +1,132 @@
+_S_e_p_a_r_a_t_e_ _c_o_m_p_i_l_a_t_i_o_n_ _a_n_d_ _`_._x_'_ _f_i_l_e_s
+
+The  Miranda  compiler  compiles  to  an  intermediate  code,  based  on
+combinators.   When a Miranda expressions are evaluated in the course of
+a session this code is executed by an interpreter.
+
+Since compilation is a  complex  process  (involving  lexical  analysis,
+parsing, type checking and code-generation, as well as a number of other
+minor steps) it is undesirable that the results of  compiling  a  script
+should  just  be  "thrown  away"  at  the  end  of  a session.  To avoid
+unnecessary acts  of  recompilation  the  Miranda  system  maintains  an
+object-code  file  in  association  with  each  source file containing a
+Miranda script.
+
+For each source file, called say `script.m',  the  Miranda  system  will
+create an object code file, called `script.x'.  No action is required by
+the user to keep these files up-to-date, since this  is  taken  care  of
+automatically by the Miranda system.  The .x files are never referred to
+directly by the Miranda user, and you should not try to edit them  (they
+contain  binary  data).
+
+You may however safely remove any .x file (if for example you don't wish
+it  to  use  up  filespace)  since  this will at worst cause the Miranda
+compiler to do some extra work later to recreate it.
+
+If you select a script as the current script of a Miranda  session,  and
+it  has  an  up-to-date  .x  file, this will be loaded instead, avoiding
+recompilation.  If the .x file does not exist, or _a_n_y_ _ _r_e_l_e_v_a_n_t_ _ _s_o_u_r_c_e_ 
+_f_i_l_e_ _h_a_s_ _b_e_e_n_ _m_o_d_i_f_i_e_d since the .x file was created, the script will be
+recompiled (and a side effect of your having selected this  source  file
+as  the  current script will be to bring into existence an up-to-date .x
+file for it).
+
+[Inductive definition - source file B is `relevant' to source file A iff
+file  A %inserts or %includes B or any file to which B is relevant.  For
+a discussion of `%include' and the other library directives  see  manual
+sections on `The Library Mechanism'.]
+
+Note that compiling a script containing %include  statements  will  have
+the  side  effect of triggering subsidiary compilation processes for any
+relevant source files which have been modified since their corresponding
+.x  file  was created.  Users familiar with the UNIX program `make' will
+recognise this process as essentially the same  as  that  which  happens
+when a `makefile' is obeyed.  In the case of Miranda however, the `make'
+process is fully automated by being built into the compiler.
+
+_M_o_r_e_ _a_d_v_a_n_c_e_d_ _i_n_f_o_r_m_a_t_i_o_n
+
+If you want to check that a  given  Miranda  script  has  an  up-to-date
+object  code  file  _w_i_t_h_o_u_t  entering  a  Miranda  session,  this can be
+accomplished from UNIX by calling mira with a special flag, thus
+	mira -make script.m
+
+will force the existence of an  up-to-date  `script.x',  performing  all
+(and only) those compilations which are necessary.  Any number of source
+files can be given after  the  -make  flag  (and  as  usual  if  a  `.m'
+extension is omitted it will be added automatically).
+
+Example:- to make  sure  every  Miranda  source  file  in  your  current
+directory has an up-to-date object code file, say `mira -make *.m'.
+
+Applying mira -make to a `.x' file is equivalent to applying it  to  the
+corresponding `.m' file.  So another way to make sure everything in your
+current directory is up-to-date is to say `mira -make  *.x'.   This  has
+the  advantage  that it will also remove any `.x' files whose `.m' files
+no longer exist.
+
+In the best UNIX tradition mira -make  does  its  work  silently  unless
+something  is wrong.  If the source files are all correct closed scripts
+with up-to-date  `.x'  files,  mira  -make  says  nothing  at  all.   If
+recompilations are necessary it informs you which source files are being
+compiled, and, as a last step, the names of any  scripts  which  contain
+errors or undefined names are listed, to stdout.
+
+The exit status  of  a  `mira  -make'  (relevant  if  you  are  a  shell
+programmer,  or wish to include a `mira -make' command in a makefile for
+a larger setup) is as follows.  If (AFTER any  necessary  recompilations
+have  been  performed)  all the source files have up-to-date `.x' files,
+and do not contain any syntax errors, type errors,  or  undefined  names
+(these  facts  are  recorded  in  .x files) the exit status will be zero
+(=ok), otherwise it will be 1.
+
+It is possible to find out what names are  exported  from  one  or  more
+Miranda scripts without entering a Miranda session by using the command
+	mira -exports files
+(as  always  the `.m' extension is added automatically to each filename,
+if missing).  This command first calls `mira -make'  on  each  file,  to
+make  sure everything is uptodate, and then lists to standard output the
+exported names together with their types (one per line).  If  more  than
+one  file  is specified each group of names will be preceded by the name
+of the file to which they appertain.
+
+Note that the export profile of a script includes information about  its
+free identifiers (if any).
+
+It is also possible to find out the names of all files on which a  given
+set  of  Miranda scripts depend, via %include and %insert statements, by
+using the command
+	mira -sources files
+This lists to standard output, one per line, the names of  all  relevant
+source  files.   The  standard  environment, <stdenv>, is always omitted
+from the list.
+
+_E_f_f_e_c_t_ _o_f_ _`_m_v_'_ _a_n_d_ _`_r_m_'
+ Finally we note a couple of points about the behaviour  of  Miranda  .x
+files under applications of mv and rm to their corresponding sources.
+
+A `.x' file records (inter alia) the names of all relevant source  files
+relative  to  the  directory  in which it is stored, together with their
+`date and time last modified'.  Note that the UNIX command `mv' does not
+alter the time-last-modified of the file being moved.  So it is possible
+when moving a miranda source file (or a group of  interdependant  source
+files)  from  one  directory  to  another  to  save  mira  the bother of
+recompiling them, simply by moving all the relevant `.x' files into  the
+new directory along with the sources.  (This doesn't work however if you
+change the name of any of the source files during the move.)
+
+[Note that `tar' has  the  same  property,  so  the  up-to-date-ness  of
+Miranda .x files is preserved across a tape dump.]
+
+If you use `rm' to remove a Miranda  source  file,  the  next  time  you
+invoke  mira  with the (now non-existent) file as its current script, it
+will promptly remove the corresponding `.x' file.  The logic of this  is
+as  follows:- `.x' files must be kept up-to-date with their sources, and
+the way to make a `.x' file up-to-date with a non-existent source is  to
+make  it  too non-existent.  As a consequence it is not possible to send
+someone a Miranda object code  file  without  the  corresponding  source
+(mira will delete it as soon as they try to use it!).
+
+From some points of view this last feature might be regarded as a bug  -
+a way round it may be provided in a later release of the Miranda system.
+
diff --git a/miralib/manual/27/contents b/miralib/manual/27/contents
new file mode 100644
index 0000000..f9db2c8
--- /dev/null
+++ b/miralib/manual/27/contents
@@ -0,0 +1,8 @@
+_T_h_e_ _M_i_r_a_n_d_a_ _L_i_b_r_a_r_y_ _M_e_c_h_a_n_i_s_m
+
+ 1. Syntax of library directives
+ 2. The %include directive (basic information)
+ 3. About library directives (more detailed information)
+ 4. The %free directive and parametrised scripts
+ 5. Separate compilation and `.x' files
+