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

[Drew Adams <drew.adams@oracle.com>]

Thanks for improving this.

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

Very good; thanks.  (I don't think there should be a blank line after the
first line, but maybe that is just a mail artifact.)

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

Yes, thanks.  But the manual speaks only of invisible newlines, and to
me this part is not clear.  And whenever we speak of newlines (especially
where we are also talking about doing something wrt lines in general),
we should say "newline characters" or "newline chars".  A "newline" as
such doesn't really exist in our vocabulary (or at least it shouldn't),
and some people might read it as meaning a "new line".

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

OK.

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

Very good (modulo newline -> newline char).

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

Yes, I sensed that.  I found (find) the juxtaposition confusing.
Maybe separate the two discussions better, and perhaps give an example
of interaction (or lack thereof) between the two.