From: Joost Kremers <joostkremers@fastmail.com>
Date: Mon, 14 Oct 2024 11:10:57 +0000 (+0200)
Subject: Update vtable documentation
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=3f6fa6e746823e0f2c291811bed19290df5279f2;p=emacs.git

Update vtable documentation

* doc/misc/vtable.texi: Document creation of empty vtables.
* etc/NEWS: Announce empty vtables.  (Bug#73775)

(cherry picked from commit ac91d190d623f6fef186b035373cdb72347cc99d)
---

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index 795d7fad037..b2ead47d0bc 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -264,6 +264,10 @@ In the latter case, if @code{:columns} is non-@code{nil} and there's
 more elements in the sequence than there is in @code{:columns}, only
 the @code{:columns} first elements are displayed.
 
+If the @code{:objects} list is empty (and no @code{:objects-function} is
+defined), an empty vtable is created.  In this case, a @code{:columns}
+spec must be provided.
+
 @item :objects-function
 It's often convenient to generate the objects dynamically (for
 instance, to make reversion work automatically).  In that case, this
@@ -295,6 +299,11 @@ The width of @var{n} @samp{x} characters in the table's face.
 @var{n} percent of the window's width.
 @end table
 
+If no @code{width} is provided, the width is calculated based on the
+column data (provided in the @code{:objects} list or through the
+@code{:objects-function}) or, if there is no data, on the basis of the
+window width.
+
 @item min-width
 This uses the same format as @code{width}, but specifies the minimum
 width (and overrides @code{width} if @code{width} is smaller than this.
@@ -576,6 +585,8 @@ index is out of range, @var{object} is prepended to @var{table} if the
 index is too small, or appended if it is too large.  In this case,
 @var{before} is ignored.
 
+If @var{table} is empty, @var{location} and @var{before} are ignored.
+
 This also updates the displayed table.
 @end defun
 
diff --git a/etc/NEWS b/etc/NEWS
index d087d4746af..73f29b8800d 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -725,6 +725,16 @@ This lets a Lisp program access the core functionality of the
 program, choosing the program according to the operating system's
 conventions.
 
++++
+** 'make-vtable' can create an empty vtable.
+It is now possible to create a vtable without data, by leaving the
+':objects' list empty, or by providing a ':objects-function' that
+(initially) produces no data.  In such a case, it is necessary to
+provide a ':columns' spec, so that the number of columns and their
+widths can be determined.  Columns widths can be set explicitly, or they
+will be calculated based on the window width.
+
+
 
 * Changes in Emacs 31.1 on Non-Free Operating Systems