Re: Documentation about Multios is misleading, and perhaps untrue

[Daniel Shahaf <d.s@daniel.shahaf.name>]

Tom Boyd wrote on Mon, 15 Oct 2018 20:45 -0400:
>  I think this section should just breifly describe that the file
> descriptors are opened before the command is executed, and that
> 
> command < file1 < file2
> 
> is *similar* to
> 
> cat file1 file2 | command
> 
> except that the first waits for all files to be opened *before* command
> executes and completely fails if any file opening fails, where as cat x y z
> | command immediately starts processing files and simply skips ones that
> fail.

It's really not zsh's job to document cat(1).

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)?

> On a more general philosophical note though, I get that context is
> important, but man pages and software references should **never** contain
> objectively false statements. It's not ok to say something that factually
> incorrect and justify it by assuming the reader will have enough "common
> sense" to determine what parts are correct and which arent. These
> references are the single souce of truth for a lot of readers.

Cheers,

Daniel