From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#17511: 24.4.50; `line-move-ignore-invisible': doc and purpose not clear Date: Sat, 17 May 2014 09:03:06 -0700 (PDT) Message-ID: <547b37b1-f55b-45e9-8c89-eb9388580d36@default> References: <<8c772b14-20d1-4e3a-9936-f81936c3d31b@default>> <<83a9age9dl.fsf@gnu.org>> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1400342681 24597 80.91.229.3 (17 May 2014 16:04:41 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 17 May 2014 16:04:41 +0000 (UTC) Cc: 17511@debbugs.gnu.org To: Eli Zaretskii , Drew Adams Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat May 17 18:04:33 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Wlh64-0003Af-87 for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 May 2014 18:04:28 +0200 Original-Received: from localhost ([::1]:40709 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wlh63-0003TC-3F for geb-bug-gnu-emacs@m.gmane.org; Sat, 17 May 2014 12:04:27 -0400 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:35955) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wlh5r-0003SE-Jn for bug-gnu-emacs@gnu.org; Sat, 17 May 2014 12:04:24 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Wlh5f-0004hm-1n for bug-gnu-emacs@gnu.org; Sat, 17 May 2014 12:04:15 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:52695) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Wlh5e-0004hi-UZ for bug-gnu-emacs@gnu.org; Sat, 17 May 2014 12:04:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1Wlh5e-0004Kw-Ci for bug-gnu-emacs@gnu.org; Sat, 17 May 2014 12:04:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 17 May 2014 16:04:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 17511 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 17511-submit@debbugs.gnu.org id=B17511.140034260116600 (code B ref 17511); Sat, 17 May 2014 16:04:02 +0000 Original-Received: (at 17511) by debbugs.gnu.org; 17 May 2014 16:03:21 +0000 Original-Received: from localhost ([127.0.0.1]:51572 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Wlh4y-0004Jd-Fk for submit@debbugs.gnu.org; Sat, 17 May 2014 12:03:21 -0400 Original-Received: from userp1040.oracle.com ([156.151.31.81]:39367) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1Wlh4v-0004JN-IC for 17511@debbugs.gnu.org; Sat, 17 May 2014 12:03:18 -0400 Original-Received: from acsinet22.oracle.com (acsinet22.oracle.com [141.146.126.238]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s4HG39vo028670 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 17 May 2014 16:03:10 GMT Original-Received: from aserz7021.oracle.com (aserz7021.oracle.com [141.146.126.230]) by acsinet22.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s4HG389e009555 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 17 May 2014 16:03:09 GMT Original-Received: from abhmp0016.oracle.com (abhmp0016.oracle.com [141.146.116.22]) by aserz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s4HG38wA009774; Sat, 17 May 2014 16:03:08 GMT In-Reply-To: <<83a9age9dl.fsf@gnu.org>> X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6691.5000 (x86)] X-Source-IP: acsinet22.oracle.com [141.146.126.238] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:89195 Archived-At: > > Thanks for improving this. >=20 > 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.) >=20 > 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) `Invisibl= e > > > > Text' speaks of "invisible newlines" (not lines), which is presumab= ly > > > > something different (newline chars vs lines of any chars except > > > > newline, possibly including the separating newlines). Are both tru= e? > > > > 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. >=20 > 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". >=20 > I'd never suspect this could be a source of confusion in Emacs. The > Glossary says: >=20 > 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. >=20 > 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.