Re: Bug#758402: ITP: python-xstatic-jquery.quicksearch -- jQuery.quicksearch XStatic support
I think I'm getting closer to understanding, but not close enough.
David Prévot wrote:
>> * Package name : python-xstatic-jquery.quicksearch
[...]
>> Description : jQuery.quicksearch XStatic support
>>
>> XStatic is a packaging standard to package external (often 3rd party) static
>> files as a Python package, so they are easily usable on all operating systems,
>> with any package management system or even without one.
Okay, a bit of research tells me there's a chunk of context missing
here: it's taking it for granted that I already know it's talking
specifically about web development where the part you're coding is in
Python but it depends on other people's JavaScript (or similar). I
would probably have understood that quicker if I was a developer, but
still, it's friendlier to the people reading this if the information
that tells them "this isn't for you" is at the start.
Some further googling reveals that by "static files", Python web
developers mean the kind of data files you might expect to find under
$DOCROOT/resources/ or somewhere. "Static" files as opposed to... I'm
not sure what. Dynamically generated pages? User-provided content?
Oh well; maybe we can get away with using the word "static" and hoping
that readers somehow already know what it means. That seems to be
what everyone else is doing.
And the point of XStatic is that you want to incorporate some
particular "static files" into your $DOCROOT/resources directory,
but... well, maybe the nature of the problem will become clear later.
But I definitely don't yet understand how XStatic renders a collection
of files "easily usable on all operating systems with any package
management system". Sure, bundling files into a Python egg might make
them accessible via a Python egg installer, but that's not the same
thing as making it possible to install them with APT.
>> .
>> Many Python projects need to use some specific data files, like javascript,
>> css, java applets, images, etc. Sometimes these files belong to YOUR project
>> (then you may want to package them separately, but you could also just put
>> them into your main package). But in many other cases, those files are
>> maintained by someone else (like jQuery javascript library or even much bigger
>> js libraries or applications) and you definitely do not really want to merge
>> them into your project.
I can't believe it needs to spend so much effort explaining the case
where there isn't a problem for this software to solve.
Should "jQuery javascript library" have an article?
So the thing to do is arrange for the package that contains your
Python software to depend on the package that contains that JavaScript
library. Right? Oh, no, of course, you can't do that because you're
not on Debian, so your packaged Python doesn't have any way of
depending on JavaScript - other than directly including the files,
which is nasty. Or... putting them in a *fake* Python package? Aaah!
Maybe this is beginning to make sense now...
>> So, you want to have static file packages, but you
>> don’t want to get lots of stuff you do not want.
The stuff I don't want to get is the stuff I do not want? What a
coincidence! Or perhaps a really turgid explanation.
>> Thus, stuff required by
>> XStatic file packages (especially the main, toplevel XStatic package) tries to
>> obey to be a MINIMAL, no-fat thing.
"To obey to be" is the only part of this that's out-and-out
ungrammatical.
"Stuff tries to be a thing." This paragraph is overstuffed.
>> XStatic doesn't "sell" any web framework
>> or other stuff you don't want. Maybe there will be optional XStatic extensions
>> for all sorts of stuff, but they won't be required if you just want the files.
I like the air of mystery - maybe there will be optional extensions
for stuff, or maybe there won't! But not only will they be optional,
they won't be required.
>> .
>> By having static files in packages, it is also easier to build virtual envs,
Borderline ungrammatical. And isn't it "virtualenvs"? (Or "virtual
environments", but that's bad because it sounds as if it means what it
says.)
>> support linux/bsd/... distribution package maintainers and even windows
>> installs using the same mechanism.
All the above is the blurb for the XStatic framework, and doesn't
belong in the python-xstatic-jquery.quicksearch package description
unless that Debian package really does make it easier to support
Windows installs. A deverbosified version could go in the package
description for python-xstatic, but I'd prefer to start from somewhere
else.
The python-xstatic-* packages should have a much, much shorter section
saying something like
XStatic (see python-xstatic) is a Python web development tool for
bundling sets of required data files from external non-Python
projects into Python packages that your app can depend on portably.
Then the ...-jquery.quicksearch package should end with a description
of this JS library, or at least a pointer to libjs-jquery.quicksearch.
>> .
>> This package provides jQuery.quicksearch support as a Python module.
So the point of this package isn't that you'd want to *install* it -
after all, you could just do "apt install libjs-jquery.quicksearch".
The point is to make it possible for your Python modules to depend on
this Python module, because that approach lets you install your webapp
on BeOS like all the cool kids are doing and have it pull in all the
appropriate data files. Except... why has it been Debianised? Nope,
this still isn't quite making sense to me.
What am I missing?
--
JBR with qualifications in linguistics, experience as a Debian
sysadmin, and probably no clue about this particular package
Reply to: