From mboxrd@z Thu Jan 1 00:00:00 1970 From: Adam Porter Subject: Re: Provide org-insert-subitem Date: Thu, 13 Feb 2020 12:45:28 -0600 Message-ID: <87o8u2l41j.fsf@alphapapa.net> References: <87tv49bf9e.fsf@gnu.org> <87v9oo28cd.fsf@alphapapa.net> <87h7zwnr26.fsf@gnu.org> <87sgjflclf.fsf@alphapapa.net> <87mu9m7w1i.fsf@bzg.fr> Mime-Version: 1.0 Content-Type: text/plain Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:37741) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j2JUc-0007DZ-PJ for emacs-orgmode@gnu.org; Thu, 13 Feb 2020 13:45:44 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j2JUX-00056x-7H for emacs-orgmode@gnu.org; Thu, 13 Feb 2020 13:45:39 -0500 Received: from ciao.gmane.io ([159.69.161.202]:33592) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1j2JUX-00053M-0g for emacs-orgmode@gnu.org; Thu, 13 Feb 2020 13:45:37 -0500 Received: from list by ciao.gmane.io with local (Exim 4.92) (envelope-from ) id 1j2JUV-0009OW-2T for emacs-orgmode@gnu.org; Thu, 13 Feb 2020 19:45:35 +0100 List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane-mx.org@gnu.org Sender: "Emacs-orgmode" To: emacs-orgmode@gnu.org Bastien 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-' (`org-insert-heading') Insert a new heading/item with the same level as the one at point. `C-' (`org-insert-heading-respect-content') Insert a new heading at the end of the current subtree. `M-S-' (`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-' (`org-insert-todo-heading-respect-content') Insert new TODO entry with same level as current heading. Like `C-', the new headline will be inserted after the current subtree. What if we add: `S-' (`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-. 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- 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.