bug#34858: indent-relative called with prefix calls tab-to-tab-stop

[Basil L. Contovounesios]

Alex Branham <alex.branham@gmail.com> writes:

> On Thu 14 Mar 2019 at 11:00, Eli Zaretskii <eliz@gnu.org> wrote:
>
>> I think this is a documentation bug, as it doesn't describe the
>> special case of "no previous nonblank line".
>
> OK, patch attached. While looking over this I noticed the lisp reference
> manual also needed to be updated a bit so I did that as well.

I think some code needs updating in addition to the Elisp manual:

>From d8c74ae527c52cffcb23d9704a899dd304188276 Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Tue, 2 Apr 2019 00:56:04 +0100
Subject: [PATCH] Avoid using obsolete indent-relative-maybe

* lisp/electric.el (electric-indent-functions-without-reindent):
* lisp/indent.el (indent-according-to-mode): Check for
indent-relative-first-indent-point in addition to its obsolete alias
indent-relative-maybe.
* lisp/obsolete/vi.el (vi-com-map): Use
indent-relative-first-indent-point in place of its obsolete alias
indent-relative-maybe.
---
 lisp/electric.el    |  6 +++---
 lisp/indent.el      | 10 ++++++----
 lisp/obsolete/vi.el |  2 +-
 3 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/lisp/electric.el b/lisp/electric.el
index 657913a396..07da2f1d9e 100644
--- a/lisp/electric.el
+++ b/lisp/electric.el
@@ -223,9 +223,9 @@ electric-indent-inhibit
 
 (defvar electric-indent-functions-without-reindent
   '(indent-relative indent-to-left-margin indent-relative-maybe
-    py-indent-line coffee-indent-line org-indent-line yaml-indent-line
-    haskell-indentation-indent-line haskell-indent-cycle haskell-simple-indent
-    yaml-indent-line)
+    indent-relative-first-indent-point py-indent-line coffee-indent-line
+    org-indent-line yaml-indent-line haskell-indentation-indent-line
+    haskell-indent-cycle haskell-simple-indent yaml-indent-line)
   "List of indent functions that can't reindent.
 If `indent-line-function' is one of those, then `electric-indent-mode' will
 not try to reindent lines.  It is normally better to make the major
diff --git a/lisp/indent.el b/lisp/indent.el
index 34757a43d7..f3d3158faa 100644
--- a/lisp/indent.el
+++ b/lisp/indent.el
@@ -65,15 +65,17 @@ indent-according-to-mode
   "Indent line in proper way for current major mode.
 Normally, this is done by calling the function specified by the
 variable `indent-line-function'.  However, if the value of that
-variable is `indent-relative' or `indent-relative-maybe', handle
-it specially (since those functions are used for tabbing); in
-that case, indent by aligning to the previous non-blank line."
+variable is `indent-relative' or `indent-relative-first-indent-point',
+handle it specially (since those functions are used for tabbing);
+in that case, indent by aligning to the previous non-blank line."
   (interactive)
   (save-restriction
     (widen)
   (syntax-propertize (line-end-position))
   (if (memq indent-line-function
-           '(indent-relative indent-relative-maybe))
+            '(indent-relative
+              indent-relative-maybe
+              indent-relative-first-indent-point))
       ;; These functions are used for tabbing, but can't be used for
       ;; indenting.  Replace with something ad-hoc.
       (let ((column (save-excursion
diff --git a/lisp/obsolete/vi.el b/lisp/obsolete/vi.el
index 7d44f561d4..df5ddfdbcf 100644
--- a/lisp/obsolete/vi.el
+++ b/lisp/obsolete/vi.el
@@ -132,7 +132,7 @@ vi-com-map
   (define-key vi-com-map "\C-e" 'vi-expose-line-below)
   (define-key vi-com-map "\C-f" 'vi-forward-windowful)
   (define-key vi-com-map "\C-g" 'keyboard-quit)
-  (define-key vi-com-map "\C-i" 'indent-relative-maybe) ; TAB
+  (define-key vi-com-map "\C-i" 'indent-relative-first-indent-point) ; TAB
   (define-key vi-com-map "\C-j" 'vi-next-line) ; LFD
   (define-key vi-com-map "\C-k" 'vi-kill-line) ; extension
   (define-key vi-com-map "\C-l" 'recenter)
-- 
2.20.1

I think the changes pertaining to the move from indent-relative-maybe to
indent-relative-first-indent-point should be pushed independently of any
changes to the behaviour of indent-relative at BOB or its documentation.

Can they be pushed to master, and only backported to emacs-26 as
needed/applicable?

> From cefe6581558e45558907996ea39ac44e512f7944 Mon Sep 17 00:00:00 2001
> From: Alex Branham <alex.branham@gmail.com>
> Date: Thu, 14 Mar 2019 11:14:18 -0500
> Subject: [PATCH] Update documentation for indent-relative functions
>
> * lisp/indent.el (indent-relative): Document what happens when there
>   is no previous nonblank line.
> * doc/lispref/text.texi (Relative Indent): Document
>   indent-relative-first-indent-point instead of obsolete
>   indent-relative-maybe. Fix documentation of which argument from
                         ^^^
Missing double space.

> diff --git a/doc/lispref/text.texi b/doc/lispref/text.texi
> index 21c5a73f88..abcea17010 100644
> --- a/doc/lispref/text.texi
> +++ b/doc/lispref/text.texi
> @@ -2571,11 +2571,11 @@ The quick brown fox jum  @point{}ped.
>  @end example
>  @end deffn
>  
> -@deffn Command indent-relative-maybe
> +@deffn Command indent-relative-first-indent-point
>  @comment !!SourceFile indent.el
>  This command indents the current line like the previous nonblank line,
>  by calling @code{indent-relative} with @code{t} as the
> -@var{unindented-ok} argument.  The return value is unpredictable.
> +@var{first-only} argument.  The return value is unpredictable.

Just curious: is there any preference between "unpredictable" and
"undefined" for documenting return values?  If so, why?

>  If the previous nonblank line has no indent points beyond the current
>  column, this command does nothing.
> diff --git a/lisp/indent.el b/lisp/indent.el
> index 34757a43d7..25615f4113 100644
> --- a/lisp/indent.el
> +++ b/lisp/indent.el
> @@ -598,8 +598,8 @@ considered.
>  
>  If the previous nonblank line has no indent points beyond the
>  column point starts at, then `tab-to-tab-stop' is done, if both
> -FIRST-ONLY and UNINDENTED-OK are nil, otherwise nothing is done
> -in this case.
> +FIRST-ONLY and UNINDENTED-OK are nil, otherwise nothing is done.
> +If there isn't a previous nonblank line, call `tab-to-tab-stop'.

I'm not against spelling this final sentence out, but in my reading it's
already covered by the first sentence, as a non-existent line vacuously
"has no indent points beyond the column point starts at". ;)

Thanks,

-- 
Basil