From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections Date: Wed, 07 Feb 2024 14:54:41 +0200 Message-ID: <86eddozb72.fsf@gnu.org> References: <7c6e1a19-8657-f72a-4372-c1caa34bc4c5@gmail.com> <86mssdymon.fsf@gnu.org> <7ba997dc-80ed-1915-0953-e013fa8a7162@gmail.com> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="452"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 68963@debbugs.gnu.org To: Jim Porter Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Feb 07 13:56:13 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1rXhTI-000AO0-EY for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 07 Feb 2024 13:56:12 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1rXhSx-0000fG-Py; Wed, 07 Feb 2024 07:55:51 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rXhSu-0000ee-VH for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:55:50 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1rXhSu-0006oF-MB for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:55:48 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1rXhT8-00020A-Cy for bug-gnu-emacs@gnu.org; Wed, 07 Feb 2024 07:56:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 07 Feb 2024 12:56:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 68963 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 68963-submit@debbugs.gnu.org id=B68963.17073105067618 (code B ref 68963); Wed, 07 Feb 2024 12:56:02 +0000 Original-Received: (at 68963) by debbugs.gnu.org; 7 Feb 2024 12:55:06 +0000 Original-Received: from localhost ([127.0.0.1]:55845 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rXhSE-0001yo-8v for submit@debbugs.gnu.org; Wed, 07 Feb 2024 07:55:06 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]:53980) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1rXhSC-0001yF-B9 for 68963@debbugs.gnu.org; Wed, 07 Feb 2024 07:55:05 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1rXhRt-0006Ky-94; Wed, 07 Feb 2024 07:54:45 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=UOS8mETf59fCOPAE1zB/or4mfq81tsbF/6hFuGLDFSY=; b=SpV4bfKlYdxQ T34AugP07wpn3Uo+vmlpAKuzBCrw66CFWhGTbgUqNQ+4n3gdIS1N6qHsjzs0zoKu7lsGelLc8gFZt wwKd2O1lyur+BuaAdQQpfHA/KRtclN3NHhpFbcmxri5evJVizgO1AF5vkGTh45rYu8BgYU1U4NOrO wvkUCXpU0/3G3rsqI5fxwPTlQSVtaHyzuhUZkhTyFMfoKenoaLaMlCaJX++AKxnjRZgYhnVBQw9xn dak/cBZKwS5TzcQXTM5tZMsOAYUIlyMxi+AOPY/Jy217dYWm1Mdfz200jRw1Q58cQ3BfvL9bxrOe6 z3107Qw0+W7KjaWEqoZILw==; In-Reply-To: <7ba997dc-80ed-1915-0953-e013fa8a7162@gmail.com> (message from Jim Porter on Tue, 6 Feb 2024 20:26:08 -0800) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:279543 Archived-At: > Date: Tue, 6 Feb 2024 20:26:08 -0800 > Cc: 68963@debbugs.gnu.org > From: Jim Porter > > On 2/6/2024 7:31 PM, Eli Zaretskii wrote: > >> Date: Tue, 6 Feb 2024 16:02:32 -0800 > >> From: Jim Porter > >> > >> Currently, the Eshell manual lists all the built-in commands in one > >> section, which can make it hard to find the commands related to the > >> topic you care about. Here's a patch to split this into subsections of > >> various (loosely-defined) topics. > > > > If people look for commands by using 'i' (Info-index), then finding > > them in a single long section will be as easy as doing that in several > > shorter ones. > > The use-case I was imagining for this was a person thinking, "What > commands does Eshell have for working with [say] directories?" But then subdivision into sections has other problems. For example, who says that 'ls' is only "for directories", ln, mv, and rm are only "for files", and info is "for searching"? A person can reasonably think about these (and others) differently. And why "basename" is not about files? That is why we use indexing for providing flexible and accurate search capabilities: you can have more than one index entry for each piece of text, so you can satisfy different use cases where people have different phrases on their mind when thinking about something. So the right way of handling this is to use better indexing. You could index each command, for example: @cindex deleting files and directories @cindex file commands, deletion [text about 'rm' here] and in addition, you could have a short section with a list of "file-related commands", where each command or group of commands is followed by a cross-reference to the relevant place/section. Using sectioning for these purposes is not flexible enough to satisfy enough use cases, because it supports only a single way of looking at a subject, and people tend to think about them differently, especially if they need that in different contexts.