Next: Copying This Manual, Previous: Packaging GNU Makefile for desklets, Up: Top
Requirements for “official” desklets packages are scarce; authors are free to do as they wish. There are only two things that should be enforced:
NAME-MAJOR.MINOR.REVISION
, where NAME
is the desklet base name, and MAJOR.MINOR.REVISION
the version. Please note that a makefile (See
Packaging GNU Makefile for desklets.) is also provided to
automate creation of such an archive on GNU systems.Starting in adesklets 0.4.4,
desklet authors are provided with a Python script to automate the
submission of their desklets: utils/adesklets_submit from the source package. Use
the --with-python-install-submission-scripts
option
at configuration time to place it in your bindir
directory upon installation.
adesklets_submit can be used to:
Desklet submission is initiated by sending a specially crafted email to adesklets@mailworks.org2. The adesklets_submit script assits you in the construction of such an email using the user configuration file $HOME/.adesklets_submit and the command line switches. Here is an example of a valid $HOME/.adesklets_submit configuration:
# Simple demo configuration file for the submit.py script coming with adesklets. # smtp_host = 'localhost' smtp_port = 25 cc_to_self = True info = { 'author_name' : 'Belial Leviathan', 'author_email' : 'leviathan@devil.net', 'send_confirmation' : False } desklets = { 'beast' : { 'version' : '0.666.0', 'thumbnail' : 'http://devil.net/beast_thumb.jpg', 'screenshot' : 'http://devil.net/beast_screen.jpg', 'download' : 'http://devil.net/malware/beast-0.666.0.tbz2', 'host_on_sourceforge': False, 'category': None, 'description' : 'Beware the power of this desklet!' } }This is pretty self-explanatory, but here are a few less obvious points:
author_name
as much as possible, unless, of
course, you already have a pretty well-established online
identity under this name.send_confirmation
specifies if an email should
be sent back to your author_email
address whenever
your desklet is succesfully published. If the submitted entry
is rejected, you will always be written back anyway with an
explanation. Usually, the maintainer will not try to make
changes to problematic entries; it will only summarize back to
the author what was not OK.author_email
address, since this is the only one the maintainer will try to
use when contacting you, regardless of what the headers say.
Failing to supply a valid address will cause all messages to
fail to be sent to you, and all new desklet entries will be
rejected.desklets
is a dictionary of dictionaries (one
dictionary per desklet, desklets' names being the keys); all
the items referring to files (thumbnail, screenshot and
download) could either be publicly accessible URI's (this is
the preferred method), or local files, either absolute or
relative to your $HOME directory. In that case, needed files
will be attached to the generated multipart email.thumbnail
or
screenshot
images if they did not change; you can
just as easily reference the already installed images on
SourceForge:
thumbnail
is always stored under
http://adesklets.sf.net/images/NAME_thumb.[jpg|png]
screenshot
is always stored under
http://adesklets.sf.net/images/NAME_screen.[jpg|png]
where NAME
is the name of the desklet.host_on_sourceforge
value, you can
choose to have your desklet package either hosted on
SourceForge or just referenced on your site if you provided a
URI. Of course, choosing this last alternative also means you
will need to keep it in place.thumbnail
image should be a JPG
(preferably) or PNG (if you really need higher
resolutions) of dimensions lying between 190x35 and 230x110
pixels.screenshot
image should be a 640x480 JPG
(preferably) or PNG. It should put your desklet in evidence,
and thus contain no other ones.Category
is unused for now, and just
ignored.For example, Belial Leviathan would fisrt check his
beast
desklet's entry by doing something similar
to:
adesklets_submit beast
If everything goes fine, it will output the resulting
submission email on stdout
. From there, Belial can
either:
smtp_host
and
smtp_port
parameters in its $HOME/.adesklets_submit. For this, Belial would
use:adesklets_submit --send beast
One last thing: you should try to avoid sending minor corrections multiple times, especially if you use local files. It both adds to the workload of the maintainer's email server and to the management work. Please try to create a valid entry then send it, not the other way around.
From adesklets 0.4.5, you now have access to the adesklets_checkin script as well. This is the Python script that the maintainer uses for checking in all submissions. Be aware that this script is only provided to desklet authors as a convenience, to lower their submission rejection count–developers are in no way forced to use it, and may even be unable to do so, since the script was not written with portability in mind as adesklets_submit was. Look at the script header for a complete list of requirements.
adesklets_checkin has two modes of operation: interactive and non-interactive. Only the non-interactive mode will interest desklet authors. In this mode, usage is fairly simple. Belial, for instance, would do:
adesklets_submit beast | adesklets_checkin
If everything goes fine, an output similar to this will be produced:
Validation started. Please wait. Everything seems fine, but keep in mind a few things cannot be verified without human intervention. See documentation for details.
If not, you will get an exception trace with some (hopefully) meaningful explanations.
Here are the remaining problems that adesklets_checkin cannot detect and thus must absolutely be solved manually (the maintainer would interactively catch most of them, and you would have to resubmit anyway):
[1] It is probably not a good idea to give away your private email adress here; for spam-related reasons, you should probably open an account on SourceForge , or at another similar place with a serious spam containment infrastructure.
[2] It is useless to send anything else to this address; all messages that cannot be parsed by the automatic reception script are just silently dropped. Write to syfou@users.sourceforge.net instead if you want to get in touch with the maintainer.