all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* convert-standard-filename documentation is insufficient
@ 2004-11-06 18:07 Jari Aalto
  2004-11-07  4:41 ` Eli Zaretskii
  0 siblings, 1 reply; 11+ messages in thread
From: Jari Aalto @ 2004-11-06 18:07 UTC (permalink / raw)



Given following description:

    (convert-standard-filename FILENAME)

    Convert a standard file's name to something suitable for the
    current OS. This function's standard definition is trivial; it
    just returns the argument. However, on some systems, the function
    is redefined with a definition that really does change some file
    names.

This leaves completely open where function would be used.
Please provide concrete examples in the documentation string.

Jari

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-06 18:07 Jari Aalto
@ 2004-11-07  4:41 ` Eli Zaretskii
  0 siblings, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2004-11-07  4:41 UTC (permalink / raw)
  Cc: bug-gnu-emacs

> From: Jari Aalto <jari.aalto@cante.net>
> Date: Sat, 06 Nov 2004 20:07:07 +0200
> 
>     (convert-standard-filename FILENAME)
> 
>     Convert a standard file's name to something suitable for the
>     current OS. This function's standard definition is trivial; it
>     just returns the argument. However, on some systems, the function
>     is redefined with a definition that really does change some file
>     names.
> 
> This leaves completely open where function would be used.
> Please provide concrete examples in the documentation string.

This function was introduced for Lisp programmers, not for users.  The
rationale for its existence and its recommended usage are explained in
the ELisp manual (which will be part of the standard Emacs distro as
of the next release).

Given the above, I personally don't see any convincing reasons to add
the usage information to the doc string.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
@ 2004-11-07 22:00 Luc Teirlinck
  2004-11-07 22:42 ` Eli Zaretskii
  0 siblings, 1 reply; 11+ messages in thread
From: Luc Teirlinck @ 2004-11-07 22:00 UTC (permalink / raw)
  Cc: bug-gnu-emacs

Eli Zaretskii wrote:
    
    Given the above, I personally don't see any convincing reasons to add
    the usage information to the doc string.

Actually, the docstring appears to have already been expanded in
current CVS:

    "Convert a standard file's name to something suitable for the current OS.
  This means to guarantee valid names and perhaps to canonicalize
  certain patterns.

  This function's standard definition is trivial; it just returns
  the argument.  However, on Windows and DOS, replace invalid
  characters.  On DOS, make sure to obey the 8.3 limitations.  On
  Windows, turn Cygwin names into native names, and also turn
  slashes into backslashes if the shell requires it (see
  `w32-shell-dos-semantics')."

I would propose a small change in the 72 character first line.
Replace `something' by `one'.  This brings it down to 66 characters,
which is within the maximum allowed 67 and looks better in the
`apropos' output:

Convert a standard file's name to one suitable for the current OS.

If there are no objections, I will install this change in CVS.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-07 22:00 Luc Teirlinck
@ 2004-11-07 22:42 ` Eli Zaretskii
  0 siblings, 0 replies; 11+ messages in thread
From: Eli Zaretskii @ 2004-11-07 22:42 UTC (permalink / raw)
  Cc: bug-gnu-emacs

> Date: Sun, 7 Nov 2004 16:00:02 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> CC: bug-gnu-emacs@gnu.org, bug-gnu-emacs@gnu.org
> 
> Eli Zaretskii wrote:
>     
>     Given the above, I personally don't see any convincing reasons to add
>     the usage information to the doc string.
> 
> Actually, the docstring appears to have already been expanded in
> current CVS:
> 
>     "Convert a standard file's name to something suitable for the current OS.
>   This means to guarantee valid names and perhaps to canonicalize
>   certain patterns.
> 
>   This function's standard definition is trivial; it just returns
>   the argument.  However, on Windows and DOS, replace invalid
>   characters.  On DOS, make sure to obey the 8.3 limitations.  On
>   Windows, turn Cygwin names into native names, and also turn
>   slashes into backslashes if the shell requires it (see
>   `w32-shell-dos-semantics')."

This still doesn't say what the OP wanted: what is the intended use of
this function.  It just says what the function does, but not in what
circumstances it should be used.

> Convert a standard file's name to one suitable for the current OS.
> 
> If there are no objections, I will install this change in CVS.

FWIW, I find the current wording more clear.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
       [not found] <mailman.1099.1099774836.8225.bug-gnu-emacs@gnu.org>
@ 2004-11-08 19:29 ` Stefan Monnier
  0 siblings, 0 replies; 11+ messages in thread
From: Stefan Monnier @ 2004-11-08 19:29 UTC (permalink / raw)


>     (convert-standard-filename FILENAME)

>     Convert a standard file's name to something suitable for the
>     current OS. This function's standard definition is trivial; it
>     just returns the argument. However, on some systems, the function
>     is redefined with a definition that really does change some file
>     names.

> This leaves completely open where function would be used.
> Please provide concrete examples in the documentation string.

This function is to be used for packages which use hardcoded file names.
E.g. it is used for ~/.emacs, ~/.gnus and things like that, where the author
has to choose a name and wants to make sure that it still works on systems
where this name might not be valid.

I'm not sure how to best express it.  Do you have a concrete suggestion for
a new docstring?  (please don't just say "yes, your above four lines would
be fine")


        Stefan


PS: Now that I think about it, why on earth does it try to handle
    cygwin filenames?  Or more specifically, under what circumstance would
    this function receive a cygwin file name?

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
@ 2004-11-08 21:58 Luc Teirlinck
  0 siblings, 0 replies; 11+ messages in thread
From: Luc Teirlinck @ 2004-11-08 21:58 UTC (permalink / raw)
  Cc: bug-gnu-emacs

Alternately, we could just put in a link to the Elisp manual.  All the
user has to do is click mouse-2 or press RETURN on the link.

Also the first line needs to be shortened since it is 72 characters, 5
longer than the maximum allowed 67.  I first suggested doing this by
replacing `something' by `one'.  An alternative is to delete "current"
in front of OS.  It is redundant.  Which _other_ operating system
could be meant?

That would give:

  "Convert a standard file's name to something suitable for the OS.
  This means to guarantee valid names and perhaps to canonicalize
  certain patterns.

  This function's standard definition is trivial; it just returns
  the argument.  However, on Windows and DOS, replace invalid
  characters.  On DOS, make sure to obey the 8.3 limitations.  On
  Windows, turn Cygwin names into native names, and also turn
  slashes into backslashes if the shell requires it (see
  `w32-shell-dos-semantics'

  See `(elisp)Standard File Names' for more details."

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
@ 2004-11-08 22:02 Luc Teirlinck
  2004-11-11 23:03 ` Jeff Dwork
  0 siblings, 1 reply; 11+ messages in thread
From: Luc Teirlinck @ 2004-11-08 22:02 UTC (permalink / raw)
  Cc: bug-gnu-emacs, monnier

Sorry, I forgot to put `Info node' in front of the link:

  "Convert a standard file's name to something suitable for the OS.
This means to guarantee valid names and perhaps to canonicalize
certain patterns.

This function's standard definition is trivial; it just returns
the argument.  However, on Windows and DOS, replace invalid
characters.  On DOS, make sure to obey the 8.3 limitations.  On
Windows, turn Cygwin names into native names, and also turn
slashes into backslashes if the shell requires it (see
`w32-shell-dos-semantics'

See Info node `(elisp)Standard File Names' for more details."

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-08 22:02 convert-standard-filename documentation is insufficient Luc Teirlinck
@ 2004-11-11 23:03 ` Jeff Dwork
  2004-11-12  5:24   ` Werner LEMBERG
                     ` (2 more replies)
  0 siblings, 3 replies; 11+ messages in thread
From: Jeff Dwork @ 2004-11-11 23:03 UTC (permalink / raw)
  Cc: bug-gnu-emacs, monnier

How about this for the first line?

  "Convert string FILENAME to a legal filename for the OS.

remainder as below.

Jeff

Luc Teirlinck writes:
 > To: teirllm@dms.auburn.edu
 > cc: bug-gnu-emacs@gnu.org, monnier@iro.umontreal.ca
 > Subject: Re: convert-standard-filename documentation is insufficient
 > Date: Mon, 8 Nov 2004 16:02:11 -0600 (CST)
 > 
 > Sorry, I forgot to put `Info node' in front of the link:
 > 
 >   "Convert a standard file's name to something suitable for the OS.
 > This means to guarantee valid names and perhaps to canonicalize
 > certain patterns.
 > 
 > This function's standard definition is trivial; it just returns
 > the argument.  However, on Windows and DOS, replace invalid
 > characters.  On DOS, make sure to obey the 8.3 limitations.  On
 > Windows, turn Cygwin names into native names, and also turn
 > slashes into backslashes if the shell requires it (see
 > `w32-shell-dos-semantics'
 > 
 > See Info node `(elisp)Standard File Names' for more details."
 > 
 > Sincerely,
 > 
 > Luc.
 > 
 > 
 > _______________________________________________
 > Bug-gnu-emacs mailing list
 > Bug-gnu-emacs@gnu.org
 > http://lists.gnu.org/mailman/listinfo/bug-gnu-emacs

-- 
Jeff Dwork                     | jeff.dwork@amd.com  408-307-2496 (cell)
Advanced Micro Devices, M/S 362| 408-749-5216 (desk) 408-774-7811 (fax)
PO Box 3453                    |----------------------------------------
Sunnyvale, Ca 94088-3453       | 

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-11 23:03 ` Jeff Dwork
@ 2004-11-12  5:24   ` Werner LEMBERG
  2004-11-12 13:34   ` Luc Teirlinck
  2004-11-12 13:54   ` Luc Teirlinck
  2 siblings, 0 replies; 11+ messages in thread
From: Werner LEMBERG @ 2004-11-12  5:24 UTC (permalink / raw)
  Cc: bug-gnu-emacs, teirllm, monnier


>   "Convert string FILENAME to a legal filename for the OS.

`valid', not `legal', please.


    Werner

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-11 23:03 ` Jeff Dwork
  2004-11-12  5:24   ` Werner LEMBERG
@ 2004-11-12 13:34   ` Luc Teirlinck
  2004-11-12 13:54   ` Luc Teirlinck
  2 siblings, 0 replies; 11+ messages in thread
From: Luc Teirlinck @ 2004-11-12 13:34 UTC (permalink / raw)
  Cc: bug-gnu-emacs, monnier

Jeff Dwork wrote:

   How about this for the first line?

     "Convert string FILENAME to a legal filename for the OS.

   remainder as below.

If I understand correctly, the purpose of `convert-standard-filename'
is not to take a file name that is _valid_ (or "legal") under GNU/Unix
type systems and convert it to a name that is valid under another OS.
I believe that is done by other functions such as
`file-name-as-directory' and `expand-file-name'.  I believe that the
purpose of `convert-standard-filename' is to convert a _standard_ file
name under GNU/Unix type systems into a name that is standard under
another OS, or maybe just "suitable" if there is no real standard form
on that OS.  Hence:

Convert a standard file's name to something suitable for the OS.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 11+ messages in thread

* Re: convert-standard-filename documentation is insufficient
  2004-11-11 23:03 ` Jeff Dwork
  2004-11-12  5:24   ` Werner LEMBERG
  2004-11-12 13:34   ` Luc Teirlinck
@ 2004-11-12 13:54   ` Luc Teirlinck
  2 siblings, 0 replies; 11+ messages in thread
From: Luc Teirlinck @ 2004-11-12 13:54 UTC (permalink / raw)
  Cc: bug-gnu-emacs, monnier

I probably used the wrong terminology in my previous reply and
explained things somewhat inaccurately.  It probably works better on
an example.  The "standard file name" of the file to store abbrevs in
is ".abbrev_defs" on GNU/Unix type systems.  This file name follows
some standard conventions on GNU/Linux.  It is not just "valid" on
GNU/Linux.  On MS-DOS this gets converted to _abbrev.def, which is not
just valid on MS-DOS, but follows conventions standard on MS-DOS.

In:

Convert a standard file's name to something suitable for the OS.

"standard file name" means something like ".abbrev_defs", as opposed
to a file name chosen by the user.  "something suitable for the OS".
means not just merely valid, but also following standard conventions
for the OS.

Sincerely,

Luc.

^ permalink raw reply	[flat|nested] 11+ messages in thread

end of thread, other threads:[~2004-11-12 13:54 UTC | newest]

Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2004-11-08 22:02 convert-standard-filename documentation is insufficient Luc Teirlinck
2004-11-11 23:03 ` Jeff Dwork
2004-11-12  5:24   ` Werner LEMBERG
2004-11-12 13:34   ` Luc Teirlinck
2004-11-12 13:54   ` Luc Teirlinck
  -- strict thread matches above, loose matches on Subject: below --
2004-11-08 21:58 Luc Teirlinck
     [not found] <mailman.1099.1099774836.8225.bug-gnu-emacs@gnu.org>
2004-11-08 19:29 ` Stefan Monnier
2004-11-07 22:00 Luc Teirlinck
2004-11-07 22:42 ` Eli Zaretskii
2004-11-06 18:07 Jari Aalto
2004-11-07  4:41 ` Eli Zaretskii

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.