bug#965: 23.0.60; filesets doc

bug#965: 23.0.60; filesets doc

[Drew Adams]

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'
 

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'

bug#965: 23.0.60; filesets doc

[Drew Adams]

Shouldn't this be eliminated entirely as a user option?

(defcustom filesets-find-file-delay
  (if (and (featurep 'xemacs) gutter-buffers-tab-visible-p)
      0.5
    0)
  "Delay before calling `find-file'.
This is for calls via `filesets-find-or-display-file'
or `filesets-find-file'.

Set this to 0, if you don't use XEmacs' buffer tabs."
  :set (function filesets-set-default)
  :type 'number
  :group 'filesets)

What's the point of having an option whose value (for GNU Emacs) should always
be 0?



> From: Drew Adams Sent: Thursday, September 11, 2008 11:30 PM
> 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'
> 
> 
> 
> 
> 
> 

bug#965: 23.0.60; filesets doc

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Shouldn't this be eliminated entirely as a user option?
>
> (defcustom filesets-find-file-delay
>   (if (and (featurep 'xemacs) gutter-buffers-tab-visible-p)
>       0.5
>     0)
>   "Delay before calling `find-file'.
> This is for calls via `filesets-find-or-display-file'
> or `filesets-find-file'.
>
> Set this to 0, if you don't use XEmacs' buffer tabs."
>   :set (function filesets-set-default)
>   :type 'number
>   :group 'filesets)
>
> What's the point of having an option whose value (for GNU Emacs) should always
> be 0?

Well, XEmacs users may find it useful to change the value, I guess?  So
it should always be 0 on Emacs, but XEmacs users may choose to have
either 0 or 0.5?

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#965: 23.0.60; filesets doc

[Drew Adams]

> Well, XEmacs users may find it useful to change the value, I 
> guess?  So it should always be 0 on Emacs, but XEmacs users may
> choose to have either 0 or 0.5?

I don't feel strongly about it, but why not handle that in the obvious way: Give
XEmacs users the option, and don't give GNU Emacs users the option (since they
don't really have an option anyway)?

(when (featurep 'xemacs) (defcustom...))

bug#965: 23.0.60; filesets doc

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> I don't feel strongly about it, but why not handle that in the obvious
> way: Give XEmacs users the option, and don't give GNU Emacs users the
> option (since they don't really have an option anyway)?
>
> (when (featurep 'xemacs) (defcustom...))

Having the `defcustom' forms not be top-level has other negative
effects, like etags not working.  And you wouldn't be able to share .elc
files...  if that's still possible.

So I don't think this is worth doing anything about, so I'm closing the
report. 

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#965: 23.0.60; filesets doc

[Drew Adams]

> > I don't feel strongly about it, but why not handle that in 
> > the obvious way: Give XEmacs users the option, and don't
> > give GNU Emacs users the option (since they don't really
> > have an option anyway)?
> > (when (featurep 'xemacs) (defcustom...))
> 
> Having the `defcustom' forms not be top-level has other negative
> effects, like etags not working.  And you wouldn't be able to 
> share .elc files...  if that's still possible.
> 
> So I don't think this is worth doing anything about, so I'm 
> closing the report. 

Whoa!?  Wait a minute.  This bug is 99.999% about things other than that
defcustom.  This bug is about the filesets _doc_ - see the Subject line, and
please read the rest of the thread.

You replied only to the (afterthought) comment I made about the defcustom, so I
replied to you only about that.  But that is _not_ what this bug is really
about.  



[Wrt that defcustom:

At the very least we should add to its doc string that it _has no effect if you
are not using XEmacs_.  We should not be giving GNU Emacs users the impression
that they have an option here.

And I'm not sure you wouldn't be able to share .elc.  Are you sure that the
`when' itself won't be present (compiled) in the .elc?  IOW, are you sure that
if compiled with GNU Emacs you couldn't load the .elc in XEmacs and get the
option?]

bug#965: 23.0.60; filesets doc

[Lars Magne Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> Whoa!?  Wait a minute.  This bug is 99.999% about things other than that
> defcustom.  This bug is about the filesets _doc_ - see the Subject line, and
> please read the rest of the thread.

Oops.  I've now reopened the bug.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#965: 23.0.60; filesets doc

[Lars Ingebrigtsen]

"Drew Adams" <drew.adams@oracle.com> writes:

> 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.

Seems to be fixed now.

> 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.

Adding these spelling variations to the index doesn't seem very productive.

> 3. Node Filesets: "initially creates only the current file": no file
> is _created_.

Can't find that string in the manual.

> 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.

It seems more useful to users than to Lisp programmers.  I've never
heard of the stuff until now.

Anyway, closing.

-- 
(domestic pets only, the antidote for overdose, milk.)
  bloggy blog http://lars.ingebrigtsen.no/

bug#965: 23.0.60; filesets doc

[Drew Adams]

> > 1. ...
> Seems to be fixed now.

Yes.

> > 2. ...
> 
> Adding these spelling variations to the index doesn't seem very
> productive.

And yet "sets of files" was added by someone.  Good; that helps.

> > 3. ...
> 
> Can't find that string in the manual.

This too was fixed.

Items 4, 5, 6, 7, and 8 of this detailed doc report have NOT
been fixed.  The bug is still open.  And there are still plenty
of good suggestions for fixing the problems - in the original
bug report.

> > 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.
> 
> It seems more useful to users than to Lisp programmers.  I've never
> heard of the stuff until now.

OK, since Lars has never heard of it, and Lars is an Emacs-Lisp
user, this cannot be interesting to other Lisp programmers. ;-)
And yet there is plenty of 3rd-party use of filesets and the
fileset code...

> Anyway, closing.

Reopening.

You ignored 4, 5, 6, 7, and 8 - all major parts of the bug report.

And you also ignored this, from a followup message:

>> Shouldn't this be eliminated entirely as a user option?
>> 
>> (defcustom filesets-find-file-delay  ...
>>   "... Set this to 0, if you don't use XEmacs' buffer tabs."...)
>> 
>> What's the point of having an option whose value (for GNU Emacs)
>> should always be 0?