GNU bug report logs - #79350
[PATCH] Update shortdoc hash-table and sequence

Previous Next

To reply to this bug, email your comments to 79350 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Gabriel do Nascimento Ribeiro <gabriel376 <at> hotmail.com>
To: "bug-gnu-emacs <at> gnu.org" <bug-gnu-emacs <at> gnu.org>
Subject: [PATCH] Update shortdoc hash-table and sequence
Date: Sat, 30 Aug 2025 19:26:09 +0000

The patch below adds more functions to shortdoc and info:

- info hash-table:
  - hash-table-keys
  - hash-table-values
  - hash-table-empty-p

- shortdoc hash-table:
  - hash-table-empty-p
  - hash-table-keys
  - hash-table-values
  - hash-table-test
  - hash-table-weakness

- shortdoc sequence
  - seq-let

It also makes the info buffer display in the same window when pushing shortdoc
buttons, which I think is a better behavior than the one that currently displays
the info buffer in another widow and does not make it selected.


From 803583c20cfa726488ce40e7365eca4311a1d4ef Mon Sep 17 00:00:00 2001
From: Gabriel Ribeiro <gabriel376 <at> hotmail.com>
Date: Sat, 30 Aug 2025 16:13:33 -0300
Subject: [PATCH] Add more functions to shortdoc hash-table and sequence

* doc/lispref/hash.texi: Add 'hash-table-keys', 'hash-table-values'
  and 'hash-table-empty-p'.
* lisp/emacs-lisp/shortdoc.el
  (define-short-documentation-group hash-table): Add
  'hash-table-empty-p', 'hash-table-keys', 'hash-table-values',
  'hash-table-test', 'hash-table-weakness'.
  (define-short-documentation-group sequence): Add 'seq-let'.
  (hash-table-weakness): Display info buffer in same window.
---
 doc/lispref/hash.texi       | 12 ++++++++++++
 lisp/emacs-lisp/shortdoc.el | 21 +++++++++++++++++++--
 2 files changed, 31 insertions(+), 2 deletions(-)

diff --git a/doc/lispref/hash.texi b/doc/lispref/hash.texi
index 56862a9d934..1660c209435 100644
--- a/doc/lispref/hash.texi
+++ b/doc/lispref/hash.texi
@@ -343,6 +343,18 @@ Other Hash
 itself is copied---the keys and values are shared.
 @end defun
 
+@defun hash-table-keys table
+This function returns the list of keys in @var{table}.
+@end defun
+
+@defun hash-table-values table
+This function returns the list of values in @var{table}.
+@end defun
+
+@defun hash-table-empty-p table
+This function non-@code{nil} if @var{table} contains any entries..
+@end defun
+
 @defun hash-table-count table
 This function returns the actual number of entries in @var{table}.
 @end defun
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 754b2016d9e..697e2a51642 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -717,7 +717,22 @@ hash-table
    :result-string "#s(hash-table ...)")
   (hash-table-count
    :no-eval (hash-table-count table)
-   :eg-result 15))
+   :eg-result 15)
+  (hash-table-empty-p
+   :no-eval (hash-table-empty-p table)
+   :eg-result t)
+  (hash-table-keys
+   :no-eval (hash-table-keys table)
+   :eg-result-string "(key1 key2 ...)")
+  (hash-table-values
+   :no-eval (hash-table-values table)
+   :eg-result-string "(value1 value2 ...)")
+  (hash-table-test
+   :no-eval (hash-table-test table)
+   :eg-result eql)
+  (hash-table-weakness
+   :no-eval (hash-table-weakness table)
+   :eg-result key-and-value))
 
 (define-short-documentation-group list
   "Making Lists"
@@ -1124,6 +1139,8 @@ sequence
    :eval (seq-sort #'> '(1 2 3)))
   (seq-sort-by
    :eval (seq-sort-by (lambda (a) (/ 1.0 a)) #'< '(1 2 3)))
+  (seq-let
+    :eval (seq-let (a b c) '(1 2 3) (+ a b c)))
   "Mapping Over Sequences"
   (seq-map
    :eval (seq-map #'1+ '(1 2 3)))
@@ -1689,7 +1706,7 @@ shortdoc--display-function
        (symbol-name function)
        'face 'button
        'action (lambda (_)
-                 (info-lookup-symbol function 'emacs-lisp-mode))
+                 (info-lookup-symbol function 'emacs-lisp-mode t))
        'follow-link t
        'help-echo "mouse-1, RET: show \
 function's documentation in the Info manual"))
-- 
2.34.1


---
Gabriel

Message #8 received at 79350 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Gabriel do Nascimento Ribeiro <gabriel376 <at> hotmail.com>
Cc: 79350 <at> debbugs.gnu.org
Subject: Re: bug#79350: [PATCH] Update shortdoc hash-table and sequence
Date: Sun, 31 Aug 2025 08:04:42 +0300

> From: Gabriel do Nascimento Ribeiro <gabriel376 <at> hotmail.com>
> Date: Sat, 30 Aug 2025 19:26:09 +0000
> msip_labels: 
> 
> The patch below adds more functions to shortdoc and info:
> 
> - info hash-table:
>   - hash-table-keys
>   - hash-table-values
>   - hash-table-empty-p
> 
> - shortdoc hash-table:
>   - hash-table-empty-p
>   - hash-table-keys
>   - hash-table-values
>   - hash-table-test
>   - hash-table-weakness
> 
> - shortdoc sequence
>   - seq-let

Thanks, but what is the rationale for adding these functions to the
ELisp manual?  I could maybe understand why we should add
hash-table-empty-p, but why the other two?  They are in subr-x.el for
a reason.  Are they important enough to be in the manual?

In any case, these are defsubst's, not defun's, so the manual should
not call them "functions".

> It also makes the info buffer display in the same window when pushing shortdoc
> buttons, which I think is a better behavior than the one that currently displays
> the info buffer in another widow and does not make it selected.

This is a change in behavior, and I personally would not like it.  It
is customary in Emacs to show help in another window by default,
because that leaves the buffer where you invoked the help command
displayed, in case the user wants to continue working on that buffer
or reading its text.  So if we want to allow such a behavior, it
should be opt-in, not the default.

(In general, independent changes are better submitted as separate bug
reports.  This report should have been split into 2 or 3 separate
ones.  Please keep this in mind in the future.)

> * doc/lispref/hash.texi: Add 'hash-table-keys', 'hash-table-values'
>   and 'hash-table-empty-p'.
> * lisp/emacs-lisp/shortdoc.el
>   (define-short-documentation-group hash-table): Add
>   'hash-table-empty-p', 'hash-table-keys', 'hash-table-values',
>   'hash-table-test', 'hash-table-weakness'.
>   (define-short-documentation-group sequence): Add 'seq-let'.
>   (hash-table-weakness): Display info buffer in same window.

A minor nit: the second and following lines of a log entry should be
flushed all the way to the left, like this:

* doc/lispref/hash.texi: Add 'hash-table-keys', 'hash-table-values'
and 'hash-table-empty-p'.
* lisp/emacs-lisp/shortdoc.el
(define-short-documentation-group hash-table): Add
'hash-table-empty-p', 'hash-table-keys', 'hash-table-values',
'hash-table-test', 'hash-table-weakness'.
(define-short-documentation-group sequence): Add 'seq-let'.
(hash-table-weakness): Display info buffer in same window.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.