import Miranda 2.066 from upstream

1 files changed, 138 insertions, 0 deletions

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.
+