bug#60587: Patch for adding links to symbols' help documentation

[Eli Zaretskii <eliz@gnu.org>]

> From: "H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de>
> Cc: monnier@iro.umontreal.ca,  60587@debbugs.gnu.org
> Date: Wed, 25 Jan 2023 22:29:31 +0100
> 
> > So I guess you will be submitting a new patch soon?
> 
> Below it is (based on a recent master commit).
> 
> > I think the first sentence should be rewritten as describing a
> > separate feature, not "the same as" something else.  Just say that
> > symbols are converted into buttons that lead to their doc strings.
> >
> > Also, the option which controls this should be mentioned and indexed.
> 
> Please have a look at a further documentation patch.

Thanks.

Juri, any comments?

> +  In Info buffers quoted symbol names are made into buttons which show
> +the symbols' help documentation when typing @key{RET} or clicking
> +@kbd{mouse-2} or @kbd{mouse-1} on it.  For example, the quoted name
> +@code{info-other-window} is made into a button which shows the
> +function's documentation string in another window, in the
> +@file{*Help*} buffer.  Such quoted symbols (variables, functions and
> +face names) are highlighted by a distinct face and can be reached, as
> +the Info manual references, with @key{TAB} and @kbd{S-Tab}.

This is fine, but please try to reword to not use the passive tense so
much.

> +;; The code below provides links of symbols (functions, variables, and
> +;; faces) within Emacs' Info viewer to their builtin help
> +;; documentation.  This linking is done when symbol names in texinfo
> +;; documentation (like the Emacs- and Elisp manual) are:
> +
> +;; 1. Quoted symbol names like `quoted-symbol' or:

You seem to have lost that ", or" in the rest of the items:

> +;; 2. Function names which are prefixed by M-x, for example M-x
> +;; function-name or are quoted and prefixed, like `M-x function-name'.
> +
> +;; 3. Function names appearing behind the following forms, which
> +;; occur, for example, in the Elisp manual:
> +
> +;;   -- Special Form: function-name
> +;;   -- Command: ...
> +;;   -- Function: ...
> +;;   -- Macro: ...
> +
> +;; 4. And variables names behind the following text:
> +
> +;;   -- User Option: variable-name
> +;;   -- Variable: ...

> +(defun info-check-docu-p ()
> +  "Check if the current info file is relevant to Emacs or Elisp.
> +That means `Info-current-file' is either found in Emacs' info/
> +directory or in `package-user-dir' and is not included in the
> +`info-none-emacs-or-elisp-documents' list."
> +  (unless info-emacs-info-dir-content
> +    (info-compile-emacs-info-dir-content))
> +  (let* ((ifile Info-current-file)
> +         (ifi (when ifile
> +                (file-name-sans-extension
> +                 (file-name-nondirectory ifile))))
> +         (pdir (when (boundp 'package-user-dir)
> +                 (expand-file-name
> +                  package-user-dir)))
> +         ;; Check if checking pdir is redundant because Package adds
> +         ;; info package folders to Info-directory-list anyway?
> +         (ifiles info-emacs-info-dir-content)
> +         (ndocu info-none-emacs-or-elisp-documents)
> +         (is-info (and ifile
> +                       (or (assoc-string (concat ifi ".info") ifiles)
> +                           ;; the top info "dir" file
> +                           (assoc-string (concat ifi ".info.gz") ifiles)
> +                           ;; info files might be archived!
> +                           (when pdir (string-match pdir ifile)))
> +                       (not (assoc-string ifi ndocu)))))

This should probably be extended to allow more extensions; see
Info-suffix-list.

> +(defface info-color
> +  '((t (:inherit font-lock-doc-face

Why not inherit from the 'link' face?

> +(defvar-keymap info-button-map
> +  :doc "Keymap used by buttons in Info buffers."
> +  "RET" #'push-button
> +  "<mouse-2>" #'push-button
> +  "<follow-link>" 'mouse-face
> +  ;; FIXME: You'd think that for keymaps coming from text-properties on the
> +  ;; mode-line or header-line, the `mode-line' or `header-line' prefix
> +  ;; shouldn't be necessary!
> +  "<mode-line> <mouse-2>" #'push-button
> +  "<header-line> <mouse-2>" #'push-button)

Is this FXIME important enough to leave in the final version?

> +(defun info-compile-emacs-info-dir-content ()
> +  "Build a list of file names from Emacs' info directories.
> +This function fills `info-emacs-info-dir-content' with files from
> +`Info-directory-list'."
> +  (setq info-emacs-info-dir-content
> +        (mapcar 'file-name-nondirectory ;'file-name-sans-extension

The comment should be removed, yes?

> +(defun info-button (match-number type &rest args)
> +  "Make a hyperlink for cross-reference text previously matched.
> +MATCH-NUMBER is the subexpression of interest in the last matched
> +regexp.  TYPE is the type of button to use.  Any remaining arguments are
> +passed to the button's info-function when it is invoked.
> +See `info-make-xrefs' Don't forget ARGS."
                       ^^^
A period is missing there.

> +  ;; Don't munge properties we've added, especially in some instances.
> +  (unless (button-at (match-beginning match-number))
> +    ;; (message "Creating button: %s." args)
> +    (make-text-button (match-beginning match-number)
> +                      (match-end match-number)
> +                      'type type 'info-args args)))

The "message" call in the comment should be removed.

> +
> +(defvar info-symbol-context
> +  '(( variable . "variable\\|option")
> +    ( function . "function\\|command\\|call")
> +    ( face . "face")
> +    ( ignore . "symbol\\|program\\|property")

Extra whitespace after an opening parenthesis.

> +    ;; ignore symbols following this context type
> +    ( definition . "source \\(?:code \\)?\\(?:of\\|for\\)"))
> +  ;; function definitions in files

These comments should be moved to _before_ the lines on which they
comment.

> +(defun info-make-xrefs (&optional buffer)
> +  "Parse and hyperlink documentation cross-references in the given BUFFER.
> +Find cross-reference information in a buffer and activate such
> +cross references for selection with `help-follow'.  The current
> +buffer is processed if the BUFFER argument is omitted.

Our style for the last sentence is

  BUFFER defaults to the current buffer if omitted or nil.

I'd also move it to be the second sentence of the doc string.

> +Function names are also detected when prefixed by `M-x`, for
> +example `M-x function-name` or are quoted and prefixed like `M-x
> +function-name`.

Please quote in doc strings `like this', not `like this`.  The latter
is not supported by the Emacs Help features.