bug#21074: [PATCH] Add docs for two tabulated-list functions

[Alex Branham <alex.branham@gmail.com>]

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


On Sat 02 Feb 2019 at 12:06, Eli Zaretskii <eliz@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@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



[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Add-documentation-for-tabulated-list-functions-in-th.patch --]
[-- Type: text/x-patch, Size: 3583 bytes --]

From 3460d745215bbbf24350786753602bf06c23e139 Mon Sep 17 00:00:00 2001
From: Alex Branham <alex.branham@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