From: Eli Zaretskii <eliz@gnu.org>
To: "H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de>,
Stefan Monnier <monnier@iro.umontreal.ca>
Cc: 60587@debbugs.gnu.org
Subject: bug#60587: Patch for adding links to symbols' help documentation
Date: Sat, 07 Jan 2023 09:38:28 +0200 [thread overview]
Message-ID: <83h6x2u74b.fsf@gnu.org> (raw)
In-Reply-To: <86tu13qydg.fsf@duenenhof-wilhelm.de> (dieter@duenenhof-wilhelm.de)
> From: "H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de>
> Date: Fri, 06 Jan 2023 20:03:23 +0100
>
> I attached a patch for the current master branch build from git
> format-patch. And spliced the code to implement the linking of symbols
> in info manuals to the help documentation into lisp/info-xref.el.
Thanks.
I think this should be in info.el, or maybe in a separate
info-SOMETHING.el file. info-xref.el is for a certain job, of
interest primarily to Emacs maintainers, that is different from this
one, and I'm not sure conflating them is TRT.
More specific comments below.
> +;; This library provides links of symbols (functions, variables,
The "This library" part is a remnant of the previous life of this
code, and should be reworded to refer to specific command(s).
> +;; In any case all symbol names must be known to Emacs, i.e. their
> +;; names are found in the variable `obarray'.
I think a more useful way of saying this is
In any case, the symbol must be known to Emacs, which means it is
either a built-in, or its Lisp package is loaded in the current
Emacs session, or the symbol is auto-loaded.
> +;; Inform is checking if the Info documents are relevant Elisp and
^^^^^^
This should be adapted to the "new life" of Inform as part of Emacs.
> +;; Emacs related files to avoid false positives. Please see the
> +;; customization variable `inform-none-emacs-or-elisp-documents'.
^^^^^^
And this.
> +;;; Change Log:
> +
> +;; 1.3:
> +
> +;; Inform is checking if the Info documents are relevant Elisp and
> +;; Emacs related files to avoid false positives.
> +
> +;; 1.2:
> +
> +;; Link Elisp descriptions of symbols to their help documentation,
> +;; like the following function example: -- Function: eval form
> +
> +;; Distinguish color of texinfo links (`link' type) and Help links
> +;; (`font-lock-function-name-face')
Not sure if it makes sense to keep this change log.
> +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> +;; Does the following belong to customize.el?
> +
> +;; Generalise linking to "customization buffers" for the "easy
> +;; customization" info documentation see also the customization
> +;; section in the elisp manual
> +
> +;; - distinguish the Customization-links from Help- and Info-links
> +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
> +
> +;;; Ideas:
> +
> +;; Link the help buffers back to higher level info manual subjects,
> +;; similar to help-fns+.el from Drew Adams.
> +
> +;; Twice clicking or RETurning removes *Help* buffer (idea: Drew
> +;; Adams)
> +
> +;; Different colors for different symbol types (idea: Drew Adams) see
> +;; package helpful and info+ / info-colors on Melpa and see
> +;; font-lock.el for common faces.
> +
> +;; - Do we need to indicate an already visited Help link with a
> +;; different color?
> +
> +;; - Would it be be good to overtake all colors of package
> +;; "info-colors"?
> +
> +;; - Do we need to distinguish the link FONTS? No, difficult to read!
> +
> +;; Back / Forward button in help buffer - back to info buffer or
> +;; remain in help mode?
> +
> +;; Linking of standard symbol properties?
> +
> +;; - (info "(elisp) Standard Properties")
> +
> +;; Elisp manual examples:
> +;; (symbol-name 'car) ... ?
> +
> +;; Shortening the verbose texinfo URLs? But how to handle the changed
> +;; indentation?
> +
> +;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Please review this part and decide which portions should be kept,
perhaps after a suitable rewording, and which should be removed.
> +(require 'button)
> +(require 'cl-lib)
> +(require 'help-mode) ;redundant?
If this is added to an existing file, there should be a ^L and some
heading-style command before it.
> +;; activate inform without manually loading it. Is there a better way?
> +;; ;;;###autoload (require 'info-xref)
>
> +;; this is spawning lisp/info-xref.el's definition to 'info! This
> +;; group is sorted now in 'docs and 'info! -FIXME-
Comments should start with a capital letter.
> +;;;###autoload
> +(defcustom info-xref-make-xref-flag t
> + "Non-nil means create symbol links in info buffers."
> + :type '(choice (const :tag "Create links" t)
> + (const :tag "Do not link" nil))
> + :group 'info-xref)
I think we frown on autoloading defcustoms.
Also, every new defcustom should have a :version tag.
> +;; Info-director-list must be initialised
^^^^^^^^
Typo. Also, comments should be complete sentences, and end with a
period (here and elsewhere in the patch).
> +(info-initialize)
Why do you need to call this? and why on top level?
> +;; Turn into regexp list necessary? Stefan
> +;; Switch to alist with explanation of file name?
> +(defcustom info-xref-none-emacs-or-elisp-documents
> + '("aarm2012" ; Stefan: Ada manual, Elpa archive
> + "arm2012" ; Stefan: Ada manual
> + "sicp" ; T.V: Structure and Interpretation of Computer Programs,
> + ; Melpa archive
> + )
> + "List of all none GNU-Emacs or Elisp documentation.
> +Or other documents not to be checked for linking to their help
> +documentation. The list must contains only the base name of the
> +files (without their file name extension \".info\")."
> + :type '(repeat string)
> + :group 'info-xref)
Not sure what is this about, and what do the names above signify.
There are also typos: "none GNU-Emacs", "must contains".
> +(defun Info-xref-make-xrefs (&optional buffer)
> + "Parse and hyperlink documentation cross-references in the given BUFFER.
The doc string should tell what happens if BUFFER is omitted or nil.
> + (while (re-search-forward Info-xref-symbol-regexp nil t)
> + (let* ((data (match-string 8))
> + (sym (intern-soft data)))
> + (if sym
> + (cond
> + ((match-string 3) ; `variable' &c
> + (and (or (boundp sym) ; `variable' doesn't ensure
> + ; it's actually bound
> + (get sym 'variable-documentation))
> + (Info-xref-button 8 'Info-xref-variable sym)))
> + ((match-string 4) ; `function' &c
> + (and (fboundp sym) ; similarly
> + (Info-xref-button 8 'Info-xref-function sym)))
> + ((match-string 5) ; `face'
> + (and (facep sym)
> + (Info-xref-button 8 'Info-xref-face sym)))
> + ((match-string 6)) ; nothing for `symbol'
> + ((match-string 7)
> + (Info-xref-button 8 'Info-xref-function-def sym))
> + ((cl-some (lambda (x) (funcall (nth 1 x) sym))
> + describe-symbol-backends)
> + (Info-xref-button 8 'Info-xref-symbol sym)))))))
Can this be rewritten so as to avoid the need for error-prone updates
of the sub-expression numbers every time Info-xref-symbol-regexp is
modified?
Finally, this needs additions to the user manual and NEWS.
next prev parent reply other threads:[~2023-01-07 7:38 UTC|newest]
Thread overview: 58+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-05 23:47 bug#60587: 30.0.50; Info pages are lacking links from symbol names to the symbol's help documentation H. Dieter Wilhelm
2023-01-06 19:03 ` bug#60587: Patch for adding links to symbols' " H. Dieter Wilhelm
2023-01-07 7:38 ` Eli Zaretskii [this message]
2023-01-08 20:06 ` H. Dieter Wilhelm
2023-01-09 12:46 ` Eli Zaretskii
2023-01-09 14:25 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-09 20:01 ` H. Dieter Wilhelm
2023-01-13 23:33 ` H. Dieter Wilhelm
2023-01-14 7:12 ` Eli Zaretskii
2023-01-15 12:48 ` H. Dieter Wilhelm
2023-01-17 21:53 ` H. Dieter Wilhelm
2023-01-18 13:20 ` Eli Zaretskii
2023-01-20 21:09 ` H. Dieter Wilhelm
2023-01-20 21:59 ` Drew Adams
2023-01-20 23:32 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-22 13:00 ` H. Dieter Wilhelm
2023-01-21 8:21 ` Eli Zaretskii
2023-01-21 20:27 ` H. Dieter Wilhelm
2023-01-22 6:00 ` Eli Zaretskii
2023-01-22 22:09 ` Drew Adams
2023-01-23 12:14 ` Eli Zaretskii
2023-01-23 16:16 ` Drew Adams
2023-01-25 21:29 ` H. Dieter Wilhelm
2023-01-25 22:24 ` Drew Adams
2023-01-26 10:29 ` Ihor Radchenko
2023-01-26 15:06 ` Drew Adams
2023-01-26 15:12 ` Ihor Radchenko
2023-01-26 15:23 ` Drew Adams
2023-01-27 21:35 ` H. Dieter Wilhelm
2023-01-27 22:12 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-01-27 23:09 ` Drew Adams
2023-01-27 23:13 ` Drew Adams
2023-01-28 8:11 ` Eli Zaretskii
2023-01-28 17:30 ` Drew Adams
2023-02-01 22:09 ` H. Dieter Wilhelm
2023-02-02 2:30 ` Drew Adams
2023-02-05 0:48 ` H. Dieter Wilhelm
2023-02-05 3:54 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-02-05 13:54 ` H. Dieter Wilhelm
2023-02-06 21:04 ` H. Dieter Wilhelm
2023-02-12 11:04 ` H. Dieter Wilhelm
2023-02-14 20:56 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-02-15 22:18 ` H. Dieter Wilhelm
2023-02-16 3:08 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-02-20 23:53 ` H. Dieter Wilhelm
2023-02-21 2:12 ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2023-03-01 21:45 ` H. Dieter Wilhelm
2023-03-11 8:32 ` Eli Zaretskii
2023-03-11 9:16 ` H. Dieter Wilhelm
2023-02-15 5:17 ` Richard Stallman
2023-02-15 9:53 ` Gregory Heytings
2023-02-15 13:42 ` Gregory Heytings
2023-01-26 10:37 ` Eli Zaretskii
2023-01-27 7:45 ` Juri Linkov
2023-01-27 8:11 ` Eli Zaretskii
2023-01-27 22:21 ` H. Dieter Wilhelm
2023-01-28 7:51 ` Eli Zaretskii
2023-02-01 21:26 ` H. Dieter Wilhelm
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=83h6x2u74b.fsf@gnu.org \
--to=eliz@gnu.org \
--cc=60587@debbugs.gnu.org \
--cc=dieter@duenenhof-wilhelm.de \
--cc=monnier@iro.umontreal.ca \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.