GNU bug report logs - #21074
25.0.50; Incomplete docs for tabulated-list-mode

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 21074 in the body.
You can then email your comments to 21074 AT debbugs.gnu.org in the normal way.

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

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

From: Marcin Borkowski <mbork <at> mbork.pl>
To: bug-gnu-emacs <at> gnu.org
Subject: 25.0.50; Incomplete docs for tabulated-list-mode
Date: Thu, 16 Jul 2015 11:05:22 +0200

Hello,

I'd like to report a bug in the documentation: the functions
`tabulated-list-get-id' and `tabulated-list-get-entry' are not mentioned
in the manual (Emacs version info below).

In GNU Emacs 25.0.50.1 (i686-pc-linux-gnu, GTK+ Version 3.10.8)
 of 2015-01-02 on aga-netbook
Repository revision: 11ee7d8bf16b8ee4fcb3659e4b09686ed8b10590
Windowing system distributor `The X.Org Foundation', version 11.0.11501000
System Description:	Ubuntu 14.04.2 LTS

Best regards,

-- 
Marcin Borkowski
http://octd.wmi.amu.edu.pl/en/Marcin_Borkowski
Faculty of Mathematics and Computer Science
Adam Mickiewicz University

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

From: Alex Branham <alex.branham <at> gmail.com>
To: 21074 <at> debbugs.gnu.org
Subject: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 15 Jan 2019 12:19:13 -0600

[Message part 1 (text/plain, inline)]

Hello -

This patch adds documentation for tabulated-list-get-{id, entry} to
doc/lispref/modes.texi.

Thanks,
Alex

From 00a4e4ef99099d5c7f597a07c374a7e679cbe851 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Tue, 15 Jan 2019 12:15:44 -0600
Subject: [PATCH] Add documentation to lispref for two tabulated-list functions

* doc/lispref/modes.texi (Tabulated List Mode): Add documentation for
  functions 'tabulated-list-get-id' and 'tabulated-list-get-entry'.

Bug #21074
---
 doc/lispref/modes.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..219aa504f8 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,20 @@ Tabulated List Mode
 from entries that haven't changed (normally all tags are removed).
 @end defun

+@defun tabulated-list-get-id &optional pos
+This function returns the entry ID of the entry at @var{pos}, which
+defaults to point if omitted or @code{nil}.  This will be an ID object
+from @var{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This function returns the entry at @var{pos}, which defaults to point
+if omitted or @code{nil}.  This will be a vector for the ID at
+@var{pos} from @var{tabulated-list-entries}. If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
--
2.19.2

[0001-Add-documentation-to-lispref-for-two-tabulated-list-.patch (text/x-patch, inline)]

From 00a4e4ef99099d5c7f597a07c374a7e679cbe851 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Tue, 15 Jan 2019 12:15:44 -0600
Subject: [PATCH] Add documentation to lispref for two tabulated-list functions

* doc/lispref/modes.texi (Tabulated List Mode): Add documentation for
  functions 'tabulated-list-get-id' and 'tabulated-list-get-entry'.

Bug #21074
---
 doc/lispref/modes.texi | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..219aa504f8 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,20 @@ Tabulated List Mode
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-get-id &optional pos
+This function returns the entry ID of the entry at @var{pos}, which
+defaults to point if omitted or @code{nil}.  This will be an ID object
+from @var{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This function returns the entry at @var{pos}, which defaults to point
+if omitted or @code{nil}.  This will be a vector for the ID at
+@var{pos} from @var{tabulated-list-entries}. If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 15 Jan 2019 21:06:14 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Date: Tue, 15 Jan 2019 12:19:13 -0600
> 
> This patch adds documentation for tabulated-list-get-{id, entry} to
> doc/lispref/modes.texi.

Thanks, but what is the rationale for adding these two, specifically?

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 15 Jan 2019 13:41:28 -0600

[Message part 1 (text/plain, inline)]

On Tue 15 Jan 2019 at 13:06, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Alex Branham <alex.branham <at> gmail.com>
>> Date: Tue, 15 Jan 2019 12:19:13 -0600
>>
>> This patch adds documentation for tabulated-list-get-{id, entry} to
>> doc/lispref/modes.texi.
>
> Thanks, but what is the rationale for adding these two, specifically?

I was surprised to see they weren't in there the other day when I was
playing around with tabulated-list-mode. "How do I get the ID of the
entry at point" is a pretty common question, I'd guess. Since I saw this
bug on the bug tracker today I figured I'd submit a patch. If it doesn't
belong in the manual feel free to ignore the patch (but then this bug
should probably be closed).

Thanks,
Alex

[signature.asc (application/pgp-signature, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>, Marcin Borkowski <mbork <at> mbork.pl>
Cc: 21074 <at> debbugs.gnu.org
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Sat, 19 Jan 2019 10:25:13 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: 21074 <at> debbugs.gnu.org
> Date: Tue, 15 Jan 2019 13:41:28 -0600
> 
> On Tue 15 Jan 2019 at 13:06, Eli Zaretskii <eliz <at> gnu.org> wrote:
> 
> >> From: Alex Branham <alex.branham <at> gmail.com>
> >> Date: Tue, 15 Jan 2019 12:19:13 -0600
> >>
> >> This patch adds documentation for tabulated-list-get-{id, entry} to
> >> doc/lispref/modes.texi.
> >
> > Thanks, but what is the rationale for adding these two, specifically?
> 
> I was surprised to see they weren't in there the other day when I was
> playing around with tabulated-list-mode. "How do I get the ID of the
> entry at point" is a pretty common question, I'd guess. Since I saw this
> bug on the bug tracker today I figured I'd submit a patch. If it doesn't
> belong in the manual feel free to ignore the patch (but then this bug
> should probably be closed).

Ah, I wasn't aware there was a previous context for this bug.  (Please
in the future say something to put things in their context, otherwise
one needs to deduce from the bug number that it might have been
discussed previously, and go look up that discussion.  I usually just
ignore the bug number.)

After looking into this for some time, I think we should document
functions of tabulated-mode that are frequently used by its clients,
of which there are some in the Emacs tree.  The above 2 functions
aren't the only ones undocumented in the manual.  So either we
document them all, or we'd need more serious rationale for documenting
just those 2.  Would you like to see what other tabulated-mode
functions are candidates for addition to the manual?

In any case, a few minor comments for the patch:

> +@defun tabulated-list-get-id &optional pos

In the code, this is a defsubst, not a defun.

> +This function returns the entry ID of the entry at @var{pos},
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Just "... returns the ID of the entry" is more clear and concise.

> +                                                               which
> +defaults to point if omitted or @code{nil}.

This "which" makes the text ambiguous: it could refer to the ID or to
POS.  So I suggest to write a separate sentence:

  If omitted or @code{nil}, @var{pos} defaults to position of point.

> +                                             This will be an ID object
> +from @var{tabulated-list-entries}.

An element of tabulated-list-entries could be a function, and what
does this return in that case?  This should be spelled out in the
manual, otherwise the reader will be left out wondering.

> +@defun tabulated-list-get-entry &optional pos
> +This function returns the entry at @var{pos}, which defaults to point
> +if omitted or @code{nil}.  This will be a vector for the ID at
> +@var{pos} from @var{tabulated-list-entries}

This is not detailed enough.  E.g., it says nothing about what will be
the elements of the vector.  The doc string is more detailed, but it
is too terse, and the manual should expand on that.  The description
should also make clear what happens if the corresponding element of
tabulated-list-entries is a function.

> +                                            . If there is no entry at
                                               ^^
Two spaces between sentences, please.

Thanks.

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, Marcin Borkowski <mbork <at> mbork.pl>
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Mon, 21 Jan 2019 10:12:22 -0600

On Sat 19 Jan 2019 at 02:25, Eli Zaretskii <eliz <at> gnu.org> wrote:

> Ah, I wasn't aware there was a previous context for this bug.  (Please
> in the future say something to put things in their context, otherwise
> one needs to deduce from the bug number that it might have been
> discussed previously, and go look up that discussion.  I usually just
> ignore the bug number.)

Will do, sorry. I'm still trying to find a good way to interact with the
bugtracker.

> After looking into this for some time, I think we should document
> functions of tabulated-mode that are frequently used by its clients,
> of which there are some in the Emacs tree.  The above 2 functions
> aren't the only ones undocumented in the manual.  So either we
> document them all, or we'd need more serious rationale for documenting
> just those 2.  Would you like to see what other tabulated-mode
> functions are candidates for addition to the manual?

I'm not sure there's a great way to decide what needs documentation and
what doesn't. Glancing through the code in the Emacs tree, these are the
functions that seem to get used fairly often by modes that derive from
tabulated-list-mode:

- tabulated-list-delete-entry
- tabulated-list-get-entry
- tabulated-list-get-id
- tabulated-list-header-overlay-p
- tabulated-list-put-tag
- tabulated-list-set-col

So perhaps start with those?

I got the rest of your comments (thanks!) and will incorporate them into
a follow-up patch once we decide what exactly needs to get documented.

Alex

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Mon, 21 Jan 2019 18:32:50 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: Marcin Borkowski <mbork <at> mbork.pl>, 21074 <at> debbugs.gnu.org
> Date: Mon, 21 Jan 2019 10:12:22 -0600
> 
> I'm not sure there's a great way to decide what needs documentation and
> what doesn't. Glancing through the code in the Emacs tree, these are the
> functions that seem to get used fairly often by modes that derive from
> tabulated-list-mode:
> 
> - tabulated-list-delete-entry
> - tabulated-list-get-entry
> - tabulated-list-get-id
> - tabulated-list-header-overlay-p
> - tabulated-list-put-tag
> - tabulated-list-set-col
> 
> So perhaps start with those?

Yes, I think so.

> I got the rest of your comments (thanks!) and will incorporate them into
> a follow-up patch once we decide what exactly needs to get documented.

Thanks.

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, Marcin Borkowski <mbork <at> mbork.pl>
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 22 Jan 2019 15:03:41 -0600

[Message part 1 (text/plain, inline)]

Thanks Eli, I'm going through this now and just have a couple quick
questions about your comments:

On Sat 19 Jan 2019 at 02:25, Eli Zaretskii <eliz <at> gnu.org> wrote:

> In any case, a few minor comments for the patch:
>
>> +@defun tabulated-list-get-id &optional pos
>
> In the code, this is a defsubst, not a defun.

How do we document these in the elisp manual? I'm struggling to find an
example. Is it just:

@findex{tabulated-list-get-id}
tabulated-list-get-id &optional pod

This function returns...

?

>> +                                             This will be an ID object
>> +from @var{tabulated-list-entries}.
>
> An element of tabulated-list-entries could be a function, and what
> does this return in that case?  This should be spelled out in the
> manual, otherwise the reader will be left out wondering.

That's not my understanding. I think tabulated-list-entries can either
be a list with elements that look like (id col), or be a function that
returns that list. As I understand, elements of the list can't be
functions. If that's correct, I think it's clear enough that the ID of
the entry at point is determined by the function
'tabulated-list-entries' and we don't need to mention it (the wording
gets complicated). If you still want to add it, perhaps something like:

This will be an ID object from @var{tabulated-list-entries} or
calculated from that function if @var{tabulated-list-entries} is a
function.

What do you think?

Thanks,
Alex

[signature.asc (application/pgp-signature, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Fri, 01 Feb 2019 11:28:17 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: Marcin Borkowski <mbork <at> mbork.pl>, 21074 <at> debbugs.gnu.org
> Date: Tue, 22 Jan 2019 15:03:41 -0600
> 
> >> +@defun tabulated-list-get-id &optional pos
> >
> > In the code, this is a defsubst, not a defun.
> 
> How do we document these in the elisp manual? I'm struggling to find an
> example. Is it just:
> 
> @findex{tabulated-list-get-id}
> tabulated-list-get-id &optional pod
> 
> This function returns...
> 
> ?

I think just say in the description something like "This
@code{defsubst} returns...".

> 
> >> +                                             This will be an ID object
> >> +from @var{tabulated-list-entries}.
> >
> > An element of tabulated-list-entries could be a function, and what
> > does this return in that case?  This should be spelled out in the
> > manual, otherwise the reader will be left out wondering.
> 
> That's not my understanding. I think tabulated-list-entries can either
> be a list with elements that look like (id col), or be a function that
> returns that list. As I understand, elements of the list can't be
> functions. If that's correct, I think it's clear enough that the ID of
> the entry at point is determined by the function
> 'tabulated-list-entries' and we don't need to mention it (the wording
> gets complicated). If you still want to add it, perhaps something like:
> 
> This will be an ID object from @var{tabulated-list-entries} or
> calculated from that function if @var{tabulated-list-entries} is a
> function.

  This is the ID object from @code{tabulated-list-entries} (if that is
  a list) or from the list returned by @code{tabulated-list-entries}
  (if it is a function).

Note: @code, not @var, because tabulated-list-entries is a literal
symbol, not an argument of a function.

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Sat, 02 Feb 2019 10:03:31 -0600

[Message part 1 (text/plain, inline)]

On Fri 01 Feb 2019 at 03:28, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> From: Alex Branham <alex.branham <at> gmail.com>
>> Cc: Marcin Borkowski <mbork <at> mbork.pl>, 21074 <at> debbugs.gnu.org
>> Date: Tue, 22 Jan 2019 15:03:41 -0600
>>
>> >> +@defun tabulated-list-get-id &optional pos
>> >
>> > In the code, this is a defsubst, not a defun.
>>
>> How do we document these in the elisp manual? I'm struggling to find an
>> example. Is it just:
>>
>> @findex{tabulated-list-get-id}
>> tabulated-list-get-id &optional pod
>>
>> This function returns...
>>
>> ?
>
> I think just say in the description something like "This
> @code{defsubst} returns...".

>> This will be an ID object from @var{tabulated-list-entries} or
>> calculated from that function if @var{tabulated-list-entries} is a
>> function.
>
>   This is the ID object from @code{tabulated-list-entries} (if that is
>   a list) or from the list returned by @code{tabulated-list-entries}
>   (if it is a function).
>
> Note: @code, not @var, because tabulated-list-entries is a literal
> symbol, not an argument of a function.

Thanks. I think the attached patch incorporates all your comments, let
me know if I missed something.

Alex

[0001-Add-documentation-for-tabulated-list-functions-in-th.patch (text/x-patch, inline)]

From dcec7e84ccf9a612cfed6a9f607dc021eb964e1a Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Sat, 2 Feb 2019 09:59:21 -0600
Subject: [PATCH] Add documentation for tabulated-list functions in the elisp
 manual

* doc/lispref/modes.texi: Add documentation for
  'tabulated-list-delete-entry', 'tabulated-list-get-id',
  'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
  'tabulated-list-put-tag', and 'tabulated-list-set-col'.
---
 doc/lispref/modes.texi | 53 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 53 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..4635a5c6e4 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,59 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-delete-entry
+This function deletes the entry at point.
+
+It returns a list @code{(id cols)} where @var{id} is the ID of the
+delete entry and @var{cols} is a vector of its column descriptors.
+It moves point to the beginning of the deleted entry.  It returns
+@code{nil} if there is no entry at point.
+
+Note that this function only changes the buffer contents; it does not
+alter @code{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-id &optional pos
+This @code{defsubst} returns the ID object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  If
+omitted or @code{nil}, @var{pos} defaults to point.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This @code{defsubst} returns the entry object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  This
+will be a vector for the ID at @var{pos}.  If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  If omitted or @code{nil}, @var{pos} defaults to
+@code{point-min}.
+@end defun
+
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+@var{tag} should be a string, with a length less than or equal to
+@code{tabulated-list-padding}.  If @var{advance} is non-nil, this
+function advances point by one line.
+@end defun
+
+@defun tabulated-list-set-col col desc &optional change-entry-data
+This function changes the tabulated list entry at point, setting
+@var{col} to @var{desc}.  @var{col} is the column number to change, or
+the name of the column to change.  @var{desc} is the new column
+descriptor, which is inserted via @code{tabulated-list-print-col}.
+
+If @var{change-entry-data} is non-nil, this function modifies the
+underlying entry data by setting the appropriate slot of the vector
+originally used to print this entry.  If @code{tabulated-list-entries}
+has a list value, this is the vector stored within it.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Sat, 02 Feb 2019 18:33:01 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: mbork <at> mbork.pl, 21074 <at> debbugs.gnu.org
> Date: Sat, 02 Feb 2019 10:03:31 -0600
> 
> Thanks. I think the attached patch incorporates all your comments, let
> me know if I missed something.

Looks good.  A couple of minor gotchas, though.

> * doc/lispref/modes.texi: Add documentation for
>   'tabulated-list-delete-entry', 'tabulated-list-get-id',
>   'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
>   'tabulated-list-put-tag', and 'tabulated-list-set-col'.

This should mention the bug number.

> +@defun tabulated-list-delete-entry
> +This function deletes the entry at point.
> +
> +It returns a list @code{(id cols)} where @var{id} is the ID of the
                                     ^
A comma is missing there.

> +delete entry and @var{cols} is a vector of its column descriptors.
               ^
And here.

Also, the "id" and "cols" inside the list should also have the @var
markup.

> +It moves point to the beginning of the deleted entry.

The last sentence is confusing: if the entry is deleted, how can we
move to its beginning?

> +@defun tabulated-list-header-overlay-p &optional POS
> +This @code{defsubst} returns non-nil if there is a fake header at
> +@var{pos}.

We should explain, in a single sentence if possible, what is a "fake
header".  It is never explained in this section.

> +@defun tabulated-list-put-tag tag &optional advance
> +This function puts @var{tag} in the padding area of the current line.

And this should explain what is the padding area, for the same reason.

> +@var{tag} should be a string, with a length less than or equal to
> +@code{tabulated-list-padding}.

Every variable mentioned in the manual should be indexed.  So please
add

 @vindex tabulated-list-padding

before the @defun.

> +If @var{change-entry-data} is non-nil, this function modifies the
> +underlying entry data by setting the appropriate slot of the vector
> +originally used to print this entry.  If @code{tabulated-list-entries}
> +has a list value, this is the vector stored within it.

This paragraph is confusing, I cannot understand what that argument
does just by reading the above text.  (The doc string says the same,
so it's of no help.)  The confusing parts are "appropriate slot" and
"originally used to print".  The code simply modifies a component of
the vector returned by tabulated-list-get-entry, so I wonder why the
description needs to be that complicated.

Thanks again for working on this.

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Sat, 02 Feb 2019 11:28:56 -0600

[Message part 1 (text/plain, inline)]

On Sat 02 Feb 2019 at 10:33, Eli Zaretskii <eliz <at> gnu.org> wrote:

> This should mention the bug number.

Thanks, done

>> +@defun tabulated-list-delete-entry
>> +This function deletes the entry at point.
>> +
>> +It returns a list @code{(id cols)} where @var{id} is the ID of the
>                                      ^
> A comma is missing there.

Thanks, added.

>> +delete entry and @var{cols} is a vector of its column descriptors.
>                ^
> And here.

I don't think a comma is needed here. It's a list of two entries, not
three, so no comma, right?

> Also, the "id" and "cols" inside the list should also have the @var
> markup.

Thanks, added like @code{(@var{id} @var{cols})}

>> +It moves point to the beginning of the deleted entry.
>
> The last sentence is confusing: if the entry is deleted, how can we
> move to its beginning?

Changed to "It moves point to the beginning of the current line."

>> +@defun tabulated-list-header-overlay-p &optional POS
>> +This @code{defsubst} returns non-nil if there is a fake header at
>> +@var{pos}.
>
> We should explain, in a single sentence if possible, what is a "fake
> header".  It is never explained in this section.

Added as "A fake header is used if @code{tabulated-list-use-header-line} is @code{nil} to put the column names at the beginning of the buffer."

>> +@defun tabulated-list-put-tag tag &optional advance
>> +This function puts @var{tag} in the padding area of the current line.
>
> And this should explain what is the padding area, for the same reason.

Added as "The padding area can be empty space at the beginning of the line, the width of which is governed by @code{tabulated-list-padding}."

>> +@var{tag} should be a string, with a length less than or equal to
>> +@code{tabulated-list-padding}.
>
> Every variable mentioned in the manual should be indexed.  So please
> add
>
>  @vindex tabulated-list-padding
>
> before the @defun.

Done (also for tabulated-list-use-header-line)

>> +If @var{change-entry-data} is non-nil, this function modifies the
>> +underlying entry data by setting the appropriate slot of the vector
>> +originally used to print this entry.  If @code{tabulated-list-entries}
>> +has a list value, this is the vector stored within it.
>
> This paragraph is confusing, I cannot understand what that argument
> does just by reading the above text.  (The doc string says the same,
> so it's of no help.)  The confusing parts are "appropriate slot" and
> "originally used to print".  The code simply modifies a component of
> the vector returned by tabulated-list-get-entry, so I wonder why the
> description needs to be that complicated.

Changed to this, which is hopefully clearer:

If @var{change-entry-data} is non-nil, this function modifies the
underlying data (usually the column descriptor in the list
@code{tabulated-list-entries}) by setting the column descriptor of the
vector to @code{desc}.

Thanks,
Alex

[0001-Add-documentation-for-tabulated-list-functions-in-th.patch (text/x-patch, inline)]

From 5d0a50705a19ad464d141ab3b4880dddf5cf37ea Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Sat, 2 Feb 2019 09:59:21 -0600
Subject: [PATCH] Add documentation for tabulated-list functions in the elisp
 manual

* doc/lispref/modes.texi: Add documentation for
  'tabulated-list-delete-entry', 'tabulated-list-get-id',
  'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
  'tabulated-list-put-tag', and 'tabulated-list-set-col'.

Bug#21074
---
 doc/lispref/modes.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..aeac421495 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,65 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-delete-entry
+This function deletes the entry at point.
+
+It returns a list @code{(@var{id} @var{cols})}, where @var{id} is the
+ID of the delete entry and @var{cols} is a vector of its column
+descriptors.  It moves point to the beginning of the current line.
+It returns @code{nil} if there is no entry at point.
+
+Note that this function only changes the buffer contents; it does not
+alter @code{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-id &optional pos
+This @code{defsubst} returns the ID object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  If
+omitted or @code{nil}, @var{pos} defaults to point.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This @code{defsubst} returns the entry object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  This
+will be a vector for the ID at @var{pos}.  If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+@vindex tabulated-list-use-header-line
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  A fake header is used if
+@code{tabulated-list-use-header-line} is @code{nil} to put the column
+names at the beginning of the buffer.  If omitted or @code{nil},
+@var{pos} defaults to @code{point-min}.
+@end defun
+
+@vindex tabulated-list-padding
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+The padding area can be empty space at the beginning of the line, the
+width of which is governed by @code{tabulated-list-padding}.
+@var{tag} should be a string, with a length less than or equal to
+@code{tabulated-list-padding}.  If @var{advance} is non-nil, this
+function advances point by one line.
+@end defun
+
+@defun tabulated-list-set-col col desc &optional change-entry-data
+This function changes the tabulated list entry at point, setting
+@var{col} to @var{desc}.  @var{col} is the column number to change, or
+the name of the column to change.  @var{desc} is the new column
+descriptor, which is inserted via @code{tabulated-list-print-col}.
+
+If @var{change-entry-data} is non-nil, this function modifies the
+underlying data (usually the column descriptor in the list
+@code{tabulated-list-entries}) by setting the column descriptor of the
+vector to @code{desc}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Sat, 02 Feb 2019 20:06:13 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: mbork <at> mbork.pl, 21074 <at> debbugs.gnu.org
> Date: Sat, 02 Feb 2019 11:28:56 -0600
> 
> >> +delete entry and @var{cols} is a vector of its column descriptors.
> >                ^
> > And here.
> 
> I don't think a comma is needed here. It's a list of two entries, not
> three, so no comma, right?

Hmm.. I guess I was confused by the "delete entry" -- you meant
"deleted", right?

Otherwise OK.

Thanks.

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

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 05 Feb 2019 14:08:50 -0600

[Message part 1 (text/plain, inline)]

On Sat 02 Feb 2019 at 12:06, Eli Zaretskii <eliz <at> gnu.org> wrote:

>> >> +delete entry and @var{cols} is a vector of its column descriptors.
>> >                ^
>> > And here.
>> 
>> I don't think a comma is needed here. It's a list of two entries, not
>> three, so no comma, right?
>
> Hmm.. I guess I was confused by the "delete entry" -- you meant
> "deleted", right?

Whoops, yes I meant "deleted." Fixed in the attached patch.

> Otherwise OK.

Great! Should I push this to master, then, or do you want to?

Thanks,
Alex


From 3460d745215bbbf24350786753602bf06c23e139 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Sat, 2 Feb 2019 09:59:21 -0600
Subject: [PATCH] Add documentation for tabulated-list functions in the elisp
 manual

* doc/lispref/modes.texi: Add documentation for
  'tabulated-list-delete-entry', 'tabulated-list-get-id',
  'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
  'tabulated-list-put-tag', and 'tabulated-list-set-col'.

Bug#21074
---
 doc/lispref/modes.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..6349dec98b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,65 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-delete-entry
+This function deletes the entry at point.
+
+It returns a list @code{(@var{id} @var{cols})}, where @var{id} is the
+ID of the deleted entry and @var{cols} is a vector of its column
+descriptors.  It moves point to the beginning of the current line.  It
+returns @code{nil} if there is no entry at point.
+
+Note that this function only changes the buffer contents; it does not
+alter @code{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-id &optional pos
+This @code{defsubst} returns the ID object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  If
+omitted or @code{nil}, @var{pos} defaults to point.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This @code{defsubst} returns the entry object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  This
+will be a vector for the ID at @var{pos}.  If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+@vindex tabulated-list-use-header-line
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  A fake header is used if
+@code{tabulated-list-use-header-line} is @code{nil} to put the column
+names at the beginning of the buffer.  If omitted or @code{nil},
+@var{pos} defaults to @code{point-min}.
+@end defun
+
+@vindex tabulated-list-padding
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+The padding area can be empty space at the beginning of the line, the
+width of which is governed by @code{tabulated-list-padding}.
+@var{tag} should be a string, with a length less than or equal to
+@code{tabulated-list-padding}.  If @var{advance} is non-nil, this
+function advances point by one line.
+@end defun
+
+@defun tabulated-list-set-col col desc &optional change-entry-data
+This function changes the tabulated list entry at point, setting
+@var{col} to @var{desc}.  @var{col} is the column number to change, or
+the name of the column to change.  @var{desc} is the new column
+descriptor, which is inserted via @code{tabulated-list-print-col}.
+
+If @var{change-entry-data} is non-nil, this function modifies the
+underlying data (usually the column descriptor in the list
+@code{tabulated-list-entries}) by setting the column descriptor of the
+vector to @code{desc}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2

[0001-Add-documentation-for-tabulated-list-functions-in-th.patch (text/x-patch, inline)]

From 3460d745215bbbf24350786753602bf06c23e139 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham <at> gmail.com>
Date: Sat, 2 Feb 2019 09:59:21 -0600
Subject: [PATCH] Add documentation for tabulated-list functions in the elisp
 manual

* doc/lispref/modes.texi: Add documentation for
  'tabulated-list-delete-entry', 'tabulated-list-get-id',
  'tabulated-list-get-entry', 'tabulated-list-header-overlay-p',
  'tabulated-list-put-tag', and 'tabulated-list-set-col'.

Bug#21074
---
 doc/lispref/modes.texi | 59 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi
index 143cc7c582..6349dec98b 100644
--- a/doc/lispref/modes.texi
+++ b/doc/lispref/modes.texi
@@ -1121,6 +1121,65 @@ that tags placed via @code{tabulated-list-put-tag} will not be removed
 from entries that haven't changed (normally all tags are removed).
 @end defun
 
+@defun tabulated-list-delete-entry
+This function deletes the entry at point.
+
+It returns a list @code{(@var{id} @var{cols})}, where @var{id} is the
+ID of the deleted entry and @var{cols} is a vector of its column
+descriptors.  It moves point to the beginning of the current line.  It
+returns @code{nil} if there is no entry at point.
+
+Note that this function only changes the buffer contents; it does not
+alter @code{tabulated-list-entries}.
+@end defun
+
+@defun tabulated-list-get-id &optional pos
+This @code{defsubst} returns the ID object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  If
+omitted or @code{nil}, @var{pos} defaults to point.
+@end defun
+
+@defun tabulated-list-get-entry &optional pos
+This @code{defsubst} returns the entry object from
+@code{tabulated-list-entries} (if that is a list) or from the list
+returned by @code{tabulated-list-entries} (if it is a function).  This
+will be a vector for the ID at @var{pos}.  If there is no entry at
+@var{pos}, then the function returns @code{nil}.
+@end defun
+
+@vindex tabulated-list-use-header-line
+@defun tabulated-list-header-overlay-p &optional POS
+This @code{defsubst} returns non-nil if there is a fake header at
+@var{pos}.  A fake header is used if
+@code{tabulated-list-use-header-line} is @code{nil} to put the column
+names at the beginning of the buffer.  If omitted or @code{nil},
+@var{pos} defaults to @code{point-min}.
+@end defun
+
+@vindex tabulated-list-padding
+@defun tabulated-list-put-tag tag &optional advance
+This function puts @var{tag} in the padding area of the current line.
+The padding area can be empty space at the beginning of the line, the
+width of which is governed by @code{tabulated-list-padding}.
+@var{tag} should be a string, with a length less than or equal to
+@code{tabulated-list-padding}.  If @var{advance} is non-nil, this
+function advances point by one line.
+@end defun
+
+@defun tabulated-list-set-col col desc &optional change-entry-data
+This function changes the tabulated list entry at point, setting
+@var{col} to @var{desc}.  @var{col} is the column number to change, or
+the name of the column to change.  @var{desc} is the new column
+descriptor, which is inserted via @code{tabulated-list-print-col}.
+
+If @var{change-entry-data} is non-nil, this function modifies the
+underlying data (usually the column descriptor in the list
+@code{tabulated-list-entries}) by setting the column descriptor of the
+vector to @code{desc}.
+@end defun
+
+
 @node Generic Modes
 @subsection Generic Modes
 @cindex generic mode
-- 
2.19.2

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 05 Feb 2019 22:26:42 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: mbork <at> mbork.pl, 21074 <at> debbugs.gnu.org
> Date: Tue, 05 Feb 2019 14:08:50 -0600
> 
> > Otherwise OK.
> 
> Great! Should I push this to master, then, or do you want to?

Go ahead and push, but to emacs-26 (the same functions exist there as
well, right?).  And thanks for working on this.

Message #52 received at 21074-done <at> debbugs.gnu.org (full text, mbox):

From: Alex Branham <alex.branham <at> gmail.com>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: mbork <at> mbork.pl, 21074-done <at> debbugs.gnu.org
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Tue, 05 Feb 2019 14:50:33 -0600

[Message part 1 (text/plain, inline)]

On Tue 05 Feb 2019 at 14:26, Eli Zaretskii <eliz <at> gnu.org> wrote:

> Go ahead and push, but to emacs-26 (the same functions exist there as
> well, right?).  And thanks for working on this.

OK, I think I did so. This is my first direct push to Emacs, so let me
know if it doesn't show up or if I did something wrong.

Thanks again,
Alex

[signature.asc (application/pgp-signature, inline)]

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: Alex Branham <alex.branham <at> gmail.com>
Cc: 21074 <at> debbugs.gnu.org, mbork <at> mbork.pl
Subject: Re: bug#21074: [PATCH] Add docs for two tabulated-list functions
Date: Wed, 06 Feb 2019 05:32:27 +0200

> From: Alex Branham <alex.branham <at> gmail.com>
> Cc: mbork <at> mbork.pl, 21074-done <at> debbugs.gnu.org
> Date: Tue, 05 Feb 2019 14:50:33 -0600
> 
> > Go ahead and push, but to emacs-26 (the same functions exist there as
> > well, right?).  And thanks for working on this.
> 
> OK, I think I did so. This is my first direct push to Emacs, so let me
> know if it doesn't show up or if I did something wrong.

Looks OK, but the log message should state the names of the functions
in which you made the changes.  For manuals, "functions" are nodes.
The command "C-x 4 a" should help you create such entries.

Previous Next

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