[sword-devel] Generating / displaying Sword

[DM Smith]

On Jan 12, 2013, at 4:26 AM, ARA Jamieson <jamie at critos.co.uk> wrote:

> I'm a newbie with OSIS / Sword, so apologies if this is a dumb question or
> I'm posting it to the wrong place.
> 
> I'm currently converting USX to OSIS using my own processing, then using
> osis2mod.pl

I'm not familiar w osis2mod.pl. Is this a wrapper around osis2mod? If it is not calling SWORD's osis2mod then all bets are off on getting a good answer.

To provide an accurate answer (not sure if that is needed) it may be helpful to know the version of osis2mod and the version of xiphos and the OS that you use.

I think USX is a variant of SFM? If so, the wiki entry might be helpful:
http://www.crosswire.org/wiki/Converting_SFM_Bibles_to_OSIS

> to generate Sword, and then displaying the results using Xiphos
> on PC.  As a test, before I start with non-English language texts, I'm
> working with a copy of the King James Version, since it makes it easier to
> see what's going on.  The first few hundred characters of the OSIS appear
> below :-
> 
> 			<?xml version='1.0' encoding='UTF-8'?>
> 			<osis xmlns=blah>
> 			<osisText osisIDWork='TESTKJVBible'
> osisRefWork='TESTKJVBible' xml:lang='en' canonical='true'>
> 			<!-- Conversion run: Thu, 10 Jan 2013 09:09:25 +0000
> -->
> 			<header>
> 			  <work osisWork='TESTKJVBible'></work>
> 			</header>
> 			 <div type='book' osisID='Matt'>
> 			     <title type='main'
> short='Matthew_A'>Matthew_B</title>
> 			     <div type='tableofContents'>Matthew_C</div> 
> 			     <title short='Matt'> Matthew_D</title>
> 			     <div type='book'><title type='main'> The Gospel
> According to St. Matthew </title></div> 
> 			     <chapter> 
> 			          <p> <verse osisID='Matt.1.1'
> sID='Matt.1.1' /> The book of the generation of Jesus Christ, the son of
> David, the son of Abraham. <verse eID='Matt.1.1' >
> 			                  <verse osisID='Matt.1.2'
> sID='Matt.1.2' /> Abraham begat Isaac ...
> 
> (I've hacked this manually a bit, because I needed to distinguish the
> various occurrences of "Matthew" in the output to help me understand what
> was coming from where.)
> 
> I thought this was in line with the OSIS spec.

If you ran it through an xml validator, providing the schema, then it is in line with the spec. That doesn't mean that it is proper OSIS (see answer to last numbered question) That doesn't mean that it plays well with any SWORD frontend.

> , but maybe it isn't, because
> Xiphos isn't display what I might have expected / hoped for - at least when
> it comes to chapter headings and titles ...

There are problems in the SWORD engine when it comes to whitespace differences when toggling headings. It doesn't appear that is your question. So I'll skip past that at this time.

Also, I suggest getting the nightly build of Bible Desktop. It handles the text differently than xiphos as it is based on JSword not SWORD. It should help you understand your markup better. Please note that JSword does not set the standard for display of a SWORD module. xiphos is a lot closer to what would be considered standard.


> 
> 
> 
> 1.	"Chapter 1", along with the "1" for verse 1, come out before any of
> the headings.

Most SWORD (and JSword) frontends create their own headings. It appears that is what is happening here, since you don't provide a title "Chapter 1" in your text. For Bible Desktop (a JSword frontend), our next release will be styling these differently so that it is obvious to developers.

Originally a SWORD module consisted only of verse text. So manufactured titles were very reasonable. Some more recent texts include titles. This means that frontends may duplicate that effort.

> 	
> 2.	I'm seeing an awful lot of headings - Matthew_B, Matthew_C,
> Matthew_D and "The Gospel ...".  I assume this means I'm generating too many
> "title" tags, but I'm not sure which of these I can safely get rid of.

All text will be displayed to the user at some point. If it is in a note or title, there is a toggle for that. If you don't want text to appear, then don't include it in your module.

You may want to move some of your titles to an attribute on the element, if supported. Our KJV does that.

Titles at the beginning of a book or chapter are put into verse 0 or verse 1 depending on how it is marked up. There are two pages in our wiki that'll help you understand how to control that:
http://www.crosswire.org/wiki/OSIS_Bibles
http://www.crosswire.org/wiki/Osis2mod

> 
> 	
> 3.	I'd assumed that the "tableOfContents" tag was used to mark the
> place in the text to which a table of contents should point.  Is this
> correct?  If so, clearly I'm using it wrongly, because Matthew_C is being
> displayed rather than simply being used internally to sort out the linkage.

SWORD does nothing special with a table of contents per se. It is merely marked up text. While the default, the div should have canonical="false" on it. It should be put into chapter 0, verse 0 (by osis2mod) and probably will toggle with the heading. This would be the expected behavior.

> 	
> 4.	I'm wondering about the fact that I have two <div type='book'>s.
> The first of these is there because we genuinely are at the start of a book.
> The second arises because the USX / USFM contains an \mt tag, and I'm
> interpreting section Appendix F of the OSIS manual as saying that's what's
> needed; but perhaps I've got that wrong.

In OSIS a title should appear w/in the container that it entitles.
You should not have nested book divs. A book div should wrap the entire book. Likewise for the chapter element and the chapter div (the chapter div shouldn't be used for a Bible, but rather a commentary)

> 
> 
> Any comments would be very gratefully received.
> 
> ARA "Jamie" Jamieson

In Him,
	DM