filesets

filesets

[Richard Stallman]

I saw the changes that you made in files.texi to try to distinguish
the two uses of "fileset".  In effect, those changes tell the reader,
"please be aware of this ambiguity and cope with it".  That does not
solve the problem.  What is needed is to remove the ambiguity.

One way to do this is to find TWO modifiers.  One concept could be "VC
fileset" and the other could be "XYZ fileset".  I can't think of a
suitable word to use in place of XYZ; can anyone else?

The other way is to rename one of these concepts entirely.  Renaming
the VC one is better since it is new, and thus not an incompatible
change.

You don't seem to recognize the importance of this problem -- you seem
to think it is ok not to fix it.  It is not OK, and if no one fixes
this right, I will just remove the term "fileset" from the VC
documentation.  (That is something I know how to do.)

Re: filesets

[Robert J. Chassell]

Since the documentation for `vc-deduce-fileset' says

    If we're in VC-dired mode, the fileset is the list of marked files.

you could remove the word `fileset' and speak only of

    the list of marked files

and refer to such a list in an argument, as does `vc-svn-diff', as

    files 

I know that speaking of `the list of marked files' is longer than
speaking of `filesets'.  That is bad.  However, the word `list' has
specific meaning in Lisp.  It is good to express it.

Actually, the argument `files' could be `files-list' which is longer,
too, but more helpful to whichever person reads the code in fifteen
years.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: filesets

[Miles Bader]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
> Actually, the argument `files' could be `files-list' which is longer,
> too, but more helpful to whichever person reads the code in fifteen
> years.

Given the pervasiveness of lists in lisp, I don't think "files-list"
_is_ particularly more helpful, and it's certainly more ugly.  If a
variable is plural, you can basically assume it's a list unless
explicitly told otherwise.

-Miles

-- 
"Whatever you do will be insignificant, but it is very important that
 you do it."  Mahatma Gandhi

Re: filesets

[Stefan Monnier]

>> Actually, the argument `files' could be `files-list' which is longer,
>> too, but more helpful to whichever person reads the code in fifteen
>> years.

> Given the pervasiveness of lists in lisp, I don't think "files-list"
> _is_ particularly more helpful, and it's certainly more ugly.  If a
> variable is plural, you can basically assume it's a list unless
> explicitly told otherwise.

I was about to write exactly the same thing.


        Stefan

Re: filesets

[Robert J. Chassell]

    Given the pervasiveness of lists in lisp, I don't think
    "files-list" _is_ particularly more helpful, and it's certainly
    more ugly.

Yes, it is more ugly.  Moreover, you are right, when a word is plural,
assume it refers to a list.

What do yo think of my other suggestion, which is to drop the word
`fileset' in documentation where the reference is to a list, as in
`vc-svn-diff'?

;; emacs/lisp/vc-svn.el

  (defun vc-svn-diff (files &optional oldvers newvers buffer)
    "Get a difference report using SVN between two revisions of fileset FILES."
    ...

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: filesets

[Miles Bader]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
> What do yo think of my other suggestion, which is to drop the word
> `fileset' in documentation where the reference is to a list, as in
> `vc-svn-diff'?
>
>   (defun vc-svn-diff (files &optional oldvers newvers buffer)
>     "Get a difference report using SVN between two revisions of fileset FILES."

I like that one -- indeed, I think the simple term "files" is much more
clear than "fileset".

[An english speaker can kind of guess what the term "fileset" must mean,
but it still has a very peculiar feel about it, like it's implying some
extra restrictions over and above a simple list of files.  Maybe there
_are_ such extra restrictions, but it's not obvious from what I've seen
of the code...]

-Miles

-- 
=====
(^o^;
(()))
*This is the cute octopus virus, please copy it into your sig so it can spread.

Re: filesets

[Paul Michael Reilly]

Richard Stallman wrote:
> I saw the changes that you made in files.texi to try to distinguish
> the two uses of "fileset".  In effect, those changes tell the reader,
> "please be aware of this ambiguity and cope with it".  That does not
> solve the problem.  What is needed is to remove the ambiguity.
> 
> One way to do this is to find TWO modifiers.  One concept could be "VC
> fileset" and the other could be "XYZ fileset".  I can't think of a
> suitable word to use in place of XYZ; can anyone else?
> 
> The other way is to rename one of these concepts entirely.  Renaming
> the VC one is better since it is new, and thus not an incompatible
> change.

Coming up with a solution to what "XYZ" should be is the optimal 
solution IMHO since it solves the problem in such a way that the next 
notion of filesets does not encounter this dilemma.  But I don't have 
any good ideas for XYZ either.  If I owned this issue, I would change 
"VC fileset" to "VC sourceset" and beg the problem for a while.

-pmr

Re: filesets

[Richard Stallman]

    I know that speaking of `the list of marked files' is longer than
    speaking of `filesets'.  That is bad.  However, the word `list' has
    specific meaning in Lisp.  It is good to express it.

At the user level, a fileset is a collection of files,
collection in an abstract sense, not a Lisp object.
To speak of a "list of files" would put in a false trail.

I am not sure how bad this confusion would be in practice.
Maybe it is acceptable.

"Set of files" would be more like it; it's the same concept as
"fileset", but by swapping the words around we would avoid the
implication that it is the same as the "fileset" discussed in
another section.

Re: filesets

[Robert J. Chassell]

    At the user level, a fileset is a collection of files, ...

A user may not call `vc-svn-diff', which says `fileset FILES' in
its documention, and provide the function with a search pattern.
He or she must provide a list.

According to emacs/lisp/filesets.el

  A fileset is either 
    a list of files, 
    a file pattern,
    a base directory and a search pattern (for files), or 
    an inclusion group (i.e. a base file including other files).

but the argument called by `vc-svn-diff' in emacs/lisp/vc-svn.el is
only a list.

`dolist', which is one of the functions called by the `vc-svn-diff'
defun and to which the `fileset' argument applies, cannot handle a
search pattern or any of the other last three items.  It can only take
a list in its second argument.

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc

Re: filesets

[Robert J. Chassell]

   Unless someone else has *specific wordsmithing* ...

Very few people have time to think up *specific wordsmithing* so that
statement comes across as bullying.  Please use wording that attracts
more help.

Please consider changes as necessary for both the function
documentation (which may apply to a bunch of VC related libraries) and
to the Info documention.

(Then changes may be -- but I am not sure -- that the word `fileset'
is not worth reusing with a different meaning in a different context
and that the word `list', meaning a Lisp list, an atomic item, needs
explanation, if that word be used instead the word `fileset'.)

-- 
    Robert J. Chassell                          GnuPG Key ID: 004B4AC8
    bob@rattlesnake.com                         bob@gnu.org
    http://www.rattlesnake.com                  http://www.teak.cc