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

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

[Alex Branham]

The docstring of indent-relative says:

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.

Yet in a buffer like this:

foo

with point at the beginning of line, C-u M-x indent-relative results in:

        test

I'm happy to submit a patch fixing this, but should it update the
documentation to match what happens or should it update the code to
match the documentation?

Thanks,
Alex

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

[Eli Zaretskii]

> From: Alex Branham <alex.branham@gmail.com>
> Date: Thu, 14 Mar 2019 10:35:13 -0500
> 
> 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.
> 
> Yet in a buffer like this:
> 
> foo
> 
> with point at the beginning of line, C-u M-x indent-relative results in:
> 
>         test
> 
> I'm happy to submit a patch fixing this, but should it update the
> documentation to match what happens or should it update the code to
> match the documentation?

I think this is a documentation bug, as it doesn't describe the
special case of "no previous nonblank line".

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

[Alex Branham]

[-- Attachment #1: Type: text/plain, Size: 2300 bytes --]


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.

Thanks,
Alex

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
  'indent-relative' is used.

Bug#34858
---
 doc/lispref/text.texi | 4 ++--
 lisp/indent.el        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

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.
 
 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'.
 
 See also `indent-relative-first-indent-point'."
   (interactive "P")
-- 
2.19.2


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Update-documentation-for-indent-relative-functions.patch --]
[-- Type: text/x-patch, Size: 1969 bytes --]

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
  'indent-relative' is used.

Bug#34858
---
 doc/lispref/text.texi | 4 ++--
 lisp/indent.el        | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

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.
 
 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'.
 
 See also `indent-relative-first-indent-point'."
   (interactive "P")
-- 
2.19.2

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

[Alex]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Alex Branham <alex.branham@gmail.com>
>> Date: Thu, 14 Mar 2019 10:35:13 -0500
>> 
>> 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.
>> 
>> Yet in a buffer like this:
>> 
>> foo
>> 
>> with point at the beginning of line, C-u M-x indent-relative results in:
>> 
>>         test
>> 
>> I'm happy to submit a patch fixing this, but should it update the
>> documentation to match what happens or should it update the code to
>> match the documentation?
>
> I think this is a documentation bug, as it doesn't describe the
> special case of "no previous nonblank line".

I believe that the case of "no previous nonblank line" could be
considered as there being a single indent point at column 0, so if
FIRST-ONLY is non-nil, then `tab-to-tab-stop' shouldn't be called. How
about the following patch instead?

diff --git a/lisp/indent.el b/lisp/indent.el
index 34757a43d7..4ee4617de9 100644
--- a/lisp/indent.el
+++ b/lisp/indent.el
@@ -597,7 +597,7 @@ indent-relative
 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
+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.
 
@@ -627,7 +627,7 @@ indent-relative
              (if (> opoint (point))
                  (goto-char opoint))
              (move-marker opoint nil)))
-          (unindented-ok nil)
+          ((or unindented-ok first-only) nil)
           (t (tab-to-tab-stop)))))
 
 (defcustom tab-stop-list nil

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

[Eli Zaretskii]

> From: Alex <agrambot@gmail.com>
> Cc: Alex Branham <alex.branham@gmail.com>,  34858@debbugs.gnu.org
> Date: Thu, 14 Mar 2019 10:45:32 -0600
> 
> Eli Zaretskii <eliz@gnu.org> writes:
> 
> >> From: Alex Branham <alex.branham@gmail.com>
> >> Date: Thu, 14 Mar 2019 10:35:13 -0500
> >> 
> >> 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.
> >> 
> >> Yet in a buffer like this:
> >> 
> >> foo
> >> 
> >> with point at the beginning of line, C-u M-x indent-relative results in:
> >> 
> >>         test
> >> 
> >> I'm happy to submit a patch fixing this, but should it update the
> >> documentation to match what happens or should it update the code to
> >> match the documentation?
> >
> > I think this is a documentation bug, as it doesn't describe the
> > special case of "no previous nonblank line".
> 
> I believe that the case of "no previous nonblank line" could be
> considered as there being a single indent point at column 0, so if
> FIRST-ONLY is non-nil, then `tab-to-tab-stop' shouldn't be called. How
> about the following patch instead?

I don't understand what you are saying here.  The doc string says "no
indent point _beyond_" the column where point starts, so assuming a
single indent point at column zero doesn't change anything.

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

[Alex]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Alex <agrambot@gmail.com>
>> Cc: Alex Branham <alex.branham@gmail.com>,  34858@debbugs.gnu.org
>> Date: Thu, 14 Mar 2019 10:45:32 -0600
>> >
>> > I think this is a documentation bug, as it doesn't describe the
>> > special case of "no previous nonblank line".
>> 
>> I believe that the case of "no previous nonblank line" could be
>> considered as there being a single indent point at column 0, so if
>> FIRST-ONLY is non-nil, then `tab-to-tab-stop' shouldn't be called. How
>> about the following patch instead?
>
> I don't understand what you are saying here.  The doc string says "no
> indent point _beyond_" the column where point starts, so assuming a
> single indent point at column zero doesn't change anything.

Sorry, I wasn't clear. I meant that the special case here could be
considered (trivially) equivalent to the case where the previous
non-blank line has a single indent point at column zero, and therefore
should be treated equivalently when FIRST-ONLY is non-nil
(`tab-to-tab-stop` should not be called if on or past the first indent
point, i.e., column 0).

The usage of `beyond' does not change the behaviour when the starting
column is on the first indent point, which outside of this special case
is doing nothing. Specifically, the `indent' branch of the cond is
normally executed when FIRST-ONLY is non-nil because `indent' is set
within the `re-search-backward' conditional to be equal to the starting
column; however, in this special case, `re-search-backward' returns nil
and so `indent' remains nil. My patch covers this case by also checking
for FIRST-ONLY in the cond.

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

[Eli Zaretskii]

> From: Alex <agrambot@gmail.com>
> Cc: alex.branham@gmail.com,  34858@debbugs.gnu.org
> Date: Thu, 14 Mar 2019 12:57:08 -0600
> 
> Sorry, I wasn't clear. I meant that the special case here could be
> considered (trivially) equivalent to the case where the previous
> non-blank line has a single indent point at column zero, and therefore
> should be treated equivalently when FIRST-ONLY is non-nil
> (`tab-to-tab-stop` should not be called if on or past the first indent
> point, i.e., column 0).

But then we'd do nothing in that situation.  How does it make sense?

> The usage of `beyond' does not change the behaviour when the starting
> column is on the first indent point, which outside of this special case
> is doing nothing.

When there are previous lines to align with, yes.  But here there's
nothing before, so what is the justification for doing nothing?

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

[Alex]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Alex <agrambot@gmail.com>
>> Cc: alex.branham@gmail.com,  34858@debbugs.gnu.org
>> Date: Thu, 14 Mar 2019 12:57:08 -0600
>> 
>> Sorry, I wasn't clear. I meant that the special case here could be
>> considered (trivially) equivalent to the case where the previous
>> non-blank line has a single indent point at column zero, and therefore
>> should be treated equivalently when FIRST-ONLY is non-nil
>> (`tab-to-tab-stop` should not be called if on or past the first indent
>> point, i.e., column 0).
>
> But then we'd do nothing in that situation.  How does it make sense?
>
>> The usage of `beyond' does not change the behaviour when the starting
>> column is on the first indent point, which outside of this special case
>> is doing nothing.
>
> When there are previous lines to align with, yes.  But here there's
> nothing before, so what is the justification for doing nothing?

I don't see the justification for calling `tab-to-tab-stop' since that
behaviour would be surprising given that `tab-to-tab-stop' is otherwise
called only if FIRST-ONLY is nil. I view FIRST-ONLY as meaning "this
procedure will not indent past the first indent point"; in the case of
no such point, I believe that doing nothing is the more reasonable
action. Also,` indent-relative-first-indent-point' expects this
behaviour.

If one wants `indent-relative' to call `tab-to-tab-stop' in the case of
no previous non-blank line, then one could call it without the
FIRST-ONLY/prefix argument.

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

[Eli Zaretskii]

> From: Alex <agrambot@gmail.com>
> Cc: alex.branham@gmail.com,  34858@debbugs.gnu.org
> Date: Thu, 14 Mar 2019 15:27:54 -0600
> 
> >> The usage of `beyond' does not change the behaviour when the starting
> >> column is on the first indent point, which outside of this special case
> >> is doing nothing.
> >
> > When there are previous lines to align with, yes.  But here there's
> > nothing before, so what is the justification for doing nothing?
> 
> I don't see the justification for calling `tab-to-tab-stop' since that
> behaviour would be surprising given that `tab-to-tab-stop' is otherwise
> called only if FIRST-ONLY is nil. I view FIRST-ONLY as meaning "this
> procedure will not indent past the first indent point"; in the case of
> no such point, I believe that doing nothing is the more reasonable
> action. Also,` indent-relative-first-indent-point' expects this
> behaviour.
> 
> If one wants `indent-relative' to call `tab-to-tab-stop' in the case of
> no previous non-blank line, then one could call it without the
> FIRST-ONLY/prefix argument.

I guess we will have to disagree, then.

Alex, feel free to start a discussion on emacs-devel regarding what to
do in this special case, it seems like there's a certain controversy.

Thanks.

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

[Filipp Gunbin]

Alex, a minor comment:

On 14/03/2019 11:17 -0500, Alex Branham wrote:

> 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'.
                                          ^
                                 and UNINDENTED-OK is nil
                                 
Filipp

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

[Alex Branham]

On Wed 20 Mar 2019 at 15:23, Filipp Gunbin <fgunbin@fastmail.fm> wrote:

> Alex, a minor comment:
>
>> -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'.
>                                           ^
>                                  and UNINDENTED-OK is nil

Thanks. I'll include that and push this patch later this week, unless I
hear back otherwise.

Alex

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

[Eli Zaretskii]

> From: Alex Branham <alex.branham@gmail.com>
> Cc: Eli Zaretskii <eliz@gnu.org>, 34858@debbugs.gnu.org
> Date: Mon, 25 Mar 2019 18:06:37 -0500
> 
> Thanks. I'll include that and push this patch later this week, unless I
> hear back otherwise.

I asked to raise the issue about which we disagreed on emacs-devel, to
see what others think.  I don't think I saw any such discussion, did I
miss it?

Thanks.

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

[Alex Branham]

On Tue 26 Mar 2019 at 10:39, Eli Zaretskii <eliz@gnu.org> wrote:

>> Thanks. I'll include that and push this patch later this week, unless I
>> hear back otherwise.
>
> I asked to raise the issue about which we disagreed on emacs-devel, to
> see what others think.  I don't think I saw any such discussion, did I
> miss it?

Confusingly, it wasn't me you disagreed with, that was a different Alex :-) 
I didn't see it either, FWIW.

Either way that gets decided, I think this is OK to push in the meantime
to emacs-26 since the behavior there will be unchanged, right? The
changed behavior would only be 27-forward.

Alex

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

[Eli Zaretskii]

> From: Alex Branham <alex.branham@gmail.com>
> Cc: fgunbin@fastmail.fm, 34858@debbugs.gnu.org
> Date: Tue, 26 Mar 2019 10:42:04 -0500
> 
> Either way that gets decided, I think this is OK to push in the meantime
> to emacs-26 since the behavior there will be unchanged, right? The
> changed behavior would only be 27-forward.

Please don't push anything to emacs-26 yet, until we either release
Emacs 26.2 or decide we need another RC.

Thanks.

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

[Basil L. Contovounesios]

[-- Attachment #1: Type: text/plain, Size: 440 bytes --]

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:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Avoid-using-obsolete-indent-relative-maybe.patch --]
[-- Type: text/x-diff, Size: 3441 bytes --]

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


[-- Attachment #3: Type: text/plain, Size: 2510 bytes --]


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

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

[Eli Zaretskii]

> From: "Basil L. Contovounesios" <contovob@tcd.ie>
> Cc: Eli Zaretskii <eliz@gnu.org>,  34858@debbugs.gnu.org
> Date: Tue, 02 Apr 2019 01:11:57 +0100
> 
> > 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:

Fine with me, thanks.

> 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?

Yes.  Please note that the emacs-26 branch is currently frozen, as we
will probably release Emacs 26.2 soon.

> > -@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?

I actually don't understand why this sentence should be there at all.
IMO, it isn't useful to say that the return value is undefined, better
not to say anything (which has the same meaning, but avoids the
possible interpretation that other doc strings, which don't say that,
imply otherwise).

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

Adding that was the main purpose of the changeset, as at least one
person wasn't sure your interpretation is so clearly implied.

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

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: "Basil L. Contovounesios" <contovob@tcd.ie>
>> Cc: Eli Zaretskii <eliz@gnu.org>,  34858@debbugs.gnu.org
>> Date: Tue, 02 Apr 2019 01:11:57 +0100
>> 
>> > 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:
>
> Fine with me, thanks.
>
>> 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?
>
> Yes.

Thanks, pushed to master.  Alex, can you also please push your docfixes
for the Elisp manual?

> Please note that the emacs-26 branch is currently frozen, as we will
> probably release Emacs 26.2 soon.

Right, that's what I was alluding to when I said "as needed/applicable".

>> > -@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?
>
> I actually don't understand why this sentence should be there at all.
> IMO, it isn't useful to say that the return value is undefined, better
> not to say anything (which has the same meaning, but avoids the
> possible interpretation that other doc strings, which don't say that,
> imply otherwise).

Seconded.

>> > --- 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". ;)
>
> Adding that was the main purpose of the changeset, as at least one
> person wasn't sure your interpretation is so clearly implied.

Right.

Thanks,

-- 
Basil

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

[Alex Branham]

On Wed 03 Apr 2019 at 12:12, Basil L. Contovounesios <contovob@tcd.ie> wrote:

>>> Can they be pushed to master, and only backported to emacs-26 as
>>> needed/applicable?
>>
>> Yes.
>
> Thanks, pushed to master.  Alex, can you also please push your docfixes
> for the Elisp manual?

Thanks! I pushed the docfix as as 10cd65878c741d2a22a1f2c36c54fcad4e516f72, 
to appear in Emacs 27.1. I'm closing this bug report.

Sorry for the delay,
Alex