bug#23643: 25.0.50; Documentation of file-name-sans-extension seems wrong

bug#23643: 25.0.50; Documentation of file-name-sans-extension seems wrong

[Thomas Emile Bourgeat]

(file-name-sans-extension "foo.bar") produces "foo" when the
documentation suggests it should produce "foo.":

> Return FILENAME sans final "extension".
> The extension, in a file name, is the part that follows the last ‘.’,
> except that a leading ‘.’, if any, doesn’t count.

In GNU Emacs 25.0.50.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.24.25)
 of 2015-10-30
Repository revision: 9c36df736b89490d14a5b5109c9c00209a0c25f5
Windowing system distributor 'The X.Org Foundation', version 11.0.11604000
System Description:	Debian GNU/Linux 8.4 (jessie)

Configured features:
XPM JPEG TIFF GIF PNG SOUND GSETTINGS NOTIFY LIBXML2 FREETYPE XFT ZLIB
TOOLKIT_SCROLL_BARS GTK2 X11

bug#23643: 25.0.50; Documentation of file-name-sans-extension seems wrong

[Eli Zaretskii]

> From: Thomas Emile Bourgeat <bthom@mit.edu>
> Date: Sat, 28 May 2016 22:04:40 -0400
> 
> (file-name-sans-extension "foo.bar") produces "foo" when the
> documentation suggests it should produce "foo.":
> 
> > Return FILENAME sans final "extension".
> > The extension, in a file name, is the part that follows the last ‘.’,
> > except that a leading ‘.’, if any, doesn’t count.

Thanks for the report.  I'm not quite sure which part of the doc
string led you to believe that "foo." should be produced: the
"follows" part or the "leading `.'" part.  So I went ahead and
clarified both for the next release.

bug#23643: 25.0.50; Documentation of file-name-sans-extension seems wrong

[Eli Zaretskii]

> From: Thomas Émile Bourgeat <bthom@mit.edu>
> Date: Mon, 30 May 2016 13:40:16 -0400
> 
> Just for information, the "follows" part confused me (I thought that the part
> that follows "a" in "abc" is "bc" and not "abc"). Although, even if we assume
> that follows is "non-strict", and that the extension contains also the dot,
> then the documentation of file-name-extension is incorrect. In the two
> documentations functions "extension" is defined the same way

The extension is clearly not defined the same way in these two
functions.  But I've seen a similar issue with file-name-extension,
and fixed that as well.  The doc strings now say

  (defun file-name-sans-extension (filename)
    "Return FILENAME sans final \"extension\".
  The extension, in a file name, is the part that begins with the last `.',
  except that a leading `.' of the file name, if there is one, doesn't count."

  (defun file-name-extension (filename &optional period)
    "Return FILENAME's final \"extension\".
  The extension, in a file name, is the part that begins with the last `.',
  excluding version numbers and backup suffixes, except that a leading `.'
  of the file name, if there is one, doesn't count.
  Return nil for extensionless file names such as `foo'.
  Return the empty string for file names such as `foo.'.

  By default, the returned value excludes the period that starts the
  extension, but if the optional argument PERIOD is non-nil, the period
  is included in the value, and in that case, if FILENAME has no
  extension, the value is \"\"."