[sword-devel] osis2mod output (Bisaya-Inunhan NT)

[DM Smith]

Jonathan Marsden wrote:
> Wearing my shiny new SWORD module creator hat:
>
> My rough draft (sans footnotes and titles) OSIS conversion of the 
> Bisaya-Inunhan NT is valid OSIS 2.1.1 per xmllint.  However, I'm 
> seeing some output from osis2mod that I need help interpreting.  
> Currently it says:
>
>   You are running osis2mod: $Rev: 2325 $
>   re-versified III John 1:15      as III John 1:13
This is informational, perhaps a warning. It is saying that III John 
1:15 is not in the versification that you chose and that 3 John 1:13 was 
the last verse that it wrote to the module that was before 3 John 1:15.
If your input had 3 John 1:14, as an individual verse, then I'd say you 
have hit a bug. I found this bug in the latest RC and fixed it in head, 
revision 2353. It finds not the right verse, but one before it.

I recommend building from head (maybe there'll be another release 
candidate soon)

>   Appending entry: Jude:
This is also informational, perhaps a warning. It pairs with the 
"re-versified ..." message and should not have read "Jude" under any 
circumstance. It should have read "Appending entry: III John 1:14" This 
too was fixed in revision 2353.

>   re-versified Revelation of John 12:18   as Revelation of John 12:16
>   Appending entry: Rev.13:
>
> (1) Enhancement request #1: I do not know if these are informational, 
> warning, or error messages.  Prefixing them with INFO: WARN: or ERROR: 
> would be really helpful in this regard.

Good idea.

>
> (2) Enhancement request #2: osis2mod does not seem to exit with an 
> exit code that reflects the worst issue found during the run -- I'm 
> seeing an exit code of zero despite these messages.
I'm not sure about this one. If a fatal error is encountered, it is 
definitely appropriate to have a documented, non-zero exit code. If 
there were "recoverable" problems (e.g. re-versification), I don't know 
that it is appropriate to have a non-zero exit code. I have always 
thought it was the UNIX tradition to use a non-zero exit code when the 
results of the run could not be trusted.
>
> (3) Enhancement request #3: If these messages could include a line 
> number from the original OSIS input file, or a line or two of it at 
> the point of the info/warning/error, that would really help.
Giving context to the error is fine.

Input files are not required to have line breaks. Some have very long 
lines and because of the potential richness of the markup the input 
might be difficult to read.

I'm not sure how to give a better context.  Ideas welcomed.

The messages sometimes give "normalized" verse references and other 
times give osisIDs. If the references were all osisIDs (this is OSIS 2 
Module after all) then it would be trivial to find the offending spot 
with something like:
egrep 'osisID="[^"]*Matt.1.5' input.xml

Would that work?
>
> NOTE: None of these are necessities for 1.6; just ideas for the future.
>
> BOTTOM LINE: Is re-versifying these things "bad"?
No. It means that the versification (probably the KJV) does not include 
those two verses as indexable in the index, but to be faithful to the 
text (not the versification) they are going to be appended to the 
nearest, prior verse.

At this time, they are an indication that another versification might be 
better. I don't know if merely trying each of the available 
versifications is a good idea or not. Asking here which to use based on 
the output of the program might be a way to find the best versification.

> Do I need to get osis2mod to run with no output before I can consider 
> the module "clean"?
No, but you need to understand them and decide whether you can live with 
the results. If there were alot of re-versification messages then it 
would be best to find a better v11n scheme.

>  What is really going on here?  
See above.
> Is there a Wiki page or other documentation that explains these 
> messages that I should have read?
The wiki page,www.crosswire.org/wiki/Osis2mod, should have it. That's a 
great idea. I am using the wiki as the man page for the program.

If I don't get to it soon, feel free to add to the page. Perhaps a 
section on Errors, Warnings and Informational Messages with an example 
message and another on Return Codes. I'll be glad to fill in the details 
and keep it up to date.

Two other pages that might be of interest are:
www.crosswire.org/wiki/OSIS_Bibles - gives best practices
and
www.crosswire.org/wiki/Alternate_Versification - explains av11n, though 
this page is in it's early stages.

Hope this helps.

And many thanks for your suggestions.

In Him,
    DM