From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-3.4 required=5.0 tests=DKIM_SIGNED,DKIM_VALID, DKIM_VALID_AU,MAILING_LIST_MULTI,RCVD_IN_DNSWL_MED,UNPARSEABLE_RELAY autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 9213 invoked from network); 14 Aug 2021 15:42:56 -0000 Received: from zero.zsh.org (2a02:898:31:0:48:4558:7a:7368) by inbox.vuxu.org with ESMTPUTF8; 14 Aug 2021 15:42:56 -0000 ARC-Seal: i=1; cv=none; a=rsa-sha256; d=zsh.org; s=rsa-20210803; t=1628955776; b=Ytxz9AwpVH3iYU0eTdI8GsOcVu36Q2cFHxvbKqFC3CHrRlV5rK9QkDtzISJFazx2MYT9q7o2It D6qmLA/pZWD5opi/RWQkka7AtmZScqysFMNHW0z1D+UGAUjAMfAeXYZNUPNNQ+JvwvtZHLc74E Uy/qB1LAjaEzz4bf+1/FWWXKN2vWHZZ0jL6mBTU4rGK5MN0LX7fRGT5yGoP5J4zTvW00qfZoyS LYqqmH/YV3eluAmKZiWBE8oH9a5i9fUpBYxe/VAR8mcYIk8Pu61Nx9byk3CMv+fZb3QQwJRaJ8 yhicU2UJRR7wKldmO+4U1oz4qjcVD4dPsZvKXjd6/LO6rQ==; ARC-Authentication-Results: i=1; zsh.org; iprev=pass (out4-smtp.messagingengine.com) smtp.remote-ip=66.111.4.28; dkim=pass header.d=daniel.shahaf.name header.s=fm1 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm3 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed; d=zsh.org; s=rsa-20210803; t=1628955776; bh=sKKyJqxHQuUkK8jDzBL1+ZT6/wloqU7YahpTjbx+fEU=; h=List-Archive:List-Owner:List-Post:List-Unsubscribe:List-Subscribe:List-Help: List-Id:Sender:In-Reply-To:Content-Transfer-Encoding:Content-Type: MIME-Version:References:Message-ID:Subject:Cc:To:From:Date:DKIM-Signature: DKIM-Signature:DKIM-Signature; b=CdgudOPR1Q3cApzcsyMUWTY8LAszJ0tRG2k18K1bwSotirQJDDFWnPrNqGUJNAWhU3oKgZ1jyg PAXZaqsp2QcW5q56CRwy6IX99SEeNbSQ4LFe1wwNubUs7eBS1wx4N6AO5WsZtjbA5tY5ys2uGS 4X4r+W2sl8mpNdmQyOovA9IPDXCuGE9+8yVWeaZIRgpc/Lj8mKtcnUVQNG4elDY9GuAYxczHrq c0klCh6oFktp0qIM5XUfklsQ2Rkqr4p8q9Pi2KKlnUvu2BlupkLUrfXmwBPmrqvxSRKQ8/ilWz iY4RhS/aO7tpFSmb0MaOK9kIRYkjWvuQHibTsQO7CMMDZw==; DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=zsh.org; s=rsa-20210803; h=List-Archive:List-Owner:List-Post:List-Unsubscribe: List-Subscribe:List-Help:List-Id:Sender:In-Reply-To:Content-Transfer-Encoding :Content-Type:MIME-Version:References:Message-ID:Subject:Cc:To:From:Date: Reply-To:Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender :Resent-To:Resent-Cc:Resent-Message-ID; bh=CnZNvSx/FXVMg/A9NUXhCNZg1rR26Mrp2Zv0z15Zrbs=; b=k+kWiBRvajkf6VOF+M3J02ByeW 84OuYlHTLU+oQW3qFXl6StmNbEMpNwfjsP02bgZl+sZPGcAZM4PFNF08y3I9LPmAqQp/kxy7k9vTT TJTO96OR8C5OTFvRbR9Gg890NAvtDnysGG/xhre+Lg0eR52JfLYUpR7rHCh7Jbems3kIRx0B2JXHg WDTHP5gWmKFI3kIG4l+lCGI4ST7ScEGd3ul11EOjyHXNaXbAKaEHKt8zDcK49LMc4K45+up2lK6Ux QCFiHVkYtdGszhAqYGJxWnNfilXk62caXYbftZNU8hAnwBhe8hRfPVkOcriimckE0j7miN7+TU5sY YFIwTKRQ==; Received: from authenticated user by zero.zsh.org with local id 1mEvoF-0004J9-PX; Sat, 14 Aug 2021 15:42:55 +0000 Authentication-Results: zsh.org; iprev=pass (out4-smtp.messagingengine.com) smtp.remote-ip=66.111.4.28; dkim=pass header.d=daniel.shahaf.name header.s=fm1 header.a=rsa-sha256; dkim=pass header.d=messagingengine.com header.s=fm3 header.a=rsa-sha256; dmarc=none header.from=daniel.shahaf.name; arc=none Received: from out4-smtp.messagingengine.com ([66.111.4.28]:47313) by zero.zsh.org with esmtps (TLS1.3:TLS_AES_256_GCM_SHA384:256) id 1mEvnE-0003c3-Kv; Sat, 14 Aug 2021 15:41:54 +0000 Received: from compute6.internal (compute6.nyi.internal [10.202.2.46]) by mailout.nyi.internal (Postfix) with ESMTP id DF9D85C00BE; Sat, 14 Aug 2021 11:41:50 -0400 (EDT) Received: from mailfrontend1 ([10.202.2.162]) by compute6.internal (MEProxy); Sat, 14 Aug 2021 11:41:50 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= daniel.shahaf.name; h=date:from:to:cc:subject:message-id :references:mime-version:content-type:content-transfer-encoding :in-reply-to; s=fm1; bh=CnZNvSx/FXVMg/A9NUXhCNZg1rR26Mrp2Zv0z15Z rbs=; b=HVMQnRGt9kdfJGQTjem/6Jz3fS0RR5Y27RRMjIMbLe1BoKDmWAfXg1ea eRrjjPfzorD+BkMiUJ+28rA//STCUSwh70CeGTfuFI7/h9IsMN42mfkEKlnvs2pG N0C3HqvPp8gfngc9IlWIL47Lbn/aXIrcvcY0mOrzg2o1J//GbXbBDjvLAkmaQtHH y/3JnG7gNp0wwD+bhGj7Id5dh8sDNPHaXgqQ8IaGWiwQCjuBcMA8NlCDTqXg4ni0 cnk41DYpCx4eLllfUAi5efyMPEdYqJOeNvXE3V0JO3uKPHD9iZzckYFHm6Wy0nAd iNkEq3ukf5ki0/hdBGWkRHw3vvrY0A== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-transfer-encoding:content-type :date:from:in-reply-to:message-id:mime-version:references :subject:to:x-me-proxy:x-me-proxy:x-me-sender:x-me-sender :x-sasl-enc; s=fm3; bh=CnZNvSx/FXVMg/A9NUXhCNZg1rR26Mrp2Zv0z15Zr bs=; b=TLyXckVNeicndYtVjDmlSL/gTMg7VGakWZUwSxwc0d036NwDbh0nxY77i w0CwkYa80QTNSYZhZym3ucQCgI4hl12HWU8jEhElEGqDuD1mnNoGi+Ypz2wgaDxz 0Qwd5PUwseZzskn6fbSvk4GY9h2f0BvWkrIKtlaL5lAKSs8hmfXxR+8aaLyuNdDj NWbhQtsJpwjqRFJDmo6X9O5B04JDNnkmF2rg6epT6q87nnW1ulsMi9bbQ6VOZO9H oqW3GC8ApL3iLLDKO6jqUjkG6xjeu+tXwDg5kPLEeUGS3lcYtm3ofio3LJyUz9cg ElJcDnbxHFmmV4wPhMpEGNbzoJypA== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgedvtddrkeejgdelfecutefuodetggdotefrodftvf curfhrohhfihhlvgemucfhrghsthforghilhdpqfgfvfdpuffrtefokffrpgfnqfghnecu uegrihhlohhuthemuceftddtnecusecvtfgvtghiphhivghnthhsucdlqddutddtmdenuc fjughrpeffhffvuffkfhggtggugfgjfgesthektddttderudenucfhrhhomhepffgrnhhi vghlucfuhhgrhhgrfhcuoegurdhssegurghnihgvlhdrshhhrghhrghfrdhnrghmvgeqne cuggftrfgrthhtvghrnhepjeekudfgieejueekheefleevhedvgeehfeetleefheefgfdv gedvteeugfehueffnecuffhomhgrihhnpehvihhmrdhithdpshhouhhrtggvfhhorhhgvg drihhonecuvehluhhsthgvrhfuihiivgeptdenucfrrghrrghmpehmrghilhhfrhhomhep ugdrshesuggrnhhivghlrdhshhgrhhgrfhdrnhgrmhgv X-ME-Proxy: Received: by mail.messagingengine.com (Postfix) with ESMTPA; Sat, 14 Aug 2021 11:41:50 -0400 (EDT) Received: by tarpaulin.shahaf.local2 (Postfix, from userid 1005) id 4Gn4RJ1R7Bz4PQ; Sat, 14 Aug 2021 15:41:48 +0000 (UTC) Date: Sat, 14 Aug 2021 15:41:48 +0000 From: Daniel Shahaf To: Zach Riggle Cc: Zsh Users Subject: Re: Better Help Docs Searching? Message-ID: <20210814154148.GF11391@tarpaulin.shahaf.local2> References: MIME-Version: 1.0 Content-Type: text/plain; charset=iso-8859-1 Content-Disposition: inline Content-Transfer-Encoding: 8bit In-Reply-To: User-Agent: Mutt/1.10.1 (2018-07-13) X-Seq: 26930 Archived-At: X-Loop: zsh-users@zsh.org Errors-To: zsh-users-owner@zsh.org Precedence: list Precedence: bulk Sender: zsh-users-request@zsh.org X-no-archive: yes List-Id: List-Help: List-Subscribe: List-Unsubscribe: List-Post: List-Owner: List-Archive: 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 >