Help and FAQ
Shadow-Developer mailing list
This mailing list is intended only for the technical -- for those who wish
to know more than anyone wants to know about the inner workings of the
Shadow software family. If you wish to read or write to the Shadow
databases, for instance, heres the place to talk to others doing it.
Shadow XML specification
If you wish to read or write Shadow Desktop XML files (produced by the
conduit), you'll want to read this.
Shadow DTD XML file
You may need this; thank Chris ("the Panther") for generating it!
Shadow Plan 3.0 Translation Plugin Kit
If you would like to build (or even to help test and play with one!)
a language plugin for Shadow Plan 3.0, everything
you need is right here. In essence, all you need is a base English plugin
and Palm Constructor, a tool for editting Palm OS "resources" (forms,
strings, icons, etc). (PalmSource builds Constructor, it is not a
Codejedi tool). Simply install Constructor, open up the base language
plugin, and edit it to be correct for your language. Then when you're
done, zip it up and send me the plugin, and I'll do some magic to make
it releasable. While you're editting it, you can fully test it by sending
it to your handheld!
Mailing list requirement::
- Sign up to Shadow-developer to avoid
duplicating work with someone else! If your'e interested in working on
a plugin, dive right in and get the tools, sign up to the list, and post
that you're going to work on it; If someone else writes back that they're
also doing it, perhaps you can work on half each or the like.
- Palm Constructor
- Shadow Plan 3.0 Base (English) Plugin for editting
- Don't forget to test as you go; make a few changes, double click on
your plugin, hotsync, and see how it goes right in Shadow Plan 3.0
- You edit your plugin; for instance, download Shadow30_base.zip and
unpack it; call yours Shadow30_foo01.prc, where 'foo' is your language in
short. Like "Fr" or "Ger" or "Cz" or the like. "01" is for version
0.1 (to start with)
- After you've changed it a bit, save it as Shadow30_foo02.prc, and
so on, incrementing the 01 to 03, then 04, etc. This way if you break it
by mucking up some dialog box, just go back to the last one that worked
and redo the recent stuff, avoiding mucking it up.
- You can test it all yourself; just upload your editted plugin to
your PDA, and you can see it working *right away*! (very cool and
rewarding to you!)
- If you break it and can't go back for some reason, I can try and
figure out why its broken. I have some debugging tools to test with.
But lets be careful instead.. its a lot of work for me to determine
problems in languages I don't know :)
- Once you've got it editted to your satisfaction, send it to me
as Shadow30_foo10.zip (10 being 1.0). I will post it for BETA, so others
can take a look at your pride and joy :)
- If people report spelling mistakes, etc, you can fix them.
- Once all is more or less well, I can post as an official plugin;
if no mistakes, it coudl be version 1.0's file, or maybe you had some
reported issues and fixed them, so by then it could be version 1.1 or
1.2 or whatever, which would look like Shadow30_foo13.zip for version
- If you're using Constructor and theres a "list object" hovering over
top of a text popup or the like you wish to edit, then you can use the
"Show Object Hierarchy" menu option to get a list of widgets in the
dialog, and pick them from there.
- If you want to edit on the road, there is a Palm OS application called
RsrcEdit that lets you edit Palm applications right on your handheld;
editting the language plugin with this tool should work fine, so you could
edit the language translation right on your handheld, and see the effects
immediately when you run Shadow Plan. (Do *not* edit Shadow Plan itself
or bad things will occur and your plugin will stop working!)
- Do not add or remove any 'widget' in a form, dialog, menubar, etc.
(doing so will make the plugin stop working; it validates itself)
- Do not change any "object IDs"; doing so will kill the plugin
- Avoid moving things around; you can slide a field left or right a
touch and the plugin will accept it. Only do it if you must to make
any meaning due to long native words or the like. Avoid it at all costs!
- If you stick with changing the text, it should work very well :)
- This is copywritten material; you can't distribute your plugins
around, so you give them back to me to beta and publish. I don't mind
if you pass it to a couple of friends to help you "debug" it with grammar
or spelling, but it is not for general distribution. Before I've "fixed"
it, it can cause problems if distributed!
Shadow <-> Omni Outliner XSLT templates
Thanks to Marc-Antoine for building these!
Some tools to work with XSLT files on Mac OSX:
- Application: http://www.entropy.ch/software/macosx/welcome.html#testxslt
- CLI tool: http://www.zveno.com/open_source/libxml2xslt.html
- Applescript tools: http://www.latenightsw.com/freeware/XSLTTools/
XSLT and README details in tar-gzip format; remember to use "tar zxvf OOScripts.tgz" to get the goods if you don't know how.
Shadow database record format (version 1.4.4 and on)
Shadow database header record format (version 1.4.4 and on)
If you wish to read the records in the Shadow databases, here are the
two main structures you need. There are rules to follow which I'll post
later.. the first record is always the header record. other records can
be of any type (though currently only normal item records are allowed)
Remember, if you're working on a conduit be sure to use a pragma to set
the boundary spacing and packing.
Update March 2003 -- use the XML instead :)
The details of the PDB formats has been pulled; the database format is
not to be considered an interface or API.. We encourage you to always
use the XML as an interface since it is both standard and will forever be
published as a spec. The PDB is the handheld application's raw data and
thus by definition changes a lot (most public releases include some
EAB extension or other, or additional options on the pref fields, etc).
These web headers haven't been up to date
in a long time, and I do not want to run into versioning problems (theres
already a few tools out there with incomplete and/or broken support, since
they adhere to an older version of the headers). So as always we will
keep the specs published so you can interact with Shadow.. and that will
be via the XML.
Of course, we're getting the Mac conduit out soon, so the XML should be
excellent.. cross platform and standard. No more endian woes!