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

Previous Next

Full log

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.