[sword-devel] Making Import Easier

[Chris Little]

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, 
use mod2imp.

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 
the documentation.)

--Chris