Re: mentioning variable aliases in `describe-variable'

[John Paul Wallington]

> 
> > I think it would be nice to mention when a variable is an alias in
> > `describe-variable'.  What do people think ?
> 
> Go for it, although I'd personally put the info near the
> first line (as is done for function aliases) rather than near
> the bottom.

I like your suggestion.  How about this:

*** help-fns.el 27 Jun 2002 16:10:23 -0000      1.12
--- help-fns.el 12 Jul 2002 00:10:52 -0000
***************
*** 426,431 ****
--- 426,439 ----
                (save-excursion
                  (forward-line -1)
                  (insert "Automatically becomes buffer-local when set in any 
fashion.\n"))))
+           ;; mention if it's an alias
+           (let ((alias (condition-case nil
+                            (indirect-variable variable)
+                          (error variable))))
+             (unless (eq alias variable)
+               (princ (format "This variable is an alias for `%s'." alias))
+               (terpri)
+               (terpri)))
            (princ "Documentation:")
            (terpri)
            (let ((obsolete (get variable 'byte-obsolete-variable)))


It could go underneath the Documentation heading, and it could omit an
alias explictly mentioned in the obsolescence note.  Which is what I
did initially; I was keen on it for twenty minutes or so but rejected
it because alias nature isn't really documentation and
`describe-variable' should spell things out rather than silently omit
information.  I thought I would include it so that someone could
reassure me it is wrong :-)

*** help-fns.el 27 Jun 2002 16:10:23 -0000      1.12
--- help-fns.el 11 Jul 2002 23:34:02 -0000
***************
*** 435,444 ****
                (princ "; ") (terpri)
                (princ (if (stringp (car obsolete)) (car obsolete)
                         (format "use `%s' instead." (car obsolete))))
!               (terpri)))
            (let ((doc (documentation-property variable 
'variable-documentation)))
              (princ (or doc "Not documented as a variable.")))
!         
            ;; Make a link to customize if this variable can be customized.
            ;; Note, it is not reliable to test only for a custom-type property
            ;; because those are only present after the var's definition
--- 435,453 ----
                (princ "; ") (terpri)
                (princ (if (stringp (car obsolete)) (car obsolete)
                         (format "use `%s' instead." (car obsolete))))
!               (terpri))
!             ;; mention if it's an alias, unless the variable it is an alias
!             ;; for is already mentioned in the obsolescence note
!             (let ((alias (condition-case nil
!                              (indirect-variable variable)
!                            (error variable))))
!               (unless (or (eq alias variable)
!                           (eq alias (car obsolete)))
!                 (princ (format "This variable is an alias for `%s'." alias))
!                 (terpri))))
            (let ((doc (documentation-property variable 
'variable-documentation)))
              (princ (or doc "Not documented as a variable.")))
! 
            ;; Make a link to customize if this variable can be customized.
            ;; Note, it is not reliable to test only for a custom-type property
            ;; because those are only present after the var's definition


-- 
John Paul Wallington