[Pkg-crosswire-devel] Libsword - utils, examples, test and bindings

[Jonathan Marsden]

Matthew Talbert wrote, quoting me:

>> ... my feeling is that overall it is better to leave the module
>> creation tools in the main libsword7 package, so that everyone has
>> them who might want to explore their use.  It's not as though they
>> take up megabytes of disk space (at least under Linux).

> Previously, diatheke was in its own package. It seems to me that it
> should be moved into libsword with the rest of the utilities. It's
> primary purpose these days is to help in module development, to see
> exactly what the engine is returning for a particular reference in
> order to troubleshoot. It's role for web stuff is nowhere nearly as
> prominent (I haven't heard of anyone actually using it for that). This
> probably raises the question of where to put diatheke.pl, which is (I
> think) an example of how to use diatheke to create a web site. I don't
> know where that should go. But I do feel that diatheke is a
> tremendously useful tool for module developers and should be put with
> the rest of the module creation utilities.

diatheke is also a front end in its own right.  There is no other text
mode SWORD front end that I am aware of.  And diatheke exists (and
works!) on machine architectures on which I doubt the main GUI front
ends will ever run (m68k, mips, etc).

BTW, I see diatheke as useful not just for module developers, but for
end user troubleshooting too -- if the big complex GUI frontend they are
using has an issue, the user will often be able to (either by
themselves, or after a request from a dev) determine whether the issue
is in the module data or in the front end application, by displaying the
same information in diatheke.

However, historically diatheke has been packaged separately (since at
least Ubuntu dapper), so current Debian and Ubuntu users expect it to
exist as a separate package.  I'm not sure that it is worth changing
that approach just because it is also useful to module creators.  In the
best case situation, the developer of a new module does not need
diatheke, they just discover and use the *2mod tools.  When they need
troubleshooting and diagnostic help, they will (presumably) turn to
documentation, which should direct them towards diatheke as a helpful
additional tool to test their new modules with.

I think there is much that is basically right about the existing
(pre-2009) approach to packaging SWORD and related software and data.
There are exactly 4 kinds of SWORD-related packages: (a) a backend
library package (libswordX); (b) front end packages (whether GUI- or
text- oriented, and one could imagine a future audio front end that
reads modules to you, even!) which use the library to access SWORD data
modules, and (c) module packages congtaining SWORD data modules which
the library can access and present to a user via a front end
application, and lastly (d) a package only used by software developers
compiling software that uses the library (libsword-dev).

In general, most users just install a front end application ( diatheke,
BibleTime, Xiphos, ...) and the library is installed automatically as a
dependency.  They can then either install some data modules from
packages, or they can use installmgr or its GUI equivalent to download
module data for themselves.

This is pretty clear, and pretty simple.  I think the benefits of
changing that overall approach need to be very clear, in order to
justify our making any such changes.  Bundling a front end (diatheke)
with the library changes this model, doesn't it?

BTW, didn't we have a discussion about how to partition stuff from the
SWORD tarball into binary packages, in February?  I didn't realize this
was still something that needed further discussion for 1.5.11 packaging.
 We now have such packaging in Debian experimental, based on the
approach we took back in February.  That doesn't mean we *can't* revisit
this, but it perhaps means we should be careful not to make unnecessary
changes.

> Would it be useful at all to package a few examples of source files
> for the module creation utilities? 

That's more a question to ask novice module developers than to ask us
packagers -- but I think it is a good one to be asking :)

The answer perhaps depends on how easily such folks currently find the
CrossWire wiki info about the various file formats and utilities?  Do
novice module writers currently rapidly find their way to such info as
http://www.crosswire.org/wiki/DevTools:Modules ?  If not, how can we put
good signposts towards it, where such folks will see them?  In a recent
post I made on sword-devel, I said that I'd like to see much of the wiki
documentation content bundled with the library, and so packaged with it
too.  However, that probably depends on the SWORD developers, unless we
choose to "be a bit radical" and include that wiki content in our
packages anyway (we could, since it is published under GNU FDL)!  I'd
prefer to persuade the SWORD developers to include it in their release
tarballs, though.

> I don't know how this stuff is usually handled for packaging. We
> don't even have (in my opinion) good small, comprehensive samples to
> include at this point, but if there were some, would it be
> appropriate to include them?

Yes, if they are small, they can (and probably should) be put in
/usr/share/libsword7/examples/  (and mentioned in the relevant utility
man pages, so people find them!).  When it comes to utilities (vpl2mod)
that require an input file with one line for every verse in a
(KJV-versification) bible, plus header lines... that's probably too big
a file to be included by default as an example!  For that, one can
suggest the user does something like

  mod2vpl KJV 0 >example-vpl-file.vpl

to generate their own example file :)

Perhaps one way to start gathering example files would be to add such
examples to the CrossWire wiki?  Then, if we can get the wiki content
included in official SWORD source tarballs, or if we decide to add it to
our packages ourselves, we'd automatically have the example files in
there too.

Jonathan