bug#2768: 23.0.60; Misleading function description for float-time

Please write in English if possible, because the Emacs maintainers
usually do not have translators to read other languages for them.

Your bug report will be posted to the [email protected] mailing list.

Please describe exactly what actions triggered the bug
and the precise symptoms of the bug:

The DOC string for float-time says

    float-time is a built-in function in `C source code'.

    (float-time &optional specified-time)

    Return the current time, as a float number of seconds since the epoch.
    If specified-time is given, it is the time to convert to float
    instead of the current time.  The argument should have the form
    (HIGH LOW . IGNORED). Thus, you can use times obtained from
    `current-time' and from `file-attributes'.  specified-time can also
    have the form (HIGH . LOW), but this is considered obsolete.

    WARNING: Since the result is floating point, it may not be exact.
    Do not use this function if precise time stamps are required.

    [back]


However, the argument "IGNORED" is not ignored but rather specifies
microseconds that _do_ appear in the resulting time value.  While the
doc string does not explicitly specify what happens to "IGNORED", its
name strongly suggests a different (and undesirable) behavior.

In GNU Emacs 23.0.60.2 (i686-pc-linux-gnu, GTK+ Version 2.12.9)
 of 2009-01-13 on lisa
Windowing system distributor `The X.Org Foundation', version 11.0.10400090
configured using `configure  '--prefix=/usr/local/emacs-21' '--without-toolkit-scroll-bars''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: nil
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: nil
  value of $LC_NUMERIC: nil
  value of $LC_TIME: nil
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default-enable-multibyte-characters: t

Major mode: Message

Minor modes in effect:
  mml-mode: t
  gnus-message-citation-mode: t
  TeX-PDF-mode: t
  server-mode: t
  desktop-save-mode: t
  tooltip-mode: t
  mouse-wheel-mode: t
  menu-bar-mode: t
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  blink-cursor-mode: t
  global-auto-composition-mode: t
  auto-composition-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t
  transient-mark-mode: t
  abbrev-mode: t

-- 
David Kastrup