zsh built in help features

zsh built in help features

[Perry Smith]

I have a newly installed Mac running Catalina with zsh.  It has a file such as /usr/share/zsh/5.7.1/help/setopt which is a help page for setopt.  How am I suppose to view that page?  "help setopt" says that help isn't a command.  "setopt --help" doesn't seem to work.

And... I'm also wondering if there are other help features which I've let to discover.

Thank you

Re: zsh built in help features

[Pier Paolo Grassi]

[-- Attachment #1: Type: text/plain, Size: 661 bytes --]

you can use the widget run-help after typing a command name on the command
line. that widget by default should be bind to alt-h. eg:
type: setopt
press: alt-h

cheers

Il giorno ven 18 ott 2019 alle 00:55 Perry Smith <pedz@easesoftware.com> ha
scritto:

> I have a newly installed Mac running Catalina with zsh.  It has a file
> such as /usr/share/zsh/5.7.1/help/setopt which is a help page for setopt.
> How am I suppose to view that page?  "help setopt" says that help isn't a
> command.  "setopt --help" doesn't seem to work.
>
> And... I'm also wondering if there are other help features which I've let
> to discover.
>
> Thank you
>
> --
Pier Paolo Grassi

Re: zsh built in help features

[Chris Nebel]

Where in macOS Terminal, “alt” is Escape, so esc-h, unless you’ve turned on “Use Option as Meta Key” in Preferences > Profiles > Keyboard, in which case it’s Option.

> On Oct 17, 2019, at 4:48 PM, Pier Paolo Grassi <pierpaolog@gmail.com> wrote:
> 
> you can use the widget run-help after typing a command name on the command
> line. that widget by default should be bind to alt-h. eg:
> type: setopt
> press: alt-h
> 
> cheers
> 
> Il giorno ven 18 ott 2019 alle 00:55 Perry Smith <pedz@easesoftware.com> ha
> scritto:
> 
>> I have a newly installed Mac running Catalina with zsh.  It has a file
>> such as /usr/share/zsh/5.7.1/help/setopt which is a help page for setopt.
>> How am I suppose to view that page?  "help setopt" says that help isn't a
>> command.  "setopt --help" doesn't seem to work.
>> 
>> And... I'm also wondering if there are other help features which I've let
>> to discover.
>> 
>> Thank you
>> 
>> --
> Pier Paolo Grassi

Re: zsh built in help features

[Perry Smith]

Thank you!!

> run-help setopt
> No manual entry for setopt
> pedz@MysticSlate ~ % setopt

Apple must not have something set up right.  I’ll go find the run-help script and see if I can fix it.

> On Oct 17, 2019, at 6:54 PM, Chris Nebel <c.nebel@mac.com> wrote:
> 
> Where in macOS Terminal, “alt” is Escape, so esc-h, unless you’ve turned on “Use Option as Meta Key” in Preferences > Profiles > Keyboard, in which case it’s Option.
> 
>> On Oct 17, 2019, at 4:48 PM, Pier Paolo Grassi <pierpaolog@gmail.com> wrote:
>> 
>> you can use the widget run-help after typing a command name on the command
>> line. that widget by default should be bind to alt-h. eg:
>> type: setopt
>> press: alt-h
>> 
>> cheers
>> 
>> Il giorno ven 18 ott 2019 alle 00:55 Perry Smith <pedz@easesoftware.com> ha
>> scritto:
>> 
>>> I have a newly installed Mac running Catalina with zsh.  It has a file
>>> such as /usr/share/zsh/5.7.1/help/setopt which is a help page for setopt.
>>> How am I suppose to view that page?  "help setopt" says that help isn't a
>>> command.  "setopt --help" doesn't seem to work.
>>> 
>>> And... I'm also wondering if there are other help features which I've let
>>> to discover.
>>> 
>>> Thank you
>>> 
>>> --
>> Pier Paolo Grassi
> 

Re: zsh built in help features

[dana]

On 17 Oct 2019, at 19:28, Perry Smith <pedz@easesoftware.com> wrote:
> Apple must not have something set up right.  I’ll go find the run-help
> script and see if I can fix it.

run-help is an alias for man by default. You need to run this (add it to your
zshrc if you like):

  unalias run-help
  autoload -Uz run-help

Then the function will be called instead.

This is documented in zshcontrib, and in the comments for run-help itself.

PS: I haven't updated to Catalina yet, but in the zsh shipped with Mojave
Apple apparently misconfigured their @runhelpdir@, so in order to get it to
work there you also had to set like HELPDIR=/usr/share/zsh/5.3/help. You might
need to do the same in Catalina if it doesn't Just Work after loading it

dana

Re: zsh built in help features

[Perry Smith]

YEA!!!

Thank you

I had found the _run-help script (is that what they are called?) and
found that HELPDIR needed to be set but then it does an
anonymous function with magic I don’t yet understand and
finally falls back to _man.  So I had gone down the path that
somehow “man” was suppose to do this — which didn’t make much
sense and it sure wasn’t working.

I hadn’t considered aliases.

Also… in my copies of _run-help, I don’t see any comments at all.



> On Oct 18, 2019, at 12:12 AM, dana <dana@dana.is> wrote:
> 
> On 17 Oct 2019, at 19:28, Perry Smith <pedz@easesoftware.com> wrote:
>> Apple must not have something set up right.  I’ll go find the run-help
>> script and see if I can fix it.
> 
> run-help is an alias for man by default. You need to run this (add it to your
> zshrc if you like):
> 
>  unalias run-help
>  autoload -Uz run-help
> 
> Then the function will be called instead.
> 
> This is documented in zshcontrib, and in the comments for run-help itself.
> 
> PS: I haven't updated to Catalina yet, but in the zsh shipped with Mojave
> Apple apparently misconfigured their @runhelpdir@, so in order to get it to
> work there you also had to set like HELPDIR=/usr/share/zsh/5.3/help. You might
> need to do the same in Catalina if it doesn't Just Work after loading it
> 
> dana
> 

Re: zsh built in help features

[dana]

On 18 Oct 2019, at 07:11, Perry Smith <pedz@easesoftware.com> wrote:
> I had found the _run-help script (is that what they are called?) and
> found that HELPDIR needed to be set but then it does an
> anonymous function with magic I don’t yet understand and
> finally falls back to _man.

The functions prefixed with _ are completion functions. The files for the
functions themselves are located elsewhere. To find one you can either run
`whence -v` on it (but it must be loaded first), or do something like the
following:

  # Print matching file paths
  print -rl - $^fpath/**/run-help(N)

  # Print contents of matching files
  cat -- $^fpath/**/run-help(N)

(whence/which/where can also print the contents, but again only after the
function is loaded, and they will strip all of the comments and formatting)

dana