[sword-devel] Semantic problem: real module names vs. Abbreviation=XYZ

[DM Smith]

> On Sep 1, 2015, at 9:01 AM, Peter von Kaehne <refdoc at gmx.net> wrote:
> 
> On Tue, 2015-09-01 at 01:26 -0700, David Haslam wrote:
>> Yesterday, I added a note in the wiki page:
>> 
>> http://www.crosswire.org/wiki/DevTools:conf_Files#cite_note-1
>> 
>> 1. We strongly advise to avoid using an Abbreviation that's identical 
>> to the
>> ModName or Abbreviation of any other module. It only leads to 
>> confusion, and
>> may have unexpected consequences for some front-ends.
> 
>> 
>> Peter thought that this might confuse some module developers, but I'm 
>> more
>> concerned about the unexpected consequences of the semantic problem 
>> at the
>> software.
> 
> I continue to think this is a totally unwarranted piece of advice which
> is not only wrong but also seriously misguided. It replaces finding a
> solution for a annoying but surmountable problem with confusion and
> mess for users and module makers alike + has the added "benefit" of
> totally undermining the utility of "Abbreviation" in the first place. 
> 
> We have 1000 + modules between the different repos and no one - neither
> user nor module maker - should ever be forced to wade through these to
> make sure that an Abbreviation (which after all is for user
> convenience!) and nothing else is not duplicated somewhere else in a
> language or a in a ModuleName most users might not ever want to use. 
> 
> Karl has pointed at a problem in Xiphos  (and possibly beyond) which
> will need attention, but no solution of it should ever result in the
> above "advice" being implemented as a fix.
> 
> We should have a clear and unique _internal_ module ID which is not
> replicated anywhere, based on some form of name space per publisher
> (Xiphos, IBT, CrossWire, eBible, Net, whoever) and the ModuleName and
> then, quite separate from that a free form, UTF8  Abbreviation, which
> might or might not be delivered by the module maker, but should
> certainly be open to users (re)defining for their own use.  
> 
> If a module is newly installed or its Abbreviation renamed by the user
> with a clashing Abbreviation then this is a problem, but the frontend
> should be able to take care of that. It should be relatively easy
> addition to most frontends to run a consistency check at start or
> whenever something changes and say "Ouch, you got two modules you
> choose to call "Luther", can you please fix this?" with the user then
> renaming one to e.g. Luther1912 and/or the other to Luther1984. 
> 
> URI's - the place where Karl found his problem - are in essence
> internal pieces of data and should be based on the Module ID to be
> consistent, clear and unique across the local system and preferentially
> beyond (e.g. for sword URI's on the net or wherever). At least when
> they leave the system they should not be based on Abbreviation.
> 
> A translation table for Abbreviations<->Module ID could be a flexible
> and dynamically created and updated table, depending on what modules a
> user has up and running. 
> 
> Greg's suggestion for the user to make a choice whether to have the URL
> handler run with Abbreviation or ModuleName (did I understand you
> right, Greg?) remains an option, but does not really solve the problem
> of Abbreviation clashing with each other (rather than with ModuleName).

The point of Abbreviation was that [name] had to be A-Za-z0-9 w/o spaces, punct and such and didn’t allow for localization. Having Abbreviation=KJV for a Thai module is clearly not the intent. To use it within a repo with uniqueness by language is entirely a bad idea. (While I’m not a typical user, I have every module I can get my hands on.)

Collisions are bad. There is always some nook or cranny in the code that has made some assumption about the [name].

In the case of BibleDesktop, we had used the [name] in a dropdown. Which is really silly looking with a 1000 modules. But it is worse when I added Abbreviation support. If there are ten KJVs in the list, how am I to know one from the other. (I do like Peter’s suggestion of allowing the end user to change/add an Abbreviation for one or both. But it’ll be a while before all users upgrade to a front-end that has such support.)

Right now SWORD and JSword has a single, joint local module repository for storage. This means that if there are two different modules with the same DataPath or conf name a collision occurs.

Does there need to be a local repository for each?

Does any front end do this already? If so, what are the naming conventions and pathing to it? I’d like for JSword based front-ends to use and provide the same downloaded modules.

— DM