bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Toby Cubitt]

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

The documentation in the Elisp manual for `file-attributes' and for
file-modification undo-list elements hasn't been updated to match the new
high-precision timestamp format.

Patch attached.

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

[-- Attachment #2: elisp_timestamp_doc.patch --]
[-- Type: text/x-patch, Size: 1659 bytes --]

=== modified file 'doc/lispref/files.texi'
--- doc/lispref/files.texi	2012-10-01 02:07:14 +0000
+++ doc/lispref/files.texi	2012-10-22 18:53:24 +0000
@@ -1220,12 +1220,13 @@
 The file's @acronym{GID}, likewise.
 
 @item
-The time of last access, as a list of two integers.
-The first integer has the high-order 16 bits of time,
-the second has the low 16 bits.  (This is similar to the
-value of @code{current-time}; see @ref{Time of Day}.)  Note that on
-some FAT-based filesystems, only the date of last access is recorded,
-so this time will always hold the midnight of the day of last access.
+The time of last access, as a list of four integers.  The first
+integer has the high-order 16 bits of the seconds, the second integer
+the low 16 bits, the third the microseconds, and the fourth the
+picoseconds.  (This is similar to the value of @code{current-time};
+see @ref{Time of Day}.)  Note that on some FAT-based filesystems, only
+the date of last access is recorded, so this time will always hold the
+midnight of the day of last access.
 
 @cindex modification time of file
 @item

=== modified file 'doc/lispref/text.texi'
--- doc/lispref/text.texi	2012-09-18 05:14:42 +0000
+++ doc/lispref/text.texi	2012-10-22 18:49:39 +0000
@@ -1233,7 +1233,7 @@
 positive, point was at the beginning of the deleted text, otherwise it
 was at the end.
 
-@item (t @var{high} . @var{low})
+@item (t @var{sec-high} @var{sec-low} @var{msec} @var{usec})
 This kind of element indicates that an unmodified buffer became
 modified.  The elements @var{high} and @var{low} are two integers, each
 recording 16 bits of the visited file's modification time as of when it

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Eli Zaretskii]

> Date: Mon, 22 Oct 2012 21:02:28 +0200
> From: Toby Cubitt <tsc25@cantab.net>
> 
> The documentation in the Elisp manual for `file-attributes' and for
> file-modification undo-list elements hasn't been updated to match the new
> high-precision timestamp format.

That's normal at this stage: documentation usually gets updated only
late in the release process, which didn't start yet.  There are
markings in etc/NEWS that tell which changes are not documented yet.

> Patch attached.

Thanks.

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Glenn Morris]

Eli Zaretskii wrote:

>> The documentation in the Elisp manual for `file-attributes' and for
>> file-modification undo-list elements hasn't been updated to match the new
>> high-precision timestamp format.
>
> That's normal at this stage: documentation usually gets updated only
> late in the release process, which didn't start yet.  There are
> markings in etc/NEWS that tell which changes are not documented yet.

The file-attributes entry is marked with "---", so it's good that we
have this report.

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Toby Cubitt]

On Mon, Oct 22, 2012 at 04:08:29PM -0400, Glenn Morris wrote:
> Eli Zaretskii wrote:
> 
> >> The documentation in the Elisp manual for `file-attributes' and for
> >> file-modification undo-list elements hasn't been updated to match the new
> >> high-precision timestamp format.
> >
> > That's normal at this stage: documentation usually gets updated only
> > late in the release process, which didn't start yet.  There are
> > markings in etc/NEWS that tell which changes are not documented yet.

Ah, I didn't realise that's how things worked. I'll know for next
time. Thanks!

> The file-attributes entry is marked with "---", so it's good that we
> have this report.

Glad it's still useful for something. I suspect the changes to the undo
entry format also risked being overlooked too, since they aren't
mentioned explicitly in that etc/NEWS entry.

Toby
-- 
Dr T. S. Cubitt
Mathematics and Quantum Information group
Department of Mathematics
Complutense University
Madrid, Spain

email: tsc25@cantab.net
web:   www.dr-qubit.org

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Eli Zaretskii]

> From: Glenn Morris <rgm@gnu.org>
> Cc: Toby Cubitt <toby-dated-1352142136.ff38c0@dr-qubit.org>,  12706@debbugs.gnu.org
> Date: Mon, 22 Oct 2012 16:08:29 -0400
> 
> Eli Zaretskii wrote:
> 
> >> The documentation in the Elisp manual for `file-attributes' and for
> >> file-modification undo-list elements hasn't been updated to match the new
> >> high-precision timestamp format.
> >
> > That's normal at this stage: documentation usually gets updated only
> > late in the release process, which didn't start yet.  There are
> > markings in etc/NEWS that tell which changes are not documented yet.
> 
> The file-attributes entry is marked with "---"

Then _that_ is a bug.

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Paul Eggert]

Thanks for the bug report.  I installed a fix for it in
trunk bzr 110628, which you can see here:

http://bzr.savannah.gnu.org/lh/emacs/trunk/revision/110628

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Glenn Morris]

Paul Eggert wrote:

> Thanks for the bug report.  I installed a fix for it in
> trunk bzr 110628, which you can see here:
>
> http://bzr.savannah.gnu.org/lh/emacs/trunk/revision/110628

There's still more to do.


You can use @code{file-attributes} to get a file's last modification
time as a list of two numbers.  @xref{File Attributes}.

@cindex modification time of file
@item
The time of last modification as a list of two integers (as above).

@item
The time of last status change as a list of two integers (as above).

For example, here are the file attributes for @file{files.texi}:
[...]
@item (19145 42977)
was last accessed on Oct 5 2009, at 10:01:37.


etc.

bug#12706: 24.2.50; Outdated timestamp documentation in Elisp manual

[Paul Eggert]

On 10/23/2012 08:57 AM, Glenn Morris wrote:
> There's still more to do.

Thanks, I fixed the documentation problems you mentioned
(and a few others that I found after looking again)
in trunk bzr 110646.