bug#21002: 25.0.50; (elisp): `Mode Line Variables', doc of `display-time-string'

bug#21002: 25.0.50; (elisp): `Mode Line Variables', doc of `display-time-string'

[Drew Adams]

Variable `global-mode-string' is described in (elisp): `Mode Line
Variables', including its default value.  `display-time-string' is
mentioned explicitly.

But `C-h v' tells you nothing about `display-time-string'.  To
understand something about it you need to look at `time.el'.

1. At the least, some doc string should be added for
   `display-time-string'.  It can, for example, refer users to command
   `display-time' or to (emacs) `Optional Mode Line', where `display-time'
   is covered.

2. (elisp): `Mode Line Variables' should itself cross-reference (emacs)
   `Optional Mode Line' or at least mention command `display-time',
   where it mentions `display-time-string'.

Displaying the time in the mode-line is a user-level thing, and there
are many user options that control the resulting `display-time-string'.
The only mention of `display-time-string' in the Elisp manual should at
least point readers to information about the things that control the
content of `display-time-string', especially since most of these things
are user-level controls (e.g., options, a command).

In GNU Emacs 25.0.50.1 (i686-pc-mingw32)
 of 2014-10-20 on LEG570
Bzr revision: 118168 rgm@gnu.org-20141020195941-icp42t8ttcnud09g
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking=yes,glyphs CPPFLAGS=-DGLYPH_DEBUG=1'

bug#21002: 25.0.50; (elisp): `Mode Line Variables', doc of `display-time-string'

[Lars Ingebrigtsen]

Drew Adams <drew.adams@oracle.com> writes:

> Variable `global-mode-string' is described in (elisp): `Mode Line
> Variables', including its default value.  `display-time-string' is
> mentioned explicitly.
>
> But `C-h v' tells you nothing about `display-time-string'.  To
> understand something about it you need to look at `time.el'.
>
> 1. At the least, some doc string should be added for
>    `display-time-string'.  It can, for example, refer users to command
>    `display-time' or to (emacs) `Optional Mode Line', where `display-time'
>    is covered.

I've now added a doc string that mentions `display-time'.

> 2. (elisp): `Mode Line Variables' should itself cross-reference (emacs)
>    `Optional Mode Line' or at least mention command `display-time',
>    where it mentions `display-time-string'.

And also this.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no