bug#965: 23.0.60; filesets doc

["Drew Adams" <drew.adams@oracle.com>]

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'