[imp-dev] Re: Questions & proposed changes to preferences specification

[Stan Sutton <suttons@xxxxxxxxxx>]

Hi Bob,

Answers are embedded in green below
....

Thanks,

Stan

Stan Sutton, Ph. D.
IBM T. J. Watson Research Center
19 Skyline Drive, Hawthorne, NY 10532 USA
telephone:  1-914-784-7316, FAX:  1-914-784-7455, T/L 863
e-mail:  suttons@xxxxxxxxxx, Stan Sutton/Watson/IBM@IBMUS

"Robert M. Fuhrer" <rfuhrer@xxxxxxxxxxxxxx>

12/02/2008 10:37 AM

To	Stan Sutton/Watson/IBM@IBMUS
cc	Jurgen Vinju <jurgen.vinju@xxxxxx>, imp-dev <imp-dev@xxxxxxxxxxx>
Subject	Questions & proposed changes to preferences specification language

>Hi Stan,

>Remind me: What's special about a "special value"?

The "special value" is a place
to provide a value that has some "special" application- or context-dependent
role.  E.g., suppose you have a preference of type String for which
the usual values are names of countries.  You may want to set the
default value to "United States" but you may want a special value
of "    " (a blank string) to be the value that is
shown initially on the preference page (e.g., in a combo box).  In
this case, the value that you may want to compute with by default is not
the same value that you may want to display by default.

Or suppose you have a preference of
type int that has a typical range of 0 to 10.  You may want to have
"0" as the default value but use "-1" as a special
value to indicate that the preference is not set.  In this case the
default value is a "valid" value (from the standpoint of typical
use), so some other value is used to indicate an "invalid" (or
"unset" or "null") value.

So, the need for and use of the "special"
value really depends on the intentions of the preferences developer.  I
can imagine that a given preference may actually have multiple "special"
values, depending on the application, and the current "special"
value is just a nod in that direction.

>Also, what does "removable" mean?

"Removable" means that the
value that is set on a given preference level can be removed from that
level, which has the effect of triggering inheritance of the value from
a more general level if the value should be requested.

>Also, would you object to making certain parts of the specification
>optional? E.g., the entire "tabs" section could be optional,
in which
>case the full set of tabs would be present with their "standard
 
>behavior" (whatever that is :-)).

Large parts of the specification are
optional.  Regarding the "tabs" section, the section itself
is required but you can omit all of the tab specs, in which case you get
the full set of tabs with their standard behavior.  (Right now you
have to omit either all or none of the fields.  If we were to allow
just some fields to be omitted, then I would think that by default the
omitted fields would be excluded, not included and given the typical behavior.)

Similarly with the "fields"
section:  currently you have to have the section but the set of specified
fields can be empty (in which case you do *not* get the full set of fields
with their standard behavior).

You don't have to specify the "conditionals"
section at all.  (And actually the language still includes a "custom"
section--for customizations specific to a particular field on a particular
level--but that is likewise optional and not included on the templates).

I arranged things this way so that the
language would match the functionality of the preference pages:  a
page (in this model) pretty much has to have tabs and fields to be minimally
useful, so those sections are required in the specification, but pages
don't in general need conditional dependencies (or level-specific customizations),
so those sections are totally optional.

So the "tabs" and "fields"
sections could be made totally optional.  It might be a slight convenience
when writing specifications, but the language would then be slightly less
true to the application domain.  It's not a big deal either way (I
don't think.)  We could also address this through templates.  We
could provide a template that has empty "tabs" and "fields"
sections (or just an empty "tabs" section), which would mean
that the user wouldn't have to edit anything in the tabs section to get
the "default" behavior (standard tab set up).  Alternatively,
we could make the "tabs" and "fields" sections optional,
but provide templates that include those, so that the user sees that those
are concerns to be addressed.

>Likewise, we could make "hasspecial"
and
>"isremovable" optional, with sensible defaults.

In my experience these are optional.
 I think that all of the attributes of tabs and fields are optional,
except for default values.  (Maybe there are one or two others that
are specific to some of the field types.)

Perhaps this is also an issue for the
templates, i.e., the examples in the current template may not suggest the
full range of optionality for some of these things.  (That could be
addressed by more varied examples or by better comments in the template.)


>Next, I think it would be somewhat simpler to have the conditional
>enablement specifications part of the field specification, rather than
>in a separate section. This way everything about a field is localized.
>E.g.:
>   boolean ExecutableToUse { ... enabledif UseDefaultExecutable;
}

We've discussed this before.  I
see this as an issue of separation of concerns, the resolution of which
may in effect be a religious issue.  My preference is to put things
about individual fields (independent of level) into the "fields"
section, and things that relate to relationships between fields into the
"conditionals" section.  (And everything that is generic
to tabs is specified in the "tabs" section, and everything that
applies to individual fields on individual levels is in the "custom"
section.)

One thing about the current approach
is that it encourages you (perhaps) to specify all of your fields before
you start talking about the dependencies among them, whereas including
the dependencies as part of the field specs means that you will introduce
some parse errors (because one field depend on another that hasn't been
defined yet) or you have to first define the fields and then go back and
rework the individual specs to include the dependency information.  I
think this is a concern, but probably not a big one, as I expect that typical
users will be reworking their specs to some degree in any case.

Another slight concern is that not everything
about all fields would be localized.  In the specification of field
A you could see that it depended on field B, but in the specification of
B you wouldn't see that A depended on it.  If the dependency information
is in a separate section, then it is somewhat farther removed from the
spec of at least one of the fields involved, but I think it may be more
clearly and symmetrically apparent overall.  As you say, if you want
to see everything there is to see about field A in one place, and A is
a dependent field, then putting it all into the one field spec would localize
that information.

Anyway, I think this is basically a
religious issue.  I definitely do have a preference for things as
they are now, but plainly other people can feel differently (without necessarily
being terrorists :-) ).  I could certainly work with the other arrangement.
 I think that really it should be decided according to the preferences
of the majority of our users, to which I would be happy to defer.


>Finally, there are a few bits of info that reside in a separate file
to
>control the compilation process, but I think it would also be better
>to put those in the main file (unless for some reason you want to
>support spreading a single specification across multiple files?).

I see this as another separation of
concerns issue.  (I wasn't thinking about spreading specifications
across multiple files--but should we?)  I see the specification of
the page/field/tab information as being different from and logically independent
of the specifications of the generation information.  What goes into
the prefspecs file (now) is information about the content of preference
pages; what goes into the gen params file (apart perhaps from the package
and class name) is about other things, mainly the attributes needed for
specifying the preferences page extension.  (In that regard, it seems
to me that the information in the gen params file may be of a somewhat
different order than the sorts of compiler directives that one might usually
embed into a source file, at least in my limited experience.  The
params say little about what is generated or how it is generated and much
about how what is generated is situated or used.)  It is mainly because
of this conceptual separation that I put the gen params into a separate
file from the preferences specifications.  (But I did put both files
into the same directory.)

I suppose, going along with the above,
that the separation of the files supports a specialization of roles in
IDE development.  Specification of the extension properties requires
no knowledge of specific preferences, while specification of specific preferences
requires no knowledge of the extension framework.  Admittedly, in
practice these roles are likely to be filled by one person in almost all
cases, so this is probably not a significant argument in terms of practice.
 For what it's worth, as the process works now, the gen params are
obtained from the wizard (which seems like a natural thing for the wizard
to provide) and the preferences specifications (apart from the initial
template) are specified by editing the .pfsp file.

Also of some relevance are certain pragmatic
issues, such as possibility of combining multiple specification files,
or the reuse of specifications in different contexts, that might be favored
by a separate gen params file.  But we don't really have a basis of
experience to motivate those yet.

With the current setup, with the current
patterns of use, the combination of the gen params information with the
preferences specification could be accommodated and would probably not
adversely impact anyone.  My preference is to keep the two types of
information separate.  This is somewhat of a religious issue, although
there seem to be some pragmatic considerations that could favor the separation.
 On the other hand, a preponderance of users might prefer to have
everything in one file, in which case I'd defer to that sentiment.  But
do we have a preponderance of users?

>BTW, I made a few fixes to the prefspecs project's plugin.xml:
>there were a couple of duplicated extension specifications,
>and the builder/nature IDs had an extra ".prefspecs" in them.

That's great.  The plugin.xml file
was created quite some time (and at least a couple of Eclipse versions)
ago and evidently had never been cleaned up.


>Cheers,
>  - Bob