Manual does not mention dictionary.el

Manual does not mention dictionary.el

[Petteri Hintsanen]

I was wondering if Emacs could do dictionary look-ups.

After failed search through the manual (for "dictionary") I resorted to
a web search.  It quickly showed that Emacs has included dictionary.el
since version 28 or so.

Why this extremely useful feature is not mentioned in the manual at all?
Or did I just miss it somehow?

-- 
Petteri

Re: Manual does not mention dictionary.el

[Divya]

[-- Attachment #1: Type: text/plain, Size: 815 bytes --]

On 11 October 2024 20:13:44 GMT, Petteri Hintsanen <petterih@iki.fi> wrote:
>I was wondering if Emacs could do dictionary look-ups.
>
>After failed search through the manual (for "dictionary") I resorted to
>a web search.  It quickly showed that Emacs has included dictionary.el
>since version 28 or so.
>
>Why this extremely useful feature is not mentioned in the manual at all?
>Or did I just miss it somehow?
>
>-- 
>Petteri
>

Hello Petteri,

Now that I realize I've been using dictionary in Emacs for years and thinking that I learnt about it from the manual when I actually got it from one of the blogposts I think.

I agree. It is crucial to include documentation about dictionary, I'd be willing to be of help if needed.

Regards,

Divya Ranjan
Mathematics, Philosophy, Libre Software

[-- Attachment #2: Type: text/html, Size: 1147 bytes --]

Re: Manual does not mention dictionary.el

[Juergen Fenn]

Am 11.10.24 um 23:35 Uhr schrieb Divya:
> Now that I realize I've been using dictionary in Emacs for years and
> thinking that I learnt about it from the manual when I actually got it
> from one of the blogposts I think.
>
> I agree. It is crucial to include documentation about dictionary, I'd be
> willing to be of help if needed.

All I've learned about dictionary.el came from Mickey Peterson's blog
(please note that the certificate for his website expired two days ago).
We could invite him to write the section for the manual! But I'd also be
happy to help out.

BTW, there also is an extension I've found rather helpful on macOS, viz.

https://github.com/xuchunyang/osx-dictionary.el

which enables the built-in dictionaries and thesauri in macOS (from
Oxford, Webster, Larousse, Duden, etc.).

Best regards,
Jürgen.

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: Petteri Hintsanen <petterih@iki.fi>
> Date: Fri, 11 Oct 2024 23:13:44 +0300
> 
> I was wondering if Emacs could do dictionary look-ups.
> 
> After failed search through the manual (for "dictionary") I resorted to
> a web search.  It quickly showed that Emacs has included dictionary.el
> since version 28 or so.
> 
> Why this extremely useful feature is not mentioned in the manual at all?
> Or did I just miss it somehow?

We don't describe in the manual every feature we add to Emacs; we
describe that in NEWS instead.  The Emacs manual is already very
large, so we add new features to it only of they are very important.

I've now added to the manual a short description of the dictionary
search facility.

Thanks.

Re: Manual does not mention dictionary.el

[Petteri Hintsanen]

Eli Zaretskii <eliz@gnu.org> writes:

> We don't describe in the manual every feature we add to Emacs; we
> describe that in NEWS instead.  The Emacs manual is already very
> large, so we add new features to it only of they are very important.

Fair enough.  I'll try to remember check NEWS next time.

> I've now added to the manual a short description of the dictionary
> search facility.

Thanks.

-- 
Petteri

Re: Manual does not mention dictionary.el

[chad]

[-- Attachment #1: Type: text/plain, Size: 666 bytes --]

On Sat, Oct 12, 2024 at 5:40 AM Petteri Hintsanen <petterih@iki.fi> wrote:

> Fair enough.  I'll try to remember check NEWS next time.
>

FWIW, when I saw your initial post I immediately checked "C-h P dict"
and found it. This UI could probably use some help, and it has been
discussed in the past, but discovery is a non-trivial problem for
roughly everyone (examples: elpa/melpa, Doom, VS Code, both Apple and
Google's app stores, roughly every version of Windows since NT,
etc.). I didn't post this earlier because your OP seemed reasonably
clearly directed at the manual, but I do find it helpful in similar
situations.

Hope that helps,
~Chad

[-- Attachment #2: Type: text/html, Size: 1064 bytes --]

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: chad <yandros@gmail.com>
> Date: Sat, 12 Oct 2024 14:23:01 -0400
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> 
> On Sat, Oct 12, 2024 at 5:40 AM Petteri Hintsanen <petterih@iki.fi> wrote:
> 
>  Fair enough.  I'll try to remember check NEWS next time.
> 
> FWIW, when I saw your initial post I immediately checked "C-h P dict"
> and found it. This UI could probably use some help, and it has been
> discussed in the past, but discovery is a non-trivial problem for
> roughly everyone (examples: elpa/melpa, Doom, VS Code, both Apple and
> Google's app stores, roughly every version of Windows since NT,
> etc.). I didn't post this earlier because your OP seemed reasonably
> clearly directed at the manual, but I do find it helpful in similar
> situations.

Discovery is a hard problem in a package as large as Emacs.  I very
much doubt that adding a passage to the user manual makes discovery
easier.  In fact, I think NEWS is much more visible than addition of a
paragraph somewhere in the manual.

As for "C-h P": I don't know what you found there, since dictionary.el
is part of Emacs, so package.el doesn't know about it.  "C-h P dict"
finds dict-tree for me, which is something different.  I guess you
have "C-h P" bound to some other command than in "emacs -Q".

Re: Manual does not mention dictionary.el

[Joost Kremers]

On Sat, Oct 12 2024, Eli Zaretskii wrote:
> As for "C-h P": I don't know what you found there, since dictionary.el
> is part of Emacs, so package.el doesn't know about it.  "C-h P dict"
> finds dict-tree for me, which is something different.  I guess you
> have "C-h P" bound to some other command than in "emacs -Q".

When I do `C-h P` and type "dict" followed BY TAB, I get:

==============================
Click on a completion to select it.
In this buffer, type RET to select the completion near point.

3 possible completions:
dict-tree
dictionary
dictionary-connection
==============================

That's with `emacs -Q`, v. 29.4. 🙂

-- 
Joost Kremers
Life has its moments

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: chad <yandros@gmail.com>,  petterih@iki.fi,  emacs-devel@gnu.org
> Date: Sat, 12 Oct 2024 23:59:11 +0200
> 
> On Sat, Oct 12 2024, Eli Zaretskii wrote:
> > As for "C-h P": I don't know what you found there, since dictionary.el
> > is part of Emacs, so package.el doesn't know about it.  "C-h P dict"
> > finds dict-tree for me, which is something different.  I guess you
> > have "C-h P" bound to some other command than in "emacs -Q".
> 
> When I do `C-h P` and type "dict" followed BY TAB, I get:
> 
> ==============================
> Click on a completion to select it.
> In this buffer, type RET to select the completion near point.
> 
> 3 possible completions:
> dict-tree
> dictionary
> dictionary-connection
> ==============================

Look under your ~/.emacs.d/elpa/ to find out why.  Or point HOME to
some other directory and try again.  Chrystal ball says you have this
cached from some MELPA access, because currently dictionary is neither
on GNU ELPA nor on NonGNU ELPA.

In a really pristine installation with an empty ~/.emacs.d/, if you
type "C-h P dict TAB", you should get "No match", I think.  I got
dict-tree because that's the only one on GNU ELPA, and I have some
cache from the last time I did "M-x list-packages".

Re: Manual does not mention dictionary.el

[chad]

[-- Attachment #1.1: Type: text/plain, Size: 1419 bytes --]

On Sun, Oct 13, 2024 at 1:12 AM Eli Zaretskii <eliz@gnu.org> wrote:

> In a really pristine installation with an empty ~/.emacs.d/, if you
> type "C-h P dict TAB", you should get "No match", I think.


I did it in a clean installation, using emacs -Q with no .emacs{,.d}
present. It completes to "dictionary", and stops because it also
knows about "dictionary-connection". Afterwards, the only thing in
.emacs.d is the eln-cache directory created by emacs -Q.

If I repeat this with C-h P di TAB, I get:

[image: image.png]

FWIW, going back to "what it does", from that same emacs -Q,
I see:

>Package dictionary is built-in.
>
>     Status: Built-In.
>    Summary: Client for rfc2229 dictionary servers
>
>dictionary allows you to interact with dictionary servers.
>
>Use `M-x customize-group RET dictionary RET' to modify user settings.
>
>Main commands for interaction are:
>`M-x dictionary'        - open a new dictionary buffer
>`M-x dictionary-search' - search for the definition of a word
>
>You can find more information in the README file of the GitHub
>repository https://github.com/myrkr/dictionary-el
>
>[back]

..which is the (expected) Commentary section of lisp/net/dictionary.el

This is from a recent HEAD build, but I get the same with a prebuilt
binary of 30.0.90 under win11 (although it's harder for me to be sure
that I passed '-Q' correctly).

~Chad

[-- Attachment #1.2: Type: text/html, Size: 2232 bytes --]

[-- Attachment #2: image.png --]
[-- Type: image/png, Size: 29472 bytes --]

Re: Manual does not mention dictionary.el

[Joost Kremers]

On Sun, Oct 13 2024, chad wrote:
> On Sun, Oct 13, 2024 at 1:12 AM Eli Zaretskii <eliz@gnu.org> wrote:
>
>> In a really pristine installation with an empty ~/.emacs.d/, if you
>> type "C-h P dict TAB", you should get "No match", I think.
>
>
> I did it in a clean installation, using emacs -Q with no .emacs{,.d}
> present. It completes to "dictionary", and stops because it also
> knows about "dictionary-connection".

Yes, I did something similar: move my .emacs.d out of the way, start with
emacs -Q, type C-h P followed by "dict" and return. I get a window with two
options: dictionary and dictionary-connection.

I mean, it makes sense that package.el knows about built-in packages,
because they are included in the list when you do 'M-x list-packages'. 

It's interesting to know, though, that there is still some interaction with
.emacs.d, even when you start Emacs with the -Q switch. I didn't know that.

-- 
Joost Kremers
Life has its moments

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: Joost Kremers <joostkremers@fastmail.fm>
> Cc: Eli Zaretskii <eliz@gnu.org>,  petterih@iki.fi,  emacs-devel@gnu.org
> Date: Mon, 14 Oct 2024 09:11:57 +0200
> 
> I mean, it makes sense that package.el knows about built-in packages,
> because they are included in the list when you do 'M-x list-packages'. 

Not here, they don't.  And that's neither on GNU/Linux nor on
MS-Windows.

> It's interesting to know, though, that there is still some interaction with
> .emacs.d, even when you start Emacs with the -Q switch. I didn't know that.

The -Q switch doesn't block access to your home directory.  Its
purpose is something else.

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: chad <yandros@gmail.com>
> Date: Sun, 13 Oct 2024 21:39:31 -0400
> Cc: Joost Kremers <joostkremers@fastmail.fm>, petterih@iki.fi, emacs-devel@gnu.org
> 
> ..which is the (expected) Commentary section of lisp/net/dictionary.el
> 
> This is from a recent HEAD build, but I get the same with a prebuilt
> binary of 30.0.90 under win11 (although it's harder for me to be sure
> that I passed '-Q' correctly).

Not sure what happens here, but I get different results on GNU/Linux
and on Windows, so I will be looking into this.  On Windows, without
~/.emacs.d/elpa/ I get [No match].  Sounds like a bug.

Also, list-packages doesn't show 'dictionary', neither on MS-Windows
nor on GNU/Linux, at least in "emacs -Q".  If it does for you, I'm
guessing you have stuff under ~/.emacs.d/elpa/.

Re: Manual does not mention dictionary.el

[chad]

[-- Attachment #1: Type: text/plain, Size: 1554 bytes --]

On Mon, Oct 14, 2024 at 9:50 AM Eli Zaretskii <eliz@gnu.org> wrote:

> > From: chad <yandros@gmail.com>
> > Date: Sun, 13 Oct 2024 21:39:31 -0400
> > Cc: Joost Kremers <joostkremers@fastmail.fm>, petterih@iki.fi,
> emacs-devel@gnu.org
> >
> > ..which is the (expected) Commentary section of lisp/net/dictionary.el
> >
> > This is from a recent HEAD build, but I get the same with a prebuilt
> > binary of 30.0.90 under win11 (although it's harder for me to be sure
> > that I passed '-Q' correctly).
>
> Also, list-packages doesn't show 'dictionary', neither on MS-Windows
> nor on GNU/Linux, at least in "emacs -Q".  If it does for you, I'm
> guessing you have stuff under ~/.emacs.d/elpa/.
>

We are seeing different behavior.

I get completions for both dictionary and dictionary-connection with
literally no
.emacs, .emacs.d. I also get it with a newly created user with nothing
related
to emacs in $HOME or env. I also get the same result under win11, although
my confidence that the environment there is "poisoned" is much lower.

I just repeated this again with a blank user/environment and the invocation:
  $ /opt/emacs/bin/emacs-31.0.50 -q --no-site-file --no-site-lisp
In the resulting emacs, there is no elpa directory of .emacs.d either before
or after 'C-h P dict TAB RET' brings up the *Help* buffer with the package
commentary from the built-in lisp/net/dictionary.el, and after that emacs is
closed, there is still only an eln-cache directory in it's just-created
.emacs.d.

Hope this helps,
~Chad

[-- Attachment #2: Type: text/html, Size: 2381 bytes --]

Re: Manual does not mention dictionary.el

[Michael Heerdegen via Emacs development discussions.]

chad <yandros@gmail.com> writes:

> > Also, list-packages doesn't show 'dictionary', neither on MS-Windows
> > nor on GNU/Linux, at least in "emacs -Q".  If it does for you, I'm
> > guessing you have stuff under ~/.emacs.d/elpa/.
>
> We are seeing different behavior.

I see that lisp/finder-inf.el defines 'dictionary' as a built-in package
in my Emacs installation.  This file is loaded when doing C-h P.  It
directly sets `package--builtins'.

Maybe that file's contents differ for you and Eli?


Michael.

Re: Manual does not mention dictionary.el

[chad]

[-- Attachment #1: Type: text/plain, Size: 755 bytes --]

On Mon, Oct 14, 2024 at 8:46 PM Michael Heerdegen via Emacs development
discussions.

> > We are seeing different behavior.
>
> I see that lisp/finder-inf.el defines 'dictionary' as a built-in package
> in my Emacs installation.  This file is loaded when doing C-h P.  It
> directly sets `package--builtins'.
>
> Maybe that file's contents differ for you and Eli?
>

Yep, good spot!

On both my regular linux laptop (with frequently rebuilt head) and on
a borrowed win11 install of emacs 30, I see lines in finder-inf.el for
both dictionary and dictionary-connection. Tracing through the
function finder-compile-keywords in finder.el, I suspect that *maybe*
this is an artifact of Eli running directly out of the build tree?

~Chad

[-- Attachment #2: Type: text/html, Size: 1133 bytes --]

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> From: chad <yandros@gmail.com>
> Date: Tue, 15 Oct 2024 01:30:19 -0400
> Cc: emacs-devel@gnu.org
> 
>  I see that lisp/finder-inf.el defines 'dictionary' as a built-in package
>  in my Emacs installation.  This file is loaded when doing C-h P.  It
>  directly sets `package--builtins'.
> 
>  Maybe that file's contents differ for you and Eli?
> 
> Yep, good spot!
> 
> On both my regular linux laptop (with frequently rebuilt head) and on
> a borrowed win11 install of emacs 30, I see lines in finder-inf.el for
> both dictionary and dictionary-connection. Tracing through the
> function finder-compile-keywords in finder.el, I suspect that *maybe*
> this is an artifact of Eli running directly out of the build tree?

No, I almost never build out of the tree.

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> Date: Tue, 15 Oct 2024 02:46:28 +0200
> From:  Michael Heerdegen via "Emacs development discussions." <emacs-devel@gnu.org>
> 
> chad <yandros@gmail.com> writes:
> 
> > > Also, list-packages doesn't show 'dictionary', neither on MS-Windows
> > > nor on GNU/Linux, at least in "emacs -Q".  If it does for you, I'm
> > > guessing you have stuff under ~/.emacs.d/elpa/.
> >
> > We are seeing different behavior.
> 
> I see that lisp/finder-inf.el defines 'dictionary' as a built-in package
> in my Emacs installation.  This file is loaded when doing C-h P.  It
> directly sets `package--builtins'.
> 
> Maybe that file's contents differ for you and Eli?

Indeed, my finder-inf.el was very old.  It doesn't get rebuilt unless
you explicitly request that or bootstrap (and I _never_ bootstrap).

Re: Manual does not mention dictionary.el

[Petteri Hintsanen]

On 12.10.2024 21.23, chad wrote:

> On Sat, Oct 12, 2024 at 5:40 AM Petteri Hintsanen <petterih@iki.fi 
> <mailto:petterih@iki.fi>> wrote:
> 
>     Fair enough.  I'll try to remember check NEWS next time.
> 
> 
> FWIW, when I saw your initial post I immediately checked "C-h P dict"
> and found it. 

C-h P is news for me, thanks.

> but discovery is a non-trivial problem for roughly everyone

It is, like data management in general.

For me, manuals (texinfo, man pages) are "the" definitive source for 
information about the installed features.  Occasionally I use C-h a too, 
as it often catches things that are not mentioned in manuals.

In this case M-x apropos RET dict RET gives meaningful results, so maybe 
I forgot to try it or did something equivalently stupid.

Anyway, I'll keep NEWS and C-h P in my mind.
Thanks.

Re: Manual does not mention dictionary.el

[Eli Zaretskii]

> Date: Sat, 23 Nov 2024 15:13:43 +0200
> Cc: Eli Zaretskii <eliz@gnu.org>, emacs-devel@gnu.org
> From: Petteri Hintsanen <petterih@iki.fi>
> 
> C-h P is news for me, thanks.
> 
> > but discovery is a non-trivial problem for roughly everyone
> 
> It is, like data management in general.
> 
> For me, manuals (texinfo, man pages) are "the" definitive source for 
> information about the installed features.  Occasionally I use C-h a too, 
> as it often catches things that are not mentioned in manuals.

This is not the best practice for Emacs.  The Emacs manuals don't
mention all the features, simply because there are too many of them,
and mentioning them all will make the manuals impractically large.

By contrast, the built-in Help commands will return information about
all the features that are either already loaded or auto-loaded.