unofficial mirror of bug-gnu-emacs@gnu.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-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
[parent not found: <mailman.1099.1099774836.8225.bug-gnu-emacs@gnu.org>]
* 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

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-06 18:07 convert-standard-filename documentation is insufficient Jari Aalto
2004-11-07  4:41 ` Eli Zaretskii
  -- strict thread matches above, loose matches on Subject: below --
2004-11-07 22:00 Luc Teirlinck
2004-11-07 22:42 ` Eli Zaretskii
     [not found] <mailman.1099.1099774836.8225.bug-gnu-emacs@gnu.org>
2004-11-08 19:29 ` Stefan Monnier
2004-11-08 21:58 Luc Teirlinck
2004-11-08 22:02 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

Code repositories for project(s) associated with this public inbox

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

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).