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 Thanks for your time, Zach Riggle
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.
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
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.
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
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.
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. >
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. > > > > >
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.
> >
> > >
> >
> >
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.
> > >
> > > >
> > >
> > >
> 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
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 >
> 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
[-- 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 --]
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.
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.
# 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
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.
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?
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.
# 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
# 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
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)
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.
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)
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 >