Lowercase text after full stop on describe-variable

Lowercase text after full stop on describe-variable

[Juanma Barranquero]

When a variable is obsolete, the help info looks ugly because the "not
documented as a variable" text is not capitalized after a full stop.

Example from local-write-file-hooks:

> Documentation:
> This variable is obsolete since 21.4.
> Use `write-file-functions' instead.
> not documented as a variable.

Perhaps it is better to put the obsolescence info after the variable
documentation, unless the current point was purposelly chosen to
highlight the fact that the variable is obsolete.


                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Stefan Monnier]

> When a variable is obsolete, the help info looks ugly because the "not
> documented as a variable" text is not capitalized after a full stop.
> 
> Example from local-write-file-hooks:
> 
> > Documentation:
> > This variable is obsolete since 21.4.
> > Use `write-file-functions' instead.
> > not documented as a variable.
> 
> Perhaps it is better to put the obsolescence info after the variable
> documentation, unless the current point was purposelly chosen to
> highlight the fact that the variable is obsolete.

How about just capitalizing the `not' ?
After all, even without the obsolete stuff it deserves a capital, doesn't it?


	Stefan

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

On Mon, 24 Jun 2002 11:23:08 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> How about just capitalizing the `not' ?
> After all, even without the obsolete stuff it deserves a capital, doesn't it?

Yes, but then, for coherence, the "not documented" strings in
describe-function-1 and describe-face should be capitalized too.


                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

And BTW, I'm wondering what's the reason you didn't include the
equivalent functionality for obsolescent functions, like in the simple
patch below (a slight modification of your describe-variable patch).

Is there some complication I'm missing?


                                                           /L/e/k/t/u




Index: help-fns.el
===================================================================
RCS file: /cvs/emacs/lisp/help-fns.el,v
retrieving revision 1.10
diff -u -2 -r1.10 help-fns.el
--- help-fns.el	23 Jun 2002 21:02:45 -0000	1.10
+++ help-fns.el	24 Jun 2002 16:25:40 -0000
@@ -278,4 +278,13 @@
 	     (princ arglist)
 	     (terpri))))
+    (let ((obsolete (get function 'byte-obsolete-info)))
+      (when obsolete
+        (terpri)
+        (princ "This function is obsolete")
+        (if (caddr obsolete) (princ (format " since %s" (caddr obsolete))))
+        (princ ".") (terpri)
+        (princ (if (stringp (car obsolete)) (car obsolete)
+                 (format "Use `%s' instead." (car obsolete))))
+        (terpri)))
     (let ((doc (documentation function)))
       (if doc

Re: Lowercase text after full stop on describe-variable

[Stefan Monnier]

> And BTW, I'm wondering what's the reason you didn't include the
> equivalent functionality for obsolescent functions, like in the simple
> patch below (a slight modification of your describe-variable patch).

Just that the needed didn't show up (where the need for vars did
when checking what C-h v local-write-file-hooks returned).

> Is there some complication I'm missing?

Not that I can see apart from the fact that caddr is not defined
unless you (require 'cl).  Feel free to install it (and fix the
capitalization issue while you're at it ;-).
Thanks,


	Stefan

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

On Mon, 24 Jun 2002 16:20:17 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> Not that I can see apart from the fact that caddr is not defined
> unless you (require 'cl).  Feel free to install it

Ok, I have a patch using `nth' instead.

WRT the upper/lower-case issue, what should I do with variables or
functions which have a NEW string (as opossed to a NEW function/variable)
starting with lowercase, not ending with a stop, or otherwise
non-normalized? Normalize them?

Currently they are:

- Variables:
  inhibit-local-variables
  unread-command-char
  unread-command-event
  before-change-function
  after-change-function
  post-command-idle-hook
  post-command-idle-delay

- Functions:
  frame-update-faces (no stop)
  char-bytes (no stop)
  baud-rate
  string-to-sequence (no stop)

`move-to-column-force' (from rect.el) is an exception because its
docstring already says that the function is obsolete, and the
make-obsolete declaration is wrong (it is passing as a NEW a string
instead of a symbol, but the string is just the name of a function).

So, what I propose is:

 1.- Installing the patch so describe-function shows the obsolescent
information too like describe-variable does now.
 2.- Changing the "not documented" strings from those functions and
`describe-face' to "Not documented".
 3.- Normalizing the NEW strings currently passed to `make-obsolete' and
`make-obsolete-variable'.
 4.- Remove the obsolescence information from `move-to-column-force's
docstring and fixing its make-obsolete declaration.

It is OK to proceed?


                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Richard Stallman]

    And BTW, I'm wondering what's the reason you didn't include the
    equivalent functionality for obsolescent functions, like in the simple
    patch below (a slight modification of your describe-variable patch).

It seems like a good idea.

Re: Lowercase text after full stop on describe-variable

[Stefan Monnier]

> So, what I propose is:
> 
>  1.- Installing the patch so describe-function shows the obsolescent
> information too like describe-variable does now.
>  2.- Changing the "not documented" strings from those functions and
> `describe-face' to "Not documented".
>  3.- Normalizing the NEW strings currently passed to `make-obsolete' and
> `make-obsolete-variable'.
>  4.- Remove the obsolescence information from `move-to-column-force's
> docstring and fixing its make-obsolete declaration.
> 
> It is OK to proceed?

Sounds just fine to me.  You might want to check what the byte compiler
does with the obsolescence info, just to make sure that your fix doesn't
make the byte-compiler warnings less correct.


	Stefan

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

On Tue, 25 Jun 2002 10:20:07 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> Sounds just fine to me.  You might want to check what the byte compiler
> does with the obsolescence info, just to make sure that your fix doesn't
> make the byte-compiler warnings less correct.

Well, there's an example of output:

c:/usr/wrk/pru.el: In toplevel form
c:/usr/wrk/pru.el:1:7: warning: inhibit-local-variables is an obsolete variable since before 19.15; Use enable-local-variables (with the reversed sense).
c:/usr/wrk/pru.el:1:7: warning: assignment to free variable inhibit-local-variables
c:/usr/wrk/pru.el:2:7: warning: auto-fill-hook is an obsolete variable since before 19.15; use auto-fill-function instead.
c:/usr/wrk/pru.el:2:7: warning: assignment to free variable auto-fill-hook
c:/usr/wrk/pru.el:3:2: warning: frame-update-faces is an obsolete function since 21.1; No longer necessary.
c:/usr/wrk/pru.el:4:2: warning: dot-marker is an obsolete function since before 19.15; use point-marker instead.
Wrote c:/usr/wrk/pru.elc

where `inhibit-local-variable' and `frame-update-faces' have been
capitalized, while `auto-fill-hook' and `dot-marker' are not (they have
no NEW string, only a symbol).

So, obviously, either the strings are un-capitalized and
describe-variable and describe-function's new functionality is somewhat
fixed, or they are capitalized and byte-compile-obsolete is modified to
put a dot instead of a semicolon, or whatever is deemed appropriate.

Suggestions?

                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

I've commited the patch to `describe-function' (`describe-function-1',
really) to show obsolescence information like `describe-variable' does
now.

Still, any kind of decision is needed about the issue of formatting of
the documentation. Currently there's a mismatch between the describe-*
functions and `byte-compile-obsolete'. The three of them write an
obsolete message and then the NEW info (NEW as in the argument to
`make-obsolete' and `make-obsolete-variable', I mean). But the
describe-* functions do it after a full stop, while `byte-compile-obsolete'
does it after a semicolon.

Example output from `describe-variable':

> post-command-idle-delay's value is 100000
> 
> Documentation:
> This variable is obsolete since before 19.34.
> use timers instead, with `run-with-idle-timer'.
> Delay time before running `post-command-idle-hook'.
> This is measured in microseconds.

Example output from `byte-compile-obsolete':

> c:/usr/wrk/pru.el: In toplevel form
> c:/usr/wrk/pru.el:1:7: warning: post-command-idle-delay is an obsolete variable since before 19.34; use timers instead, with `run-with-idle-timer'.

I think the best answer would be to put all obsolete info
non-capitalized and then make the describe-* functions capitalize it on
the fly.

Opinions?


                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Stefan Monnier]

> `make-obsolete' and `make-obsolete-variable', I mean). But the
> describe-* functions do it after a full stop, while `byte-compile-obsolete'
> does it after a semicolon.

Why not change the describe-* functions to also use a semi-colon ?


	Stefan

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

On Thu, 27 Jun 2002 10:24:01 -0400, "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

> Why not change the describe-* functions to also use a semi-colon ?

Because I'm deeply idiot, that's why. :(

I've followed your suggestion, which really simplifies things.

I've had to normalize a few obsolescence declarations, and in two or
three cases I've taken the liberty of removing redundant obsolescence
info from docstrings when the same or equivalent info is already in the
`make-obsolete*' declaration; now that the info is also shown it makes
no sense to say the same thing twice in a row.

Anyway, I'd be grateful if a native English- or Emacs- speaker checks
the changes I've done :)

I haven't touched the docstring of `font-lock-defaults-alist' because I
find it confusing:

> font-lock-defaults-alist's value is shown below.
> 
> Documentation:
> This variable is obsolete; 
> use `font-lock-defaults' instead.
> Alist of fall-back Font Lock defaults for major modes.
> 
> This variable should not be used any more.
> Set the buffer-local `font-lock-keywords' in the major mode instead.
> [...]

The `make-obsolete-variable' declaration says to use `font-lock-defaults',
and the docstring says to use `font-lock-keywords'. Perhaps the
docstring should be reworked somehow (and the bit about "should not be
used anymore" removed, I suppose).

Only vaguely related: with the recent font-lock hoopla `Info-fontify'
has been deleted. Wouldn't have been more logical to
`make-obsolete-variable' it?

                                                           /L/e/k/t/u

Re: Lowercase text after full stop on describe-variable

[Stefan Monnier]

> The `make-obsolete-variable' declaration says to use `font-lock-defaults',
> and the docstring says to use `font-lock-keywords'. Perhaps the

Yes.  I'm an idiot.  The docstring should also refer to `font-lock-defaults'.
(font-lock-keywords is set via font-lock-defaults or font-lock-defaults-alist)


	Stefan

Re: Lowercase text after full stop on describe-variable

[Colin Walters]

On Thu, 2002-06-27 at 12:27, Juanma Barranquero wrote:

> Only vaguely related: with the recent font-lock hoopla `Info-fontify'
> has been deleted. Wouldn't have been more logical to
> `make-obsolete-variable' it?

There was no sane way to support both it and font-lock, and I doubt most
users had changed it from its default value anyways.

Re: Lowercase text after full stop on describe-variable

[Juanma Barranquero]

On 27 Jun 2002 15:14:20 -0400, Colin Walters <walters@verbum.org> wrote:

> There was no sane way to support both it and font-lock, and I doubt most
> users had changed it from its default value anyways.

Ok, now I understand. Thanks,


                                                           /L/e/k/t/u