DM Smith wrote:[...]

Apologies for not noticing your question. I'm cross-posting to osis-user 
since this may be of general interest
[...]

Generally, annotateRef uses the same format as osisRef. But, where 
osisRef says "I point/refer to REF", annotateRef says "I am 
about/discuss REF". The annotateType list is in the schema, but 
generally commentaries are "commentary". If more values of annotateType 
would be useful, we'd love to hear about them.

If you have a chunk of text discussing a passage, you would place the 
annotateRef & annotateType attributes on the container of that passage. 
E.g.: <div osisID="Matt.1!A" type="section" annotateType="commentary" 
annotateRef="Bible.KJV:Matt.1.1-Matt.1.5">...</div>.

Here I've got a chunk of text, which I'm saying maps to a portion of 
Matt.1 in my ref system (e.g. Bible.KJV), and I'm identifying this 
section of my commentary as the "A" portion of my Matt.1 commentary. And 
"Matt.1!A" is a "commentary" on the text in osisIDs "Matt.1.1-Matt.1.5" 
of the work "Bible.KJV".
[...]

osis2mod is really JUST an OSIS Bible to Sword versekey module importer. 
If anyone actually writes an OSIS commentary that we could import that 
isn't set up like an OSIS Bible, we would write an importer. The small 
wrinkle in this is that commentaries can potentially be much more 
complex than Bibles and we might need to use the treekey system instead 
of versekey. In that case you might have decent success using the 
xml2gbs (OSIS/ThML to Sword treekey module importer) instead of 
osis2mod. Of course, this in turn would benefit greatly from the 
addition of treekey to versekey mapping within Sword, which is currently 
on the Todo list.
[...]

That kind of markup isn't best practice from the OSIS standard's 
standpoint, but it's perfectly acceptable to Sword. :) It produces the 
same resulting module as we would hope to produce from a best practice 
conformant OSIS commentary document, but you're removing a lot of the 
potential ambiguity inherent to real commentaries by structuring it in 
Bible-format.

Hope that helps.

--Chris