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

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

> > Thanks for improving this.
> 
> Can this bug be closed, then?

It's up to you.  I have some comments below, but you are of course
free to ignore them or disagree with them.

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

Take a look at the Emacs Lisp sources.  You will see such a blank line
only rarely.

Look at simple.el, for example. There are only a few doc strings that
have such a blank line.  I count only these 17 out of the *hundreds*
of doc strings in simple.el:

`next-error-buffer-p', `next-error-find-buffer', `next-error',
`previous-error', `shell-command-history', `async-shell-command',
`process-file-side-effects', `start-file-process', `mark',
`region-active-p', `shift-select-mode', `default-line-height',
`window-screen-lines', `set-variable-value-history',
`create-indirect-buffer', `normal-erase-is-backspace',
`define-alternatives'.

I thought that not adding a blank line after the first line was a
doc-string convention/guideline/standard (the opposite of what you
say), in addition to reflecting the overwhelming practice.

But I do not see it mentioned at (elisp) `Documentation Tips', so
I guess I was wrong about that (as are you?).  (I do see mention
of the first paragraph being used for disabled command help, but
is not so important here.)

So take my input on this as just one opinion.  I don't see that
adding a blank line after the first helps users - in *Help* output,
for example.  But clearly it is not proscribed, and there is not
even a published guideline against it.

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

If the fact that I found this confusing helps you improve it, fine.
If not, fine.

> > 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".
> 
> I'd never suspect this could be a source of confusion in Emacs.  The
> Glossary says:
> 
>   Newline
>        Control-J characters in the buffer terminate lines of text and are
>        therefore also called newlines.

OK.  I disagree that that is the right approach, but it is the approach
taken, so fine.  If it were I, I would always say "newline char", to be
clear.

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