[sword-devel] Linking to General Books

[Chris Little]

Brian J. Dumont wrote:
> Not so long ago, Matthew Talbert mentioned the use of sword:// to link 
> to items from a dictionary.  I am trying to prepare an OSIS commentary 
> which references a number of other commentaries as well as a number of 
> General Book modules.  I've been trying to use Matthew's methodology and 
> extend it to General books.
> 
> It's not simple, however.  The links need to reference the General Book 
> key, which is often in ThML.  The link however, needs to be a valid OSIS 
> reference.  This restricts the link from using same characters that are 
> typically a part of the ThML key.  This includes spaces, forward 
> slashes, % signs, etc.  Note that the fact that a % sign can't be in a 
> valid OSIS reference removes the possibility of url-style encoding.

Character escaping was taken into consideration when writing the 
osisID/osisRef format. The relevant bit of the regex is: 
(\p{L}|\p{N}|_|(\\[^\s]))+

The last option permits escaping any non-space character with a leading 
\. Further to that, NBSP (0xA0), by convention, represents space (0x20) 
in osisID/osisRef. But it will need to be escaped since it's not a 
letter, number, or underscore.

> How should I prepare these modules so that in the future they will 
> properly link?  Could we decide on syntax?  If I need to go back and 
> start changing General Book module keys, then I will.  I just don't want 
> to do it twice.  Furthermore, I'd like to avoid making new modules 
> incorrectly.
> 
> I might propose something like:
> 
>     * Best  practice is that general book keys should be made to avoid
>       special characters

This is a good idea, and should be a necessary to create OSIS or TEI 
documents.

>     * osis2mod will convert all "." characters (which divide segments of
>       an OSIS reference) into "/" characters (which divide segments of a
>       general book reference) whenever the reference is to a general book.

This isn't the proper function of osis2mod. We should still store valid 
osisIDs/osisRefs in modules. The conversion of osisRefs to sword:// 
links is particular to certain render formats, so any conversion like 
you describe should take place within render filters. Likewise, decoding 
of escapes and converting between NBSP and space should take place 
within the render filters (as necessary).

--Chris