revised read manual entry

[Peter Stephenson <pws@xxxxxxxxxxxx>]

The manual entry for the read builtin is a mess.  This divides the
options up sensibly, and also notes that -q and -k only read from the
terminal, which wasn't mentioned before.

One day, nobody will ever have to write nroff source again.  It's
thoughts like that that keep me going.

*** Doc/zshbuiltins.1.tidy	Fri Dec  1 16:08:39 1995
--- Doc/zshbuiltins.1	Fri Dec  1 16:47:34 1995
***************
*** 690,728 ****
  \fBr\fP
  Equivalent to \fBfc \-e \-\fP.
  .TP
! \fBread\fP [ \-\fBrzpqAclneE\fP ] [ -k [ \fInum\fP ] ] [ \-\fBu\fIn\fR ] [ \fIname\fP?\fIprompt\fP ] [ \fIname\fP ...  ]
  Read one line and break it into fields using the characters
! in \fBIFS\fP as separators.  In raw mode, \-\fBr\fP, a \e
! at the end of a line does not signify line continuation.
! With the \-\fBq\fP flag read only one character and set \fIname\fP to
! `y' if this character was `y' or `Y' and to `n' otherwise.  With this
! flag set the return value is zero only if the character was `y' or `Y'.
! If the \-\fBk\fP flag is given read only one (or \fInum\fP) characters.
! If the \-\fBz\fP flag is set, read from the editor buffer stack.
  The first field is assigned to the first \fIname\fP, the second field
  to the second \fIname\fP, etc., with leftover
  fields assigned to the last \fIname\fP.
! If the \-\fBe\fP or the \-\fBE\fP flag is given, the words read are
! printed after the whole line is read. If the \-\fBe\fP flag is set,
! the words are not assigned to the parameters.
! If the \-\fBA\fP flag is set, the first \fIname\fP is taken as the
  name of an array and all words are assigned to it.
! The \-\fBc\fP and \-\fBl\fP flags are allowed only if called inside a
  function used for completion (specified with the \-\fBK\fP flag to
  \fBcompctl\fP). If the \-\fBc\fP flag is given, the words of the
  current command are read. If the \-\fBl\fP flag is given, the whole
! line is assigned as a scalar. Together with the \-\fBn\fP flag these
! options give the number of the word the cursor is on and the index of
  the character the cursor is on respectively.
! If \fIname\fP is omitted then \fBREPLY\fP is used for scalars and
! \fBreply\fP for arrays.
! If \-\fBu\fIn\fR is specified, then input is read from file
! descriptor \fIn\fP; if \-\fBp\fP is specified, then input is
! read from the coprocess.
  If the first argument contains a \fB?\fP, the remainder of this
  word is used as a \fIprompt\fP on standard error when the shell
  is interactive.  The exit status is 0 unless an end-of-file
  is encountered.
  .TP
  \fBreadonly\fP [ \fIname\fP[=\fIvalue\fP] ] ...
  The given \fInames\fP are marked readonly; these names
--- 690,762 ----
  \fBr\fP
  Equivalent to \fBfc \-e \-\fP.
  .TP
! .PD 0
! \fBread\fP [ \-\fBrzpqAclneE\fP ] [ -k [ \fInum\fP ] ]
! .br
! [ \-\fBu\fIn\fR ] [ \fIname\fP?\fIprompt\fP ] [ \fIname\fP ...  ]
! .PD
! .RS
! .PP
  Read one line and break it into fields using the characters
! in \fBIFS\fP as separators.
! .PD 0
! .TP
! .B \-r
! Raw mode: a \e at the end of a line does not signify line
! continuation.
! .TP
! \-\fBq\fP
! Read only one character from the terminal and set \fIname\fP to
! `y' if this character was `y' or `Y' and to `n' otherwise.
! With this flag set the return value is zero only if the character was
! `y' or `Y'.
! .TP
! \-\fBk\fP [ \fInum\fP ]
! Read only one (or \fInum\fP) characters from the terminal.
! .TP
! \-\fBz\fP
! Read from the editor buffer stack.
  The first field is assigned to the first \fIname\fP, the second field
  to the second \fIname\fP, etc., with leftover
  fields assigned to the last \fIname\fP.
! .TP
! \-\fBe\fP
! .TP
! \-\fBE\fP
! The words read are printed after the whole line is read. If the
! \-\fBe\fP flag is set, the words are not assigned to the parameters.
! .TP
! \-\fBA\fP
! The first \fIname\fP is taken as the
  name of an array and all words are assigned to it.
! .TP
! \-\fBc\fP
! .TP
! \-\fBl\fP
! These flags are allowed only if called inside a
  function used for completion (specified with the \-\fBK\fP flag to
  \fBcompctl\fP). If the \-\fBc\fP flag is given, the words of the
  current command are read. If the \-\fBl\fP flag is given, the whole
! line is assigned as a scalar.  If \fIname\fP is omitted then
! \fBREPLY\fP is used for scalars and \fBreply\fP for arrays.
! .TP
! \-\fBn\fP
! Together with either of the previous flags, this
! option gives the number of the word the cursor is on or the index of
  the character the cursor is on respectively.
! .TP
! \-\fBu\fIn\fP
! Input is read from file descriptor \fIn\fP.
! .TP
! \-\fBp\fP
! Input is read from the coprocess.
! .PD
! .PP
  If the first argument contains a \fB?\fP, the remainder of this
  word is used as a \fIprompt\fP on standard error when the shell
  is interactive.  The exit status is 0 unless an end-of-file
  is encountered.
+ .RE
  .TP
  \fBreadonly\fP [ \fIname\fP[=\fIvalue\fP] ] ...
  The given \fInames\fP are marked readonly; these names

-- 
Peter Stephenson <pws@xxxxxx>       Tel: +49 33762 77366
WWW:  http://www.ifh.de/~pws/       Fax: +49 33762 77330
Deutches Electronen-Synchrotron --- Institut fuer Hochenergiephysik Zeuthen
DESY-IfH, 15735 Zeuthen, Germany.