From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs Subject: bug#7521: 24.0.50; doc for `delimit-columns-*' Date: Sat, 2 Jul 2011 08:21:40 -0700 Message-ID: <06B232927CEE40FC91F8398F1EFDDF97@us.oracle.com> References: <6AF7D745DDFA44439FAE15E2647441AF@us.oracle.com> NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: dough.gmane.org 1309620209 29435 80.91.229.12 (2 Jul 2011 15:23:29 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 2 Jul 2011 15:23:29 +0000 (UTC) Cc: 7521@debbugs.gnu.org To: "'Lars Magne Ingebrigtsen'" Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jul 02 17:23:24 2011 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([140.186.70.17]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1Qd22V-0003ep-Tv for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Jul 2011 17:23:24 +0200 Original-Received: from localhost ([::1]:55021 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qd22U-0000Oc-4Z for geb-bug-gnu-emacs@m.gmane.org; Sat, 02 Jul 2011 11:23:22 -0400 Original-Received: from eggs.gnu.org ([140.186.70.92]:45095) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qd22C-0000OD-AW for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2011 11:23:05 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1Qd22B-0007LI-BC for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2011 11:23:04 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:39001) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1Qd22B-0007LC-8U for bug-gnu-emacs@gnu.org; Sat, 02 Jul 2011 11:23:03 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1Qd22A-0005dk-MB; Sat, 02 Jul 2011 11:23:02 -0400 X-Loop: help-debbugs@gnu.org Resent-From: "Drew Adams" Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 02 Jul 2011 15:23:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 7521 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 7521-submit@debbugs.gnu.org id=B7521.130962012521599 (code B ref 7521); Sat, 02 Jul 2011 15:23:02 +0000 Original-Received: (at 7521) by debbugs.gnu.org; 2 Jul 2011 15:22:05 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qd21E-0005cK-U6 for submit@debbugs.gnu.org; Sat, 02 Jul 2011 11:22:05 -0400 Original-Received: from acsinet15.oracle.com ([141.146.126.227]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1Qd21D-0005br-0g for 7521@debbugs.gnu.org; Sat, 02 Jul 2011 11:22:03 -0400 Original-Received: from acsinet21.oracle.com (acsinet21.oracle.com [141.146.126.237]) by acsinet15.oracle.com (Switch-3.4.4/Switch-3.4.4) with ESMTP id p62FLtnP010129 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Sat, 2 Jul 2011 15:21:56 GMT Original-Received: from acsmt357.oracle.com (acsmt357.oracle.com [141.146.40.157]) by acsinet21.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id p62FLsVR009543 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Sat, 2 Jul 2011 15:21:55 GMT Original-Received: from abhmt110.oracle.com (abhmt110.oracle.com [141.146.116.62]) by acsmt357.oracle.com (8.12.11.20060308/8.12.11) with ESMTP id p62FLnbP015146; Sat, 2 Jul 2011 10:21:49 -0500 Original-Received: from dradamslap1 (/10.159.63.244) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Sat, 02 Jul 2011 08:21:49 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: Thread-Index: Acw4v59V1RVfUIlFQHmJo4BVc6pwiwACy7hw X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.6109 X-Source-IP: acsinet21.oracle.com [141.146.126.237] X-Auth-Type: Internal IP X-CT-RefId: str=0001.0A090201.4E0F3794.00D6:SCFMA922111,ss=1,re=-4.000,fgs=0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sat, 02 Jul 2011 11:23:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) X-Received-From: 140.186.70.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-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:47759 Archived-At: > > You cannot understand a thing about commands > > `delimit-columns-region' and `delimit-columns-rectangle' > > without reading the commentary in Lisp > > file delim-col.el. In sum, there is no help for users - no doc. > > I suspect that the workings of delim-col.el are too complicated to be > explained in a doc string for any of the commands. If these commands > are to be useful to users, I think the proper solution is to document > them in the elisp manual. You might be right; I really don't know. My take is that these things are explained in the source-code comments, and that this info needs to be made available to users via help/doc. If the details get transferred to the manual, OK. But even then the doc strings of the various functions (these are user _commands_, after all) need to give some explanation. If we cannot explain these commands at all then maybe that's a sign that the commands themselves are overly complex. A user should be able to get some idea of what to expect from a command by reading its doc string. That s?he might need to consult the manual for more detail is fine. But that's not a reason to have incomprehensible or vacuous doc strings.