From mboxrd@z Thu Jan  1 00:00:00 1970
From: Bastien <bzg@gnu.org>
Subject: Re: Provide org-insert-subitem
Date: Thu, 13 Feb 2020 09:04:25 +0100
Message-ID: <87mu9m7w1i.fsf@bzg.fr>
References: <CA+Yh0SSLW=aWbRyXjB-Q=m+tq+2pd_TM=bu0hpC0DuwLoT9FgA@mail.gmail.com>
 <87tv49bf9e.fsf@gnu.org> <87v9oo28cd.fsf@alphapapa.net>
 <87h7zwnr26.fsf@gnu.org> <87sgjflclf.fsf@alphapapa.net>
Mime-Version: 1.0
Content-Type: text/plain
Return-path: <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane-mx.org@gnu.org>
Received: from eggs.gnu.org ([2001:470:142:3::10]:60090)
 by lists.gnu.org with esmtp (Exim 4.90_1)
 (envelope-from <bzg@gnu.org>) id 1j29U5-00077r-CA
 for emacs-orgmode@gnu.org; Thu, 13 Feb 2020 03:04:30 -0500
List-Id: "General discussions about Org-mode." <emacs-orgmode.gnu.org>
List-Unsubscribe: <https://lists.gnu.org/mailman/options/emacs-orgmode>,
 <mailto:emacs-orgmode-request@gnu.org?subject=unsubscribe>
List-Archive: <https://lists.gnu.org/archive/html/emacs-orgmode>
List-Post: <mailto:emacs-orgmode@gnu.org>
List-Help: <mailto:emacs-orgmode-request@gnu.org?subject=help>
List-Subscribe: <https://lists.gnu.org/mailman/listinfo/emacs-orgmode>,
 <mailto:emacs-orgmode-request@gnu.org?subject=subscribe>
Errors-To: emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane-mx.org@gnu.org
Sender: "Emacs-orgmode"
 <emacs-orgmode-bounces+geo-emacs-orgmode=m.gmane-mx.org@gnu.org>
To: Adam Porter <adam@alphapapa.net>
Cc: emacs-orgmode@gnu.org

Hi Adam,

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

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

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.

> And it's in org.el, so it's in Org's
> "core", right?  I guess we're thinking in different terms.

Well, my thinking is not about core vs not-core, it is more on how to
advertize such commands and functions.  I would recommand putting them
in org-utils.el but I'm not sure.  And yes, I'm not entirely convinced
such a library, if it existed, should live in Org's core :)

Best,

-- 
 Bastien