import Miranda 2.066 from upstream

10 files changed, 899 insertions, 0 deletions

diff --git a/miralib/manual/31/1 b/miralib/manual/31/1
new file mode 100644
index 0000000..388cc0d
--- /dev/null
+++ b/miralib/manual/31/1
@@ -0,0 +1,92 @@
+_I_n_p_u_t_ _f_r_o_m_ _U_N_I_X_ _f_i_l_e_s_ _e_t_c_.
+
+The following Miranda functions provide an interface to  the  UNIX  file
+system from within Miranda expressions:
+
+	read :: [char]->[char]
+This takes a string valued argument, which it treats as a UNIX pathname,
+and returns the contents of the file or device of that name, also  as  a
+string  (i.e.   as  a  list  of  characters).   There  is no end-of-file
+character, the termination of the file is indicated simply by the end of
+the list of characters.  The Miranda evaluation terminates with an error
+message if the file does not exist  or  the  user  does  not  have  read
+permission for it.
+
+A special case - the notation `$-' denotes the contents of the  standard
+input,  as a list of characters.  Note that multiple occurrences of `$-'
+always denote a single shared input stream.  So for example ($-  ++  $-)
+reads one lot of data from the terminal and duplicates it.
+
+(See separate subsection on Input/Output of binary data for  the  binary
+versions readb and $:-)
+
+	filemode :: [char]->[char]
+Takes   a   pathname  and  returns  a  string  representing  the  access
+permissions of the current process to the file of that name.  The string
+is  empty  if  the  file  does not exist, otherwise it is of length four
+containing, in order, the following characters - 'd' if the  file  is  a
+directory,  'r'  if it is readable, 'w' if it is writeable, 'x' if it is
+executable.  Each character not applicable is replaced by '-'.   So  for
+example   "drwx"  is  the  filemode  of  a  directory  with  all  access
+permissions, while "-rw-" is the filemode of a normal file with read and
+write but no execute permission.
+
+	getenv :: [char]->[char]
+Looks  up  the  string  associated with a given name in the current UNIX
+environment (see man (2) getenv in the UNIX manual system).  For example
+	getenv "HOME"
+returns the name of the  current  home  directory.   Returns  the  empty
+string if the given name not present in the environment.
+
+	system :: [char]->([char],[char],num)
+The effect of `system string' is that a UNIX process is  forked  off  to
+execute  `string'  as a shell command (by `/bin/sh').  The result of the
+call to `system' is a  triple  containing  the  standard  output,  error
+output,  and  exit_status, respectively, resulting from the execution of
+the UNIX command.  (The exit_status of a UNIX command is a number in the
+range  0..127,  with a non-zero exit status usually indicating some kind
+of abnormal event.) Note that inspecting the exit_status will force  the
+Miranda  process  to  wait  until the execution of the shell command has
+completed - otherwise the two processes proceed concurrently.
+
+If  the  attempt  to  set up a shell process fails, `system' returns the
+result ([],errmess,-1), where errmess is an error message.
+
+WARNING - the function `system' provides a  very  general  interface  to
+UNIX.   Obviously,  this  can  be  abused  to  cause the evaluation of a
+Miranda expression to have side effects  on  the  state  of  the  filing
+system.   It is not intended to be used in this way - `system' should be
+used only to _o_b_t_a_i_n _i_n_f_o_r_m_a_t_i_o_n about the state of the  world.   If  you
+wish  to change the state of the world, this should be done by placing a
+`System' message in your output list (see next manual section).
+
+Since reading data from the terminal would constitute a side effect, the
+background  process  created  by  `system'  comes  into  being  with its
+standard input closed.
+
+_I_m_p_l_e_m_e_n_t_a_t_i_o_n_ _R_e_s_t_r_i_c_t_i_o_n
+ `read', `filemode', `getenv', and `system' all require  their  argument
+to be at most 1024 characters long.
+
+_N_o_t_e_ _o_n_ _s_y_s_t_e_m_ _r_e_a_d_i_n_g_ _f_u_n_c_t_i_o_n_s_ _a_n_d_ _r_e_f_e_r_e_n_t_i_a_l_ _t_r_a_n_s_p_a_r_e_n_c_y
+
+Although `read', `filemode', `getenv' do not have side effects, they are
+not  referentially  transparent  because it cannot be guaranteed that an
+expression like
+	read "file"
+will return the same result if evaluated twice.  Some external event may
+have  changed  the  state of the filing system in the meantime.  Clearly
+the same  problem  applies  to  `system'  -  consider  for  example  the
+expression
+	system "date"
+which  gets  date-and-time  as  a  string.   Evaluating  this  twice  in
+succession is unlikely to produce the same result.
+
+Strictly speaking all calls to `read' and the other  functions  in  this
+section  ought to be evaluated with respect to the state-of-the-world as
+it existed  before  the  evaluation  of  the  given  Miranda  expression
+commenced.   Otherwise  referentially  transparent  behaviour  cannot be
+guaranteed.  Enforcing this would appear to require, among other things,
+taking   a   copy  of  the  whole  filing  system  before  each  Miranda
+command-level evaluation.  For obvious reasons this is not implemented.
+
diff --git a/miralib/manual/31/2 b/miralib/manual/31/2
new file mode 100644
index 0000000..9348cc5
--- /dev/null
+++ b/miralib/manual/31/2
@@ -0,0 +1,138 @@
+_O_u_t_p_u_t_ _t_o_ _U_N_I_X_ _f_i_l_e_s_ _e_t_c_.
+
+Since Miranda is a functional language, the evaluation of an  expression
+cannot  in  itself  cause  a side effect on the state of the world.  The
+side effects occur when the value of the  expression  is  printed.   The
+value  of  a  command  level  expression is a list of `system messages',
+where the possible forms of message are  shown  by  the  following  type
+declaration,
+
+  sys_message ::= Stdout [char] | Stderr [char] | Tofile [char] [char] |
+                  Closefile [char] | Appendfile [char] | System [char] |
+                  Exit num |  Stdoutb [char] |  Tofileb [char] [char]  |
+                  Appendfileb [char]
+
+The  system `prints' such a list of messages by reading it in order from
+left to right, evaluating and obeying each message  in  turn  as  it  is
+encountered.  The effect of the various messages is as follows.
+
+	Stdout string
+The  list  of characters `string' is transmitted to the standard output,
+which will normally be connected to the user's screen.  So  for  example
+the effect of obeying
+	[Stdout "!!!"]
+is that three exclamation marks appear on the screen.
+
+	Stderr string
+The  list  of  characters `string' is sent to the standard error output.
+[Explanation to those unfamiliar with UNIX stream philosophy: all normal
+UNIX processes come into existence with a standard input stream, and two
+output streams, called standard out  and  standard  error  respectively.
+Under  normal  circumstances  standard  error  and standard out are both
+connected to the users screen, but in principle they could be  connected
+to different places.]
+
+	Tofile fil string
+The characters of the string are transmitted to the file or device whose
+UNIX pathname is given by `fil'.  Successive `Tofile'  messages  to  the
+same  destination  are  appended  together  (i.e. the first such message
+causes the file to be opened for writing, and it remains open until  the
+end  of  the  whole  message list).  Note that opening a file for output
+destroys its previous  contents  (unless  preceded  by  an  `Appendfile'
+message, see below).
+
+	Closefile fil
+The  stream  which  has  been  opened  to the file `fil' (presumably the
+subject of some previous `Tofile' messages) is closed.  If `fil' was not
+in  fact  open  this  command  has  no  effect  (i.e. is harmless).  All
+open-for-output streams  are  automatically  closed  at  the  end  of  a
+message-list  evaluation,  so it is only necessary to invoke `Closefile'
+explicitly if you wish to  terminate  output  to  given  file  during  a
+message-list  evaluation.   (One reason why you might want to do this is
+so as not to have too many output files open at  one  time,  since  many
+UNIX  systems place a limit on the number of streams which a process can
+have.)
+
+	Appendfile fil
+If obeyed before any `Tofile' messages to destination `fil', causes  the
+file  to  be opened in `append-mode', so its previous contents are added
+to, instead of being replaced.
+
+See separate subsection on Input/Output of binary data for  explanation
+of the binary versions Stdoutb, Tofileb, Appendfileb.
+
+	System string
+Causes `string' to be executed as a shell command (by `/bin/sh') at this
+point  in  time.   Enables  arbitrary  UNIX  commands to be invoked from
+within a Miranda output list.  The shell process comes into  being  with
+its  streams (standard input, standard output, standard error) inherited
+from the Miranda process.
+
+	Exit num
+Causes the UNIX process evaluating the message list to terminate at this
+point  with  exit  status  `num'  (an  integer  between 0 and 127).  The
+remaining messages in the list (if any) are discarded.  The exit  status
+of  a  Miranda  evaluation which terminates other than by a call to Exit
+will be 0 if it terminates successfully or 1 if it encounters a  runtime
+error.   The  exit  status  is only relevant if you are using Miranda to
+implement a stand-alone UNIX command (see  separate  manual  page  about
+this).
+
+[Explanation: the exit status of a UNIX command is a one  byte  quantity
+which  is communicated back to the calling shell and can be tested by it
+- the usual convention is that 0 exit status means all ok, anything else
+means  something  was  amiss.  If you are not into shell programming you
+can safely ignore the whole issue.]
+
+_T_h_e_ _d_e_f_a_u_l_t_ _o_u_t_p_u_t_ _m_e_c_h_a_n_i_s_m
+
+We have stated above that the value of a  command  level  expression  is
+expected  to be of type `[sys_message]'.
+
+If it is not of that type mira applies the following rules:
+ (i) if the value is of type  [char]  the  characters  are  directed  to
+standard output, as if you had written [Stdout (expr)].
+ (ii)  if  it is of another type, show is first applied to convert it to
+type [char], so it is as if you had written [Stdout (show (expr))]
+
+This explains how the Miranda system is able to function in its standard
+`desk-calculator' mode.
+
+Be aware that if <stdenv> is not loaded (because you invoked  mira  with
+-stdenv, and the script does not explicitly %include <stdenv> there will
+be no type sys_message and only the default  output  mechanism  will  be
+available.
+
+_O_u_t_p_u_t_ _r_e_d_i_r_e_c_t_i_o_n
+
+A Miranda command of the form
+	exp &> pathname
+causes a background process to be set up for the  evaluation  of  `exp',
+with  both  the  standard  output  and  the standard error output of the
+process redirected to `pathname'.  If `exp' is  of  type  [sys_message],
+the  destination  of  `Tofile'  messages  are not affected by the global
+redirection - only messages which  would  otherwise  have  gone  to  the
+screen are sent to `pathname'.
+
+If two (blank separated) pathnames are given after  the  `&>',  standard
+output is redirected to the first file and standard error to the second.
+Thus:
+	exp &> outfil errfil
+
+If the `&>' is replaced by a `&>>', instead of overwriting the  previous
+contents, the relevant output is appended to the end of the file.  Thus:
+	exp &>> pathname(s)
+As  with  the  `&>'  command,  either one or two pathnames can be given,
+depending on whether you wish standard error to be merged with  standard
+out, or separated from it.
+
+Note that a background process created by a `&>' or `&>>' command has no
+standard input - if  the  expression  contains  `$-',  the  latter  will
+evaluate to `[]'.
+
+_I_m_p_l_e_m_e_n_t_a_t_i_o_n_ _R_e_s_t_r_i_c_t_i_o_n_s
+ Arguments representing pathnames (to Tofile, Appendfile, Closefile) are
+restricted  to  1024  characters  in length - pathnames longer than this
+cause an error message.  The shell command supplied to  System  is  also
+restricted to 1024 characters in length.
+
diff --git a/miralib/manual/31/3 b/miralib/manual/31/3
new file mode 100644
index 0000000..1746682
--- /dev/null
+++ b/miralib/manual/31/3
@@ -0,0 +1,42 @@
+_R_e_a_d_i_n_g_ _w_i_t_h_ _i_n_t_e_r_p_r_e_t_a_t_i_o_n_ _(_`_r_e_a_d_v_a_l_s_'_ _a_n_d_ _`_$_+_'_)
+
+There is a function _r_e_a_d_v_a_l_s which takes a string  representing  a  UNIX
+pathname,  and  returns a list of values found in the file of that name.
+The values may be represented by arbitrary Miranda expressions,  written
+one  per  line.   Blank  lines,  and  Miranda style comments (||...) are
+ignored.  If the input file appears to be a teletype, _r_e_a_d_v_a_l_s reacts to
+syntactically  incorrect  or wrongly typed data by prompting the user to
+repeat the line, and such bad values are omitted from the  result  list.
+If  the  input  file  does  not appear to be a teletype, bad data causes
+readvals to abort with an error message.
+
+Note that, similarly to _s_h_o_w
+ (i) _r_e_a_d_v_a_l_s is a reserved word, not an identifier.
+ (ii) the context in which it is used must be such as to  determine  its
+type  monomorphically.   Extra  type specifications may be needed in the
+script to meet this condition.
+
+Here is a simple example of how _r_e_a_d_v_a_l_s might be used in a script
+	x :: [num]
+	x = readvals "data"
+The file `data' should contain expressions of type num (one per line).
+
+The _r_e_a_d_v_a_l_s function provides  Miranda  with  a  simple  form  of  data
+persistence - data can be written to a file (e.g. using `_s_h_o_w') and read
+back using _r_e_a_d_v_a_l_s in a later session.  Data objects saved in this  way
+must  of  course  be  finite.  Notice also that if you wish to save data
+containing functions, you will have to set up some special  arrangement,
+since such data cannot be written out using `_s_h_o_w'.
+
+Data of abstract type can be written to file using _s_h_o_w  and  read  back
+with  _r_e_a_d_v_a_l_s - provided that an appropriate show-function was included
+in the signature of the abstract type (see manual  section  on  abstract
+types).
+
+Finally note that $+ behaves exactly like an application of _r_e_a_d_v_a_l_s  to
+the  name  of  the  file  to which the standard input is connected.  For
+example
+	sum $+
+read a sequence of numeric expressions from the keyboard (one per  line)
+up to the next control-D, and then returns their sum.
+
diff --git a/miralib/manual/31/4 b/miralib/manual/31/4
new file mode 100644
index 0000000..5378454
--- /dev/null
+++ b/miralib/manual/31/4
@@ -0,0 +1,175 @@
+_U_s_i_n_g_ _M_i_r_a_n_d_a_ _t_o_ _b_u_i_l_d_ _e_x_e_c_u_t_a_b_l_e_ _f_i_l_e_s
+
+FIRST METHOD (using a `magic string')
+
+Create a file, prog.m say, containing a normal miranda script, but  with
+first line
+	#! /usr/bin/mira -exec
+
+The first two characters must be "#!" followed by an optional space  and
+the absolute pathname of the miranda interpreter.  This may be somewhere
+other than /usr/bin/mira, the UNIX shell  command  "which  mira"  should
+tell  you where it is.  The flag "-exec" is necessary and no other flags
+should be added.  (Note "-exec2" can be  substituted  for  "-exec",  see
+below.)
+
+The remainder of the file can be any legal  miranda  script,  which  may
+%include  other  scripts. Somewhere in the file, or in an included file,
+there must be a definition of `main'.  When `prog.m' is  executed  as  a
+UNIX  command,  the  result  will be that `main' is evaluated, using the
+same rules as if you had entered it in an interactive session,  and  the
+results  sent  to  standard  output.   Remember to give the file execute
+permission (e.g. by saying `chmod +x prog.m').
+
+A  command  of  this form can take data from the terminal.  The notation
+`$-' can be used anywhere in the second and later lines of the  file  to
+denote  the  list of characters taken from the standard input.  (That is
+`$-' behaves like a Miranda identifier of type [char].)
+
+The command can be invoked with arguments, eg
+	prog.m fig 23
+and the notation `$*' can be used in the script as a Miranda  identifier
+of  type  [[char]]  denoting the argument list, with the convention that
+the initial (zero'th) argument is the name of the command.  So  in  this
+case the value of `$*' would be
+	["prog.m","fig","23"]
+If there are no arguments, `$*' will be a singleton list containing just
+the command name.
+
+_E_x_p_l_a_n_a_t_i_o_n
+ The line beginning `#!' is a standard UNIX incantation, called a `magic
+string',  indicating that the following pathname is an interpreter to be
+invoked with the name of the file in which it occurs  as  argument  (see
+under  `execve'  in  section  2  of  the UNIX manual).  The flag "-exec"
+instructs the Miranda system to evaluate `main', which  can  be  of  any
+type.   If  main is a string this is sent to stdout, if it is of another
+printable type `show main' is sent to stdout, or  if  main  is  of  type
+[sys-message] the sequence of I/O commands is executed.
+
+Examples
+ Here is the Miranda "hello world" program
+	#! /usr/bin/mira -exec
+	main = "hello world\n"
+	
+The following script is a Miranda version of the UNIX `cat' command - if
+it  is  invoked without arguments it simply copies its standard input to
+its standard output, otherwise  it  concatenates  the  contents  of  its
+argument files to the standard output.
+	#! /usr/bin/mira -exec
+
+	main = [Stdout $-], _i_f tl $* = []
+             = [Stdout (concat(map read(tl $*)))],     _i_f badargs=[]
+             = [Stderr (concat(map errmess badargs))], _o_t_h_e_r_w_i_s_e
+	badargs = [f|f<-tl $*;~member(filemode f)'r']
+	errmess f = f++": cannot access\n"
+
+See the manual pages on input from UNIX files and output to  UNIX  files
+for  the  explanation of `read', `filemode' and the constructors Stdout,
+Stderr etc.
+
+The rule that Miranda source files must have names ending in ".m" is not
+enforced  for  "magic" scripts, in keeping with the UNIX convention that
+executables require no special suffix.  However  a  magic  script  whose
+name  ends  in  ".m"  can also be made the subject of a miranda session.
+This is advantageous during development, as individual  definitions  can
+be tested.  A first line beginning #! is ignored by the Miranda compiler
+which treats it as a comment.  In this situation $* has  the  value  [],
+since the script was not executed as a command.
+
+Note also that if your Miranda executable file has the  ".m"  suffix,  a
+corresponding  ".x" file will be created at its first call, avoiding the
+need for mira to recompile it on subsequent calls (unless there has been
+an update of the source file).
+
+Notes
+ (1) In some UNIX-like systems `execve' places  a  limit  on  the  total
+length of the `magic string'.
+ (2)  Because in many systems (including Linux) `execve' permits at most
+one flag in a magic string, mira does not understand a `-lib' flag given
+in  conjunction  with  a  `-exec'  flag.   This  is a possible source of
+difficulty if you keep the miralib directory at  a  non-standard  place.
+One  way  round  this is to set environment variable MIRALIB, instead of
+using a `-lib' flag.  See manual section on flags  etc.   [To  do:  more
+general mechanism to add other flags to -exec in a magic string - DT]
+ (3) If called from the UNIX command line,
+	mira -exec script.m
+will  find and evaluate `main' in script.m and in this situation you can
+combine -exec with other flags, -lib miralib, -heap N, etc preceding the
+name of the script.  Any additional arguments following script.m will
+be found in $*.
+
+_D_e_b_u_g_g_i_n_g_ _s_t_a_n_d_-_a_l_o_n_e_ _s_c_r_i_p_t_s
+ As an aid to debugging a variant flag is available:
+	#!/usr/bin/mira -exec2
+        definitions...
+The -exec2 flag has the same effect as -exec but runtime  errors  (only,
+not compile time errors) are redirected to file miralog/prog, where prog
+is the name of the script.  The redirection takes  place  if  a  miralog
+directory  exists  in  the  current  working  directory  and the process
+running the script has write permission  to  it.   This  is  useful  for
+debugging  cgi  scripts  written  in  Miranda,  particularly  in the not
+infrequent situation that they compile without errors and seem  to  work
+fine  from the command line but fail when invoked by an http call.  (You
+will need to create a directory miralog  in  cgi-bin  and  chown  it  to
+apache, or whatever personality cgi scripts run as).
+
+SECOND METHOD (using a `here document')
+
+Create a file ("prog' say) containing the following
+
+	mira [script] <<!
+	exp1
+	exp2
+	.
+	.
+	.
+	!
+
+The `!' after << can be replaced by any character sequence  -  the  same
+sequence, on a line by itself, terminates the `here document'.
+
+Remember to make the file executable (by saying `chmod +x  prog').   Now
+when  `prog'  is executed as a UNIX command, the result will be that the
+miranda  expressions  `exp1',  `exp2'  ...  will  be  evaluated  in  the
+environment  defined  by  `script', and the results sent to the standard
+output.  As usual, if `script' is omitted, a default name `script.m'  is
+assumed.   The  text following the special redirection `<<!' is called a
+"here-document".  The contents of the here-document are fed to the  mira
+command  in place of its standard input.  (So anything you would type to
+the miranda system at top level can appear in the here document.)
+
+Here-documents are a normal feature of UNIX, not  something  special  to
+miranda.   Miranda's  only  contribution to making this work smoothly is
+that it detects when its input is not coming from  a  terminal,  and  in
+this  case  suppresses prompts and other extraneous feedback.  Note also
+that  lines  beginning  `||'  are  ignored  by   the   Miranda   command
+interpreter,  which  gives  a way to include comments in the text of the
+here-document.
+
+The program `prog' might be invoked with  one  or  more  arguments,  for
+example,
+	prog big 23
+In  the  here-document,  `$1'  can be used to denote the first argument,
+`$2' the second and so on - in this case  `big'  and  `23'  respectively
+will  be textually substituted for these before the here-document is fed
+to mira as input.  Arguments not present are  replaced  by  empty  text.
+Other  replacements  carried  out on the text of the here-document are -
+`$*' is replaced by all the arguments together, as  a  single  piece  of
+text,  `$#'  is  replaced by the number of arguments present (`2' in the
+case shown above), and `$0' is replaced by the name of the program being
+executed (in this case `prog').  
+
+If the here-document contains instances of  `$'  which  you  don't  want
+replaced by something (for example inside a Miranda string), you have to
+escape them by preceding them with a backslash character.   But  if  the
+delimiter after the >> is in quotation marks, eg
+	mira [script] <<"!"
+	stuff
+        !
+then no substitutions will take place inside the here-document.
+
+The drawbacks of commands built in this way are two - (a) they  have  no
+way  of  taking  information from the terminal during execution (because
+the here-document replaces the standard input) and  (b)  the  method  of
+access to command line arguments is clumsy.
+
diff --git a/miralib/manual/31/5 b/miralib/manual/31/5
new file mode 100644
index 0000000..546724d
--- /dev/null
+++ b/miralib/manual/31/5
@@ -0,0 +1,105 @@
+_H_o_w_ _t_o_ _c_h_a_n_g_e_ _t_h_e_ _d_e_f_a_u_l_t_ _e_d_i_t_o_r
+
+The Miranda /edit or /e command (see  manual  page  on  Miranda  command
+interpreter)  invokes  an  editor.  By default this is the screen editor
+"vi", but if you wish to use another editor, this is easily changed.
+
+The Miranda command
+	/editor
+
+reports the editor currently in use by the Miranda system.  To change it
+to (for example) pico, say
+	/editor pico
+
+Alternatively, when next invoking the miranda system from UNIX  you  can
+supply it with a flag requesting a specific editor by name, as follows:
+	mira -editor pico
+
+In either case it is only necessary to do this once  since  the  Miranda
+system  stores  this and other information in a file called ".mirarc" in
+your home directory - you should not remove or try to edit this file.
+
+You can select any editor that is installed on your system.  If you  are
+unfamiliar  with  vi  and haven't an editor in mind, the editor pico (if
+installed) is particularly easy to use - it has instructions on  screen.
+Similar  are nano (an open source clone of pico) and joe.  Other editors
+include emacs and gvim - these both open a separate editor window.
+
+The editor you select will be used by both the /e command and by
+	??identifier
+which opens the relevant source file at the definition of identifier.
+
+_M_o_r_e_ _a_d_v_a_n_c_e_d_ _i_n_f_o_r_m_a_t_i_o_n
+
+The Miranda system is designed to work with an editor which can  open  a
+file  at  a  specified line number.  For example to make the editor `vi'
+open `file' at line 13, the UNIX command is
+        vi +13 file
+the Miranda system has built in knowledge of this, so if  the  installed
+editor  is `vi' and the compiler has found a syntax error in the script,
+the `/e' command will open the script at the line containing the error.
+
+To retain this ability when substituting another editor,  the  `/editor'
+command  requires  a  template for invoking the chosen editor at a given
+line number.  In this template the line number  is  represented  by  the
+character  `!'  and  the filename by `%'.  For example the full template
+for `vi' would be supplied as follows
+        /editor vi +! %
+
+If the `%' character does not occur in the template,  Miranda  will  add
+the  name  of  the  file at the end of the command.  So the template for
+`vi' could equally well be given as
+	/editor vi +!
+The same formula works for pico, nano, joe.  If the editor is  one  that
+starts up its own window, separate from the Miranda session window (gvim
+and emacs do this), you will want to make the editor run as a concurrent
+process by putting "&" at the end of the command, thus
+	/editor emacs +! % &
+Note  that  in  this  case  you  must include % where the filename goes,
+because adding it after the "&" would not make sense.
+
+In fact Miranda has built in knowledge of vi, pico, nano, joe, emacs and
+gvim,  so  just  giving the name of the editor will generate the correct
+template in these cases.
+
+If you install an editor without  the  capability  to  be  opened  at  a
+specified  line  number  (i.e.   you  cannot  give  a  template  for  it
+containing the `!' character), the /e command loses its ability to go to
+the right place after an error, and the `??' command will be disabled.
+
+The Miranda system will work without either of these features, but there
+is a significant loss of power in the user interface.
+
+If the installed editor lacks the `open at line number' feature, you may
+find  it  convenient  to  have  the  script  listed to the screen during
+compilation (this feature of the compiler can be switched on and off  by
+the  commands `/list', `/nolist').  As an assistance to naive users, the
+Miranda system turns on `/list' for you if the `/editor' command is used
+to install an editor without the `open at line number' feature.
+
+[Pathological case: if the editor command you wish to install contains a
+literal  `!'  or  `%'  that  you  don't want replaced, place a backslash
+before the relevant !  or %.  This protects it from being expanded.]
+
+_C_h_e_c_k_i_n_g_ _f_o_r_ _s_o_u_r_c_e_ _u_p_d_a_t_e_s
+
+If during a session changes have been made to any relevant source  file,
+the  Miranda  system automatically recompiles the current script and any
+other scripts which it directly or indirectly `%includes' and which have
+been  changed.   At  a  minimum this check is performed after each /edit
+command and after each shell escape.
+
+A mode of operation possible on a windowing system is to keep an  editor
+window and Miranda session window both open.  In this case more frequent
+checking is appropriate and you should say /recheck (see 6  "Summary  of
+remaining  commands").   This  sets  a  flag  which  tells  the  Miranda
+interpreter to check for source file  updates  before  each  evaluation,
+instead  of  only  after /e and !  commands.  But remember that you will
+need to save any edits to file before the `mira' session can see them.
+
+As an assistance to naive users /recheck is automatically turned  on  if
+/editor  is  used  to install an editor template which includes "&", the
+symbol used in UNIX shell commands to start a concurrent process.
+
+Say /norecheck to revert to the default behaviour.
+
diff --git a/miralib/manual/31/6 b/miralib/manual/31/6
new file mode 100644
index 0000000..d088c79
--- /dev/null
+++ b/miralib/manual/31/6
@@ -0,0 +1,38 @@
+_H_o_w_ _t_o_ _a_l_t_e_r_ _t_h_e_ _s_i_z_e_s_ _o_f_ _w_o_r_k_s_p_a_c_e_s
+
+The Miranda system uses two main internal workspaces called  "heap"  and
+"dic".   If  either overflows during a session, a self explanatory error
+message is given.  The sizes of both areas may changed by  the  user  if
+required.   Any  change made is remembered thereafter and for subsequent
+sessions until countermanded.
+
+The heap contains almost all the data structures  created  both  by  the
+Miranda  compiler and the evaluation system.  To compile and/or run very
+large scripts you may need a bigger heap.   To  find  out  (change)  the
+current size of the heap say
+	/heap		(or /heap newsize  e.g.   /heap 2000000 )
+
+The heap size may also be altered by using  a  flag  (see  below).   You
+should  be  aware  that running Miranda processes with a very large heap
+may give you slower responses.
+
+The dictionary is used to  store  identifiers  and  file  names  by  the
+Miranda  compiler.  It is unlikely that you will need to change the size
+of  the  dictionary.   The  current  size  of  the  dictionary  can   be
+ascertained by the command
+	/dic
+
+it  cannot  be  changed dynamically, from within the Miranda system.  To
+alter the dictionary size use a flag (see next para).
+
+The sizes of either or both areas may be set by flags when invoking  the
+miranda system.  The following shows both possibilities
+	mira -dic 80000 -heap 2000000 [script]
+
+Note that the size of the heap is given in `cells' (a cell is  9  bytes,
+currently) and the size of the dictionary is in bytes.
+
+The  most  recent settings of the workspace sizes are stored in the file
+".mirarc" in the users home directory, and automatically carried over to
+the next miranda session.
+
diff --git a/miralib/manual/31/7 b/miralib/manual/31/7
new file mode 100644
index 0000000..ae6b20c
--- /dev/null
+++ b/miralib/manual/31/7
@@ -0,0 +1,160 @@
+_O_p_t_i_o_n_s_,_ _s_e_t_u_p_ _f_i_l_e_s_ _e_t_c_.
+
+The full form of the `mira' command is
+	mira [flags...] [script]
+this command causes a Miranda session to be entered with the given  file
+as  current  script.   If  no  script  is  specified  a default filename
+`script.m' is assumed.  The specified file need not yet exist - in  this
+case  you  will  be  starting  a  Miranda  session with an empty current
+script.
+
+Note that `.m' is the standard extension  for  Miranda  language  source
+files  - the mira command always adds the `.m' extension, if missing, to
+any filename argument denoting a Miranda script.
+
+The available options are:
+
+	-lib pathname
+Tells mira to find miralib (directory containing libraries, manual pages
+etc.) at `pathname'.  The default is to look for miralib of same version
+number as the program  at  `/usr/lib/miralib',  `/usr/local/lib/miralib'
+and  `./miralib',  in  that  order.  The -lib flag overrides the version
+number check.  The same effect is obtained  by  setting  an  environment
+variable MIRALIB, see next manual section.
+
+	-gc
+Switches on a flag causing the garbage collector  to  print  information
+each  time  a  garbage  collection  takes  place.  This flag can also be
+switched on and off from within the  miranda  session  by  the  commands
+`/gc', `/nogc'.
+
+	-count
+Switches  on  a  flag  causing  statistics  to  be  printed  after  each
+expression  evaluation.   This flag can also be switched on and off from
+within the miranda session by the commands `/count', `/nocount'.
+
+	-list
+	-nolist
+Switches on (off) a flag causing Miranda scripts to  be  listed  to  the
+screen  during  compilation.   This flag can also be switched on and off
+from within the miranda session by the commands `/list', `/nolist'.
+
+	-nostrictif
+Enables  the  compiler  to  accept  old  Miranda  scripts  with  missing
+occurrences  of the keyword `if' in guard syntax.  Probably obsolete but
+retained just in case someone needs it.
+
+	-hush
+	-nohush
+The  miranda  system  decides  whether  or not to give prompts and other
+feedback by testing its standard input with `isatty'.  If  the  standard
+input  does not appear to be a terminal it assumes that prompts would be
+inappropriate, otherwise it gives them.  In either case  this  behaviour
+can be overriden by an explicit flag ("-hush" for silence, "-nohush" for
+prompts etc).  This switch is  also  available  from  within  a  miranda
+session by the commands `/hush', `/nohush'.
+
+	-dic SIZE
+Causes  the  dictionary (used by the compiler to store identifiers etc.)
+to be set up with SIZE bytes instead of the default 24kb.
+
+	-heap SIZE
+Causes the heap to be set up with SIZE  cells  instead  of  the  default
+(currently 100k).  This can also be done from within the miranda session
+by the command `/heap SIZE'.  A cell currently occupies 9 bytes.
+
+	-editor name
+Causes the resident  editor  (initially  `vi',  unless  the  environment
+variable  EDITOR  was set to something else) to be `name' instead.  This
+can also be done from within the miranda session by the command `/editor
+name'.
+
+	-UTF-8
+	-noUTF-8
+Assume the current locale is (is not) UTF-8 overriding environment vars
+(version 2.044 and later).
+
+	-stdenv
+Run mira without loading the standard environment.   Every  script  that
+needs  functions  from the standard environment will then have to either
+explicitly %include  <stdenv>  or  define  the  required  functions  for
+itself.  Not recommended as normal practice since it may have unexpected
+consequences (for example I/O will be limited by  the  absence  of  type
+sys-message).
+
+	-object
+Used for debugging the compiler.  Modifies behaviour  of  ?identifier(s)
+to  show  the  associated  combinator  code,  which  may  or  may not be
+comprehensible as there is no documentation other than the source code.
+
+_S_P_E_C_I_A_L_ _C_A_L_L_S
+ In addition the following special calls to `mira' are  available  which
+do  not  enter  a  Miranda  session  but  accomplish another purpose, as
+described below.
+
+	mira -man
+To enter the miranda online manual system directly from the UNIX shell.
+
+	mira -exp
+Special call permitting the use of miranda script as a stand-alone  UNIX
+command.  See separate manual page for details.
+
+	mira -log
+Same as -exp except that it redirects stderr to a file  log/mira.errors,
+if  log  directory  exists  in  the current directory and mira has write
+permission to it.
+
+	mira -make [sourcefiles]
+Forces  a check that all the miranda source files listed have up-to-date
+object code files, triggering compilation processes  if  necessary  (see
+manual subsection on the library mechanism: separate compilation).
+
+	mira -exports [sourcefiles]
+Sends  to  stdout  a  list  of  the  identifiers  exported  (see  manual
+subsection  on library mechanism: separate compilation) from each of the
+given miranda source files, together with their types  (may  also  force
+recompilation if needed).
+
+	mira -sources [sourcefiles]
+Sends to stdout a list of all the Miranda  source  files  on  which  the
+given  source  files  directly  or  indirectly  depend  (via %include or
+%insert statements), excluding the standard environment <stdenv>.
+
+	mira -version
+Gives version information.  This information can also be  obtained  from
+within a Miranda session by the command `/version'.
+
+	mira -V
+More detailed version information.
+
+_S_E_T_U_P_ _F_I_L_E_S
+
+The current settings of _d_i_c, _h_e_a_p and  _e_d_i_t_o_r  are  saved  in  the  file
+`.mirarc'  in  the users home directory, and are thereby carried over to
+the next miranda session.  The  settings  of  the  compiler  flag  which
+controls   whether  or  not  source  is  listed  to  the  screen  during
+compilation (toggled by the commands  _/_l_i_s_t  _/_n_o_l_i_s_t  during  a  Miranda
+session)  and  of  the flag which controls the frequency of checking for
+source updates (toggled by the commands /recheck  /norecheck)  are  also
+saved in the users `.mirarc' file.
+
+The default settings of these entities, which will be picked up  by  new
+users  executing  `mira' for the first time, are dic 24000 (bytes), heap
+100000 (9-byte  cells),  editor  _v_i,  nolist,  norecheck.   The  current
+settings  can  be  interrogated  from  a  Miranda session by the command
+`/settings' or `/s'.
+
+The defaults can be changed, on a system wide basis, by moving a copy of
+a  `.mirarc'  file  containing  the  desired settings into the `miralib'
+directory  (normally  found  at  /usr/lib/miralib).   The  user's  local
+.mirarc  file,  once  created in his home directory by the first call to
+mira, will override the global one, however.
+
+The behaviour of the `mira' program is also sensitive to the settings of
+certain environment variables - see separate manual entry about this.
+
+_O_U_T_P_U_T_ _B_U_F_F_E_R_I_N_G
+ Output from the Miranda system to the user's  terminal  should  not  be
+line buffered, or some things will not work as they are intended.  There
+is no problem about input being line buffered, however.
+
diff --git a/miralib/manual/31/8 b/miralib/manual/31/8
new file mode 100644
index 0000000..7b35202
--- /dev/null
+++ b/miralib/manual/31/8
@@ -0,0 +1,83 @@
+_E_n_v_i_r_o_n_m_e_n_t_ _v_a_r_i_a_b_l_e_s_ _u_s_e_d_ _b_y_ _M_i_r_a_n_d_a
+ (This section may be of particular interest to  installers  and  system
+administrators)
+
+The behaviour of the `mira' program is  sensitive  to  the  settings  of
+certain environment variables.
+
+An alternative location for the miralib directory may  be  specified  by
+setting  the  environment variable "MIRALIB".  An explicit -lib flag, if
+present, overrides this.
+
+The  first time it is called (i.e. if no .mirarc file is present, either
+in the home directory or in miralib) the miranda  system  picks  up  the
+name  of  the  resident editor from the environment variable EDITOR - if
+this is not set it assumes `vi'.
+
+At startup (version 2.044 and later) `mira' inspects LC_CTYPE or if that
+is  empty  LANG,  to  determine  if it is running in a UTF-8 locale.  On
+Windows/Cygwin this information is taken  from  the  "user-default  ANSI
+code page".  The flag -UTF-8 or -noUTF-8, if present, overrides.
+
+If the environment variable RECHECKMIRA is set (to any non-empty string)
+the  Miranda  system  rechecks  to see if any relevant source files have
+been updated, and performs  any  necessary  recompilation,  before  each
+interaction  with the user - this is the appropriate behaviour if an (eg
+emacs) editor window is being kept open permanently during  the  Miranda
+session.   If  this  environment  variable  is  not  set,  the  check is
+performed only after `/e' commands and `!' escapes.
+
+To decide  what  shell  to  use  in  `!'  escapes,  mira  looks  in  the
+environment  variable  SHELL (this will normally contain the name of the
+user's login shell).  If no SHELL is entered in the environment, /bin/sh
+is assumed.
+
+If environment variable MIRAPROMPT is set, its contents will be used  as
+the  session  prompt,  instead of the default prompt "Miranda " (version
+2.044 and later).
+
+If the environment variable NOSTRICTIF is set (to any non-empty  string)
+Miranda accepts old scripts with no `if' after the guard comma.
+
+For displaying pages of the manual mira uses the program entered in  the
+environment  as  VIEWER  -  if  this  variable is not set the default is
+likely to be 'more -d' or (roughly equivalent) 'less -EX'.
+
+If you set VIEWER to something, you may also need to set an  environment
+variable RETURNTOMENU.
+
+RETURNTOMENU=YES prevents another prompt being  given  after  displaying
+each  section, causing instead an immediate return to contents page.  It
+should be `YES' if VIEWER is a program that pauses for input at  end  of
+file (eg "less"), `NO' if VIEWER is a program that quits silently at end
+of file (eg "more", "less -EX").
+
+Finally note that a third environment variable MENUVIEWER can be set  to
+choose  the  program  used to display contents pages (by default this is
+normally 'cat' or 'more').
+
+To find the current settings of these display commands enter
+	???
+to the "next selection" prompt of the manual system.
+
+_H_o_w_ _t_o_ _s_e_t_ _a_n_ _e_n_v_i_r_o_n_m_e_n_t_ _v_a_r_i_a_b_l_e_ _i_n_ _y_o_u_r_ _U_N_I_X_ _s_h_e_l_l_:
+ (Reminder/tutorial information)
+
+Example, setting the environment variable VIEWER to /usr/local/view
+
+ (i) if you use a Bourne-like shell (sh ksh bash)
+     say at the UNIX command level (i.e. before calling Miranda)
+
+     export VIEWER=/usr/local/view
+
+     to undo the above say `unset VIEWER',
+     to make permanent add this line to your .profile or .bashrc
+
+ (ii) if you use a C shell (csh tcsh)
+      say at the UNIX command level (i.e. before calling Miranda)
+
+      setenv VIEWER /usr/local/view
+
+      to undo the above say `unsetenv VIEWER',
+      to make permanent add the setenv line to your .login or .cshrc
+
diff --git a/miralib/manual/31/9 b/miralib/manual/31/9
new file mode 100644
index 0000000..8e6bb2d
--- /dev/null
+++ b/miralib/manual/31/9
@@ -0,0 +1,54 @@
+_I_n_p_u_t_/_o_u_t_p_u_t_ _o_f_ _b_i_n_a_r_y_ _d_a_t_a
+
+From version 2.044 Miranda stdenv.m includes a function
+	readb :: [char]->[char]
+and new sys-message constructors
+	Stdoutb     :: [char]->sys_message
+	Tofileb     :: [char]->[char]->sys_message
+	Appendfileb :: [char]->[char]->sys_message
+
+These  behave  similarly  to  (respectively)   read,   Stdout,   Tofile,
+Appendfile  but  are needed in a UTF-8 locale for reading/writing binary
+data (for further explanation see below).  In a non UTF-8 locale they do
+not  behave differently from read, Stdout etc but you might still prefer
+to use them for handling binary data, for portability reasons.
+
+The notation $:- is used for the binary version of the  standard  input.
+In  a  non UTF-8 locale $:- and $- will produce the same results.  It is
+an error to access both $:- and $- in the same evaluation.
+
+_E_x_p_l_a_n_a_t_i_o_n
+
+The locale of a  UNIX  process  is  a  collection  of  settings  in  the
+environment  which  specify, among other things, what character encoding
+is in use.  To see this information use `locale'  as  a  shell  command.
+The analogous concept in Windows is called a "code page".
+
+UTF-8 is a standard for encoding text from a wide variety  of  languages
+as  a  byte  stream,  in  which  ascii  characters  (codes  0..127)  are
+represented by themselves while  other  symbols  are  represented  by  a
+sequence of two or more bytes: a `multibyte character'.
+
+The Miranda type `char' consists of characters  in  the  range  (0..255)
+where  the  codes  above  127  represent  various  accented  letters etc
+according to the conventions of Latin-1 (i.e. ISO-8859-1, commonly  used
+for  West  European  languages).  There are national variants on Latin-1
+but since Miranda source, outside  comments  and  string  and  character
+constants, uses only ascii this does not normally cause a problem.
+
+In a UTF-8 locale: on reading string/character literals  or  text  files
+Miranda has to translate multibyte characters to the corresponding point
+in the Latin-1 range (128-255).  If the text does  not  conform  to  the
+rules  of  UTF-8,  or  includes  a  character not present in Latin-1, an
+"illegal character"  error  occurs.   On  output,  Miranda  strings  are
+translated back to UTF-8.
+
+If data being read/written is not text, but binary data  of  some  kind,
+translation  from/to  UTF-8  is not appropriate and could cause "illegal
+character" errors, and/or corruption of data.  Whence the need  for  the
+byte  oriented  I/O functions readb etc, which transfer data without any
+conversion from/to UTF-8.
+
+In a non UTF-8 locale read and readb, Tofile and Tofileb,  etc.  do  not
+differ in their results.
+
diff --git a/miralib/manual/31/contents b/miralib/manual/31/contents
new file mode 100644
index 0000000..ef9fdbd
--- /dev/null
+++ b/miralib/manual/31/contents
@@ -0,0 +1,12 @@
+_U_N_I_X_/_M_i_r_a_n_d_a_ _s_y_s_t_e_m_ _i_n_t_e_r_f_a_c_e_ _i_n_f_o_r_m_a_t_i_o_n
+
+ 1. Input from UNIX files etc
+ 2. Output to UNIX files etc
+ 3. Reading with interpretation (`_r_e_a_d_v_a_l_s' and $+)
+ 4. Using Miranda to build UNIX commands
+ 5. How to change the default editor
+ 6. How to alter sizes of workspaces
+ 7. Options, setup files etc
+ 8. Environment variables used by Miranda
+ 9. Input/Output of binary data
+