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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 68963 in the body.
You can then email your comments to 68963 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: 30.0.50; [PATCH] Split Eshell built-in command documentation into
 subsections
Date: Tue, 6 Feb 2024 16:02:32 -0800

[Message part 1 (text/plain, inline)]

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.

I welcome any suggestions about the division or the name of the 
subsections. For example, I split them into "Commands for Directories" 
and "Commands for Files", but an alternate scheme could be "Commands for 
Files and Directories" and "Commands for Changing the Current Directory".

Here's how I split the commands up in the patch, so you don't have to 
read through a huge diff:

# Commands for Directories
cd, dirs, du, ls, mkdir, popd, pushd, pwd, rmdir

# Commands for Files
cat, cp, diff, ln, mv, rm

# Commands for Searching
grep, agrep, egrep, fgrep, rgrep, glimpse, info, locate, man, occur

# Commands for Variables
env, export, set, setq, unset

# Commands for Using Other Commands
., addpath, alias, compile, jobs, kill, source, time, wait, which

# Miscellaneous Commands
basename, clear, clear-scrollback, date, dirname, echo, eshell-debug, 
exit, history, listify, make, printnl, umask, whoami

[0001-Split-Eshell-built-in-commands-documentation-into-su.patch (text/plain, attachment)]

Message #8 received at 68963 <at> debbugs.gnu.org (full text, mbox):

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

> 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.

Message #11 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Tue, 6 Feb 2024 20:26:08 -0800

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?" Since 
those were previously interspersed throughout the full command list, it 
would take a fair bit of skimming past irrelevant commands to find the 
directory-related ones.

For looking up a specific command though, I agree that the current 
manual is fine.

Message #14 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: 68963 <at> debbugs.gnu.org
Subject: Re: 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.

Message #17 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>, Jim Porter <jporterbugs <at> gmail.com>
Cc: 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Wed, 7 Feb 2024 12:22:55 -0800

Eli Zaretskii <eliz <at> gnu.org> writes:

>> Date: Tue, 6 Feb 2024 20:26:08 -0800
>> Cc: 68963 <at> debbugs.gnu.org
>> From: Jim Porter <jporterbugs <at> gmail.com>
>>
>> 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?

FWIW, I tend to agree with Eli: having all built-in commands on one page
also provides some benefit, especially to power users (the likely
audience for eshell) that are already familiar with a standard Unix
shell and just wants to know "what's different about Eshell" or "what
does Eshell provide".

However, I agree that the section is a bit long and unwieldy.  To make
it shorter, how about moving the section "Defining new built-in
commands" to some other part of the manual instead?  For example some
chapter that talks about "Extending Eshell" or similar.

Just my two cents.

Message #20 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Stefan Kangas <stefankangas <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Wed, 7 Feb 2024 18:05:07 -0800

[Message part 1 (text/plain, inline)]

On 2/7/2024 12:22 PM, Stefan Kangas wrote:
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
>> 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?
> 
> FWIW, I tend to agree with Eli: having all built-in commands on one page
> also provides some benefit, especially to power users (the likely
> audience for eshell) that are already familiar with a standard Unix
> shell and just wants to know "what's different about Eshell" or "what
> does Eshell provide".

Ok, no problem. It just seemed a bit hard to navigate to me, but I don't 
have any issues with keeping all the commands together.

> However, I agree that the section is a bit long and unwieldy.  To make
> it shorter, how about moving the section "Defining new built-in
> commands" to some other part of the manual instead?  For example some
> chapter that talks about "Extending Eshell" or similar.
> 
> Just my two cents.

How about the attached patch instead? It just moves the list of commands 
to a sub-node, and also makes the "defining new built-ins" a proper 
sub-node too. That should keep things a bit easier to navigate, and then 
we can add more indexing as needed later.

[0001-Put-the-list-of-built-in-Eshell-commands-in-its-own-.patch (text/plain, attachment)]

Message #23 received at 68963 <at> debbugs.gnu.org (full text, mbox):

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

> Date: Wed, 7 Feb 2024 18:05:07 -0800
> Cc: 68963 <at> debbugs.gnu.org
> From: Jim Porter <jporterbugs <at> gmail.com>
> 
> On 2/7/2024 12:22 PM, Stefan Kangas wrote:
> > Eli Zaretskii <eliz <at> gnu.org> writes:
> > 
> >> 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?
> > 
> > FWIW, I tend to agree with Eli: having all built-in commands on one page
> > also provides some benefit, especially to power users (the likely
> > audience for eshell) that are already familiar with a standard Unix
> > shell and just wants to know "what's different about Eshell" or "what
> > does Eshell provide".
> 
> Ok, no problem. It just seemed a bit hard to navigate to me, but I don't 
> have any issues with keeping all the commands together.

I'm not against subdividing that section.  My point was that if you
want these commands to be easier to find, the subdivision itself is
not enough; you need additional measures.

> How about the attached patch instead? It just moves the list of commands 
> to a sub-node, and also makes the "defining new built-ins" a proper 
> sub-node too. That should keep things a bit easier to navigate, and then 
> we can add more indexing as needed later.

No objections here.  But once again: your points about being able to
find the commands by categories are well-taken, and adding indexing to
make that easier would also be a good change.

Thanks.

Message #26 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stefankangas <at> gmail.com, 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Thu, 8 Feb 2024 12:30:46 -0800

[Message part 1 (text/plain, inline)]

On 2/7/2024 11:07 PM, Eli Zaretskii wrote:
> I'm not against subdividing that section.  My point was that if you
> want these commands to be easier to find, the subdivision itself is
> not enough; you need additional measures.

I think you and Stefan have successfully convinced me that there's no 
need to try and fuss with making arbitrary divisions of the built-in 
commands. It's tricky to split them up just right, and time spent on 
that should go towards adding indexing instead.

> No objections here.  But once again: your points about being able to
> find the commands by categories are well-taken, and adding indexing to
> make that easier would also be a good change.

Attached are some initial improvements to the indexing (patch 0003 in 
the series). It would probably be worth adding concept indices to 
most/all of the built-in commands, but the few I added here are pretty 
straightforward, and I can just poke at this a bit at a time for the 
remainder. (Writing documentation isn't the most viscerally exciting 
thing to do, so I prefer to spread the work out.)

I also added patch 0002, which moves the indexing above the "@item"s. 
That way, when you navigate to the entry from the index, it shows the 
header line listing the supported arguments when viewing the 
documentation as HTML.

[0001-Put-the-list-of-built-in-Eshell-commands-in-its-own-.patch (text/plain, attachment)]

[0002-In-Eshell-manual-put-command-index-anchors-above-the.patch (text/plain, attachment)]

[0003-Add-concept-indices-for-some-Eshell-commands.patch (text/plain, attachment)]

Message #29 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Stefan Kangas <stefankangas <at> gmail.com>
To: Jim Porter <jporterbugs <at> gmail.com>, Eli Zaretskii <eliz <at> gnu.org>
Cc: 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Thu, 8 Feb 2024 13:32:09 -0800

Jim Porter <jporterbugs <at> gmail.com> writes:

> Ok, no problem. It just seemed a bit hard to navigate to me, but I don't
> have any issues with keeping all the commands together.

I don't want to object to splitting it up or anything like that.
I'm only offering my perspective and ideas.

Should you go a different route, here are some ideas to improve your
categorization:

    # Commands for Directories
    cd, dirs, du, ls, mkdir, popd, pushd, pwd, rmdir

    # Commands for Files
    cat, cp, diff, ln, mv, rm

Probably unify these into one?

    # Commands for Searching
    grep, agrep, egrep, fgrep, rgrep, glimpse, info, locate, man, occur

"info" and "man" might belong under Miscellaneous Commands.

BTW, the "glimpse" command could use some documentation.  It's not as
popular as "grep", AFAIK, and many users don't know what it does.

    # Commands for Variables
    env, export, set, setq, unset

    # Commands for Using Other Commands
    ., addpath, alias, compile, jobs, kill, source, time, wait, which

Rather than "Using Other Commands" isn't this called "job control" or
something like that?

    # Miscellaneous Commands
    basename, clear, clear-scrollback, date, dirname, echo, eshell-debug,
    exit, history, listify, make, printnl, umask, whoami

"basename", "dirname" might belong under files/directories.

> How about the attached patch instead? It just moves the list of commands
> to a sub-node, and also makes the "defining new built-ins" a proper
> sub-node too. That should keep things a bit easier to navigate, and then
> we can add more indexing as needed later.

Yeah, this would also be an improvement.

BTW, another idea that might work is to offer both a summary in the form
of a table/list, and the detailed documentation in subnodes.  For
example, the above list placing commands into different categories could
go on the first page of your most recent patch.

Indexing would definitely help, too.  It's the first thing I reach for
in any manual.

Thanks again for working on improving the Eshell manual.  It's much
appreciated.

Message #32 received at 68963 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Jim Porter <jporterbugs <at> gmail.com>
Cc: stefankangas <at> gmail.com, 68963 <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Fri, 09 Feb 2024 09:05:18 +0200

> Date: Thu, 8 Feb 2024 12:30:46 -0800
> Cc: stefankangas <at> gmail.com, 68963 <at> debbugs.gnu.org
> From: Jim Porter <jporterbugs <at> gmail.com>
> 
> > No objections here.  But once again: your points about being able to
> > find the commands by categories are well-taken, and adding indexing to
> > make that easier would also be a good change.
> 
> Attached are some initial improvements to the indexing (patch 0003 in 
> the series). It would probably be worth adding concept indices to 
> most/all of the built-in commands, but the few I added here are pretty 
> straightforward, and I can just poke at this a bit at a time for the 
> remainder. (Writing documentation isn't the most viscerally exciting 
> thing to do, so I prefer to spread the work out.)
> 
> I also added patch 0002, which moves the indexing above the "@item"s. 
> That way, when you navigate to the entry from the index, it shows the 
> header line listing the supported arguments when viewing the 
> documentation as HTML.

LGTM, thanks.  Yes, index entries should always be before the
corresponding @item's.

Message #37 received at 68963-done <at> debbugs.gnu.org (full text, mbox):

From: Jim Porter <jporterbugs <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: stefankangas <at> gmail.com, 68963-done <at> debbugs.gnu.org
Subject: Re: bug#68963: 30.0.50; [PATCH] Split Eshell built-in command
 documentation into subsections
Date: Fri, 9 Feb 2024 17:44:59 -0800

On 2/8/2024 11:05 PM, Eli Zaretskii wrote:
> LGTM, thanks.  Yes, index entries should always be before the
> corresponding @item's.

Thanks, good to know for sure. Merged to master as de5acc3b0d8, so 
closing this now. I'll keep looking for more places to add indexing to 
the manual as I go through it.

Previous Next

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