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: Thu, 26 Jan 2023 12:37:01 +0200 Message-ID: <83cz71eg4y.fsf@gnu.org> 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> Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="40835"; mail-complaints-to="usenet@ciao.gmane.io" Cc: 60587@debbugs.gnu.org, monnier@iro.umontreal.ca To: "H. Dieter Wilhelm" , Juri Linkov Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Jan 26 11:37: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 1pKzd2-000APe-9M for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 26 Jan 2023 11:37:12 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pKzct-0006gS-OS; Thu, 26 Jan 2023 05:37:03 -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 1pKzcs-0006fe-DG for bug-gnu-emacs@gnu.org; Thu, 26 Jan 2023 05:37: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 1pKzcs-000225-5Q for bug-gnu-emacs@gnu.org; Thu, 26 Jan 2023 05:37:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pKzcr-0004Fc-MS for bug-gnu-emacs@gnu.org; Thu, 26 Jan 2023 05:37: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: Thu, 26 Jan 2023 10:37:01 +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.167472941816329 (code B ref 60587); Thu, 26 Jan 2023 10:37:01 +0000 Original-Received: (at 60587) by debbugs.gnu.org; 26 Jan 2023 10:36:58 +0000 Original-Received: from localhost ([127.0.0.1]:60844 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pKzcn-0004FI-Q2 for submit@debbugs.gnu.org; Thu, 26 Jan 2023 05:36:58 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:59956) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pKzck-0004F3-Fh for 60587@debbugs.gnu.org; Thu, 26 Jan 2023 05:36:56 -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 1pKzcd-0001xl-V3; Thu, 26 Jan 2023 05:36:47 -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=9HbhPW3iZoi8Y/UleOdLeWas1dv4cffM1eN1mskJuHk=; b=XzM5rk+xlFwL AxgnR7w2gT23/QjuOnX/b6VFoZrRtSvaC6THcM4ASwqJVyJITzcx1wvEPrgy1HSmW1Zbd2srrxj0s +rlVdWU6tsQYHsdzFJxysoHNzg/Jlb5GkhIgdm95R54UfbAJYGhz/w9IH9c0esU4o//ePPXqnQRYL ATaW6vGUmxdngz0IFqtJkh6E0HLbrbN1ZIDOyjWsumtLDSbrOeN3kl8vGmoCd84ra5lENA271z3LV Uc+J31iafPL9CLLho0zTVHjDoVXux5Gx6853mW48yLq6x/eXh8sLwjelZ8zdVTFqZ7huwYHEXzrxN 1YMtYd2lalq/ge93oyIcrw==; 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 1pKzcd-0006hK-EB; Thu, 26 Jan 2023 05:36:47 -0500 In-Reply-To: <86wn5anw04.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:254201 Archived-At: > From: "H. Dieter Wilhelm" > 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 > + "" #'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? > +(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.