From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.bugs Subject: bug#60587: Patch for adding links to symbols' help documentation Date: Sat, 07 Jan 2023 09:38:28 +0200 Message-ID: <83h6x2u74b.fsf@gnu.org> References: <86y1qgr1bf.fsf@duenenhof-wilhelm.de> <86tu13qydg.fsf@duenenhof-wilhelm.de> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="15323"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 60587@debbugs.gnu.org To: "H. Dieter Wilhelm" , Stefan Monnier Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Sat Jan 07 08:39:14 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1pE3nN-0003oM-1d for geb-bug-gnu-emacs@m.gmane-mx.org; Sat, 07 Jan 2023 08:39:13 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pE3nF-0000wS-6H; Sat, 07 Jan 2023 02:39:05 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pE3nC-0000wG-9M for bug-gnu-emacs@gnu.org; Sat, 07 Jan 2023 02:39:02 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pE3nC-0004IH-02 for bug-gnu-emacs@gnu.org; Sat, 07 Jan 2023 02:39:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pE3nB-0006d9-SK for bug-gnu-emacs@gnu.org; Sat, 07 Jan 2023 02:39:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Eli Zaretskii Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 07 Jan 2023 07:39:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60587 X-GNU-PR-Package: emacs Original-Received: via spool by 60587-submit@debbugs.gnu.org id=B60587.167307709925420 (code B ref 60587); Sat, 07 Jan 2023 07:39:01 +0000 Original-Received: (at 60587) by debbugs.gnu.org; 7 Jan 2023 07:38:19 +0000 Original-Received: from localhost ([127.0.0.1]:56381 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pE3mU-0006bv-Sg for submit@debbugs.gnu.org; Sat, 07 Jan 2023 02:38:19 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:42710) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pE3mS-0006bi-QH for 60587@debbugs.gnu.org; Sat, 07 Jan 2023 02:38:17 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pE3mM-00046M-Jg; Sat, 07 Jan 2023 02:38:10 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=References:Subject:In-Reply-To:To:From:Date: mime-version; bh=r6IKAMTILweRcSY3x0ec315NbzPXwK9hvsO0hiFT5YU=; b=VyCMZubEdiOV H9BL0pFCmoZIlIcOBDXQ0jW2TeB2/9YX4VvT+MssTdHXN3LEZI3T4qzl6wlmcXBsY+H3nZJdWDgqE IL1IrT88dmkgwe3+skJ27O2EvlrR4i1OWs9is6JyzYJCfRHBNNSRH/KY7LB3CaXSG83B8YEGdfF/0 qmHqkhHm6DUTo2NE39n5bPtVppQ3AcJAxEpGoWfgfSeEP+Zeyvqk0aEHFX9oikER8jtmAVC8akc5C zyNNeJyJGrhdckjHPHGAp5X6rDEUI9eagc8R0Fhxwdncz2YiSlCK08uLuIKpuZnZhXiLq6jjbnKA1 2y+dLW78XFMdKPHOsbAO8w==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1pE3mL-0000WE-Rn; Sat, 07 Jan 2023 02:38:10 -0500 In-Reply-To: <86tu13qydg.fsf@duenenhof-wilhelm.de> (dieter@duenenhof-wilhelm.de) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:252768 Archived-At: > From: "H. Dieter Wilhelm" > 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.