run-help's man arguments

run-help's man arguments

[Peter Stephenson]

I've only recently started using the vanilla run-help supplied with the
shell.  Ages ago, in

http://www.zsh.org/mla/workers//2000/msg01589.html

run-help got changed to invoke "man $@" rather than "man $1".  This was
described as being "to allow the specification of sections and other man
options through" (sic, presumably something missing?)

The text has changed since then, but the basic feature is still there.

Nobody's ever complained about this, but this is surely weird; that's
not how you use run-help, the $@ is the stuff on the command line which
doesn't include anything for "man" unless you type it yourself, which is
rather against the spirit of run-help (and very well hidden).

I ran into this running run-help on

  locate -r stuff

which caused man to barf immediately due to the annoying and confusing
GNU feature that options can occur anywhere on the command line, so -r
is picked up as an option to "man" rather than "locate".  This
particular problem is fixed by

  POSIXLY_CORRECT=1 man $@:t

which is presumably benign for other versions of man so I'll commit it.

However, the original query remains.  Why do we need $@ rather than $1?
Why do I need man to produce the error messages

No manual entry for -r
No manual entry for stuff

?

I can see that help on something like "nice locate -r stuff" (stupid
example) or even "nice -n 10 locate -r stuff" does something sensible
but with some harmless error messages.  Is this the correct rationale?

Index: Functions/Misc/run-help
===================================================================
RCS file: /cvsroot/zsh/zsh/Functions/Misc/run-help,v
retrieving revision 1.15
diff -u -r1.15 run-help
--- Functions/Misc/run-help	25 Apr 2009 20:30:20 -0000	1.15
+++ Functions/Misc/run-help	5 Jun 2009 11:06:22 -0000
@@ -8,8 +8,7 @@
 #	autoload run-help
 #
 
-emulate -R zsh
-setopt localoptions
+emulate -RL zsh
 
 local HELPDIR="${HELPDIR:-/usr/share/zsh/$ZSH_VERSION/help}"
 
@@ -103,7 +102,7 @@
 		done
 		eval "run-help-$1:t ${(q@)cmd_args[2,-1]}"
 	    else
-		man $@:t
+		POSIXLY_CORRECT=1 man $@:t
 	    fi
 	fi
 	;;
-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: run-help's man arguments

[Bart Schaefer]

On Jun 5, 12:10pm, Peter Stephenson wrote:
}
} run-help got changed to invoke "man $@" rather than "man $1".  This was
} described as being "to allow the specification of sections and other man
} options through" (sic, presumably something missing?)

"options [to pass] through" I think.

} Nobody's ever complained about this, but this is surely weird; that's
} not how you use run-help, the $@ is the stuff on the command line
} which doesn't include anything for "man" unless you type it yourself,
} which is rather against the spirit of run-help (and very well hidden).

Someone probably mistook run-help for a function that one is intended
to be able to type out by hand (rather than invoke with a keystroke),
and wanted it to become a superset of the "man" command.  Although
how that would work for any of the other variations on where a command
is found, I have no idea.

} However, the original query remains.  Why do we need $@ rather than $1?

I don't think we ever did.  I suppose one could do something such as

    alias run-help='\run-help 1'

to try to restrict help to executable commands only, but then that will
fail for anything that is not an external command, so ...

Re: run-help's man arguments

[Jun T.]

I'm not familiar with zsh internals, but I think ESC-h (in the default  
bindings) is bound to the ZLE widget 'run-help' which calls the  
function "run-help" as "run-help $1". So "man $@:t" in the function is  
equivalent to "man $1:t" if called from the widget.

I believe most people use the run-help function via key binding, but  
there is a possibility that someone use it by explicitly typing it. Or  
by "alias m=run-help" and "m history", "m 3 printf" etc.

Re: run-help's man arguments

[Bart Schaefer]

On Jun 6, 12:52pm, Jun T. wrote:
} Subject: Re: run-help's man arguments
}
} I'm not familiar with zsh internals, but I think ESC-h (in the default  
} bindings) is bound to the ZLE widget 'run-help' which calls the  
} function "run-help" as "run-help $1".

You have a point there.  PWS, how did you manage to get run-help to
pass the entire locate command line to "man $@:t"?

The only time the whole command line is obtained is when there's a
function or alias named (in this example) "run-help-locate".

The only OTHER time multiple arguments are in $@ is when $1 is quoted
so the command is re-applied to ${(Q)1}, but in that case $@ is the
output from "whence", not the original command line.

} So "man $@:t" in the function is equivalent to "man $1:t" if called
} from the widget.

True except in the second of those latter two cases.
 
} I believe most people use the run-help function via key binding, but  
} there is a possibility that someone use it by explicitly typing it. Or  
} by "alias m=run-help" and "m history", "m 3 printf" etc.

That's the sort of "against the spirit" and "well-hidden" behavior to
which PWS referred.  Also note that "m 3 printf" will produce a bunch
of errors about not finding "3" before it gets around to running "man",
so it's not a particularly good use of run-help.

Re: run-help's man arguments

[Peter Stephenson]

Bart Schaefer wrote:
> On Jun 6, 12:52pm, Jun T. wrote:
> } Subject: Re: run-help's man arguments
> }
> } I'm not familiar with zsh internals, but I think ESC-h (in the default  
> } bindings) is bound to the ZLE widget 'run-help' which calls the  
> } function "run-help" as "run-help $1".
> 
> You have a point there.  PWS, how did you manage to get run-help to
> pass the entire locate command line to "man $@:t"?

It seems I'm using this widget.


local -a line

line=(${(qq)${(z)BUFFER}})
zle push-line
BUFFER="run-help ${line}"
zle accept-line


-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: run-help's man arguments

[Clint Adams]

On Mon, Jun 08, 2009 at 09:52:19AM +0100, Peter Stephenson wrote:
> It seems I'm using this widget.
> 
> 
> local -a line
> 
> line=(${(qq)${(z)BUFFER}})
> zle push-line
> BUFFER="run-help ${line}"
> zle accept-line

Presumably we can't start doing something like this by default
because of the default alias to man.

Re: run-help's man arguments

[Peter Stephenson]

Clint Adams wrote:
> On Mon, Jun 08, 2009 at 09:52:19AM +0100, Peter Stephenson wrote:
> > It seems I'm using this widget.
> > 
> > 
> > local -a line
> > 
> > line=(${(qq)${(z)BUFFER}})
> > zle push-line
> > BUFFER="run-help ${line}"
> > zle accept-line
> 
> Presumably we can't start doing something like this by default
> because of the default alias to man.

True, although if it seems useful it can be mentioned in the
documentation for the replacement run-help.  Based on recent experience,
I haven't been finding it *that* useful.  With a widget like this,
run-help could be made cleverer in this respect by offering to give help
for words following coproc, noglob, etc.

-- 
Peter Stephenson <pws@csr.com>                  Software Engineer
CSR PLC, Churchill House, Cambridge Business Park, Cowley Road
Cambridge, CB4 0WZ, UK                          Tel: +44 (0)1223 692070

Re: run-help's man arguments

[Bart Schaefer]

On Jun 8,  9:52am, Peter Stephenson wrote:
} Subject: Re: run-help's man arguments
}
} Bart Schaefer wrote:
} > You have a point there.  PWS, how did you manage to get run-help to
} > pass the entire locate command line to "man $@:t"?
} 
} It seems I'm using this widget.

(Sound of hand smacking forehead.)  I completely misunderstood your
original mail on this thread and confused the widget with the run-help
function that you patched.

} local -a line
} 
} line=(${(qq)${(z)BUFFER}})
} zle push-line
} BUFFER="run-help ${line}"
} zle accept-line

I can't find that anywhere (except this) in the zsh lists archives back
to 2003 (which I have where I can grep them).  Where did you find it, or
why did you write it?  (E.g., did you start trying it because you saw
the $@:t in run-help, or did you find $@:t because you were trying this?)

Incidentally $@:t has other problems with this widget, namely, it yields
an array consisting of the tail of every word on the command line, which
is probably not what you want.

On Jun 8,  3:03pm, Peter Stephenson wrote:
}
} I haven't been finding it *that* useful.  With a widget like this,
} run-help could be made cleverer in this respect by offering to give help
} for words following coproc, noglob, etc.

Hmm, run-help already does that for some keywords:

schaefer<503> coproc foo
schaefer<503> run-help foo  
foo not found
No manual entry for foo
schaefer<504> coproc foo

It doesn't do so for "noglob", "exec", etc. so I don't know exactly what
it is about coproc that's magical.

Re: run-help's man arguments

[Peter Stephenson]

On Mon, 08 Jun 2009 09:06:42 -0700
Bart Schaefer <schaefer@brasslantern.com> wrote:
> } local -a line
> } 
> } line=(${(qq)${(z)BUFFER}})
> } zle push-line
> } BUFFER="run-help ${line}"
> } zle accept-line
> 
> I can't find that anywhere (except this) in the zsh lists archives back
> to 2003 (which I have where I can grep them).  Where did you find it, or
> why did you write it?  (E.g., did you start trying it because you saw
> the $@:t in run-help, or did you find $@:t because you were trying this?)

It looks like I wrote it in January when I switched from my own run-help to
the standard one, so I must have been looking to see what else to do with
it and possibly spotted the multiple manual entry thing, but actually I
can't remember.

pws