zsh-users
 help / color / mirror / code / Atom feed
From: Daniel Shahaf <d.s@daniel.shahaf.name>
To: Zach Riggle <zachriggle@gmail.com>
Cc: Zsh Users <zsh-users@zsh.org>
Subject: Re: Better Help Docs Searching?
Date: Sat, 14 Aug 2021 15:41:48 +0000	[thread overview]
Message-ID: <20210814154148.GF11391@tarpaulin.shahaf.local2> (raw)
In-Reply-To: <CAMP9c5m=oOwSvEaqVF62GF0=BjjMnS8fBEmbcWz9ydxqx=tvZQ@mail.gmail.com>

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
> 


      parent reply	other threads:[~2021-08-14 15:42 UTC|newest]

Thread overview: 26+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-08-01 10:44 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 18:52     ` Bart Schaefer
2021-08-01 20:11       ` Ray Andrews
2021-08-03  5:45         ` Zach Riggle
2021-08-03  8:03           ` Zach Riggle
2021-08-03  8:09             ` Zach Riggle
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
2021-08-03 11:28             ` david rayner
2021-08-05 15:31             ` Vincent Lefevre
2021-08-03 16:52           ` Bart Schaefer
2021-08-01 16:25 ` Bart Schaefer
2021-08-05  9:56   ` Vincent Lefevre
2021-08-04  6:30 ` Roman Neuhauser
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
2021-08-04 16:05   ` Bart Schaefer
2021-08-04 16:45     ` Roman Neuhauser
2021-08-14 15:41 ` Daniel Shahaf [this message]

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=20210814154148.GF11391@tarpaulin.shahaf.local2 \
    --to=d.s@daniel.shahaf.name \
    --cc=zachriggle@gmail.com \
    --cc=zsh-users@zsh.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.vuxu.org/mirror/zsh/

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).