[sword-devel] How broadly do we define "API"

[Chris Little]

Dmitrijs Ledkovs wrote:
> 2009/6/10 Jonathan Marsden <jmarsden at fastmail.fm>:
>> At the level of utilities that are used in scripts, and whose command
>> line parameters are therefore in some sense an "API" for those who write
>> scripts using them, the very recent (post 1.6.0) change to osis2mod that
>> adds the -d option *already* broke "osis2mod API compatibility" :)
>>
> 
> Well *adding* function calls, flags etc does not break API. *Changing*
> behaviour of existings flags, function calls or removing them breaks
> api.
> 
> My 2 UK pence
> 

I think I'd further say that we don't consider command line parameters 
part of the API. I think when we say API and refer to API stability, we 
mean it in the standard sense that programmers mean it, i.e. function 
calls, methods, etc. within the Sword library.

As Dmitrijs suggests, I think we should, in general shy away from 
modifying existing command line parameters in a subtractive sense. So 
existing parameters *should* be maintained in general, but additions 
like -d on osis2mod are fine. Trying to make the utilities more user 
friendly, accessible, and generally stable are all admirable objectives, 
but fundamentally these are internal tools used by us for content 
creation and doing that well is far more important than maintaining any 
sort of argument stability for hypothetical script writers.

--Chris