Re: Documentation about Multios is misleading, and perhaps untrue

[Peter Stephenson <p.stephenson@xxxxxxxxxxx>]

On Tue, 2018-10-16 at 02:07 +0000, Daniel Shahaf wrote:
> However, I agree with your overall point, that the statement about
> "equivalence" in the manual is incorrect.  At the same time, I think a
> different fix would be better:
> 
> 1. Ensure that it's documented that all redirections (input and output)
>    are opened before the command is even exec'd.  This is true for all
>    redirections, not just for MULTIOS syntaxes.
> 
> 2. In the section that gives analogies to cat(1) and sort(1), simply
>    state that the examples assume that all dirent names are ordinary,
>    readable files.
> 
> Makes sense?  Anybody volunteering to write the patch (not me)?

Not really.  This is the same point as Bart's --- that this is
documentation for zsh, not a primer on how shells work.
I won't labour the point, but this isn't a good place to document how a
shell normally does redirection.

Where I think there is a point here is for multios, where there is an
extra process hidden away to concatenate the files (and it's a forked
shell, not a "cat").  The fact that *that* process opens files
immediately isn't obvious and isn't standard.  So this could probably do
with a comment somewhere.  I've added this below (this updates my
previous comparison with cat).

Qualifying the documentation to say if this isn't an ordinary file or
isn't readable it might not behave in an ordinary way or you might not
be able to read it is also verbiage that's trying to cover for ignorance
beyond what the shell manual can deal with.  We could just as well
document any example in the manual that uses files to say you need to be
able to read them or you'll get an error, or that if it's a special file
it might be special.  Our job is instead to document, for example, the
way the nature of an error might differ from what a shell user might
expect.

One of our big problems is people finding the existing documentation too
thick to get through.  We can go on making it wordier and harder to get
through till the cows come home and it still won't make it a basic shell
primer.

What's needed here is not zsh documentation, it's something properly
written in its own right that introduces what a redirection (and,
indeed, everything else) is.  This would give proper examples and
context and comparisons and further reading and stuff you just don't get
in user manuals for tools, any tool.  Such things no doubt exist and it
would be better to refer to here rather than do a half-baked job
ourselves.

I have to say, even there, that if you look at my user guide (now rather
old, but basic syntax hasn't changed):

http://zsh.sourceforge.net/Guide/zshguide03.html#l60

which is very much more verbose, I think I assume even there that it's
obvious that in general (and ignoring the special nature of multios) a
redirection happens before the command is run.  But that's the sort of
place to mention this sort of thing.

pws

diff --git a/Doc/Zsh/redirect.yo b/Doc/Zsh/redirect.yo
index c793638..2c406b6 100644
--- a/Doc/Zsh/redirect.yo
+++ b/Doc/Zsh/redirect.yo
@@ -234,6 +234,9 @@ example(date >foo | cat)
 
 writes the date to the file `tt(foo)', and also pipes it to cat.
 
+Note that the shell opens all the files to be used in the multio process
+immediately, not at the point they are about to be written.
+
 Note also that redirections are always expanded in order.  This happens
 regardless of the setting of the tt(MULTIOS) option, but with the option
 in effect there are additional consequences. For example,
@@ -268,9 +271,13 @@ example(echo exit 0 >> *.sh)
 
 If the user tries to open a file descriptor for reading more than once,
 the shell opens the file descriptor as a pipe to a process that copies
-all the specified inputs to its output in the order
-specified, similar to bf(cat),
-provided the tt(MULTIOS) option is set.  Thus
+all the specified inputs to its output in the order specified, provided
+the tt(MULTIOS) option is set.  It should be noted that each file is
+opened immediately, not at the point where it is about to be read:
+this behaviour differs from tt(cat), so if strictly standard behaviour
+is needed, tt(cat) should be used instead.
+
+Thus
 
 example(sort <foo <fubar)