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: RE: doc string of insert-default-directory is unclear Date: Sat, 9 Feb 2008 07:59:15 -0800 Message-ID: <001301c86b34$b882f240$a350908d@us.oracle.com> References: <001301c86604$8c9e5c30$2c49908d@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1202572849 31461 80.91.229.12 (9 Feb 2008 16:00:49 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Sat, 9 Feb 2008 16:00:49 +0000 (UTC) Cc: bug-gnu-emacs@gnu.org To: "'Eli Zaretskii'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 09 17:01:12 2008 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1JNs8c-0006LP-PF for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Feb 2008 17:01:11 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JNs89-0005ys-Sx for geb-bug-gnu-emacs@m.gmane.org; Sat, 09 Feb 2008 11:00:41 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1JNs85-0005vn-K5 for bug-gnu-emacs@gnu.org; Sat, 09 Feb 2008 11:00:37 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1JNs84-0005tf-Po for bug-gnu-emacs@gnu.org; Sat, 09 Feb 2008 11:00:37 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1JNs84-0005tV-KU for bug-gnu-emacs@gnu.org; Sat, 09 Feb 2008 11:00:36 -0500 Original-Received: from agminet01.oracle.com ([141.146.126.228]) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1JNs80-0006q0-RJ; Sat, 09 Feb 2008 11:00:33 -0500 Original-Received: from agmgw2.us.oracle.com (agmgw2.us.oracle.com [152.68.180.213]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id m19G0STa026891; Sat, 9 Feb 2008 10:00:29 -0600 Original-Received: from acsmt351.oracle.com (acsmt351.oracle.com [141.146.40.151]) by agmgw2.us.oracle.com (Switch-3.2.0/Switch-3.2.0) with ESMTP id m19G0Su7003577; Sat, 9 Feb 2008 09:00:28 -0700 Original-Received: from inet-141-146-46-1.oracle.com by acsmt350.oracle.com with ESMTP id 3567839131202572735; Sat, 09 Feb 2008 07:58:55 -0800 Original-Received: from dradamslap1 (/141.144.80.163) by bhmail.oracle.com (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 09 Feb 2008 07:58:54 -0800 X-Mailer: Microsoft Office Outlook 11 In-reply-to: Thread-Index: AchrJCmK+B2M1WzBR0me46w6iDLxXgADQnWg X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3198 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:17515 Archived-At: > > In previous releases, the doc string said only what its first line > > says. The rest was presumably added in Emacs 22 to clarify > > the meaning and use. > > Not just clarify, to document its different semantics. That semantic difference is not clear to me from the new doc string you propose. Sorry. Could you point out the difference? > > Please consider rephrasing the entire doc string. A good starting > > point could be to explain the significance of the initial contents > > being non-empty. > > I took a shot at this. Thanks. > The new doc string is this: > > *Non-nil means when reading a filename start with default > dir in minibuffer. > > When the initial minibuffer contents show a name of a > file or a directory, typing RETURN without editing the > initial contents is equivalent to typing > the default file name. > > If this variable is non-nil, the minibuffer contents are always > initially non-empty, and typing RETURN without editing > will fetch the default name, if one is provided. Note however > that this default name is not necessarily the same as initial > contents inserted in the minibuffer, > if the initial contents is just the default directory. > > If this variable is nil, the minibuffer often starts out > empty. In that case you may have to explicitly fetch the next > history element to request the default name; typing RETURN > without editing will leave the minibuffer empty. > > For some commands, exiting with an empty minibuffer has a > special meaning, such as making the current buffer visit no > file in the case of `set-visited-file-name'. Here's some additional feedback. If it makes sense to you, fine; if not, ignore. The variable controls the behavior of one or more functions, but it is not clear which. It's not necessarily the case that every time a file name is read in Emacs the behavior is controlled by this variable. And even if that is true of vanilla Emacs, it might not be true in general. Isn't this only about `read-file-name'? If so, then it should say "when a file name is read with `read-file-name'". If it is mainly about `read-file-name' but there are some other cases, it still might be better to mention "when read by functions such as `read-file-name'." Some of the statements are too general: "If this variable is non-nil, the minibuffer contents are always initially non-empty". That's certainly not true of the minibuffer in general (e.g. `M-x'). This would be cleared up by saying that we are talking only of the context of `read-file-name' (or whatever). Readers can be confused by the concept of "default file name", which can depend on the particular command. I think that should be clarified. And references to the default directory should refer to `default-directory', so users can look up what that means. More generally, for information about different behaviors and special cases, the doc string should refer to the functions and variables whose doc strings explain those cases in context. "Typing RETURN without editing will leave the minibuffer empty." No, it will exit the minibuffer, returning the empty string. RETURN doesn't empty the minibuffer or just leave it empty (no-op). I hate to say it, but I think that, in general, the added text just adds confusion. So far, I think it is clearest to say simply that non-nil means that `default-directory' is inserted initially in the minibuffer when a name is read by `read-file-name'. It is the doc of `read-file-name' etc. that should explain what happens if you empty the minibuffer or if you hit RETURN without typing anything. What is the problem that adding this text is intended to solve? If you tell me what the problem we are solving is, perhaps I can help some more with the wording.