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

From: "Drew Adams" <[email-masked]>
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.