Adding a new transliteration scheme

[Lee Nackman]

I am exploring the possibility of generating a complete transliteration for a Machzor my synagogue uses (not in time for this year!).  I'd like to use a transliteration scheme that is as close as possible to the transliterations that currently appear in the Machzor.  

I've cloned the git repository and have the system running on my local machine.  I've also found the xml files that define the demonstration transliteration schemes.  I have a few questions:

1. I haven't been able to find any documentation that explains the definition of the transliteration scheme files.  Is there any documentation?  After writing a new transliteration, how does one get the system to recognize it?
2. What's the recommended development environment for working on something like this?  I was a developer decades ago but have no experience with XQuery and eXist.

Thanks.

[Efraim Feinstein]

Hi Lee,

Welcome to the project.

On Thu, Sep 22, 2016 at 5:26 PM, Lee Nackman <lee.r....@gmail.com> wrote:

I've cloned the git repository and have the system running on my local machine.  I've also found the xml files that define the demonstration transliteration schemes.  I have a few questions:

1. I haven't been able to find any documentation that explains the definition of the transliteration scheme files.  Is there any documentation?  After writing a new transliteration, how does one get the system to recognize it?

The format is relatively simple. The only currently available documentation is in the schema file, which you can also use to validate against: https://github.com/opensiddur/opensiddur/blob/develop/opensiddur-server/src/schema/transliteration.rnc 

Validation:

$ lib/jing -c opensiddur-server/build/schema/transliteration.rnc transliteration_file.xml

The easiest way to understand the format as of now is to look at the examples that you found in the source code at https://github.com/opensiddur/opensiddur/tree/develop/opensiddur-sources/src/data/transliteration

Every transliteration schema is basically a copy of any other, because you have to define how to transliterate every letter and vowel and some special letter combinations. 

The things that may be non-obvious are:

<tr:lang> defines which languages (using 2 letter ISO language codes) the schema is defined for.

There is 1 possible tr:option element currently recognized:

<tr:option name="replace-tetragrammaton" value="off"/>

^ Whether the transliteration should replace yod-heh-vav-heh with אדוני. (on by default)

The <tr:tr> element has 2 supported attributes other than the obvious "from" and "to":

silent: The presence of <tr:tr from="X" to="Y" silent="Z"/> means that the letter X will be transliterated to Z when it is a silent letter instead of Y. Silent letters show up when a letter that is ordinarily a consonant has no associated vowel or is part of the vowel (aleph and he do that). Also, there is one special case of silent sin in יששכר. 

double: If the consonant is virtually doubled by a dagesh, replace it by the value of attribute double instead of doubling whatever is in attribute to

Feel free to ask questions on this list if anything is unclear.

Getting the system to recognize it: if you're using a running local installation, you can: 

(1) put it in the opensiddur-sources/src/data/transliteration directory and it will be scooped up on building/installation (which I admit is a bear): https://github.com/opensiddur/opensiddur/wiki/Building (requires a full reinstall)

(2) post it to localhost via HTTP according to the directions below

(3) use eXist's web-based editor, accessible at http://localhost:8080/exist/apps/eXide/index.html to put it into the database's /db/data/transliteration directory

 

1. What's the recommended development environment for working on something like this?  I was a developer decades ago but have no experience with XQuery and eXist.

If you're writing transliteration schemas, you don't need a full development environment. You don't even need to build the code. Any text editor will do, but for making sure the XML is at least well-formed, Eclipse and IntelliJ both have  XML editors. The web-based eXide edits directly in the database.

If you're willing to share the schema publicly, you can (1) email it to me and I can post it for you on app.opensiddur.org *and/or* (2) send a pull request with the schema's XML file in the opensiddur-sources/src/data/transliteration directory if you want it included in the next server release.

If you're willing to share your schema publicly *and* want to be able to edit it yourself once it's online:

1. sign up for an account at http://app.opensiddur.org (use a junk password for now and only enter information you want to be public -- no SSL!)

2. To save your schema, send a POST request to http://app.opensiddur.org/api/data/transliteration with the content of the file, being sure to specify the Content-Type header to be application/xml (curl is good for this):

curl -v -u USERNAME:PASSWORD -H "Content-Type: application/xml" http://app.opensiddur.org/api/data/transliteration -d @transliteration_filename.xml

A 201 Created response indicates success, anything else is a failure. You should get an error message with any failure.

One of the headers you get back is the Location header. That will tell you what URL the saved schema is at. To edit it, send a PUT request:

curl -v -X PUT -u USERNAME:PASSWORD -H "Content-Type: application/xml" http://app.opensiddur.org/api/data/transliteration/LOCATION -d @transliteration_filename.xml

A 200 OK response indicates success; again, error messages will be given on failure.

Eventually, I'd like to put a transliteration schema editor in the client app, one of the many things in the development backlog.

Hope this helps (and doesn't dump too much/too many options on you at once),

-Efraim