Re: Better Help Docs Searching?

[Mikael Magnusson <mikachu@xxxxxxxxx>]

On 8/1/21, Zach Riggle <zachriggle@xxxxxxxxx> wrote:
> Hello all!
>
> The documentation for Zsh is awesome, when I can find the appropriate
> part of the online pages / man pages.  Unfortunately, finding the
> correct location in the docs is very hard -- e.g. when I'm trying to
> find out what a given builtin / flag / option / etc. does.
>
> A good example is the builtin 'read'.  Even knowing it's a builtin,
> and searching the docs [1] / man pages for builtins, it's still not
> very straightforward to find the docs on 'read'.  (There are 91
> matches for "read" on the online docs and 82 in zshbuiltins).
>
> I checked out the Zsh source, and can trivially find e.g.
>
> $ git grep 'findex(read)'
> Doc/Zsh/builtins.yo:1492:findex(read)
>
> Which is neat, but not quite useful since reading the raw YODL text is
> cumbersome.  YODL itself seems to be end-of-life / deprecated, so I
> don't expect this situation to change, and it would be an immense
> undertaking to rewrite Zsh docs in a different way.
>
> All of that said, is there any way to easily find keywords / flags in
> either the online docs OR the man pages -- rather than having way too
> many matches for other things that mention the same word (e.g. "read"
> as mentioned above).
>
> [1]: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html

I'm sure you tried the Index link at the top already, but if you click
Contents and scroll down, you'll see that there are multiple indices,
one of which is what you want:
https://zsh.sourceforge.io/Doc/Release/zsh_14.html#index_split-13_fn_letter-R

You can also find these in the pdf version of the documentation (not
sure if we provide this anywhere but you can build it yourself). The
info version also probably has them, but I'm not sure if anyone knows
how to navigate an info document.

-- 
Mikael Magnusson