[sword-devel] Making Import Easier
chrislit at crosswire.org
Mon Apr 6 19:28:09 MST 2009
Jonathan Marsden wrote:
> Greg Hellings wrote:
>> I was just chatting with Matthew Talbert about the process of making
>> module import a much easier task than it is now. ...
> Interesting. To me (I am probably a very atypical module creator, but I
> have played with the mod2* and *2mod tools as part of packaging them!),
> the hard part was that the various "source" forms of modules are not
> well documented, or if they are, finding that documentation takes work.
> For example, tei2mod. TEI - OK, Google it, discover what it is, find
> out that there is a schema for that... but then it turns out (after
> further googling) that the schema that tei2mod uses is a special
> SWORD-unique variant of it :) And the output of tei2mod --help does not
> point the user towards that schema, or any related documentation, and no
> man page for tei2mod was provided with the library (but see below!).
> Also... why is there no mod2tei for the inverse conversion operation?
> This process of discovery appeared to me as somewhat "unfriendly"
> (unnecessarily difficult). Normal humans might well decide to give up
> before I did.
Basically, none of the source formats are of our invention, they're
standards maintained by other groups and documented by other groups.
(The IMP format is the exception, but it's very simple and well
documented to the extent that it is documentable at
http://www.crosswire.org/wiki/DevTools:Modules.) We do offer basic
documentation for all formats and about their use within Sword in the
Wiki. We do expect users to actually read this documentation or, failing
that, ask questions via any of the many support channels.
Our use of TEI in particular does not require the use of *our* TEI
schema. Obviously it would make the most sense for a new user of TEI to
check our Wiki, where everything will be spelled out. But, in
investigating TEI, one should quickly come to the realization that there
isn't "a shcema". TEI is specifically designed to be modular, and its
their intention that applications of TEI roll their own schemata or
dtds--which is precisely what we've done.
Any standard TEI P5 doc should work fine for our importer (to the extent
that we support TEI, which is to say, for dictionaries--as our Wiki
shows). The additional attributes in our version of the schema are just
that: additional. They aren't a necessity, but are useful for marking
Bible references in a standard format (namely, in the OSIS way).
There aren't any plans to write mod2tei. mod2osis exists in order to
encourage adoption of OSIS. If you want to see module internal markup,
Also, I've posted some example docs and announced them in the past, but
it does seem prudent to link them from the Wiki, so I've just done that.
>> they have trouble finding the Windows build of the binaries,
> This sounds more like an advertising/publicity/documentation issue than
> a technical one? Or it could be a packaging issue -- how are such users
> getting their SWORD library onto their Windows PCs, and doesn't it come
> with the utilities?? If not, why not?
Windows builds are static and found at
http://crosswire.org/ftpmirror/pub/sword/utils/win32/. This is linked
from the Wiki documentation, of course. If anyone wants to make this
more prominent & obvious they're welcome, but I think it's sensible to
find this link within the module making documentation. (You're not
really ready to use the utilities until you've at least skimmed some of
More information about the sword-devel