From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: "Drew Adams" Newsgroups: gmane.emacs.bugs,gmane.emacs.pretest.bugs Subject: bug#965: 23.0.60; filesets doc Date: Thu, 11 Sep 2008 20:17:18 -0700 Message-ID: <000001c91486$11e281c0$0200a8c0@us.oracle.com> Reply-To: Drew Adams , 965@emacsbugs.donarmstrong.com NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-Trace: ger.gmane.org 1221190081 22112 80.91.229.12 (12 Sep 2008 03:28:01 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 12 Sep 2008 03:28:01 +0000 (UTC) To: Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Sep 12 05:28:56 2008 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.50) id 1KdzL2-0008N4-Bw for geb-bug-gnu-emacs@m.gmane.org; Fri, 12 Sep 2008 05:28:55 +0200 Original-Received: from localhost ([127.0.0.1]:59568 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KdzK0-0007RJ-8R for geb-bug-gnu-emacs@m.gmane.org; Thu, 11 Sep 2008 23:27:48 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1KdzJw-0007R8-QH for bug-gnu-emacs@gnu.org; Thu, 11 Sep 2008 23:27:44 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1KdzJs-0007Qo-U5 for bug-gnu-emacs@gnu.org; Thu, 11 Sep 2008 23:27:44 -0400 Original-Received: from [199.232.76.173] (port=51622 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1KdzJs-0007Ql-OV for bug-gnu-emacs@gnu.org; Thu, 11 Sep 2008 23:27:40 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]:35678) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1KdzJr-00061X-Fi for bug-gnu-emacs@gnu.org; Thu, 11 Sep 2008 23:27:41 -0400 Original-Received: from rzlab.ucr.edu (rzlab.ucr.edu [127.0.0.1]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m8C3RXuM022053; Thu, 11 Sep 2008 20:27:33 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id m8C3P40s020676; Thu, 11 Sep 2008 20:25:04 -0700 X-Loop: don@donarmstrong.com Resent-From: "Drew Adams" Resent-To: bug-submit-list@donarmstrong.com Resent-CC: Emacs Bugs Resent-Date: Fri, 12 Sep 2008 03:25:04 +0000 Resent-Message-ID: Resent-Sender: don@donarmstrong.com X-Emacs-PR-Message: report 965 X-Emacs-PR-Package: emacs X-Emacs-PR-Keywords: Original-Received: via spool by submit@emacsbugs.donarmstrong.com id=B.122118946318593 (code B ref -1); Fri, 12 Sep 2008 03:25:04 +0000 Original-Received: (at submit) by emacsbugs.donarmstrong.com; 12 Sep 2008 03:17:43 +0000 Original-Received: from fencepost.gnu.org (fencepost.gnu.org [140.186.70.10]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m8C3Hc2G018583 for ; Thu, 11 Sep 2008 20:17:40 -0700 Original-Received: from mail.gnu.org ([199.232.76.166]:52467 helo=mx10.gnu.org) by fencepost.gnu.org with esmtp (Exim 4.67) (envelope-from ) id 1Kdz8P-0003hF-JN for emacs-pretest-bug@gnu.org; Thu, 11 Sep 2008 23:15:49 -0400 Original-Received: from Debian-exim by monty-python.gnu.org with spam-scanned (Exim 4.60) (envelope-from ) id 1KdzA6-0004pB-LV for emacs-pretest-bug@gnu.org; Thu, 11 Sep 2008 23:17:38 -0400 Original-Received: from rgminet01.oracle.com ([148.87.113.118]:19204) by monty-python.gnu.org with esmtps (TLS-1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1KdzA6-0004nn-7v for emacs-pretest-bug@gnu.org; Thu, 11 Sep 2008 23:17:34 -0400 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by rgminet01.oracle.com (Switch-3.2.4/Switch-3.1.6) with ESMTP id m8C3HM3Q006881 for ; Thu, 11 Sep 2008 21:17:22 -0600 Original-Received: from acsmt702.oracle.com (acsmt702.oracle.com [141.146.40.80]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id m8C3HL52002025 for ; Thu, 11 Sep 2008 21:17:21 -0600 Original-Received: from dradamslap1 (/24.23.165.218) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 11 Sep 2008 20:17:21 -0700 X-Mailer: Microsoft Office Outlook 11 Thread-Index: AckUhg4aUke/Oi5BQX+ZFEqp7ECKxg== X-MimeOLE: Produced By Microsoft MimeOLE V6.00.2900.3350 X-Brightmail-Tracker: AAAAAQAAAAI= X-Brightmail-Tracker: AAAAAQAAAAI= X-Whitelist: TRUE X-Whitelist: TRUE X-detected-kernel: by monty-python.gnu.org: Linux 2.4-2.6 X-detected-kernel: by monty-python.gnu.org: Linux 2.6 (newer, 3) Resent-Date: Thu, 11 Sep 2008 23:27:44 -0400 X-BeenThere: bug-gnu-emacs@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:20497 gmane.emacs.pretest.bugs:23037 Archived-At: Some quick feedback on the filesets doc: 1. `i' in the Emacs manual followed by `filesets' shows index entries `filesets' and `filesets <1>'. The former is not about filesets in general, but about version control editing. The latter is the normal filesets entry, but `<1>' means nothing to users. 2. There is no index entry for `file set' or `file-set' or `sets of files'. A user might not know that `fileset' just happens to be written that (non-standard) way. 3. Node Filesets: "initially creates only the current file": no file is _created_. 4. There is no explanation of the Filesets menu items. There is an `About' item with a link to a non-GNU Web page - should there be (dunno - maybe)? What is the meaning of `#' and `+' in front of the submenus? I see, from customizing group Filesets, that there is an option Filesets Menu Shortcuts Flag, and I can guess from that what the # and + are for, but (1) Why this non-standard convention only here? (2) Why nothing in the Info doc about it? 5. Using Customize: a. After using DEL to delete a fileset, SET for the current session should automatically "rebuild" the menu to remove that fileset, no? b. There is a wealth of information in the Customize description for Filesets Data, but it is mostly at the Emacs-Lisp level. Nevertheless, it is useful, and totally missing from the doc (manual). This stuff needs to be _explained_ to users: what the features are and how to use them. c. In group Filesets, These options (at least) are not very understandable: - Filesets Menu In Menu - Filesets Menu Shortcuts Marker - Filesets Menu Cache Contents - Filesets Menu Cache Contents (needs to be explained better) - Filesets Cache Hostname Flag - Filesets Browse Dir Function (external command not clear) - Filesets Find File Delay (what for?) - Filesets Commands (explanation unclear) - Filesets External Viewers (Properties is especially unclear) - Filesets Ingroup Patterns Also, "splitted" -> "split"; "a filesets' files" -> "a fileset's files". 6. Generally, the filesets doc is poor, hidden, and inside out - you need to dig through Customize or the source code to piece together what this is all about and how you might put it to use. There is only one Info node for this stuff, and it explains nothing about 90% of the user-level fileset features. The Customize description reads like a disparate collection of code comments - not very helpful to users, but it is the best information available so far. 7. There is nothing in the Emacs-Lisp manual about filesets. The fileset features and the Emacs Lisp behind them (e.g. keywords) should be explained (somewhere). Presumably, filesets should be of interest to Lisp programmers. 8. The Website linked to from menu item About has a page with documentation on filesets: http://members.a1.net/t.link/CompEmacsFilesetsDoc.html. All of that information needs to be added to the Emacs manual (or a separate Filesets Info manual, if too large). That would be a good start. Beyond the doc: 1. Is there a command that removes (deletes) a fileset, or must you use Customize or `setq'? 2. Why isn't `filesets-init' interactive? The third sentence of the doc says that you "must" put (fileset-init) in .emacs. Surely that is not the way to teach this - better to walk users through using a command than to tell them to edit .emacs and start over. IN SUM: It's a shame this stuff isn't documented clearly. If it were, people might use it more. It seems like it should have potential, but the doc is not encouraging. CAVEAT: I took a very quick look, so I apologize if I overlooked or misunderstood some things. Take this input as just one Emacs user's first impression. In GNU Emacs 23.0.60.1 (i386-mingw-nt5.1.2600) of 2008-08-29 on LENNART-69DE564 Windowing system distributor `Microsoft Corp.', version 5.1.2600 configured using `configure --with-gcc (3.4) --no-opt --cflags -Ic:/g/include -fno-crossjumping'