RE: Improving browsing and discoverability in the Packages Menu

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

> >> And I'm pretty sure you won't see any occurrence of
> >>   ;; Keywords: modeline, electronic mail
> >>   ;; Package Keywords: mode-line, email
> >> even if there was a new field.
> >
> > Sorry, I didn't catch your last point.  Perhaps you mean to say that
> > `Keywords' will disappear?  All the kids will run to play in the new
> > sandbox?
> 
> No, what I've meant to say is that when a maintainer adds the new
> `Package Keywords' header duplicating the existing `Keywords' header and
> then sees that byte-compilation suggests to use the more commonly used
> "mode-line" and "email" instead of "modeline" and "electronic mail", why
> should she change only `Package Keywords` accordingly and not
> `Keywords', too?  (Assuming that she agrees that "mode-line" and "email"
> express what she intended to express, too.)

If package.el continues to issue warnings for stuff that is in `Keywords'
(not `Package Keywords'), then it is not playing fair.  In that case it
would have created its own sandbox (good) but continue to poke its nose
into the old community sandbox, kick sand around, and annoy its occupants
with bullying warnings and such (bad).

If not, then there should be no problem.  Keywords inserted in `Package
Keywords' should obey the new rules - or else warnings & helpful
electroshock will duly ensue, per spec.

If someone blindly copies existing non-package keywords from `Keywords'
to `Package Keywords', and if some of those flaunt the clean, Streng
Verboten rules of package.el, then the copier gets what s?he deserves:
appropriate insults (er, guidance) from package.el.

> She doesn't know that there are some people that don't want `Keywords'
> to be changed.  Or should the warning say something like that?

Yes, `Keywords' is not for package keywords.  That should be part of 
the message for users (the doc).  `Package Keywords', and only `Package
Keywords', is for package keywords, which have (whatever) strict
semantics.

Not a big deal.  Clean, tidy.  Should make parsing and controlling
by package.el easy, without stepping on any toes - no sand in eyes.

`Keywords' need not (& should not) be mentioned in the package doc.
But if it is, just say that it is lax - no special semantics.  The
message should be only that keywords related to packages belong in
`Package Keywords' - that's all.

There is no mention of `Keywords' in the current Emacs manual, and no
need to add any mention of it (IMO).  Search case-sensitively for
`Keywords' in the Emacs manual and - guess what? - you find hits only
for (drum roll...) `Package Keywords'.  Seems that Ms Manual has
already paved the way for my suggestion.

Oh, but the Elisp manual mentions `Keywords' in its discussion of
packages.  What it says there (node `Simple Packages') is only
specific to use of `Keywords' by package.el.  This text should
refer instead to `Package Keywords', of course.

The Elisp manual mentions `Keywords' also in node `Library Headers'.
And (guess what?) there the text mentions the use of `Keywords' by
`finder-by-keyword' - which is NOT and should NOT be limited to
packages as defined by package.el.  That is all as it should be.

Unfortunately, the description of `Keywords' in node `Library
Headers' has been updated to mention that it is now used also by
package.el.  That is inappropriate and should be cleaned up.
Instead of saying this:

  The name of this field is unfortunate, since people often assume
  it is the place to write arbitrary keywords that describe their
  package, rather than just the relevant Finder keywords.

The correct approach here is to use a new, NOT-unfortunate name for
package keywords, and continue to let `finder-by-keyword' and any
other longstanding code use `Keywords' as originally intended (no
special rules, syntax, or relations).

Just as finder.el is not (& should not be made to be) limited to
what is good for package.el (both `finder-known-keywords' and
`finder-list-keywords' predate package.el), so should file-header
keyword `Keywords' not be limited to package.el relevance.

>     The Package Keywords entry "modeline" is likely to mean "mode-line".
>     If you agree, change it accordingly but please let the Keywords
>     header as-is for the Olt Town's habitants peace of mind.

I'd say just mention what `Package Keywords' is for in the doc, and
not repeat the doc in each warning about package keywords.  But you
know better than I what warnings people should be scared with. ;-)