bug#26272: default-directory: Remark that it must be a directory name

[Tino Calancha <tino.calancha@gmail.com>]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Tino Calancha <tino.calancha@gmail.com>
>> Date: Mon, 27 Mar 2017 19:13:05 +0900
>> 
>> 
>> The docstring of `file-name-as-directory' suggests that is
>> important that `default-directory' be a directory name, i.e.,
>> for instance in GNU/Linux ends with '/'.  The docstring of
>> `default-directory' doesn't mention it.
>
> Didn't we discuss that at some point in the past?
I don't remember it.  Maybe with another person.

>>    DEFVAR_PER_BUFFER ("default-directory", &BVAR (current_buffer, directory),
>>  		     Qstringp,
>>  		     doc: /* Name of default directory of current buffer.
>> -To interactively change the default directory, use command `cd'.  */);
>> +It must be a directory name, as the output of `file-name-as-directory'.
>> +To interactively change the default directory, use command `cd'.
>> +In a Elisp program is better to do
>> +(setq default-directory (file-name-as-directory DIR)) */);
>
> A word of advice for the future: it is usually best to start from
> informal text that describes well what you mean in your own words, and
> then "formalize" it as needed, taking care not to lose key words and
> concepts.
Thanks for the advice.  It's a useful one.
>If you compare your informal description above with the
> patched doc string, I think you will agree with me that the former
> says what you mean in a much more clear and concise way.
I agree.
> Here's my suggestion:
>
>   It should be a directory name (as opposed to a directory file-name).
>   On GNU and Unix systems, directory names and in a slash `/'.
>
> This basically says what your original description said, which is spot
> on.
Much clear.  Updated the patch with yout suggestion.
I have changed
'and in a slash' with 'end in a slash'.

--8<-----------------------------cut here---------------start------------->8---
From e63611ca54a59d8cff18de5ad1413f9678f3a51c Mon Sep 17 00:00:00 2001
From: Tino Calancha <tino.calancha@gmail.com>
Date: Tue, 28 Mar 2017 00:07:35 +0900
Subject: [PATCH] default-directory: Remark that it must be a directory name

* src/buffer.c (default-directory): Update docstring (Bug#26272).
---
 src/buffer.c | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/buffer.c b/src/buffer.c
index c1c53dd220..8ef27dee0f 100644
--- a/src/buffer.c
+++ b/src/buffer.c
@@ -5754,7 +5754,9 @@ visual lines rather than logical lines.  See the documentation of
   DEFVAR_PER_BUFFER ("default-directory", &BVAR (current_buffer, directory),
 		     Qstringp,
 		     doc: /* Name of default directory of current buffer.
-To interactively change the default directory, use command `cd'.  */);
+It should be a directory name (as opposed to a directory file-name).
+On GNU and Unix systems, directory names end in a slash `/'.
+To interactively change the default directory, use command `cd'. */);
 
   DEFVAR_PER_BUFFER ("auto-fill-function", &BVAR (current_buffer, auto_fill_function),
 		     Qnil,
-- 
2.11.0

--8<-----------------------------cut here---------------end--------------->8---
In GNU Emacs 25.2.5 (x86_64-pc-linux-gnu, GTK+ Version 3.22.9)
 of 2017-03-27
Repository revision: fb18bff91f01a3051253319e766ca276e5b756bd