org.el (org-insert-heading): Be more consistent in respecting content

* org.el (org-insert-heading): With one universal prefix
argument or `org-insert-heading-respect-content' set to `t',
always respect the content, i.e. don't insert a list item and
don't convert normal lines into headings.  Update docstring.
(org-insert-heading-respect-content): Remove unused arg.
(org-insert-todo-heading-respect-content): Don't use
`org-insert-todo-heading-respect-content', use the second
argument of `org-insert-todo-heading' instead.

* org-mobile.el (org-mobile-edit): Use only one arg.

Thanks to Bernt Hansen for reporting this.

2 files changed, 16 insertions, 20 deletions

diff --git a/lisp/org-mobile.el b/lisp/org-mobile.el
index f59d1c4..41a9958 100644
--- a/lisp/org-mobile.el
+++ b/lisp/org-mobile.el
@@ -1074,7 +1074,7 @@ be returned that indicates what went wrong."
 	    ;; which prevents correct insertion when point is invisible
 	    (org-show-subtree)
 	    (end-of-line 1)
-	    (org-insert-heading-respect-content '(16) t)
+	    (org-insert-heading-respect-content t)
 	    (org-demote))
 	(beginning-of-line)
 	(insert "* "))
diff --git a/lisp/org.el b/lisp/org.el
index 14a35c0..1318ce1 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7557,23 +7557,22 @@ When NEXT is non-nil, check the next line instead."
 	   (looking-at "[ \t]*$")))))
 
 (defun org-insert-heading (&optional arg invisible-ok)
-  "Insert a new heading or item with same depth at point.
+  "Insert a new heading or an item with the same depth at point.
 
 If point is at the beginning of a heading or a list item, insert
-a heading or a list item before it.
-
-If point is at the beginning of a normal line, turn this line
-into a heading.
+a new heading or a new item above the current one.  If point is
+at the beginning of a normal line, turn the line into a heading.
 
 If point is in the middle of a headline or a list item, split the
 headline or the item and create a new headline/item with the text
 in the current line after point \(see `org-M-RET-may-split-line'
 on how to modify this behavior).
 
-With one universal prefix argument: If point is within a list,
-insert a heading instead of a list item.  Otherwise, set the
-value of `org-insert-heading-respect-content' to t for the
-duration of the command.
+With one universal prefirx argument, set the user option
+`org-insert-heading-respect-content' to t for the duration of
+the command.  This modifies the behavior described above in this
+ways: on list items and at the beginning of normal lines, force
+the insertion of a heading after the current subtree.
 
 With two universal prefix arguments, insert the heading at the
 end of the grandparent subtree.  For example, if point is within
@@ -7601,7 +7600,7 @@ command."
 	       (or arg (not itemp))))
       ;; At beginning of buffer or so high up that only a heading
       ;; makes sense.
-      (cond ((bolp) (insert "* "))
+      (cond ((and (bolp) (not respect-content)) (insert "* "))
 	    ((not respect-content)
 	     (unless may-split (end-of-line))
 	     (insert "\n* "))
@@ -7671,8 +7670,7 @@ command."
 
 	  ;; If we insert after content, move there and clean up whitespace
 	  (when (and respect-content
-		     (not (org-looking-at-p org-outline-regexp-bol))
-		     (not (bolp)))
+		     (not (org-looking-at-p org-outline-regexp-bol)))
 	    (if (not (org-before-first-heading-p))
 		(org-end-of-subtree nil t)
 	      (re-search-forward org-outline-regexp-bol)
@@ -7807,17 +7805,15 @@ This is a list with the following elements:
   (org-move-subtree-down)
   (end-of-line 1))
 
-(defun org-insert-heading-respect-content (&optional arg invisible-ok)
+(defun org-insert-heading-respect-content (&optional invisible-ok)
   "Insert heading with `org-insert-heading-respect-content' set to t."
-  (interactive "P")
-  (let ((org-insert-heading-respect-content t))
-    (org-insert-heading '(4) invisible-ok)))
+  (interactive)
+  (org-insert-heading '(4) invisible-ok))
 
 (defun org-insert-todo-heading-respect-content (&optional force-state)
   "Insert TODO heading with `org-insert-heading-respect-content' set to t."
-  (interactive "P")
-  (let ((org-insert-heading-respect-content t))
-    (org-insert-todo-heading force-state '(4))))
+  (interactive)
+  (org-insert-todo-heading force-state '(4)))
 
 (defun org-insert-todo-heading (arg &optional force-heading)
   "Insert a new heading with the same level and TODO state as current heading.