From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: "H. Dieter Wilhelm" Newsgroups: gmane.emacs.bugs Subject: bug#60587: Patch for adding links to symbols' help documentation Date: Fri, 27 Jan 2023 23:21:12 +0100 Message-ID: <86edrfobzb.fsf@duenenhof-wilhelm.de> References: <86y1qgr1bf.fsf@duenenhof-wilhelm.de> <86tu13qydg.fsf@duenenhof-wilhelm.de> <83h6x2u74b.fsf@gnu.org> <863588rfos.fsf@duenenhof-wilhelm.de> <83o7qw0yjy.fsf@gnu.org> <864jskx6a8.fsf@duenenhof-wilhelm.de> <831qnomh6l.fsf@gnu.org> <86wn5anw04.fsf@duenenhof-wilhelm.de> <83cz71eg4y.fsf@gnu.org> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="3615"; mail-complaints-to="usenet@ciao.gmane.io" User-Agent: Gnus/5.13 (Gnus v5.13) Cc: 60587@debbugs.gnu.org, monnier@iro.umontreal.ca, Juri Linkov To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Fri Jan 27 23:22:12 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 1pLX6p-0000mf-Er for geb-bug-gnu-emacs@m.gmane-mx.org; Fri, 27 Jan 2023 23:22:11 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pLX6i-00051N-Da; Fri, 27 Jan 2023 17:22:04 -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 1pLX6g-00050x-QE for bug-gnu-emacs@gnu.org; Fri, 27 Jan 2023 17:22: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 1pLX6g-0003pq-II for bug-gnu-emacs@gnu.org; Fri, 27 Jan 2023 17:22:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pLX6g-0000tU-Do for bug-gnu-emacs@gnu.org; Fri, 27 Jan 2023 17:22:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: "H. Dieter Wilhelm" Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Fri, 27 Jan 2023 22:22:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60587 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60587-submit@debbugs.gnu.org id=B60587.16748580883393 (code B ref 60587); Fri, 27 Jan 2023 22:22:02 +0000 Original-Received: (at 60587) by debbugs.gnu.org; 27 Jan 2023 22:21:28 +0000 Original-Received: from localhost ([127.0.0.1]:38844 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pLX67-0000se-Re for submit@debbugs.gnu.org; Fri, 27 Jan 2023 17:21:28 -0500 Original-Received: from mout.kundenserver.de ([217.72.192.75]:42707) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pLX65-0000sP-Jx for 60587@debbugs.gnu.org; Fri, 27 Jan 2023 17:21:26 -0500 Original-Received: from ping ([109.250.147.186]) by mrelayeu.kundenserver.de (mreue106 [212.227.15.183]) with ESMTPSA (Nemesis) id 1My3Mv-1oSKjm1VQV-00zaYJ; Fri, 27 Jan 2023 23:21:13 +0100 In-Reply-To: <83cz71eg4y.fsf@gnu.org> (Eli Zaretskii's message of "Thu, 26 Jan 2023 12:37:01 +0200") X-Provags-ID: V03:K1:qlqNp7gx9+6vVIsJ/NQDo2oGfVos3k5RyMZpL1GGAZoZXIGZhQt /khK/zjTXlVuwvLRTd7wgFGJZLQwstqcWARC18f393Fbtx24DQkGfANLlLEGyMsZH1CQzqd HP6ozyAJKkA9M2O82JDZG6PW0NQRBgabyPbrV+x+8Du4JIgFRBFKDoHdNv3hxDf8OIPGEUC clA2oR2xWGNJ68KLqUnEg== UI-OutboundReport: notjunk:1;M01:P0:FkAlTsQXj/U=;EbT+88AZsWfeY0E11JQVujJKZNM wXgKJsXi3jM6QnBkyw39X2mOkxO+Bqcqn9LilIQMNC+BE5z+byGdPZpmjPwGV70DIst7akD9L SkgWPXkK1NgKtQQ8CChQA6NOOn4/Z/AT1gMPlOFA63TEw/8e284xjcvetkGxRwX+VEetCN1Qa ilzQn+ZX4M5RwRBBBFKr7BKhuVYKiYBYezKASEdbhWIQXfrdooE/TaqfbAwOyEH+M9WeNCS92 mKwgqS6sDDvdXzT+4Mx8sI53TR8e8ZrN3a/g3NpapETaLAwL1ztqWCI4FHmbE01qzzZPmSy0E h6XrwmTzuQYToSynLCorpjV9WFLex5SaczMHZhqXKyjk258JzR1oPdcholutWJH2eqLC4MWnF pN7itfHYEU+KWilvmakE6Qn0SM5Ac0vW4uiPVA65YHF/CKgBSY9YjAH1qHmPL04RJ9EOqO7Wx E3iz4gPs79Ikb+yaWjAjlxRtp+ixV/Nq9Z1L8UgE21H3+OmR1fUl9SpBiYHPFwDPODYEE3ZMW WUod3ESB6Iys6XQ3KT97qAIYACgR9loRSERP7xwj6gh3yPuhh5H5U/+F+dwFsVCXGj+YHNNST e3np44IJ4Pv6AesklthnxMLzhHzhhVPAqzXya8W3HXsLwxCRYTyOskLJYYDQe5GCYWZwNHTGx VyQ8P5rWDhLa6G2odaObHJwfv4CO1z/eDlDaZ/LfIQ== 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:254279 Archived-At: Thank you for your help. Eli Zaretskii writes: >> + 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. What do you think about the following formulation, is it already a better "mix"? Info makes quoted symbol names 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. Info highlights such quoted symbols (variables, functions and face names) by a distinct face and these can be reached, as regular Info manual references, with @key{TAB} and @kbd{S-Tab}. Drew reminded me that it should be better to write solely @kbd{mouse-2} and / or possibly explaining `mouse-1-click-follows-link'. I'm curious about your opinion. >> +;; 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: I wanted to express: ;; 1. Quoted symbol names like `quoted-symbol' or 2. (below). ;; 2. Function names which are prefixed by M-x, for example M-x But you're right, since we are already in a numbered list, I dropped the redundant phrase: ;; 1. Quoted symbol names like `quoted-symbol'. ;; 2. Function names which are prefixed by M-x, for example M-x >> + (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. Thanks for hinting at Info-suffix-list. I'll try to accommodate the other suffices in the code and will send another iteration of info.el patches. >> +(defface info-color >> + '((t (:inherit font-lock-doc-face > > Why not inherit from the 'link' face? I wanted a different face compared to the regular Info links. Because they are acting differently! But yesterday I realised that Info distinguishes (slightly) already quoted symbols from the regular text. I dropped now the info-color face because the user can sufficiently distinguish between text, buttons and Info links. >> +(defvar-keymap info-button-map >> + :doc "Keymap used by buttons in Info buffers." >> + "RET" #'push-button >> + "" #'push-button >> + "" '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! >> + " " #'push-button >> + " " #'push-button) > > Is this FXIME important enough to leave in the final version? I really don't know, just copied the complete keymap code from button.el. (The comment is gone now.) >> +(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? Yes, it's gone. >> +(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. Yes, a period and a whitespace ;-) >> + ;; 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. Yes, I removed it now. >> + >> +(defvar info-symbol-context >> + '(( variable . "variable\\|option") >> + ( function . "function\\|command\\|call") >> + ( face . "face") >> + ( ignore . "symbol\\|program\\|property") > > Extra whitespace after an opening parenthesis. Indeed, marked the whitespace column and C-x r t >> + ;; ignore symbols following this context type >> + ( definition . "source \\(?:code \\)?\\(?:of\\|for\\)")) >> + ;; function definitions in files (changed also (definition ..) ) > These comments should be moved to _before_ the lines on which they > comment. Makes sense to be consistent =F0=9F=98=85, improved that part. >> +(defun info-make-xrefs (&optional buffer) >> + "Parse and hyperlink documentation cross-references in the given BUFF= ER. >> +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. I see, changed it in that way. >> +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. I'm sorry, when writing that piece I had Emacs wrongly configured duplicating every ``' and didn't discern the difference. ("Back" back quotes are gone now.) --=20 Best wishes H. Dieter Wilhelm Zwingenberg, Germany