Glǽmscribe

Integration and development documentation

This is the Developer Website for Glǽmscribe.

Its purpose is to centralize all the pieces of documentation for all those who want to use Glǽmscribe’s engine outside of its official web integration, mainly by integrating it or using it as a command line tool.

What is Glǽmscribe ?
Installation
Integration
About fonts
Command line tool
Mode development
License

What is Glǽmscribe ?

Glǽmscribe (also written Glaemscribe) is a software dedicated to the transcription of texts between writing systems, and more specifically dedicated to the transcription of J.R.R. Tolkien’s invented languages to some of his devised writing systems. It has been conceived and developed by Benjamin Babut (Talagan).

The official integration of Glǽmscribe’s engine is hosted on the Glǽmscrafu website. It is a complete online transcription tool built on top of the open source engine.

Installation

The Glǽmscribe engine has currently two implementations : a ruby one and a javascript one.

Ruby

Glǽmscribe is released as a gem, so you can either install it in your current ruby installation with

gem install glaemscribe

Or, alternatively, if in a project that uses bundle, edit your Gemfile, add the glaemscribe gem and run bundle install.

Javascript

Glǽmscribe comes as a standalone library. You can download the latest version here. You can either use glaemscribe.js or glaemscribe.min.js depending on your environment.

Simply add it to your web pages as you would do with a standard js library.

Or, alternatively, you can retrieve a front-end package for npm, for an easy installation, version management and upgrade. Just use

npm install glaemscribe

Integration

Ruby

Require glaemscribe

require 'glaemscribe' # Optional if used with bundler

Load modes

# Load ALL shipped modes
Glaemscribe::API::ResourceManager::load_modes 

# Load only several modes
Glaemscribe::API::ResourceManager::load_modes("quenya")
Glaemscribe::API::ResourceManager::load_modes(["quenya","sindarin"])

Transcribe some text

# Access loaded modes
quenya = Glaemscribe::API::ResourceManager::loaded_modes["quenya"]

# Use a mode
quenya.transcribe("Ai ! Laurie lantar lassi súrinen !")
# Will give the transcription in the default charset of the quenya mode, 
# 'ds_based', which corresponds to the common charset of the fonts based 
# on the old fonts designed by Dan Smith
 => [true, "lE Á j.E7T`V jE4#6 jE,T 8~M7T5$5 Á"]

# Slightly change the behaviour by using options defined by the mode
quenya.finalize(always_use_romen_for_r: true)
quenya.transcribe("Ai ! Laurie lantar lassi súrinen !")
 => [true, "lE Á j.E7T`V jE4#7 jE,T 8~M7T5$5 Á"]
 
# Use an alternative charset for better rendering, depending on the font 
# you want to use
eldamar = Glaemscribe::API::ResourceManager::loaded_charsets["tengwar_ds_eldamar"]

quenya.transcribe("Ai ! Laurie lantar lassi súrinen !", eldamar)
 => [true, "lD Á j.E7T`V jE4#6 jE,G 8~M7T5$5 Á"]

Get mode options info

# Get a list of options proposed by the mode
quenya.options
 => {
  always_use_romen_for_r: {
    name: "always_use_romen_for_r",
    type: "BOOL",
    default_value_name: "false"
  },
  reverse_numbers: {
    name: "reverse_numbers",
    type: "BOOL",
    default_value_name: "true"
  },
  split_diphthongs: {
    name: "split_diphthongs",
    type: "BOOL",
    default_value_name: "false"
  },
  numbers_base: {
    name: "numbers_base",
    type: "ENUM",
    default_value_name: "BASE_12",
    values: {
      BASE_10: 10,
      BASE_12: 12
    }
  }
}

Javascript

Include glaemscribe

  
// Include glaemscribe engine (you can use .min.js or plain .js version)
<script src="../glaemscribe/js/glaemscribe.min.js"/>	

// Include the charsets you need
<script src="../glaemscribe/js/charsets/tengwar_ds.cst.js"/>	
<script src="../glaemscribe/js/charsets/cirth_ds.cst.js"/>	

// Include the modes you need
<script src="../glaemscribe/js/modes/khuzdul.glaem.js"/>	
<script src="../glaemscribe/js/modes/quenya.glaem.js"/>	
<script src="../glaemscribe/js/modes/sindarin-beleriand.glaem.js"/>	
<script src="../glaemscribe/js/modes/sindarin-classical.glaem.js"/>

Load modes

     
// Load all the included modes
Glaemscribe.resource_manager.load_modes()
// Or load only several ones
Glaemscribe.resource_manager.load_modes("quenya")
Glaemscribe.resource_manager.load_modes(["quenya","sindarin-beleriand"])

Transcribe some text

 
// Access loaded modes
var quenya = Glaemscribe.resource_manager.loaded_modes["quenya"]

// Use a mode
quenya.transcribe("Ai ! Laurie lantar lassi súrinen !")
// Will give the transcription in the default charset of the quenya mode, 
// 'ds_based', which corresponds to the common charset of the fonts based 
// on the old fonts designed by Dan Smith
 => [true, "lE Á j.E7T`V jE4#6 jE,T 8~M7T5$5 Á"]
  
// Slightly change the behaviour by using options defined by the mode
quenya.finalize( { always_use_romen_for_r: true } )
quenya.transcribe("Ai ! Laurie lantar lassi súrinen !")
 => [true, "lE Á j.E7T`V jE4#7 jE,T 8~M7T5$5 Á"]
 
// Use an alternative charset for better rendering, depending on the font 
// you want to use
var eldamar = Glaemscribe.resource_manager.loaded_charsets["tengwar_ds_eldamar"]

quenya.transcribe("Ai ! Laurie lantar lassi súrinen !", eldamar)
 => [true, "lD Á j.E7T`V jE4#6 jE,G 8~M7T5$5 Á"]

Get mode options info

// Get a list of options proposed by the mode
quenya.options
 => {
  always_use_romen_for_r: {
    name: "always_use_romen_for_r",
    type: "BOOL",
    default_value_name: "false"
  },
  reverse_numbers: {
    name: "reverse_numbers",
    type: "BOOL",
    default_value_name: "true"
  },
  split_diphthongs: {
    name: "split_diphthongs",
    type: "BOOL",
    default_value_name: "false"
  },
  numbers_base: {
    name: "numbers_base",
    type: "ENUM",
    default_value_name: "BASE_12",
    values: {
      BASE_10: 10,
      BASE_12: 12
    }
  }
}

About Fonts

Font integration, particularily webfont integration, is of your responsability. We do not own or are the authors of any font dedicated to the transcription of Tolkien languages and writing systems.

Still, you can find there on Glǽmscrafu a few of the fonts we slightly modified to make them work with the distributed official modes for Glǽmscribe.

Using the command line tool

 glaemscribe help 

  NAME:

    glaemscribe

  DESCRIPTION:

    Glǽmscribe (also written Glaemscribe) is a software dedicated to the
    transcription of texts between writing systems, and more specifically
    dedicated to the transcription of J.R.R. Tolkien's invented languages 
    to some of his devised writing systems.

  COMMANDS:
        
    help       Display global or [command] help documentation           
    info       Displays information about an embedded mode              
    list       Lists all available embedded modes               
    transcribe Transcribes a file (default command)     

  GLOBAL OPTIONS:
        
    -h, --help 
        Display help documentation
        
    -v, --version 
        Display version information
        
    -t, --trace 
        Display backtrace when an error occurs
          
  AUTHOR:

    Benjamin Talagan Babut

glaemscribe help transcribe

  NAME:

    transcribe

  SYNOPSIS:

    glaemscribe transcribe file [options]

  DESCRIPTION:

    Transcribes a file with the given options. You can use '-' instead of a file name to work with stdin.

  OPTIONS:
        
    -m, --mode mode 
        The name of the embedded mode to use. See the 'list' command to get a list of available modes names.
        
    -c, --charset charset 
        The name of the charset to use. If not given, glaemscribe will load and use the default charset defined in the mode.
        
    --modefile modefile 
        Use a custom mode file instead of an embedded one. The file extension must be .glaem .
        
    --charsetfile charsetfile 
        Use a custom charset file instead of an embedded one. The file extension must be .cst .
        
    -o, --options name1:value1,name2:value2,... 
        Pass options to the transcriptor (see the mode options documentation).

Mode development

If you’re interested in developing modes for Glǽmscribe, please check the official mode authoring documentation on Glǽmscrafu. We have chosen to separate that specific part of the documentation because we have considered that it deals with matters of usage development rather than integration development stricto sensu.

License

Glǽmscribe is released under the terms of the GNU Affero General Public License :

Glǽmscribe (also written Glaemscribe) is a software dedicated to
the transcription of texts between writing systems, and more 
specifically dedicated to the transcription of J.R.R. Tolkien's 
invented languages to some of his devised writing systems.

Copyright (C) 2015 Benjamin Babut (Talagan).

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, either version 3 of the License, or
any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.