From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED.ciao.gmane.org!not-for-mail From: Alex Branham Newsgroups: gmane.emacs.bugs Subject: bug#21074: [PATCH] Add docs for two tabulated-list functions Date: Tue, 22 Jan 2019 15:03:41 -0600 Message-ID: <87k1iwl80i.fsf@gmail.com> References: <87a8uwmq0d.fsf@mbork.pl> <871s5diy1q.fsf@gmail.com> <83won5d9ll.fsf@gnu.org> <87zhs1hfo7.fsf@gmail.com> <83k1j1awba.fsf@gnu.org> Mime-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha256; protocol="application/pgp-signature" Injection-Info: ciao.gmane.org; posting-host="ciao.gmane.org:195.159.176.228"; logging-data="194240"; mail-complaints-to="usenet@ciao.gmane.org" User-Agent: mu4e 1.1.0; emacs 27.0.50 Cc: 21074@debbugs.gnu.org, Marcin Borkowski To: Eli Zaretskii Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Jan 22 22:34:15 2019 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.org with esmtps (TLS1.0:RSA_AES_256_CBC_SHA1:256) (Exim 4.89) (envelope-from ) id 1gm3gV-000oIB-CF for geb-bug-gnu-emacs@m.gmane.org; Tue, 22 Jan 2019 22:34:15 +0100 Original-Received: from localhost ([127.0.0.1]:50442 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gm3gP-0004Wk-8z for geb-bug-gnu-emacs@m.gmane.org; Tue, 22 Jan 2019 16:34:09 -0500 Original-Received: from eggs.gnu.org ([209.51.188.92]:49649) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gm3Jp-0000Fj-BW for bug-gnu-emacs@gnu.org; Tue, 22 Jan 2019 16:10:50 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gm3DG-0001Ny-KG for bug-gnu-emacs@gnu.org; Tue, 22 Jan 2019 16:04:04 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]:42337) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gm3DG-0001NA-Fa for bug-gnu-emacs@gnu.org; Tue, 22 Jan 2019 16:04:02 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1gm3DG-0007UI-1s for bug-gnu-emacs@gnu.org; Tue, 22 Jan 2019 16:04: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: Tue, 22 Jan 2019 21:04:01 +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.154819103328769 (code B ref 21074); Tue, 22 Jan 2019 21:04:01 +0000 Original-Received: (at 21074) by debbugs.gnu.org; 22 Jan 2019 21:03:53 +0000 Original-Received: from localhost ([127.0.0.1]:41618 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gm3D7-0007Tw-C7 for submit@debbugs.gnu.org; Tue, 22 Jan 2019 16:03:53 -0500 Original-Received: from mail-oi1-f171.google.com ([209.85.167.171]:41049) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1gm3D4-0007Tj-A5 for 21074@debbugs.gnu.org; Tue, 22 Jan 2019 16:03:50 -0500 Original-Received: by mail-oi1-f171.google.com with SMTP id j21so18646516oii.8 for <21074@debbugs.gnu.org>; Tue, 22 Jan 2019 13:03:50 -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=4nvqRz94UWksiyp15lM4jdMl9wmtLzK95Ll/wqKK+yY=; b=VFPkDT0V/5udDjPbhmwmk5Jvoz2MZt13Lwv/Y6C6tOxoye+m1+blXttiN6FQKLGZLk ExvmAxHpLeJjUA9aq/786OWdrSuKAe8+EX5wXn4WLM/heXX4uBiFwCoMdS702cbdQ1vo r6LmcqirVEvpRZH9nrRr05hsnXv546r5psrHbdrQxxPyT8wHu/f7Wn4SfpbIENRA/Y4P BcRN4z8AdhvnBf+PVJVISdWnmCA6qGip36iSuRY+/Q1DvjkE9/GH+CRsISeaMpFisGXJ ZQOMZO/nkVOCdrUlunNV4zJCe3cqml6br2ANBWImKbufpGFPp4/rp+HIKiRqYtjFnMAU wOfQ== 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=4nvqRz94UWksiyp15lM4jdMl9wmtLzK95Ll/wqKK+yY=; b=iyVRx6mQlBzbTYr9F8XQ+MeUoUr6UsRIh3Gg5MVprjxv0xpBDTy9W7bu/Hsx2QKEB2 54cscK/PR6wYacvnOqpvezudNP8TNGCo37CuP//zLC/DR6QDOQ9mS9gX6061anBh6hwz uVfdj1vVtdqnggtssfykj7QUok/4lmvY/RGh1LNcncaffJiRv8arcE5gM3hsSFucTyjE SONI7XLB1B2lyJ23BdGMqx6b1K8PI5xij2sqRd+mME9OFRhyz+XrCAvpCX9Kmi5jlRc4 RT3/xNzKelTEtJI6RWLtRAtvQpdH2TJyvFNIg6/cQ7lnt6ob4IJc0oayV5uDbMl8PHGE BeeA== X-Gm-Message-State: AJcUukcWaLJcc6cR3hP1ajqZHGCOeuMNMojgh6j+xasGZFq0bzClaTfJ HXNljat2WOuMrXNqJ8dIYPQl0nLA X-Google-Smtp-Source: ALg8bN6h9Dlwh88yIZRYAaQjceb/LxyVivUbxSrvyFXg749daUYDXtRxRQuaZ7XDGcSvyWVmUP+Yhw== X-Received: by 2002:aca:3c06:: with SMTP id j6mr9117090oia.126.1548191024326; Tue, 22 Jan 2019 13:03:44 -0800 (PST) Original-Received: from mars (nat-128-62-58-163.public.utexas.edu. [128.62.58.163]) by smtp.gmail.com with ESMTPSA id b2sm7995957oia.8.2019.01.22.13.03.43 (version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256); Tue, 22 Jan 2019 13:03:43 -0800 (PST) In-reply-to: <83k1j1awba.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:154679 Archived-At: --=-=-= Content-Type: text/plain 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 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 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQEzBAEBCAAdFiEEeEJ4XAMgliXNXicpHkInolPpmscFAlxHhS0ACgkQHkInolPp msfVRAf/aoIZ+cquuwfuJ6/DZmEW+GfTPoYNuqY581CbV9zwo/wVUTTjy6jBD/eK OFio6zOIMcCM/MNfHV9f43FDjVKy5Hxkd/bVy1Jnb4VWCo6VxzYpGc8TO7u0gFXO oRed7fzjLQJAtxMQalfLiuvwsEKjDfOzTEFtfCuxdy+btNKJVg9RdXjsn/exin1U L7LozST0WnK6pw5DM7QCCBKEmERX8seQRhrJrxqJxBUFRbmeyt4ohtSZB7CIEsZR K3QvBFG8EI0eQ1QkQiCXVa+A7kVWSjcnwfbu8gYMnGNnJwNO6Buvwb34FRKsLSte 4ooEga909v2xx/Ofwv3LeqbhQ51Kkw== =LGtl -----END PGP SIGNATURE----- --=-=-=--