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

[Stefan Kangas]

Jim Porter <jporterbugs@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.