On Sat, 09 Jun 2007 11:06:25 +0200 Jeroen Vloothuis wrote:
> To make development with KSS a bit nicer I was thinking
of adding a few
> features.
>
> The first feature would be a listing of the available
commands. This
> could be implemented as a simple Javascript function
which displays all
> commands with their documentation.
>
We have been long planning a feature that ends up similar to
this, and
although it's not written yet, I discussed it in details
with a lot of
developers including you. So I would expect you to remember
it, but maybe
I did not make myself clear enough when we talked about the
last time in
April. Anyway I am writing you a bit about it now but it's a
long planned
feature with more than I could detail in a single mail.
This was called maybe the "docstring feature" but
there was no
established name for it yet. It is quite high priority for
me personally,
the main reason for not starting on it is because while we
cannot fulfill
our more burning obligations like fix Plone bugs, we cannot
start giving
resources to a "nice to have" feature.
Nevertheless I support the idea to
start working on this on an upcoming sprint and I already
planned it for
the Snowsprint, and also for Potsdam (where I could not
attend in the
end), but there was not enough interest between the
developers to start
with it really.
Some differences between your proposal and the original
proposal is, that
- we want to handle both documentation and registration
metadata, and
- we don't plan to do the mechanism that delivers this
information from
javascript. Instead we want to store the data itself inside
the
javascript, but deliver it from python.
The original idea was this:
We want to have something that is like how the dosctrings
function in
python. For this we need to establish a documentation
standard that is
both pythonic and also fits the java world.
This way the javascript plugins would become self
documenting. They would
contain comments blocks next to the plugin registrations.
This would
document the given function (action, provider, selector, eg.
everything
that is extensible) probably in ReST. In addition it would
contain rich
metadata that would describe
- the identification (type and name of the plugin)
- mandatory and optional parameters to default value
- and every other information that we currently register
from zcml.
This way all the documentation and registration information
would be in
the javascript, close to the actual code it documents.
Instead of the
number of the zcml directives we would have a *single zcml
directive*
that defines a javascript file as a plugin. Then it would
parse the
docstring information from the file and build up the
registration
database on the server side so we would have the same data
available as
currently but without the need for registering both on the
client and on
the server redundantly.
In addition we would have a plain python api and a
commandline for the
same task. This means that any other server side (non-zope
or even non-
python) could use the same extractor to fetch the necessary
information.
One of the use of the fetched information (as currently) is
doing early
semantical checks on the server like disallow marshalling
nonexistent
commands, and the second is to offer the documentation from
the server.
>From zope this would be on-line rendering of the plugin
documentation
from a view, presented from a document tab somewhere. For
other systems
we can build a set of static html pages that can be served
up to the
client.
To avoid a misunderstanding, we do not, by no means, want to
generate any
javascript code. The javascript plugins would be registered
as before,
only their usage would be annotated in the docstrings next
to them.
The original idea as described above was for the
self-documenting of the
plugin javascript. At the time when this idea was born, we
did not yet
have the commandsets, so it did not cover then. But
obviously the same
can be extended to the commandsets either, to have the
documentation of
them available. This would even be esaier since parsing the
python does
not require a separate parser. However also together with
this, as a
separate but connecting task, we would want to standardize
the loading of
the commandsets for zope and plain python as well.
About the actual tasks that are needed to start with first,
we would need
two things:
1. Design the actual documentation format. If we use ReST,
there is
chance that we can describe the metadata als with syntax
already existing
in RsST. We have to investigate if this is possible.
2. Find a parser builder in python. I did some research that
included
about six python parser builders but I could not settle on
any of them.
As a direct goal, we need a parser because we need to
extract the
comments out of the javascript. Even just this is far from
trivial, and
imo, instead of doing complex regexp magic, we need to
choose one of the
available parser builder libraries.
Both these two are tasks that we could typically do
together, on a
sprint. Maybe a bit separate task is to have code that
extracts the
comment blocks from js, this could be dome before the
sprint.
> Because KSS is a pluggable framework a developer can
then easily see
> which command's are available for the chosen platform.
Something like
> this would help Plone developers because there
are/might be a few
> specific Plone commands.
>
> Using a self documenting feature means you will always
have the proper
> documentation.
So as I described above, this is planned to be provided, and
even more.
> Another feature would be to have some interactive
prompt support.
> Currently Firebug already provides us with a console.
It would be great
> if we could use this to execute something like:
>
> kssApplyRule('a.special:click { ... }')
>
> kssClearRules()
>
> Does anyone else see value in these ideas?
Would be nice to think about this, except that kssClearRules
is not
possible currently with the kss core. Again I do not want to
go deeper
into this, just briefly:
Clearing rules would be a desirable feature. It would
require however
that the physically bound browser events can be cleared.
This is not
supported by DOM/BOM, only posible if we have already
depended on one of
the javascript frameworks or use custom code.
Even after this, it would require a significant rewrite of
the kss core.
One of the main challenges is, how to implement the
rebinding of nodes
when a html class changes. Ie, this is the main feature
where clearing
of events would become necessary. However in the worst case
such an
operation, unfortunately, may degrade to rebinding all the
rules in a
page. I don't want to go deeper into this, realistically
this is not
something we will have soon, but it could come after wa have
completed
the other four or five planned/ongoing "nice to
have" projects.
However the kssApplyRule would be feasible.
What would be, however, even more interesting and even more
feasible, is
write introspection utilities for kss, to provide a way to
see which
rules are bound where. In the end we could arrive to FireBug
where you
can introspect kss similarly the way you can introspect html
nodes.
--------------------------
Summarizing, both features you raised are important on the
long term
however they involve pretty complex details, and we have
much higher
priority tasks at the moment that we must complete first for
the success
of kss. Nevertheless we need to start planning these things
in parallel,
but since there has been lots of brainstorming done on these
issues
already, and that they involve the deep knowledge of the
core code, I
find it inevitable that we start working on these issues
together, during
a sprint.
--
Balazs Ree
_______________________________________________
Kss-devel mailing list
Kss-devel codespeak.net
http:
//codespeak.net/mailman/listinfo/kss-devel
|
