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 23:29:39 -0700 Message-ID: <001e01c914a0$ef485e30$0200a8c0@us.oracle.com> References: <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 1221202071 26200 80.91.229.12 (12 Sep 2008 06:47:51 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Fri, 12 Sep 2008 06:47:51 +0000 (UTC) To: <965@emacsbugs.donarmstrong.com>, Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Fri Sep 12 08:48:45 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 1Ke2SS-00043V-WC for geb-bug-gnu-emacs@m.gmane.org; Fri, 12 Sep 2008 08:48:45 +0200 Original-Received: from localhost ([127.0.0.1]:39813 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Ke2RS-0001Iz-7C for geb-bug-gnu-emacs@m.gmane.org; Fri, 12 Sep 2008 02:47:42 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Ke2RO-0001Il-UV for bug-gnu-emacs@gnu.org; Fri, 12 Sep 2008 02:47:38 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Ke2RM-0001IT-Bm for bug-gnu-emacs@gnu.org; Fri, 12 Sep 2008 02:47:38 -0400 Original-Received: from [199.232.76.173] (port=52274 helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Ke2RM-0001IP-8Y for bug-gnu-emacs@gnu.org; Fri, 12 Sep 2008 02:47:36 -0400 Original-Received: from mx20.gnu.org ([199.232.41.8]:28069) by monty-python.gnu.org with esmtps (TLS-1.0:RSA_AES_256_CBC_SHA1:32) (Exim 4.60) (envelope-from ) id 1Ke2RL-0005Qo-TH for bug-gnu-emacs@gnu.org; Fri, 12 Sep 2008 02:47:36 -0400 Original-Received: from rzlab.ucr.edu ([138.23.92.77]) by mx20.gnu.org with esmtp (Exim 4.60) (envelope-from ) id 1Ke2RK-0004so-To for bug-gnu-emacs@gnu.org; Fri, 12 Sep 2008 02:47:35 -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 m8C6lXaP027729; Thu, 11 Sep 2008 23:47:33 -0700 Original-Received: (from debbugs@localhost) by rzlab.ucr.edu (8.13.8/8.13.8/Submit) id m8C6Z5G1023058; Thu, 11 Sep 2008 23:35:05 -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 06:35:05 +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 965-submit@emacsbugs.donarmstrong.com id=B965.122120099321124 (code B ref 965); Fri, 12 Sep 2008 06:35:05 +0000 Original-Received: (at 965) by emacsbugs.donarmstrong.com; 12 Sep 2008 06:29:53 +0000 Original-Received: from agminet01.oracle.com (agminet01.oracle.com [141.146.126.228]) by rzlab.ucr.edu (8.13.8/8.13.8/Debian-3) with ESMTP id m8C6TnHH021118 for <965@emacsbugs.donarmstrong.com>; Thu, 11 Sep 2008 23:29:50 -0700 Original-Received: from rgmgw1.us.oracle.com (rgmgw1.us.oracle.com [138.1.186.110]) by agminet01.oracle.com (Switch-3.2.4/Switch-3.1.7) with ESMTP id m8C6TeRC019289; Fri, 12 Sep 2008 01:29:40 -0500 Original-Received: from acsmt705.oracle.com (acsmt705.oracle.com [141.146.40.83]) by rgmgw1.us.oracle.com (Switch-3.2.4/Switch-3.2.4) with ESMTP id m8C6TdhS023534; Fri, 12 Sep 2008 00:29:39 -0600 Original-Received: from dradamslap1 (/24.23.165.218) by default (Oracle Beehive Gateway v4.0) with ESMTP ; Thu, 11 Sep 2008 23:29:38 -0700 X-Mailer: Microsoft Office Outlook 11 In-Reply-To: <000001c91486$11e281c0$0200a8c0@us.oracle.com> Thread-Index: AckUhg4aUke/Oi5BQX+ZFEqp7ECKxgAGfUqw 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 mx20.gnu.org: Linux 2.6 (newer, 3) X-detected-kernel: by monty-python.gnu.org: Linux 2.6, seldom 2.4 (older, 4) Resent-Date: Fri, 12 Sep 2008 02:47:38 -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:20504 gmane.emacs.pretest.bugs:23039 Archived-At: FWIW: * The doc on the author's Web site (http://members.a1.net/t.link/CompEmacsFilesetsDoc.html) is quite a bit better than the Emacs Info doc for Filesets. * The version of Filesets on the author's Web site is 2.2. The version of Filesets in Emacs 23 is 1.8.4. Time for GNU Emacs to upgrade? > -------------------8<---------------------- > From: Drew Adams Sent: Thursday, September 11, 2008 8:17 PM > 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'