From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.blaine.gmane.org!not-for-mail From: Alex Branham Newsgroups: gmane.emacs.bugs Subject: bug#21074: [PATCH] Add docs for two tabulated-list functions Date: Sat, 02 Feb 2019 11:28:56 -0600 Message-ID: <87va229k13.fsf@gmail.com> References: <87a8uwmq0d.fsf@mbork.pl> <871s5diy1q.fsf@gmail.com> <83won5d9ll.fsf@gnu.org> <87zhs1hfo7.fsf@gmail.com> <83k1j1awba.fsf@gnu.org> <87k1iwl80i.fsf@gmail.com> <83zhrfyi1a.fsf@gnu.org> <87y36y9nzg.fsf@gmail.com> <83h8dmw3pe.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: blaine.gmane.org; posting-host="blaine.gmane.org:195.159.176.226"; logging-data="23601"; mail-complaints-to="usenet@blaine.gmane.org" User-Agent: mu4e 1.1.0; emacs 27.0.50 Cc: 21074@debbugs.gnu.org, mbork@mbork.pl To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Feb 02 18:33:13 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by blaine.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gpzAF-0005xC-3C for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Feb 2019 18:33:11 +0100 Original-Received: from localhost ([127.0.0.1]:44845 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpzAD-0002RQ-PQ for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Feb 2019 12:33:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:52328) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gpz9u-0002KX-3j for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 12:32:51 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gpz7D-0003Uy-20 for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 12:30:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:57281) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gpz7C-0003TX-Td for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 12:30:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gpz7C-0000Gl-KX for bug-gnu-emacs@gnu.org; Sat, 02 Feb 2019 12:30:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Alex Branham Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Feb 2019 17:30:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 21074 X-GNU-PR-Package: emacs Original-Received: via spool by 21074-submit@debbugs.gnu.org id=B21074.1549128547945 (code B ref 21074); Sat, 02 Feb 2019 17:30:02 +0000 Original-Received: (at 21074) by debbugs.gnu.org; 2 Feb 2019 17:29:07 +0000 Original-Received: from localhost ([127.0.0.1]:56561 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gpz6I-0000FB-Jr for submit@debbugs.gnu.org; Sat, 02 Feb 2019 12:29:07 -0500 Original-Received: from mail-oi1-f170.google.com ([209.85.167.170]:37252) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gpz6G-0000Ei-TN for 21074@debbugs.gnu.org; Sat, 02 Feb 2019 12:29:05 -0500 Original-Received: by mail-oi1-f170.google.com with SMTP id y23so8443958oia.4 for <21074@debbugs.gnu.org>; Sat, 02 Feb 2019 09:29:04 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=references:user-agent:from:to:cc:subject:in-reply-to:date :message-id:mime-version; bh=pIio96jpCKTZ7MRkY2VvBLFw9BetiiStjfwxbdmkuog=; b=eVpAetappQsW6kVYJNQK7ito2i5IG5/BwuqOJQTIrFVdDtgdfCQZeH/897KPvesAaV ZFBsRR9q5tXqeqbphH4OOsjr5fgST+jqPmR3u92G74AJQc3SyHLvNCDnHURnV4GYq3ut 3uF1/AQcB1hFDnnCSc2bb1DNfGS1r3O16Z9wlsxYUhwyvBi8fBXf/XT74PYV5PvAWt12 HSpAih3zqujJd/NWUwbCjSgu2Del1vL6W1nQKLvW6CVIcAaOYFGWrgouDTqlJKD43ivR 5M3cttGtB9yp/Ftw6LTkKUYVKXG8K8nQeUB4WRAbwj0naA6kn7gd05IzuGIZ3LzCl18E urCw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:references:user-agent:from:to:cc:subject :in-reply-to:date:message-id:mime-version; bh=pIio96jpCKTZ7MRkY2VvBLFw9BetiiStjfwxbdmkuog=; b=kCtaJNLXlrgAXVMbKayf/G7nn8Lq2gIy+2HI5Rx9ru/SXvWCAQ1/R8Qt9dQM/AEn/4 g5hMeBo5tiHklZ8jhSIUTrG8oIY+gEJNQnSBC7iMz3dU7RkZcESEEh2OqjYh4LuYoOLO s1M1VV0w+TKuFh2RDmMkzUhVTVPvietDzxf10PpoUsaUdHF8bRmZL8ADmCW7JwkzE96b cczVwCrGIhJx1D2o5QeZTwUJI/GlEQtpBLp233TLHEB1Fl7tpmgOlAlc8qy7HiN/P98z vy8q8D1Yz0ucSNSUUFI6mTkwahv/tH5Y42wLacImZ5+GH8QakVO6CG8pS27KDxvfwe9K F+Ow== X-Gm-Message-State: AHQUAuYZQMoEx3yvltmtBL65L4yb/sM4is1lXFeq56mRsVNlrculCl2a EXpvgIapLjpTGEG6jR9gp/5ZEr29 X-Google-Smtp-Source: AHgI3IYZSGR/0psP19zCAHgkMjrSEyP7GbwwwoExwxEMq6fVae2aLFN0ccQaDTtQy2IvVmrfuddFNg== X-Received: by 2002:aca:4e0a:: with SMTP id c10mr19020687oib.36.1549128538836; Sat, 02 Feb 2019 09:28:58 -0800 (PST) Original-Received: from mars (72-47-130-203.brhmcmtc01.res.dyn.suddenlink.net. [72.47.130.203]) by smtp.gmail.com with ESMTPSA id m207sm5003630oig.2.2019.02.02.09.28.57 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Sat, 02 Feb 2019 09:28:57 -0800 (PST) In-reply-to: <83h8dmw3pe.fsf@gnu.org> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 209.51.188.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: "bug-gnu-emacs" Xref: news.gmane.org gmane.emacs.bugs:155029 Archived-At: --=-=-= Content-Type: text/plain On Sat 02 Feb 2019 at 10:33, Eli Zaretskii 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 --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-Add-documentation-for-tabulated-list-functions-in-th.patch >From 5d0a50705a19ad464d141ab3b4880dddf5cf37ea Mon Sep 17 00:00:00 2001 From: Alex Branham 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 --=-=-=--