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

[Eli Zaretskii]

> Date: Sat, 17 May 2014 09:03:06 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> Cc: 17511@debbugs.gnu.org
> 
> > > (I don't think there should be a blank line after the first line,
> > > but maybe that is just a mail artifact.)
> > 
> > It's not; it's a standard formatting of a doc string, AFAIK.
> 
> I don't think so.  Perhaps I've been operating under a misconception
> all these years.  For Lisp code I've seen such a blank line only
> occasionally (rarely), and nearly always in 3rd-party code and typically
> from newbies.

OK, I removed the empty line.

> > > > > 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.
> > 
> > The doc string now speaks about that as well.  What's not clear about
> > that?  A newline is just a character, and as such can be invisible.
> 
> I told you it was not clear to me, as one reader.  Previously, the doc
> string spoke only of invisible lines, and the manual spoke only of
> invisible newlines.  The doc string now mentions invisible newline
> chars too - good.  Does the manual mention invisible lines of text?

I see no reason to mention invisible lines, because that might be
confusing: what matters are not the lines, but the newlines.
Therefore, the doc string now only talks about newlines, and the
manual now says:

    Ordinarily, functions that operate on text or move point do not care
  whether the text is invisible, they process invisible characters and
  visible characters alike.  The user-level line motion commands,
  such as @code{next-line}, @code{previous-line}, ignore invisible
  newlines if @code{line-move-ignore-invisible} is non-@code{nil} (the
  default), i.e., behave like these invisible newlines didn't exist in
  the buffer, but only because they are explicitly programmed to do so.

> > > 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.
> > 
> > It's a separate paragraph already, and I removed the leading
> > "However", which might hint on some too tight relation.
> 
> I'm sure it's better.  If you find it clear enough in this respect now,
> that's good enough for me.

Feel free to file another bug report if you find the new text in the
manual still confusing about the relation between
line-move-ignore-invisible and point adjustments.