bug#17511: 24.4.50; `line-move-ignore-invisible': doc and purpose not clear

[Eli Zaretskii]

> Date: Fri, 16 May 2014 13:52:58 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> 1. The doc string says only that `next-line' and `previous-line' ignore
> invisible lines.  What does it mean for these commands to "ignore
> invisible lines" - what does "ignore" mean here?  What's the
> user-visible BEHAVIOR difference between a nil and a non-nil value?
> Why/when might a user change the value to nil?

I changed the doc string to this:

  "Non-nil means commands that move by lines ignore invisible newlines.

When this option is non-nil, \\[next-line], \\[previous-line], 
\\[move-end-of-line], and \\[move-beginning-of-line] behave
as if newlines that are invisible didn't exist, and count
only visible newlines.  Thus, moving across across 2 newlines
one of which is invisible will be counted as a one-line move.
Also, a non-nil value causes invisible text to be ignored when
counting columns for the purposes of keeping point in the same
column by \\[next-line] and \\[previous-line].

Outline mode sets this."

I hope this answers all of your questions in #1.

> 2. The doc string speaks of invisible lines.  But (elisp) `Invisible
> Text' speaks of "invisible newlines" (not lines), which is presumably
> something different (newline chars vs lines of any chars except newline,
> possibly including the separating newlines).  Are both true?  Which?

I think the doc string now clarifies this as well.

> 3 The manual speaks of "the user-level line motion commands", not just
> `next-line' and `previous-line'.  Is there a difference?  What other
> commands are involved here, besides those two?

Again, I believe the doc string now clarifies that.

> 4. This Elisp manual node is not very clear in general.  Again, what
> does it mean for these line commands to ignore invisible newlines?  Or,
> for that matter, for them to "not care whether the text is invisible"?
> What user-visible BEHAVIOR difference is there?

I clarified in that paragraph that "ignoring" invisible text means
behaving as if it didn't exist in the buffer.  This implies that an
invisible newline does not count as a newline, so when invisible text
is ignored, such a line is considered to be part of the next line.
IOW, commands that count lines will not count a line whose newline is
invisible, when this option is non-nil, so, e.g., "C-u 10 C-n" will
not decrement its counter when it moves across an invisible newline.

> 5. After saying that we provide option `line-move-ignore-invisible'
> specifically to let you prevent line motion commands from ignoring
> invisible newlines (whatever that might mean!), this node says that if
> ANY command ends with point in a certain position relative to invisible
> text, then the cursor is automatically moved past that stretch of
> invisible text (one direction or the other).  How is this related to the
> previous text about line motion commands and
> `line-move-ignore-invisible'?

It isn't related to line-move-ignore-invisible.  It is related to the
broader issue described by that node, which is invisible text in
general.

> If a user ends up understanding something coherent and useful from this
> text, s?he is lucky indeed.

Unhelpful comment, I wish you'd stop making them.