Re: Provide org-insert-subitem

[Adam Porter]

Bastien <address@hidden> writes:

> First of all, don't be afraid, I don't have a grand plan for "cleaning
> up" things.

Don't worry, I trust you.  :)  Org wouldn't be what it is today without
your work, and I'm grateful for how much time you've been putting into
improving Org lately.

>> I'm not sure what you mean about functions mentioned as usable by the
>> user.  org-insert-subheading is an interactive command, so it's
>> explicitly usable by the user.
>
> Yes, org-insert-subheading is interactive and usable and in Org's core
> but how can a user *discover* this command?
>
> There is no keybinding for it and no mention in the manual.  Even as a
> function, it is not even used in Org codebase.
>
> The ways I can see for a user to discover this command is by trying to
> complete M-x org-insert TAB or by reading Org's code (or other code in
> the wild using it.)

I guess what happened here is that I found that command years ago,
probably from either reading someone else's config online or, as you
say, using completion (I discover so many things using Helm
completion--I'm constantly using "C-h f org-" when working on
Org-related code).  Then I bound it to S-RET in my config, and I've been
using it ever since.  To me it feels like just as much a part of Org as
any other Org command.

> So to me it's a "utility" command: something that Org does not depend
> on, something that provides a useful feature, but not useful enough to
> have a keybinding in Org's core or to be used as a function in Org's
> core.

What if we document it in the manual?  For example, in section 2.5,
"Structure editing", we have:

    `M-<RET>'     (`org-insert-heading')
         Insert a new heading/item with the same level as the one at point.

    `C-<RET>'     (`org-insert-heading-respect-content')
         Insert a new heading at the end of the current subtree.  

    `M-S-<RET>'     (`org-insert-todo-heading')
         Insert new TODO entry with same level as current heading.  See
         also the variable `org-treat-insert-todo-heading-as-state-change'.  

    `C-S-<RET>'     (`org-insert-todo-heading-respect-content')
         Insert new TODO entry with same level as current heading.  Like
         `C-<RET>', the new headline will be inserted after the current
         subtree.  

What if we add:

    `S-<RET>'     (`org-insert-subheading')
         Insert a new subheading and demote it.
         Works for outline headings and for plain lists alike.

Note that I also propose binding it to S-<RET>.  It seems that, by
default, that key is currently bound in Org buffers to
org-table-copy-down:

    Copy the value of the current field one row below.

That's surely a useful function, but I feel like it probably isn't
widely used enough to deserve to be bound to S-<RET> in all contexts.
Of course, frequent users of this command, feel free to correct me, lest
I be a hypocrite.  ;)

If that seems agreeable, then I'd also propose renaming the command
(preserving its old name in an alias, of course) to something which
would not imply that it only works in outlines, perhaps
org-insert-subitem or org-insert-demoted.

In the longer term , perhaps we could make a new, contextual command
that would call one command in tables and another command in non-table
contexts.  If there were a clever way we could make similar, roughly
corresponding actions in both tables and tree structures use the same
bindings contextually, that might be useful.  I think it would be
reasonable, because if point is in a table, the user probably won't want
to insert a new outline heading in the middle of it.

What do you think?  Thanks.