bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes

bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes

[Drew Adams]

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)'
 

bug#4638: 23.1; doc string and Elisp manual descriptions of file-attributes

[Drew Adams]

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,...?

bug#4638: marked as done (23.1; doc string and Elisp manual descriptions of file-attributes)

[Emacs bug Tracking System]

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

Your message dated Mon, 05 Oct 2009 10:47:03 +0200
with message-id <83ocomns6w.fsf@gnu.org>
and subject line Re: bug#4638: 23.1;	doc string and Elisp manual descriptions of file-attributes
has caused the Emacs bug report #4638,
regarding 23.1; doc string and Elisp manual descriptions of file-attributes
to be marked as done.

This means that you claim that the problem has been dealt with.
If this is not the case it is now your responsibility to reopen the
bug report if necessary, and/or fix the problem forthwith.

(NB: If you are a system administrator and have no idea what this
message is talking about, this may indicate a serious mail system
misconfiguration somewhere. Please contact owner@emacsbugs.donarmstrong.com
immediately.)


-- 
4638: http://emacsbugs.donarmstrong.com/cgi-bin/bugreport.cgi?bug=4638
Emacs Bug Tracking System
Contact owner@emacsbugs.donarmstrong.com with problems

[-- Attachment #2: Type: message/rfc822, Size: 5063 bytes --]

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

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)'
 




[-- Attachment #3: Type: message/rfc822, Size: 5801 bytes --]

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

> From: "Drew Adams" <drew.adams@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.