document cygwin-convert-path-{from,to}-windows?

document cygwin-convert-path-{from,to}-windows?

[Glenn Morris]

If the functions cygwin-convert-path-from-windows and
cygwin-convert-path-to-windows need documenting in the manuals, please
could someone do that? Maybe they don't, given that "Cygwin" essentially
isn't mentioned anywhere in the manuals. On the other hand, if you feel
that is a disservice, now is a chance to rectify it! :)

Re: document cygwin-convert-path-{from,to}-windows?

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Date: Fri, 16 Nov 2012 22:39:58 -0500
> 
> If the functions cygwin-convert-path-from-windows and
> cygwin-convert-path-to-windows need documenting in the manuals, please
> could someone do that? Maybe they don't, given that "Cygwin" essentially
> isn't mentioned anywhere in the manuals. On the other hand, if you feel
> that is a disservice, now is a chance to rectify it! :)

I think they do need to be documented: as time passes, they will be
more and more used in the sources.

I do have a gripe wrt their names: GNU coding standards frown upon
using "path" for anything but PATH-style lists of directories.  But my
comments about that at the time evidently weren't enough to convince
the guilty parties.

Re: document cygwin-convert-path-{from,to}-windows?

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 899 bytes --]

On 11/17/12 12:18 AM, Eli Zaretskii wrote:
>> From: Glenn Morris <rgm@gnu.org>
>> Date: Fri, 16 Nov 2012 22:39:58 -0500
>>
>> If the functions cygwin-convert-path-from-windows and
>> cygwin-convert-path-to-windows need documenting in the manuals, please
>> could someone do that? Maybe they don't, given that "Cygwin" essentially
>> isn't mentioned anywhere in the manuals. On the other hand, if you feel
>> that is a disservice, now is a chance to rectify it! :)
> 
> I think they do need to be documented: as time passes, they will be
> more and more used in the sources.
> 
> I do have a gripe wrt their names: GNU coding standards frown upon
> using "path" for anything but PATH-style lists of directories.  But my
> comments about that at the time evidently weren't enough to convince
> the guilty parties.

It's not too late to change the names. What would you suggest?



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 235 bytes --]

Re: document cygwin-convert-path-{from,to}-windows?

[Eli Zaretskii]

> Date: Sun, 18 Nov 2012 12:35:46 -0800
> From: Daniel Colascione <dancol@dancol.org>
> CC: Glenn Morris <rgm@gnu.org>, emacs-devel@gnu.org
> 
> > I do have a gripe wrt their names: GNU coding standards frown upon
> > using "path" for anything but PATH-style lists of directories.  But my
> > comments about that at the time evidently weren't enough to convince
> > the guilty parties.
> 
> It's not too late to change the names. What would you suggest?

cygwin-convert-filename-to-windows, and similarly for the other one.
IOW, replace "path" with "filename".

TIA.

Re: document cygwin-convert-path-{from,to}-windows?

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 685 bytes --]

On 11/18/12 1:21 PM, Eli Zaretskii wrote:
>> Date: Sun, 18 Nov 2012 12:35:46 -0800
>> From: Daniel Colascione <dancol@dancol.org>
>> CC: Glenn Morris <rgm@gnu.org>, emacs-devel@gnu.org
>>
>>> I do have a gripe wrt their names: GNU coding standards frown upon
>>> using "path" for anything but PATH-style lists of directories.  But my
>>> comments about that at the time evidently weren't enough to convince
>>> the guilty parties.
>>
>> It's not too late to change the names. What would you suggest?
> 
> cygwin-convert-filename-to-windows, and similarly for the other one.
> IOW, replace "path" with "filename".
> 

But the functions convert directory names too.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 235 bytes --]

Re: document cygwin-convert-path-{from,to}-windows?

[Eli Zaretskii]

> Date: Sun, 18 Nov 2012 13:22:30 -0800
> From: Daniel Colascione <dancol@dancol.org>
> CC: rgm@gnu.org, emacs-devel@gnu.org
> 
> > cygwin-convert-filename-to-windows, and similarly for the other one.
> > IOW, replace "path" with "filename".
> > 
> 
> But the functions convert directory names too.

"Filename" doesn't contradict that.  We have, e.g.,
directory-file-name, file-name-as-directory, expand-file-name, etc.

RE: document cygwin-convert-path-{from,to}-windows?

[Drew Adams]

> > > cygwin-convert-filename-to-windows, and similarly for the 
> > > other one.  IOW, replace "path" with "filename".
> > 
> > But the functions convert directory names too.
> 
> "Filename" doesn't contradict that.  We have, e.g.,
> directory-file-name, file-name-as-directory, expand-file-name, etc.

I agree.  Emacs practice calls for replacing "path" with "filename" or (better)
"file-name" here.

However, I would suggest replacing "windows" with whatever is the accepted term
used in Emacs names these days (win32?).  We do not want to confuse users.  This
is about Microsoft Windows file names; it is not about Emacs windows. 

Re: document cygwin-convert-path-{from,to}-windows?

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 970 bytes --]

On 11/18/12 1:50 PM, Drew Adams wrote:
>>>> cygwin-convert-filename-to-windows, and similarly for the 
>>>> other one.  IOW, replace "path" with "filename".
>>>
>>> But the functions convert directory names too.
>>
>> "Filename" doesn't contradict that.  We have, e.g.,
>> directory-file-name, file-name-as-directory, expand-file-name, etc.
> 
> I agree.  Emacs practice calls for replacing "path" with "filename" or (better)
> "file-name" here.

I've renamed these functions in the trunk. Should I push them to the
emacs-24 branch too? (Is there a way to do that without checking out a
complete copy of that branch?)

> However, I would suggest replacing "windows" with whatever is the accepted term
> used in Emacs names these days (win32?).  We do not want to confuse users.  This
> is about Microsoft Windows file names; it is not about Emacs windows.

"windows" is clear enough in context, and the function names are long
enough as it is.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 235 bytes --]

Re: document cygwin-convert-path-{from,to}-windows?

[Eli Zaretskii]

> Date: Sun, 18 Nov 2012 17:44:30 -0800
> From: Daniel Colascione <dancol@dancol.org>
> Cc: 'Eli Zaretskii' <eliz@gnu.org>, emacs-devel@gnu.org
> 
> I've renamed these functions in the trunk.

Thanks.

> Should I push them to the emacs-24 branch too?

If the functions exist on the branch, yes.

> (Is there a way to do that without checking out a complete copy of
> that branch?)

No.  But if you do the "bzr branch" command in the same shared repo
(i.e., under the same parent directory where you have the trunk), the
initial branch command will be much faster than the one for the trunk,
because meta-date of most revisions is already on your disk, so bzr
will only fetch the few different ones, and then proceed to build the
working tree.

> > However, I would suggest replacing "windows" with whatever is the accepted term
> > used in Emacs names these days (win32?).  We do not want to confuse users.  This
> > is about Microsoft Windows file names; it is not about Emacs windows.
> 
> "windows" is clear enough in context, and the function names are long
> enough as it is.

win32 is also incorrect.  It's actually utf-16, but I doubt that using
that would help users.

Re: document cygwin-convert-path-{from,to}-windows?

[Stefan Monnier]

>> However, I would suggest replacing "windows" with whatever is the
>> accepted term used in Emacs names these days (win32?).  We do not
>> want to confuse users.  This is about Microsoft Windows file names;
>> it is not about Emacs windows.
> "windows" is clear enough in context, and the function names are long
> enough as it is.

I'm fine with "windows".  If we wan to change it, "win32" is not a good
choice since we've been avoiding the use of "win", so it would be "w32"
instead, which is used at many other places in Emacs.


        Stefan

Re: document cygwin-convert-path-{from,to}-windows?

[Glenn Morris]

Daniel Colascione wrote:

> I've renamed these functions in the trunk. Should I push them to the
> emacs-24 branch too?

Since you didn't add compat aliases, and changed the 24.3 NEWS section,
yes (please put the word "backport" somewhere in the commit message).
It would have been better to install it to the emacs-24 branch only, and
let it get merged to trunk "automatically". See admin/notes/bzr.

Re: document cygwin-convert-path-{from,to}-windows?

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 230 bytes --]

On 11/20/12 11:00 AM, Glenn Morris wrote:
> It would have been better to install it to the emacs-24 branch only, and
> let it get merged to trunk "automatically". See admin/notes/bzr.

Thanks. I'll do that in the future.



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 235 bytes --]

Re: document cygwin-convert-path-{from,to}-windows?

[Stefan Monnier]

>>>> I do have a gripe wrt their names: GNU coding standards frown upon
>>>> using "path" for anything but PATH-style lists of directories.  But my
>>>> comments about that at the time evidently weren't enough to convince
>>>> the guilty parties.
>>> It's not too late to change the names. What would you suggest?
>> cygwin-convert-filename-to-windows, and similarly for the other one.
>> IOW, replace "path" with "filename".
> But the functions convert directory names too.

You clearly need to (re-)read the GNU coding standards.


        Stefan

Re: document cygwin-convert-path-{from,to}-windows?

[Daniel Colascione]

[-- Attachment #1: Type: text/plain, Size: 1114 bytes --]

On 11/18/2012 6:37 PM, Stefan Monnier wrote:
>>>>> I do have a gripe wrt their names: GNU coding standards frown upon
>>>>> using "path" for anything but PATH-style lists of directories.  But my
>>>>> comments about that at the time evidently weren't enough to convince
>>>>> the guilty parties.
>>>> It's not too late to change the names. What would you suggest?
>>> cygwin-convert-filename-to-windows, and similarly for the other one.
>>> IOW, replace "path" with "filename".
>> But the functions convert directory names too.
> 
> You clearly need to (re-)read the GNU coding standards.

The GNU Coding Standards are silent on the topic except for the following
sentence in section 6.1:

"Please do not use the term “pathname” that is used in Unix documentation; use
“file name” (two words) instead. We use the term “path” only for search paths,
which are lists of directory names."

The document could be clearer on what to call names that can refer to either
files or directories. (FWIW, I find "path" the least confusing option, and I
find names like "directory-file-name" confusing.)


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 258 bytes --]

Re: document cygwin-convert-path-{from,to}-windows?

[Stefan Monnier]

> "Please do not use the term “pathname” that is used in Unix
> documentation; use “file name” (two words) instead. We use the term
> “path” only for search paths, which are lists of directory names."

> The document could be clearer on what to call names that can refer to either
> files or directories.

I don't understand what you find unclear about it.  It says that what
many people call "pathname" should be called "file name".
AFAIK "pathname" is used for both files and directories, so the above
says that "file name" should be used for it.

> (FWIW, I find "path" the least confusing option, and I
> find names like "directory-file-name" confusing.)

"directory-file-name" should be read as "directory -> file-name", so it
takes the a name that refers to a directory and returns the file name of
that directory.  It's not the most clear, I admin, but I'm not sure how
else to call a function that goes from "foo/" to "foo" (or from
"[foo]" to "foo.dir" back in the VMS days).


        Stefan