* Re: Better Help Docs Searching?
2021-08-01 10:44 Better Help Docs Searching? Zach Riggle
@ 2021-08-01 11:01 ` Roman Perepelitsa
2021-08-01 16:21 ` Mikael Magnusson
` (3 subsequent siblings)
4 siblings, 0 replies; 26+ messages in thread
From: Roman Perepelitsa @ 2021-08-01 11:01 UTC (permalink / raw)
To: Zach Riggle; +Cc: Zsh Users
On Sun, Aug 1, 2021 at 12:46 PM Zach Riggle <zachriggle@gmail.com> wrote:
>
> 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).
There might be better ways but here's how I do it.
I have this in my ~/.zshrc:
autoload -Uz run-help
unalias run-help
This allows me to type "read" in an interactive shell and press Alt+h
(aka ESC h) to open the help file for the read builtin.
Sometimes this doesn't work (for example, try it with "bindkey"). In
this case I would run `man zshall` (one page to rule them all) and
search for " read" -- note a bunch of spaces in front. If this
query has too many hits, I would use "^ {4,}read\b". I use the same
trick when searching for the description of flags in man pages. For
example, to find the description of "-z" in `man rsync`, I would first
search for " -z" because it's easy to type and then for the more
specific "^ {4,}-z\b" in case I get too many hits.
Roman.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 10:44 Better Help Docs Searching? Zach Riggle
2021-08-01 11:01 ` Roman Perepelitsa
@ 2021-08-01 16:21 ` Mikael Magnusson
2021-08-01 16:33 ` Stephane Chazelas
2021-08-01 16:25 ` Bart Schaefer
` (2 subsequent siblings)
4 siblings, 1 reply; 26+ messages in thread
From: Mikael Magnusson @ 2021-08-01 16:21 UTC (permalink / raw)
To: Zach Riggle; +Cc: Zsh Users
On 8/1/21, Zach Riggle <zachriggle@gmail.com> 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
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 16:21 ` Mikael Magnusson
@ 2021-08-01 16:33 ` Stephane Chazelas
2021-08-01 18:52 ` Bart Schaefer
0 siblings, 1 reply; 26+ messages in thread
From: Stephane Chazelas @ 2021-08-01 16:33 UTC (permalink / raw)
To: Mikael Magnusson; +Cc: Zach Riggle, Zsh Users
2021-08-01 18:21:14 +0200, Mikael Magnusson:
[...]
> 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.
[...]
I only use "info" for reading the zsh manual (or any manual
larger than a few pages and that has an info manual, there's a
good reason we talk of man pages, and not man books, man is
really not adequate for a manual the size of zsh's).
In info, the "i" and "I" commands are your friends. They search
the index and have completion. There's also "g" to search the
nodes (the table of contents).
In zsh, the index is very good.
info zsh read
Will bring you to the section about the read builtin.
Within "info zsh", press "I" (Shift+i) and enter "read", and
you'll see all the index entries that contain "read".
IIRC, zsh completion also used to work properly with "info", but
as seen in the other thread I started in zsh-workers, it's
a bit broken currently. No big deal as info's own completion is
adequate.
Press "h" within "info" to get started with it.
It's really astonishing that so few people know about it after
so many decades it's been around.
--
Stephane
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 16:33 ` Stephane Chazelas
@ 2021-08-01 18:52 ` Bart Schaefer
2021-08-01 20:11 ` Ray Andrews
0 siblings, 1 reply; 26+ messages in thread
From: Bart Schaefer @ 2021-08-01 18:52 UTC (permalink / raw)
To: Mikael Magnusson, Zach Riggle, Zsh Users
On Sun, Aug 1, 2021 at 9:33 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>
> It's really astonishing that so few people know about it after
> so many decades it's been around.
GNU made a push some years ago to try to move everything from "man" to
"info", but it never really took hold.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 18:52 ` Bart Schaefer
@ 2021-08-01 20:11 ` Ray Andrews
2021-08-03 5:45 ` Zach Riggle
0 siblings, 1 reply; 26+ messages in thread
From: Ray Andrews @ 2021-08-01 20:11 UTC (permalink / raw)
To: zsh-users
On 2021-08-01 11:52 a.m., Bart Schaefer wrote:
> On Sun, Aug 1, 2021 at 9:33 AM Stephane Chazelas <stephane@chazelas.org> wrote:
>> It's really astonishing that so few people know about it after
>> so many decades it's been around.
Little tidbits like you guys have just coughed up would have saved God
knows how much frustration here. There's always a solution, but finding
it might not be so easy.
> GNU made a push some years ago to try to move everything from "man" to
> "info", but it never really took hold.
Strange, isn't it? Something in the culture sticks to the trusted
tradition even when a clear improvement is available. Seems to be a
Linux/Unix wide thing. I still remember my first successful install of
Linux. Bash without even command recall and no DELETE key, and one was
expected to either already know emacs or to use the nano editor. DOS
seemed advanced by comparison. Even zsh, one might think there's be
some default to user friendly setup out of the box but that's not the
way. Anyway not to whine -- thanks for the 'info' tips.
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 20:11 ` Ray Andrews
@ 2021-08-03 5:45 ` Zach Riggle
2021-08-03 8:03 ` Zach Riggle
2021-08-03 16:52 ` Bart Schaefer
0 siblings, 2 replies; 26+ messages in thread
From: Zach Riggle @ 2021-08-03 5:45 UTC (permalink / raw)
To: Ray Andrews; +Cc: Zsh Users
Thanks for all of the info (pun intended!), guys.
I've never intentionally used the "info" command, only used it
accidentally when I didn't import my zsh logging library (which
defines debug/info/warn/err/die etc for use in my various scripts).
## Using Info
When I invoke "info zsh" on my system (macOS 12) I do get some output.
However when I hit shift-i, the status line at the bottom states "No
indices found."
Invoking manually doesn't work either, so I think there's something
broken about the default install of Zsh on macOS (though I *also* have
it installed via homebrew).
$ info --index-search=read zsh
no index entries found for `read'
The "g" command works to jump between commands (e.g. "g read" takes me
to the equivalent of read(2) man pages).
I get "No indices found" for "info read" as well. :(
## Building Info from Source
It seems that I'm doing this incorrectly. I inspected the Makefile
and there is *definitely* an "info" target, but Make doesn't seem to
like it. I tried both with the OS-provided GNU Make (3.81), and also
with Homebrew installed GNU Make (4.3).
$ make info
make: *** No rule to make target `info'. Stop.
There is definitely an "info" target.
$ grep -E '\binfo\b' Makefile.in | head -1
dvi ps html info pdf:
Even trying to make it manually doesn't work
$ make -C Doc -f Makefile.in info
Makefile.in:30: *** missing separator. Stop.
## Other Info Curiosities
One thing that I really like / prefer about man pages is the $MANPAGER
variable, which I have configured to use bat(3) [1] as my pager, which
gives syntax highlighting, highlights command names, and flag names.
Is there an equivalent for "info" pages?
Here's a few examples:
* sh: https://i.imgur.com/rGjQo9v.png
* bash: https://i.imgur.com/ymnDh5V.png
* git: https://i.imgur.com/ABqbZmE.png
[1]: export MANPAGER="sh -c 'col -bx | bat -l man -p'"
(See https://github.com/sharkdp/bat#man. The entire "bat" project
is truly amazing.)
Zach Riggle
On Sun, Aug 1, 2021 at 3:11 PM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> On 2021-08-01 11:52 a.m., Bart Schaefer wrote:
> > On Sun, Aug 1, 2021 at 9:33 AM Stephane Chazelas <stephane@chazelas.org> wrote:
> >> It's really astonishing that so few people know about it after
> >> so many decades it's been around.
> Little tidbits like you guys have just coughed up would have saved God
> knows how much frustration here. There's always a solution, but finding
> it might not be so easy.
> > GNU made a push some years ago to try to move everything from "man" to
> > "info", but it never really took hold.
> Strange, isn't it? Something in the culture sticks to the trusted
> tradition even when a clear improvement is available. Seems to be a
> Linux/Unix wide thing. I still remember my first successful install of
> Linux. Bash without even command recall and no DELETE key, and one was
> expected to either already know emacs or to use the nano editor. DOS
> seemed advanced by comparison. Even zsh, one might think there's be
> some default to user friendly setup out of the box but that's not the
> way. Anyway not to whine -- thanks for the 'info' tips.
>
> >
>
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 5:45 ` Zach Riggle
@ 2021-08-03 8:03 ` Zach Riggle
2021-08-03 8:09 ` Zach Riggle
` (2 more replies)
2021-08-03 16:52 ` Bart Schaefer
1 sibling, 3 replies; 26+ messages in thread
From: Zach Riggle @ 2021-08-03 8:03 UTC (permalink / raw)
To: Ray Andrews; +Cc: Zsh Users
Okay, I'm a bit of an idiot. I've been so spoiled by "brew install"
that I forgot to "autoconf && ./configure".
This explains the "make" failures I was getting above. "make info"
now works for me, and generates "Docs/zsh.texi".
I don't want to "make install" and break things by putting stuff in
/usr/local (and I expect that using --prefix=some/other/directory will
prevent "info" from actually finding that content) -- so information
on how to generate the indices for the "info" command would still be
welcome.
I spent a while on Google searching things like "gnu info generate
(index|indices)" but can't really find much. "man info" isn't
helpful, and "info info" is doubly unhelpful.
Zach Riggle
On Tue, Aug 3, 2021 at 12:45 AM Zach Riggle <zachriggle@gmail.com> wrote:
>
> Thanks for all of the info (pun intended!), guys.
>
> I've never intentionally used the "info" command, only used it
> accidentally when I didn't import my zsh logging library (which
> defines debug/info/warn/err/die etc for use in my various scripts).
>
> ## Using Info
> When I invoke "info zsh" on my system (macOS 12) I do get some output.
> However when I hit shift-i, the status line at the bottom states "No
> indices found."
>
> Invoking manually doesn't work either, so I think there's something
> broken about the default install of Zsh on macOS (though I *also* have
> it installed via homebrew).
>
> $ info --index-search=read zsh
> no index entries found for `read'
>
> The "g" command works to jump between commands (e.g. "g read" takes me
> to the equivalent of read(2) man pages).
>
> I get "No indices found" for "info read" as well. :(
>
> ## Building Info from Source
> It seems that I'm doing this incorrectly. I inspected the Makefile
> and there is *definitely* an "info" target, but Make doesn't seem to
> like it. I tried both with the OS-provided GNU Make (3.81), and also
> with Homebrew installed GNU Make (4.3).
>
> $ make info
> make: *** No rule to make target `info'. Stop.
>
> There is definitely an "info" target.
>
> $ grep -E '\binfo\b' Makefile.in | head -1
> dvi ps html info pdf:
>
> Even trying to make it manually doesn't work
>
> $ make -C Doc -f Makefile.in info
> Makefile.in:30: *** missing separator. Stop.
>
> ## Other Info Curiosities
> One thing that I really like / prefer about man pages is the $MANPAGER
> variable, which I have configured to use bat(3) [1] as my pager, which
> gives syntax highlighting, highlights command names, and flag names.
> Is there an equivalent for "info" pages?
>
> Here's a few examples:
> * sh: https://i.imgur.com/rGjQo9v.png
> * bash: https://i.imgur.com/ymnDh5V.png
> * git: https://i.imgur.com/ABqbZmE.png
>
> [1]: export MANPAGER="sh -c 'col -bx | bat -l man -p'"
> (See https://github.com/sharkdp/bat#man. The entire "bat" project
> is truly amazing.)
>
> Zach Riggle
>
> On Sun, Aug 1, 2021 at 3:11 PM Ray Andrews <rayandrews@eastlink.ca> wrote:
> >
> > On 2021-08-01 11:52 a.m., Bart Schaefer wrote:
> > > On Sun, Aug 1, 2021 at 9:33 AM Stephane Chazelas <stephane@chazelas.org> wrote:
> > >> It's really astonishing that so few people know about it after
> > >> so many decades it's been around.
> > Little tidbits like you guys have just coughed up would have saved God
> > knows how much frustration here. There's always a solution, but finding
> > it might not be so easy.
> > > GNU made a push some years ago to try to move everything from "man" to
> > > "info", but it never really took hold.
> > Strange, isn't it? Something in the culture sticks to the trusted
> > tradition even when a clear improvement is available. Seems to be a
> > Linux/Unix wide thing. I still remember my first successful install of
> > Linux. Bash without even command recall and no DELETE key, and one was
> > expected to either already know emacs or to use the nano editor. DOS
> > seemed advanced by comparison. Even zsh, one might think there's be
> > some default to user friendly setup out of the box but that's not the
> > way. Anyway not to whine -- thanks for the 'info' tips.
> >
> > >
> >
> >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 8:03 ` Zach Riggle
@ 2021-08-03 8:09 ` Zach Riggle
2021-08-03 8:44 ` Peter Stephenson
2021-08-03 11:28 ` david rayner
2021-08-05 15:31 ` Vincent Lefevre
2 siblings, 1 reply; 26+ messages in thread
From: Zach Riggle @ 2021-08-03 8:09 UTC (permalink / raw)
To: Ray Andrews; +Cc: Zsh Users
Follow-up-to-follow-up, and apologies for the spam. It appears that,
while "make info" worked, it did not actually generate anything useful
in "Doc/zsh.texi".
$ make info
makeinfo ./zsh.texi
$ git status --ignored -sb | grep '!!' | awk '{print $2}' | xargs wc -l
114 Config/defs.mk
655 Doc/Makefile
36 Doc/Zsh/manmodmenu.yo
221 Doc/Zsh/modlist.yo
38 Doc/Zsh/modmenu.yo
9 Doc/version.yo
2 Doc/zsh.info <------- two bytes
0 Doc/zsh.texi <------- zero
292 Etc/Makefile
403 Makefile
452 Src/Makefile
306 Test/Makefile
22195 config.log
194 config.modules.sh
1368 config.status
16791 configure
43076 total
Zach Riggle
On Tue, Aug 3, 2021 at 3:03 AM Zach Riggle <zachriggle@gmail.com> wrote:
>
> Okay, I'm a bit of an idiot. I've been so spoiled by "brew install"
> that I forgot to "autoconf && ./configure".
>
> This explains the "make" failures I was getting above. "make info"
> now works for me, and generates "Docs/zsh.texi".
>
> I don't want to "make install" and break things by putting stuff in
> /usr/local (and I expect that using --prefix=some/other/directory will
> prevent "info" from actually finding that content) -- so information
> on how to generate the indices for the "info" command would still be
> welcome.
>
> I spent a while on Google searching things like "gnu info generate
> (index|indices)" but can't really find much. "man info" isn't
> helpful, and "info info" is doubly unhelpful.
>
> Zach Riggle
>
> On Tue, Aug 3, 2021 at 12:45 AM Zach Riggle <zachriggle@gmail.com> wrote:
> >
> > Thanks for all of the info (pun intended!), guys.
> >
> > I've never intentionally used the "info" command, only used it
> > accidentally when I didn't import my zsh logging library (which
> > defines debug/info/warn/err/die etc for use in my various scripts).
> >
> > ## Using Info
> > When I invoke "info zsh" on my system (macOS 12) I do get some output.
> > However when I hit shift-i, the status line at the bottom states "No
> > indices found."
> >
> > Invoking manually doesn't work either, so I think there's something
> > broken about the default install of Zsh on macOS (though I *also* have
> > it installed via homebrew).
> >
> > $ info --index-search=read zsh
> > no index entries found for `read'
> >
> > The "g" command works to jump between commands (e.g. "g read" takes me
> > to the equivalent of read(2) man pages).
> >
> > I get "No indices found" for "info read" as well. :(
> >
> > ## Building Info from Source
> > It seems that I'm doing this incorrectly. I inspected the Makefile
> > and there is *definitely* an "info" target, but Make doesn't seem to
> > like it. I tried both with the OS-provided GNU Make (3.81), and also
> > with Homebrew installed GNU Make (4.3).
> >
> > $ make info
> > make: *** No rule to make target `info'. Stop.
> >
> > There is definitely an "info" target.
> >
> > $ grep -E '\binfo\b' Makefile.in | head -1
> > dvi ps html info pdf:
> >
> > Even trying to make it manually doesn't work
> >
> > $ make -C Doc -f Makefile.in info
> > Makefile.in:30: *** missing separator. Stop.
> >
> > ## Other Info Curiosities
> > One thing that I really like / prefer about man pages is the $MANPAGER
> > variable, which I have configured to use bat(3) [1] as my pager, which
> > gives syntax highlighting, highlights command names, and flag names.
> > Is there an equivalent for "info" pages?
> >
> > Here's a few examples:
> > * sh: https://i.imgur.com/rGjQo9v.png
> > * bash: https://i.imgur.com/ymnDh5V.png
> > * git: https://i.imgur.com/ABqbZmE.png
> >
> > [1]: export MANPAGER="sh -c 'col -bx | bat -l man -p'"
> > (See https://github.com/sharkdp/bat#man. The entire "bat" project
> > is truly amazing.)
> >
> > Zach Riggle
> >
> > On Sun, Aug 1, 2021 at 3:11 PM Ray Andrews <rayandrews@eastlink.ca> wrote:
> > >
> > > On 2021-08-01 11:52 a.m., Bart Schaefer wrote:
> > > > On Sun, Aug 1, 2021 at 9:33 AM Stephane Chazelas <stephane@chazelas.org> wrote:
> > > >> It's really astonishing that so few people know about it after
> > > >> so many decades it's been around.
> > > Little tidbits like you guys have just coughed up would have saved God
> > > knows how much frustration here. There's always a solution, but finding
> > > it might not be so easy.
> > > > GNU made a push some years ago to try to move everything from "man" to
> > > > "info", but it never really took hold.
> > > Strange, isn't it? Something in the culture sticks to the trusted
> > > tradition even when a clear improvement is available. Seems to be a
> > > Linux/Unix wide thing. I still remember my first successful install of
> > > Linux. Bash without even command recall and no DELETE key, and one was
> > > expected to either already know emacs or to use the nano editor. DOS
> > > seemed advanced by comparison. Even zsh, one might think there's be
> > > some default to user friendly setup out of the box but that's not the
> > > way. Anyway not to whine -- thanks for the 'info' tips.
> > >
> > > >
> > >
> > >
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 8:09 ` Zach Riggle
@ 2021-08-03 8:44 ` Peter Stephenson
2021-08-03 9:40 ` Zach Riggle
0 siblings, 1 reply; 26+ messages in thread
From: Peter Stephenson @ 2021-08-03 8:44 UTC (permalink / raw)
To: Zsh Users
> On 03 August 2021 at 09:09 Zach Riggle <zachriggle@gmail.com> wrote:
> Follow-up-to-follow-up, and apologies for the spam. It appears that,
> while "make info" worked, it did not actually generate anything useful
> in "Doc/zsh.texi".
>
> $ make info
> makeinfo ./zsh.texi
>
> $ git status --ignored -sb | grep '!!' | awk '{print $2}' | xargs wc -l
> 114 Config/defs.mk
> 655 Doc/Makefile
> 36 Doc/Zsh/manmodmenu.yo
> 221 Doc/Zsh/modlist.yo
> 38 Doc/Zsh/modmenu.yo
> 9 Doc/version.yo
> 2 Doc/zsh.info <------- two bytes
> 0 Doc/zsh.texi <------- zero
zsh.texi is generated by an earlier stage from the Yodl source; makeinfo simply uses what's
there. If you don't have Yodl you can grab the doc package from the same place as the
source package and it has all this pre-built.
pws
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 8:44 ` Peter Stephenson
@ 2021-08-03 9:40 ` Zach Riggle
2021-08-03 9:57 ` Peter Stephenson
2021-08-03 16:47 ` Bart Schaefer
0 siblings, 2 replies; 26+ messages in thread
From: Zach Riggle @ 2021-08-03 9:40 UTC (permalink / raw)
To: Peter Stephenson; +Cc: Zsh Users
Peter
## Building Docs from Source
Thanks for the information. I might be misinterpreting your
information ("earlier stage...uses what's there") so I tried a "make
all" and the Docs/ directory seems to be in an even worse situation.
I also took "If you don't have Yodl" to mean "not having Yodl
installed / a yodl binary in $PATH". I don't see anything that I can
"brew install" that handles this, and having checked out the source
code for yodl (https://gitlab.com/fbb-git/yodl.git). Building YODL
itself requires "icmake" which is unavailable, and not installable via
"brew" (Homebrew).
## Using the Docs from SourceForge
> If you don't have Yodl you can grab the doc package from the same place as the
> source package and it has all this pre-built
I do see SourceForge has [1] a zsh-5.8-doc.tar.xz, which may be what
you referred to. It has the pre-built source, a pre-built PDF, and
does appear to have some ".info" files pre-built.
After extraction, running the command "info -f Doc/zsh.info" works.
Selecting the "17 Shell Builtin Commands" section, I can hit shift-i
to go to an "Index Entry". This is good! Before there were no
indices.
Typing in "read" the index prompt, takes me to the first incidence of
the word "read" (which is under the ". FILE" section), which isn't
much better than the man-pages or web-browser search. Hitting the
comma key (",") to move to the next match cycles between matches, but
never actually arrives at the documentation for the "read" builtin
[2].
[1]: https://zsh.sourceforge.io/Arc/source.html
[2]: https://i.imgur.com/2dPlevy.png
Zach Riggle
On Tue, Aug 3, 2021 at 3:45 AM Peter Stephenson
<p.w.stephenson@ntlworld.com> wrote:
>
> > On 03 August 2021 at 09:09 Zach Riggle <zachriggle@gmail.com> wrote:
> > Follow-up-to-follow-up, and apologies for the spam. It appears that,
> > while "make info" worked, it did not actually generate anything useful
> > in "Doc/zsh.texi".
> >
> > $ make info
> > makeinfo ./zsh.texi
> >
> > $ git status --ignored -sb | grep '!!' | awk '{print $2}' | xargs wc -l
> > 114 Config/defs.mk
> > 655 Doc/Makefile
> > 36 Doc/Zsh/manmodmenu.yo
> > 221 Doc/Zsh/modlist.yo
> > 38 Doc/Zsh/modmenu.yo
> > 9 Doc/version.yo
> > 2 Doc/zsh.info <------- two bytes
> > 0 Doc/zsh.texi <------- zero
>
> zsh.texi is generated by an earlier stage from the Yodl source; makeinfo simply uses what's
> there. If you don't have Yodl you can grab the doc package from the same place as the
> source package and it has all this pre-built.
>
> pws
>
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 9:40 ` Zach Riggle
@ 2021-08-03 9:57 ` Peter Stephenson
2021-08-03 16:47 ` Bart Schaefer
1 sibling, 0 replies; 26+ messages in thread
From: Peter Stephenson @ 2021-08-03 9:57 UTC (permalink / raw)
To: Zsh Users
> On 03 August 2021 at 10:40 Zach Riggle <zachriggle@gmail.com> wrote:
>
> ## Building Docs from Source
> Thanks for the information. I might be misinterpreting your
> information ("earlier stage...uses what's there") so I tried a "make
> all" and the Docs/ directory seems to be in an even worse situation.
>
> I also took "If you don't have Yodl" to mean "not having Yodl
> installed / a yodl binary in $PATH". I don't see anything that I can
> "brew install" that handles this, and having checked out the source
> code for yodl (https://gitlab.com/fbb-git/yodl.git). Building YODL
> itself requires "icmake" which is unavailable, and not installable via
> "brew" (Homebrew).
Yes, you do need the Yodl package (binary plus other files, so it's not
trivial) if you want to get all the way yourself.
Sorry I was unclear --- the Doc package comes from the source *site*, not
within the source distribution. So latest (a little out of date but should
be absolutely fine for your needs) is at
https://www.zsh.org/pub/zsh-5.8-doc.tar.xz
BTW as you were asking about other sources of help offlist, but this is more
widely useful: there is an active chat group that recently moved servers, though I don't
use it myself. This should definitely go in the FAQ. I think the following is up to date
(despite the misleading date associated with the page, you'll see the message has been
recently updated):
https://zsh.sourceforge.io/Arc/irc.html
pws
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 9:40 ` Zach Riggle
2021-08-03 9:57 ` Peter Stephenson
@ 2021-08-03 16:47 ` Bart Schaefer
1 sibling, 0 replies; 26+ messages in thread
From: Bart Schaefer @ 2021-08-03 16:47 UTC (permalink / raw)
To: Zach Riggle; +Cc: Peter Stephenson, Zsh Users
On Tue, Aug 3, 2021 at 2:40 AM Zach Riggle <zachriggle@gmail.com> wrote:
>
> I also took "If you don't have Yodl" to mean "not having Yodl
> installed / a yodl binary in $PATH". I don't see anything that I can
> "brew install" that handles this, and having checked out the source
> code for yodl (https://gitlab.com/fbb-git/yodl.git). Building YODL
> itself requires "icmake" which is unavailable, and not installable via
> "brew" (Homebrew).
Yodl is available from MacPorts.
> Typing in "read" the index prompt, takes me to the first incidence of
> the word "read" (which is under the ". FILE" section), which isn't
> much better than the man-pages or web-browser search.
The version of "info" that comes stock with MacOS 10.15 is very old
(4.8). The commands we've been recommending that you use expect a
more recent version, e.g., on Ubuntu it's 6.7. In older versions of
"info" the index entries only jump to the appropriate top-level
section and then search for the key string, which means they can end
up in the wrong place if the keyword appears more than once in a given
section.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 8:03 ` Zach Riggle
2021-08-03 8:09 ` Zach Riggle
@ 2021-08-03 11:28 ` david rayner
2021-08-05 15:31 ` Vincent Lefevre
2 siblings, 0 replies; 26+ messages in thread
From: david rayner @ 2021-08-03 11:28 UTC (permalink / raw)
To: zsh-users
[-- Attachment #1: Type: text/plain, Size: 504 bytes --]
On 03/08/2021 09:03, Zach Riggle wrote:
>
>> Invoking manually doesn't work either, so I think there's something
>> broken about the default install of Zsh on macOS (though I *also* have
>> it installed via homebrew).
>>
>> $ info --index-search=read zsh
>> no index entries found for `read'
>>
I had this problem on Linux Mint but not on Cygwin so assumed I'd broken
something
but actually I needed
sudo apt-get install zsh-doc
now following works
info --index-search=read zsh
zzapper
[-- Attachment #2: Type: text/html, Size: 955 bytes --]
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 8:03 ` Zach Riggle
2021-08-03 8:09 ` Zach Riggle
2021-08-03 11:28 ` david rayner
@ 2021-08-05 15:31 ` Vincent Lefevre
2 siblings, 0 replies; 26+ messages in thread
From: Vincent Lefevre @ 2021-08-05 15:31 UTC (permalink / raw)
To: Zach Riggle; +Cc: Ray Andrews, Zsh Users
On 2021-08-03 03:03:35 -0500, Zach Riggle wrote:
> Okay, I'm a bit of an idiot. I've been so spoiled by "brew install"
> that I forgot to "autoconf && ./configure".
>
> This explains the "make" failures I was getting above. "make info"
> now works for me, and generates "Docs/zsh.texi".
>
> I don't want to "make install" and break things by putting stuff in
> /usr/local (and I expect that using --prefix=some/other/directory will
> prevent "info" from actually finding that content) -- so information
> on how to generate the indices for the "info" command would still be
> welcome.
You can use --prefix=/some/other/directory and add
/some/other/directory/share/info to $INFOPATH.
--
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-03 5:45 ` Zach Riggle
2021-08-03 8:03 ` Zach Riggle
@ 2021-08-03 16:52 ` Bart Schaefer
1 sibling, 0 replies; 26+ messages in thread
From: Bart Schaefer @ 2021-08-03 16:52 UTC (permalink / raw)
To: Zach Riggle; +Cc: Zsh Users
On Mon, Aug 2, 2021 at 10:45 PM Zach Riggle <zachriggle@gmail.com> wrote:
>
> One thing that I really like / prefer about man pages is the $MANPAGER
> variable, which I have configured to use bat(3) [1] as my pager, which
> gives syntax highlighting, highlights command names, and flag names.
> Is there an equivalent for "info" pages?
There is not. Unlike manual pages, info pages are not designed for
display by a text pager. The info browser is the info browser.
If you use emacs, it has a more sophisticated "info" interface, but
it's still not a text pager.
RE the other thread about "info" on MacOS being old: If you've
downloaded the zsh-5.8-doc tarball, you've got the HTML files as well,
so you could browse those locally; they have the indexes.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 10:44 Better Help Docs Searching? Zach Riggle
2021-08-01 11:01 ` Roman Perepelitsa
2021-08-01 16:21 ` Mikael Magnusson
@ 2021-08-01 16:25 ` Bart Schaefer
2021-08-05 9:56 ` Vincent Lefevre
2021-08-04 6:30 ` Roman Neuhauser
2021-08-14 15:41 ` Daniel Shahaf
4 siblings, 1 reply; 26+ messages in thread
From: Bart Schaefer @ 2021-08-01 16:25 UTC (permalink / raw)
To: Zach Riggle; +Cc: Zsh Users
On Sun, Aug 1, 2021 at 3:45 AM Zach Riggle <zachriggle@gmail.com> wrote:
>
> 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).
Install either texinfo or the standalone info browser and use "info
zsh" (or "info -f Doc/zsh.info" if you are in the zsh build tree and
have run "make info"). Those findex() references etc. that you found
in the yodl files are there to create linked index nodes for "info".
You can also jump straight to individual entries from the command line, e.g.,
info --index-search=read zsh
As it happens "info zsh read" also goes directly to the "read" builtin
but that form prefers menu items to the index.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 16:25 ` Bart Schaefer
@ 2021-08-05 9:56 ` Vincent Lefevre
0 siblings, 0 replies; 26+ messages in thread
From: Vincent Lefevre @ 2021-08-05 9:56 UTC (permalink / raw)
To: Bart Schaefer; +Cc: Zach Riggle, Zsh Users
On 2021-08-01 09:25:32 -0700, Bart Schaefer wrote:
> You can also jump straight to individual entries from the command line, e.g.,
>
> info --index-search=read zsh
>
> As it happens "info zsh read" also goes directly to the "read" builtin
> but that form prefers menu items to the index.
Shouldn't the run-help function use that (if available) instead of
the man page?
--
Vincent Lefèvre <vincent@vinc17.net> - Web: <https://www.vinc17.net/>
100% accessible validated (X)HTML - Blog: <https://www.vinc17.net/blog/>
Work: CR INRIA - computer arithmetic / AriC project (LIP, ENS-Lyon)
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 10:44 Better Help Docs Searching? Zach Riggle
` (2 preceding siblings ...)
2021-08-01 16:25 ` Bart Schaefer
@ 2021-08-04 6:30 ` Roman Neuhauser
2021-08-04 14:56 ` Ray Andrews
2021-08-04 16:05 ` Bart Schaefer
2021-08-14 15:41 ` Daniel Shahaf
4 siblings, 2 replies; 26+ messages in thread
From: Roman Neuhauser @ 2021-08-04 6:30 UTC (permalink / raw)
To: Zach Riggle, Zsh Users
# zachriggle@gmail.com / 2021-08-01 05:44:52 -0500:
> 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).
"/^ *read \[" (without the quotes) followed by ^J or ^M will get you
there, but boy, the ergonomy of three consecutive key presses with a
stretched out pinky finger... :(
# zachriggle@gmail.com / 2021-08-03 00:45:22 -0500:
> One thing that I really like / prefer about man pages is the $MANPAGER
> variable, which I have configured to use bat(3) [1] as my pager, which
> gives syntax highlighting, highlights command names, and flag names.
> Is there an equivalent for "info" pages?
that's an impossible task, metadata in info files only goes as far as
^L preceding menus from what i've seen... man pages can be styled by
your pager because the file you're viewing in the pager includes the
style info. roff is a cumbersome markup language, but it's what you
make it to be. while most man pages you'll find on linux are written
using the man(7) macro set, mdoc(7) provides a semantic marup language.
man(7) from https://mandoc.bsd.lv/ (found in many BSDs and Linux
distros):
The man language was the standard formatting language for AT&T UNIX
manual pages from 1979 to 1989. Do not use it to write new manual
pages: it is a purely presentational language and lacks support for
semantic markup. Use the mdoc(7) language, instead.
just to clarify, this is not about abandoning man pages. man(7) and
mdoc(7) are "just" different markups to write man pages in.
btw, zsh's man pages use man(7), as is usual with generated man pages.
man(7) gives you this level of info:
.PD 0
\fBcd\fP [ \fB\-qsLP\fP ] [ \fIarg\fP ]
.TP
.PD 0
\fBcd\fP [ \fB\-qsLP\fP ] \fIold\fP \fInew\fP
.TP
.PD = vertical margin
\fB = bold font
\fI = italic font
\fP = previous font
.TP = "tagged paragraph", normally term + definition in a list
of definitions. not here though.
they're on different levels, and i can see why someone writing
manuals for linux would find man pages pointless.
this could have been (in mdoc(7)):
.Ic cd
.Op Fl qsLP
.Op Ar arg
.
.Ic cd
.Op Fl qsLP
.Ar old
.Ar new
.Ic = interactive command, .Op = optional, .Ar argument.
the Op macro generates the brackets around its argument.
totally different level of discourse.
two more examples; these three are entirely different and
perfectly distinguishable:
.\" optional flag to the program
.Op Fl n
.\" optional flag to the program, requires an argument
.Op Fl n Ar DIR
.\" mandatory operand to the program
.Ar DIR
environment variables don't get mixed up with syntax non-terminals:
.Ev TERM
.Sy TERM
and if i go looking for all parts of git which accept --origin,
i won't drown in all the passing mentions of the flag elsewhere.
cooking with gas! meanwhile...
as long as our software vendors deliver man pages marked up in
man(7) we're out of luck: their pages may be pretty (if you ever
bothered to print one) but otherwise quite useless. it's different
with mdoc(7), tools to mine the data don't exist yet afaik, but at
they are feasible.
mdoc(7) is better than man(7) but still quite unpleasant to write
(better than docbook! low standard, i know), and certainly not
sufficient for things like finegrained links (all you get is semantic
markup for a list of references at the bottom, and intra-document
links targeting other *sections*). but it's already here and people
seem unwilling to give man pages up.
a good way forward imo is to deprecate the current man+pager model,
this coupling is too loose, man/whatis/apropos simply sucks, and
the pager can't fill the shoes either. there's no reason we shouldn't
be able to follow links between man pages or have ad-hoc indexes
generated from our in-viewer queries. info is not magic.
i believe that GNU could have spent a fraction of the effort they put
into texinfo on man instead, and we'd all be much happier today.
anyway, if your software vendors provide you with man(7)-based pages,
demand better! (you may have to roll up your sleeves though. :)
--
roman
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 6:30 ` Roman Neuhauser
@ 2021-08-04 14:56 ` Ray Andrews
2021-08-04 16:08 ` Bart Schaefer
2021-08-04 16:38 ` Roman Neuhauser
2021-08-04 16:05 ` Bart Schaefer
1 sibling, 2 replies; 26+ messages in thread
From: Ray Andrews @ 2021-08-04 14:56 UTC (permalink / raw)
To: zsh-users
On 2021-08-03 11:30 p.m., Roman Neuhauser wrote:
>
> simply sucks, and
It simply does, and it sure is comforting to hear it from an adeptus,
the novice tends to think that it's all his fault but sometimes not.
"i believe that GNU could have spent a fraction of the effort they put
into texinfo on man instead, and we'd all be much happier today."
It's more fun to hack code than to document it. I wish we had more cathedral and less bazaar. I remember my first exposure to a Linux GUI, I think it was KDE and you click on 'Help' and some of the pages were entirely blank or had one useless sentence. I wonder if anything at all could possibly be done about this.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 14:56 ` Ray Andrews
@ 2021-08-04 16:08 ` Bart Schaefer
2021-08-05 12:00 ` Ray Andrews
2021-08-04 16:38 ` Roman Neuhauser
1 sibling, 1 reply; 26+ messages in thread
From: Bart Schaefer @ 2021-08-04 16:08 UTC (permalink / raw)
To: Ray Andrews; +Cc: Zsh Users
I'm not really excited about carrying on this conversation in THIS forum, but:
On Wed, Aug 4, 2021 at 7:57 AM Ray Andrews <rayandrews@eastlink.ca> wrote:
>
> I remember my first exposure to a Linux GUI, I think it was KDE and you click on 'Help' and some of the pages were entirely blank or had one useless sentence.
That was a direct result of (1) GNU attempting to force all the
documentation into info format while the GUI help tools were still
man-page based, and (2) Linux vendors leaving out the full manual
pages by default because they wanted the smallest possible
distributions.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 16:08 ` Bart Schaefer
@ 2021-08-05 12:00 ` Ray Andrews
0 siblings, 0 replies; 26+ messages in thread
From: Ray Andrews @ 2021-08-05 12:00 UTC (permalink / raw)
To: zsh-users
On 2021-08-04 9:08 a.m., Bart Schaefer wrote:
> That was a direct result of (1) GNU attempting to force all the
> documentation into info format while the GUI help tools were still
> man-page based, and (2) Linux vendors leaving out the full manual
> pages by default because they wanted the smallest possible
> distributions.
Sheesh. I love those little insights you provide. But yes, no
conversation is the rule here.
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 14:56 ` Ray Andrews
2021-08-04 16:08 ` Bart Schaefer
@ 2021-08-04 16:38 ` Roman Neuhauser
1 sibling, 0 replies; 26+ messages in thread
From: Roman Neuhauser @ 2021-08-04 16:38 UTC (permalink / raw)
To: Ray Andrews; +Cc: zsh-users
# rayandrews@eastlink.ca / 2021-08-04 07:56:47 -0700:
> On 2021-08-03 11:30 p.m., Roman Neuhauser wrote:
> > simply sucks, and
> It simply does, and it sure is comforting to hear it from an adeptus,
> the novice tends to think that it's all his fault but sometimes not.
there's a little more to the story, i failed to keep up with the times!
parts of the tooling are much better nowadays than they were twenty
years ago, cf.
* https://www.freebsd.org/cgi/man.cgi?query=apropos&manpath=FreeBSD+4.4-RELEASE
* https://www.freebsd.org/cgi/man.cgi?query=apropos&manpath=FreeBSD+13.0-RELEASE
the contemporary version is basically altavista at its heyday, just
for man pages. the remaining work is to retire the man+pager combo
and make the advanced capabilities accessible from inside the integrated
viewer alongside a simplified interface.
> I wonder if anything at all could possibly be done about this.
"will nobody think of the beginners" is a perpetual problem. you can
learn to program, be very good at it, be in the right place at the
right time to actually have impact, and see how long you'll keep
interest in writing software that isn't for you anymore because you
have learned more efficient ways. all the while facing a deluge of
users complaining that it's still not enough. and do it gratis. :)
--
roman
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 6:30 ` Roman Neuhauser
2021-08-04 14:56 ` Ray Andrews
@ 2021-08-04 16:05 ` Bart Schaefer
2021-08-04 16:45 ` Roman Neuhauser
1 sibling, 1 reply; 26+ messages in thread
From: Bart Schaefer @ 2021-08-04 16:05 UTC (permalink / raw)
To: Roman Neuhauser; +Cc: Zach Riggle, Zsh Users
On Tue, Aug 3, 2021 at 11:30 PM Roman Neuhauser <neuhauser@sigpipe.cz> wrote:
>
> btw, zsh's man pages use man(7), as is usual with generated man pages.
> [...]
> anyway, if your software vendors provide you with man(7)-based pages,
> demand better! (you may have to roll up your sleeves though. :)
Certainly the yodl files for zsh could be amended to produce an mdoc
version, but does that really help when there are no capable display
programs?
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-04 16:05 ` Bart Schaefer
@ 2021-08-04 16:45 ` Roman Neuhauser
0 siblings, 0 replies; 26+ messages in thread
From: Roman Neuhauser @ 2021-08-04 16:45 UTC (permalink / raw)
To: Bart Schaefer; +Cc: Zach Riggle, Zsh Users
# schaefer@brasslantern.com / 2021-08-04 09:05:54 -0700:
> On Tue, Aug 3, 2021 at 11:30 PM Roman Neuhauser <neuhauser@sigpipe.cz> wrote:
> >
> > btw, zsh's man pages use man(7), as is usual with generated man pages.
> > [...]
> > anyway, if your software vendors provide you with man(7)-based pages,
> > demand better! (you may have to roll up your sleeves though. :)
>
> Certainly the yodl files for zsh could be amended to produce an mdoc
> version, but does that really help when there are no capable display
> programs?
chicken/egg problem, but see the other message, maybe the time is right.
--
roman
^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Better Help Docs Searching?
2021-08-01 10:44 Better Help Docs Searching? Zach Riggle
` (3 preceding siblings ...)
2021-08-04 6:30 ` Roman Neuhauser
@ 2021-08-14 15:41 ` Daniel Shahaf
4 siblings, 0 replies; 26+ messages in thread
From: Daniel Shahaf @ 2021-08-14 15:41 UTC (permalink / raw)
To: Zach Riggle; +Cc: Zsh Users
Zach Riggle wrote on Sun, Aug 01, 2021 at 05:44:52 -0500:
> 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.
We have a Vim syntax highlighting for yodl files which may help
(Util/zyodl.vim).
It should even be possible to create tags for both texinode() and
cindex()/findex()/kindex()/pindex()/tindex()/vindex() instances, using
ctags(1) with a few regexes on the command-line, and then use the usual
tag-jumping commands (:h -t, :h Q_ta).
> 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).
>
You could grep the yodl sources for «(read» _including_ the parentheses.
That would find references to the builtin without finding uses of the
ordinary English word "read". If your $EDITOR doesn't have yodl syntax
highlighting configured, you could then open the same part of the manual
in ${PREFERRED_VIEWING_FORMAT}.
Cheers,
Daniel
> [1]: https://zsh.sourceforge.io/Doc/Release/Shell-Builtin-Commands.html
>
> Thanks for your time,
> Zach Riggle
>
^ permalink raw reply [flat|nested] 26+ messages in thread