unofficial mirror of emacs-devel@gnu.org 
 help / color / mirror / code / Atom feed
From: Drew Adams <drew.adams@oracle.com>
To: Lars Ingebrigtsen <larsi@gnus.org>, Dmitry Gutov <dgutov@yandex.ru>
Cc: "laszlomail@protonmail.com" <laszlomail@protonmail.com>,
	Eli Zaretskii <eliz@gnu.org>,
	"emacs-devel@gnu.org" <emacs-devel@gnu.org>
Subject: RE: [External] : Re: Would you say this information window is well designed?
Date: Mon, 22 Feb 2021 22:30:12 +0000	[thread overview]
Message-ID: <SA2PR10MB44740945641DD91E4E6CE67DF3819@SA2PR10MB4474.namprd10.prod.outlook.com> (raw)
In-Reply-To: <87im6jepft.fsf@gnus.org>

> I think linking to the manual (as much as practically possible) from
> *Help* is a good idea.  However, `info-lookup-symbol' (the innards of
> which we basically have to call) is a bit on the slow side.

I don't find it slow.  And it can be invoked only
when a user clicks (or uses RET) on a link.

I do that (in help-fns+.el) when the only manuals
to be searched are Emacs and Elisp.

This is the logic I use, FWIW:

,----
| Info-make-manuals-xref is a Lisp function in 'help-fns+.el'.
| 
| (Info-make-manuals-xref OBJECT &optional NO-NEWLINES-AFTER-P
| MANUALS-SPEC NOMSG)
| 
| For more information see the manuals.
| 
| Create a cross-ref link for entries for OBJECT in manuals.
| Non-`nil' optional arg NO-NEWLINES-AFTER-P means do not add two
| newlines after the cross reference.
| 
| Optional arg MANUALS-SPEC controls which manuals to search.  It has
| the same form as option `help-cross-reference-manuals', and it
| defaults to the value of that option.
| 
| Do nothing if the car of MANUALS-SPEC is nil (no manuals to search).
| 
| Otherwise, there are 3 cases:
| 
| 1. The cdr is `nil' and the car has the two manuals "emacs" and
|    "elisp", and only these (this is the default).
| 
|    Create the link without first searching any manuals.  Clicking the
|    link uses `help-lookup-symbol'.
| 
| 2. The cdr is `nil' and the car does not have just those two manuals.
| 
|    Create the link without first searching any manuals.  Clicking the
|    link then searches the manuals.
| 
| 3. The cdr is non-`nil'.
| 
|    Create the link only if there are search hits in the manuals.
|    This takes time.
| 
| In cases #1 and #2, clicking the link might find that there are no
| search hits in the manuals.  In case #3, if there is a link then it is
| sure to lead to hits.
| 
| In cases #2 and #3, clicking the link brings up an Info index buffer
| for the manuals with hits.  In case #1, clicking the link takes you
| directly to a hit in one of the manuals, Emacs or Elisp.
| 
| Cases #1 and #2 create the `*Help'* buffer quickly.  Case #3 takes
| time to create it - possibly considerable time.
`----

User option `help-cross-reference-manuals':

,----
| help-cross-reference-manuals is a variable defined in `help-fns+.el'.
| Its value is (("emacs" "elisp"))
| 
| Documentation:
| Manuals to search, for a `*Help*' buffer link to the manuals.
| The default value is (("emacs" "elisp")).  Clicking the
| cross-reference link in `*Help*' uses `info-lookup-symbol' to take you
| directly to the relevant doc in the Emacs or Elisp manual.  This is
| very quick.
| 
| Any other value means that clicking the link searches the indexes of
| the specified manuals and then opens an Info Index buffer with links
| to the relevant manuals.  This can take a while, and if there are no
| matches then the `*info*' buffer shown is empty.  The advantage of
| this approach is that you can get to a hit in more than one manual.
| 
| The option value is a cons: (MANUALS . SEARCH-FIRST).
| 
|  MANUALS is the list of manuals to search, or the symbol `all', to
|   search all.  If `nil' then do not create a cross-reference link.
| 
|  SEARCH-FIRST is a Boolean value.  If MANUALS specifies other than
|  just the Emacs and Elisp manuals (both) then:
| 
|   * `nil' SEARCH-FIRST means create a cross-reference link
|     immediately, whether or not there are actually any matches.
| 
|   * Non-`nil' SEARCH-FIRST means search the indexes, and create a link
|     only if there are matches.  The indexes are thus searched before
|     populating buffer `*Help*', which takes time.  You probably do not
|     want to use this possibility.
| 
| You can customize this variable.
| 
| For more information see the manuals.
`----



  reply	other threads:[~2021-02-22 22:30 UTC|newest]

Thread overview: 32+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2021-02-22 18:37 Would you say this information window is well designed? Peter Dean
2021-02-22 18:48 ` Eli Zaretskii
2021-02-22 19:23   ` Dmitry Gutov
2021-02-22 19:28     ` Eli Zaretskii
2021-02-22 20:28       ` Joost Kremers
2021-02-22 21:49       ` Dmitry Gutov
2021-02-22 21:57         ` Lars Ingebrigtsen
2021-02-22 22:30           ` Drew Adams [this message]
2021-02-23  0:45             ` [External] : " Stefan Kangas
2021-02-23  5:34               ` Drew Adams
2021-02-23  5:46                 ` Drew Adams
2021-02-23  5:54                 ` Peter Dean
2021-02-23 15:22                   ` Eli Zaretskii
2021-02-23 15:29                     ` Peter Dean
2021-02-23 16:00                       ` Eli Zaretskii
2021-02-23 17:32                         ` Peter Dean
2021-02-23 17:40                           ` Eli Zaretskii
2021-02-23 17:59                             ` Peter Dean
2021-02-23 18:26                               ` Eli Zaretskii
2021-02-23 19:36                                 ` Peter Dean
2021-02-23 19:46                                   ` Eli Zaretskii
2021-02-23 21:58                                     ` Peter Dean
2021-02-24  3:25                                       ` Eli Zaretskii
2021-02-27 21:44                                 ` Dmitry Gutov
2021-02-28 17:32                                   ` Eli Zaretskii
2021-03-01  5:22                                     ` Richard Stallman
2021-02-23  5:44               ` Drew Adams
2021-02-23 14:18               ` Lars Ingebrigtsen
2021-02-23 15:44                 ` Drew Adams
2021-02-23 16:15                   ` Stefan Kangas
2021-02-23 16:28                     ` Drew Adams
2021-02-22 21:19 ` Stefan Kangas

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

  List information: https://www.gnu.org/software/emacs/

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=SA2PR10MB44740945641DD91E4E6CE67DF3819@SA2PR10MB4474.namprd10.prod.outlook.com \
    --to=drew.adams@oracle.com \
    --cc=dgutov@yandex.ru \
    --cc=eliz@gnu.org \
    --cc=emacs-devel@gnu.org \
    --cc=larsi@gnus.org \
    --cc=laszlomail@protonmail.com \
    /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 public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).