Better documentation for the fractional part of seconds fields for -printf and similar actions.

ChangeLog

@@ -1,5 +1,15 @@
 2007-06-22  James Youngman  <jay@gnu.org>
 
+	Better documentation for the fractional part of seconds fields for
+	-printf and similar actions.
+	* doc/find.texi (Time Components): Point out that the seconds
+	field of the timestamp is often printed out with a fractional part
+	of unspecified length and precision.  The '%Tc' field has no
+	seconds part.
+	(Combined Time Formats): Point out the same thing for '%T@'.
+	* find/find.1 (%A): Point out the same thing.
+	* NEWS: Mention these changes.
+
 	Fix various lint-type complaints taken from the rules in the
 	coreutils Makefile.maint file (see build-aux/src-sniff.py).
 	* xargs/xargs.c: Removed unnecessary parentheses in "#if defined"

NEWS

@@ -6,6 +6,12 @@ GNU findutils NEWS - User visible changes.	-*- outline -*- (allout)
 #20139: find -[acm]time -N (wrongly) includes files from N days ago,
 as well as (correctly) from less than N days ago.
 
+** Documentation Fixes
+
+Point out more explicitly that the subsecond timestamp support
+introduced by findutils-4.3.3 introduces a change in the format of
+several fields.
+
 * Major changes in release 4.3.8
 
 ** Bug Fixes

doc/find.texi

@@ -1885,11 +1885,20 @@ time zone (e.g., EDT), or nothing if no time zone is determinable
 @item M
 minute (00..59)
 @item S
-second (00..61)
+second (00..61).  There is a fractional part.
 @item @@
-seconds since Jan. 1, 1970, 00:00 GMT.
+seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.
 @end table
 
+The fractional part of the seconds field is of indeterminate length
+and precision.  That is, the length of the fractional part of the
+seconds field will in general vary between findutils releases and
+between systems.  This means that it is unwise to assume that field
+has any specific length.  The length of this field is not usually a
+guide to the precision of timestamps in the underlying file system.
+
+
+
 @node Date Components
 @subsubsection Date Components
 
@@ -1937,15 +1946,19 @@ time, 24-hour (hh:mm:ss)
 @item X
 locale's time representation (H:M:S)
 @item c
-locale's date and time (Sat Nov 04 12:02:33 EST 1989)
+locale's date and time in ctime format (Sat Nov 04 12:02:33 EST
+1989).  This format does nto include any fractional part in the
+seconds field.
 @item D
 date (mm/dd/yy)
 @item x
 locale's date representation (mm/dd/yy)
 @item +
-Date and time, separated by '+', for example `2004-04-28+22:22:05'.
+Date and time, separated by '+', for example
+`2004-04-28+22:22:05.0000000000'.
 The time is given in the current timezone (which may be affected by
-setting the TZ environment variable).  This is a GNU extension.
+setting the TZ environment variable).  This is a GNU extension.  The
+seconds field includes a fractional part.
 @end table
 
 @node Formatting Flags

find/find.1

@@ -807,7 +807,7 @@ available on all systems, due to differences in `strftime' between
 systems.  
 .RS
 .IP @
-seconds since Jan. 1, 1970, 00:00 GMT.
+seconds since Jan. 1, 1970, 00:00 GMT, with fractional part.
 .PP
 Time fields:
 .IP H
@@ -825,13 +825,14 @@ locale's AM or PM
 .IP r
 time, 12-hour (hh:mm:ss [AP]M)
 .IP S
-second (00..61)
+Second (00.00 .. 61.00).  There is a fractional part.
 .IP T
 time, 24-hour (hh:mm:ss)
 .IP +
-Date and time, separated by '+', for example `2004\-04\-28+22:22:05'.
-The time is given in the current timezone (which may be affected by
-setting the TZ environment variable).  This is a GNU extension.
+Date and time, separated by '+', for example
+`2004\-04\-28+22:22:05.0'.  This is a GNU extension.  The time is
+given in the current timezone (which may be affected by setting the TZ
+environment variable).  The seconds field includes a fractional part.
 .IP X
 locale's time representation (H:M:S)
 .IP Z
@@ -847,7 +848,11 @@ locale's abbreviated month name (Jan..Dec)
 .IP B
 locale's full month name, variable length (January..December)
 .IP c
-locale's date and time (Sat Nov 04 12:02:33 EST 1989)
+locale's date and time (Sat Nov 04 12:02:33 EST 1989).  The format is
+the same as for 
+.BR ctime (3)
+and so to preserve compatibility with that format, there is no fractional part
+in the seconds field.
 .IP d
 day of month (01..31)
 .IP D