bug#965: 23.0.60; filesets doc

[Drew Adams]

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'