GNU bug report logs - #68963
30.0.50; [PATCH] Split Eshell built-in command documentation into subsections

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: 68963 <at> debbugs.gnu.org
Subject: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command documentation into subsections
Date: Wed, 07 Feb 2024 14:54:41 +0200

> Date: Tue, 6 Feb 2024 20:26:08 -0800
> Cc: 68963 <at> debbugs.gnu.org
> From: Jim Porter <jporterbugs <at> gmail.com>
> 
> On 2/6/2024 7:31 PM, Eli Zaretskii wrote:
> >> Date: Tue, 6 Feb 2024 16:02:32 -0800
> >> From: Jim Porter <jporterbugs <at> gmail.com>
> >>
> >> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.