GNU bug report logs - #4638
23.1; doc string and Elisp manual descriptions of file-attributes

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 4638 in the body.
You can then email your comments to 4638 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <bug-gnu-emacs <at> gnu.org>
Subject: 23.1; doc string and Elisp manual descriptions of file-attributes
Date: Sun, 4 Oct 2009 17:58:15 -0700

From the doc string:
 
 1. Number of links to file.
 
Please state that it is an integer value.
 
 2. File uid as a string or a number.  If a string value cannot be
    looked up, a numeric value, either an integer or a float, is
    returned.
 
Can we say how long the string is (fixed length or max)?
 
 10. inode number.  If inode number is larger than the Emacs integer...
 
Should presumably say "than the _largest_ Emacs integer".
 
Also, #10 contradicts what is said in the Elisp manual, node `File
Attributes'. Which is correct? The doc string speaks of a cons cell
containing possibly 3 integers. (And how can a single cons cell
contain 3 integers? Not clear.) The manual speaks of a (single) cons
cell with car and cdr integers.
 
 11. Device number.  If it is larger than the Emacs integer, this is
     a cons cell, similar to the inode number.
 
Again, it should presumably say _largest_ Emacs integer.
 
Also, it's not clear what "device number" means, and the Elisp manual
describes this differently, as "the file system number of the file
system that the file is in". Neither description is understandable,
but they especially do not seem to correspond, at least not in a
self-evident way. These desciptions need to be improved, at the very
least by referring to the original terminology (UNIX) or reference.
 
The following note is referenced only from #4, but #5 and #6 say
"likewise". The note speaks of "access time". It is not clear whether
the note applies only to #4 (access time) or also to #5 and #6. If it
applies only to #4, then it should just be moved to #4. Otherwise,
things should be rephrased to make clear what is meant (not
necessarily access time).
 
 On some FAT-based filesystems, only the date of last
 access is recorded, so last access time will always be
 midnight of that day.

It is important to get these descriptions right. How can we expect someone to
write code that depends on these values, if s?he cannot even know what forms
they can take?
 

In GNU Emacs 23.1.1 (i386-mingw-nt5.1.2600)
 of 2009-07-29 on SOFT-MJASON
Windowing system distributor `Microsoft Corp.', version 5.1.2600
configured using `configure --with-gcc (4.4)'
 

Message #10 received at submit <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: <4638 <at> debbugs.gnu.org>, <bug-gnu-emacs <at> gnu.org>
Subject: RE: bug#4638: 23.1;doc string and Elisp manual descriptions of file-attributes
Date: Sun, 4 Oct 2009 18:12:48 -0700

I forgot to mention that #6 is unclear in both doc string and manual: What does
"status change" mean? Does it mean change of mode (rwx), owner, group,...?

Message #20 received at 4638-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Drew Adams <drew.adams <at> oracle.com>, 4638-done <at> debbugs.gnu.org
Subject: Re: bug#4638: 23.1;	doc string and Elisp manual descriptions of file-attributes
Date: Mon, 05 Oct 2009 10:47:03 +0200

> From: "Drew Adams" <drew.adams <at> oracle.com>
> Date: Sun, 4 Oct 2009 17:58:15 -0700
> Cc: 
> 
> From the doc string:
>  
>  1. Number of links to file.
>  
> Please state that it is an integer value.

I don't think this is important.  A "number" means what `numberp' will
return non-nil for.  Stating that it's an integer is a maintenance
burden, because, like other attributes in this function, it may evolve
from an integer to a float.  (Other attributes in the doc say
specifically that they can be floats because in the past the doc
string stated they are integers.)

>  2. File uid as a string or a number.  If a string value cannot be
>     looked up, a numeric value, either an integer or a float, is
>     returned.
>  
> Can we say how long the string is (fixed length or max)?

There's no limit, as far as Emacs is concerned (except that every
string is inherently limited by the size of an Emacs integer), so no,
we can't state any useful limitation.

>  10. inode number.  If inode number is larger than the Emacs integer...
>  
> Should presumably say "than the _largest_ Emacs integer".

Changed this to say "is larger than what Emacs integer can hold".

> Also, #10 contradicts what is said in the Elisp manual, node `File
> Attributes'. Which is correct? The doc string speaks of a cons cell
> containing possibly 3 integers. The manual speaks of a (single) cons
> cell with car and cdr integers.

The manual is wrong, I fixed it.

> (And how can a single cons cell contain 3 integers? Not clear.)

"M-: (cons 'a (cons 'b 'c)) RET"

Anyway, I changed the text not to use ``cons cell'' in this case.

>  11. Device number.  If it is larger than the Emacs integer, this is
>      a cons cell, similar to the inode number.
>  
> Again, it should presumably say _largest_ Emacs integer.
>  
> Also, it's not clear what "device number" means, and the Elisp manual
> describes this differently, as "the file system number of the file
> system that the file is in". Neither description is understandable,
> but they especially do not seem to correspond, at least not in a
> self-evident way. These desciptions need to be improved, at the very
> least by referring to the original terminology (UNIX) or reference.

The doc string now says

  11. Filesystem device number.  If it is larger than what the Emacs
    integer can hold, this is a cons cell, similar to the inode number.

A more detailed description already existed in the manual.  I don't
think the Unix terminology will help here, btw, because we want this
documentation to be as system independent as possible, and the Unix
meaning is wrong on Windows.  The important part is this:

  On most filesystems, the combination of the inode and the device
  number uniquely identifies the file.

which I added to the doc string (it was already in the manual, albeit
in slightly different wording).

> The following note is referenced only from #4, but #5 and #6 say
> "likewise". The note speaks of "access time". It is not clear whether
> the note applies only to #4 (access time) or also to #5 and #6. If it
> applies only to #4, then it should just be moved to #4. Otherwise,
> things should be rephrased to make clear what is meant (not
> necessarily access time).
>  
>  On some FAT-based filesystems, only the date of last
>  access is recorded, so last access time will always be
>  midnight of that day.

It applies only to the last access time.  The note now says

  (See a note below about access time on FAT-based filesystems.)

I don't think it's a good idea to have the note right at #4 because
this is an obscure misfeature of an old DOS/Windows filesystem, so
it should be near the end of the doc string.

> What does "status change" mean? Does it mean change of mode (rwx),
> owner, group,...?

I hope this new text is more clear:

 5. Last modification time, likewise.  This is the time of the last
  change to the file's contents.
 6. Last status change time, likewise.  This is the time of last change
  to the file's attributes: owner and group, access mode bits, etc.

> How can we expect someone to write code that depends on these
> values, if s?he cannot even know what forms they can take?

I don't think the situation was quite that bad, and I hope it is
better now.

Message #21 received at 4638-done <at> emacsbugs.donarmstrong.com (full text, mbox):

From: "Drew Adams" <drew.adams <at> oracle.com>
To: "'Eli Zaretskii'" <eliz <at> gnu.org>, <4638-done <at> debbugs.gnu.org>
Subject: RE: bug#4638: 23.1;	doc string and Elisp manual descriptions of file-attributes
Date: Mon, 5 Oct 2009 07:27:36 -0700

> >  1. Number of links to file.
> >  
> > Please state that it is an integer value.
> 
> I don't think this is important.  A "number" means what `numberp' will
> return non-nil for.  Stating that it's an integer is a maintenance
> burden, because, like other attributes in this function, it may evolve
> from an integer to a float.  (Other attributes in the doc say
> specifically that they can be floats because in the past the doc
> string stated they are integers.)

OK.

> >  2. File uid as a string or a number.  If a string value cannot be
> >     looked up, a numeric value, either an integer or a float, is
> >     returned.
> >  
> > Can we say how long the string is (fixed length or max)?
> 
> There's no limit, as far as Emacs is concerned (except that every
> string is inherently limited by the size of an Emacs integer), so no,
> we can't state any useful limitation.

OK.

> >  10. inode number.  If inode number is larger than the 
> Emacs integer...
> >  
> > Should presumably say "than the _largest_ Emacs integer".
> 
> Changed this to say "is larger than what Emacs integer can hold".

OK.

> > Also, #10 contradicts what is said in the Elisp manual, node `File
> > Attributes'. Which is correct? The doc string speaks of a cons cell
> > containing possibly 3 integers. The manual speaks of a (single) cons
> > cell with car and cdr integers.
> 
> The manual is wrong, I fixed it.

Thx.

> > (And how can a single cons cell contain 3 integers? Not clear.)
> 
> "M-: (cons 'a (cons 'b 'c)) RET"

That's two cons cells. 

> Anyway, I changed the text not to use ``cons cell'' in this case.

OK.

> >  11. Device number.  If it is larger than the Emacs integer, this is
> >      a cons cell, similar to the inode number.
> >  
> > Again, it should presumably say _largest_ Emacs integer.
> >  
> > Also, it's not clear what "device number" means, and the 
> Elisp manual
> > describes this differently, as "the file system number of the file
> > system that the file is in". Neither description is understandable,
> > but they especially do not seem to correspond, at least not in a
> > self-evident way. These desciptions need to be improved, at the very
> > least by referring to the original terminology (UNIX) or reference.
> 
> The doc string now says
> 
>   11. Filesystem device number.  If it is larger than what the Emacs
>     integer can hold, this is a cons cell, similar to the 
> inode number.

OK.

> A more detailed description already existed in the manual.  I don't
> think the Unix terminology will help here, btw, because we want this
> documentation to be as system independent as possible, and the Unix
> meaning is wrong on Windows.  The important part is this:
> 
>   On most filesystems, the combination of the inode and the device
>   number uniquely identifies the file.
> 
> which I added to the doc string (it was already in the manual, albeit
> in slightly different wording).

Good.

> > The following note is referenced only from #4, but #5 and #6 say
> > "likewise". The note speaks of "access time". It is not 
> clear whether
> > the note applies only to #4 (access time) or also to #5 and 
> #6. If it
> > applies only to #4, then it should just be moved to #4. Otherwise,
> > things should be rephrased to make clear what is meant (not
> > necessarily access time).
> >  
> >  On some FAT-based filesystems, only the date of last
> >  access is recorded, so last access time will always be
> >  midnight of that day.
> 
> It applies only to the last access time.  The note now says
> 
>   (See a note below about access time on FAT-based filesystems.)

OK.

> I don't think it's a good idea to have the note right at #4 because
> this is an obscure misfeature of an old DOS/Windows filesystem, so
> it should be near the end of the doc string.

OK.

> > What does "status change" mean? Does it mean change of mode (rwx),
> > owner, group,...?
> 
> I hope this new text is more clear:
> 
>  5. Last modification time, likewise.  This is the time of the last
>   change to the file's contents.
>  6. Last status change time, likewise.  This is the time of 
> last change
>   to the file's attributes: owner and group, access mode bits, etc.

Good.

> > How can we expect someone to write code that depends on these
> > values, if s?he cannot even know what forms they can take?
> 
> I don't think the situation was quite that bad, and I hope it is
> better now.

Thanks.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.