emacs-orgmode@gnu.org archives
 help / color / mirror / code / Atom feed
From: Adam Porter <adam@alphapapa.net>
To: emacs-orgmode@gnu.org
Subject: Re: Provide org-insert-subitem
Date: Thu, 13 Feb 2020 12:45:28 -0600	[thread overview]
Message-ID: <87o8u2l41j.fsf@alphapapa.net> (raw)
In-Reply-To: 87mu9m7w1i.fsf@bzg.fr

Bastien <bzg@gnu.org> 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.

  reply	other threads:[~2020-02-13 18:45 UTC|newest]

Thread overview: 18+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2019-09-22  9:04 Provide org-insert-subitem Dmitrii Korobeinikov
2020-02-02  7:49 ` Bastien
2020-02-02 10:11   ` Dmitrii Korobeinikov
2020-02-02 17:43   ` Adam Porter
2020-02-12  8:33     ` Bastien
2020-02-12 21:28       ` Adam Porter
2020-02-13  5:13         ` Corwin Brust
2020-02-13  8:04         ` Bastien
2020-02-13 18:45           ` Adam Porter [this message]
2020-02-14 10:02             ` Bastien
2023-12-08  2:51               ` Adam Porter
2023-12-09 14:09                 ` Ihor Radchenko
2023-12-09 17:53                   ` Bastien Guerry
2023-12-14 15:00                     ` Ihor Radchenko
2023-12-25  9:14                       ` Bastien
2023-12-25  9:40                         ` Ihor Radchenko
2023-12-17  5:59                     ` Adam Porter
2023-12-25  9:21                       ` Bastien

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: https://www.orgmode.org/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87o8u2l41j.fsf@alphapapa.net \
    --to=adam@alphapapa.net \
    --cc=emacs-orgmode@gnu.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).