Some information here is quite important, so you should read it before you start using Gemse for serious tasks.
Basically, it works like this: You enter a command into the input box (which you find at the top) and as soon as the command is complete, it gets executed and the box cleared. Many commands consist of one character only, some are two or three characters in length and some have arbitrary length and have to be terminated by hitting enter. Be aware that the input box is not a normal input box as you are familiar with. You can not use the arrow keys to move the cursor and you can not use the backspace key to remove a wrong character you entered. Often, one manages to mess up the input. In such a case, one has to hit the escape key in order to clear the input field. So, the escape key is your friend.
Another important concept in Gemse are the modes. Initially, Gemse is in the edit mode. There are more modes: The attribute mode, the visual selection mode and different insert modes. Every mode has its own commands, so hitting a key in edit mode can have a different meaning than hitting the same key in insert mode. Except for the edit mode, any mode can be terminated by hitting the escape key while the input box is empty.
Gemse's window is separated into parts which are called views. An arrangement of such views in the window is called a viewset. In the edit mode, you can choose among predefined viewsets. It is also possible to hide a single view of the current viewset.
First, Gemse is only useful to people who can see. On the other hand, I want that also people can use Gemse who can see something but still are visually impaired, for example because of color blindness. The solution is to provide different stylesheets. In the future their will be a monochrome stylesheet and perhaps also a black/white one.
Persons who have problems using a keyboard can perhaps still use gemse. The names of the commands can be adapted. The requirement is that the user can insert unicode characters in some way. However, Gemse can not be used with a pointing device. (Except if you use the pointing device to stear an on-screen keyboard which generates unicode input for Gemse.)
Here some important notes on how Gemse loads and saves equations, so you do not destroy your data.
Loading and saving has just been reimplemented and has to be tested. Please be careful, make a copy of the document which contains the equation you want to edit before you open it in Gemse. If you encounter problems, please report them, so bugs can be fixed.
You can open equations from any XML document that can be loaded by Firefox. You have to reference them by URL. Depending on the protocol, you can also save the document or Gemse can even check whether a document has changed while you were editing one of its equations.
Gemse loads equations. But they are not documents (or files) on their own, they are contained in a document. One document can contain more than one equation. To make things more complex, Gemse has to parse the entire document and keep it in memory while you edit the equation. When you save the equation, the document is written back entirely. The problem arises when you open more than one equation from the same file. In this case, Gemse must load the document into memory only once. Normally, you do not need to care about that, since it works as you would expect it. However, you should know how it works anyway.
When you load an equation from a document, Gemse first checks whether the document has already been loaded into memory. If not, Gemse opens (by reading the file or retrieving it via HTTP) and parses the document. Then it locates the equation in the document and creates a copy of it which the user the can edit. Gemse remembers for every open equation where it came from within the document.
When you close an equation, Gemse checks whether any other open equation originates from the same document. If not, the document is closed, i.e. removed from memory.
When you save an equation, Gemse first makes a copy of it. The old equation in the document is then replaced by this copy. Finally, Gemse serializes the document and writes it to disk or PUTs it via HTTP.
To sum up, we can say that a document is in Gemse's memory if and only if there is an open equation from this document. If this state changes, Gemse parses the document into or drops it from Gemse's memory. When you save an equation, the document is written.
You must be aware that Gemse only reads a document from the filesystem or from the network if it is not already present in memory. Say you load an equation from a document and then you change the document with another application. If you now load more equations from this document, the old version will be used, since it is already represented in the memory. If you want to work with the new version of your document, you have to close all equations of this document, so that it is removed from Gemse's memory.
Be aware that it is never a good idea to change a document outside of Gemse while you still have open equations belonging to this document. Do not open equations from the same document with different instances of Gemse, since they have no idea from each other.
URLs that begin with http:// are treated as local
files. Equation from such files can be saved. When you give an URL
of a local file when saving, Gemse checks whether the file already
exists and prevents you from overwriting it. If the file has changed
since you loaded, Gemse refuses to save.
Documents with URLs that begin with http:// are loaded
via a HTTP GET request. They are saved by sending a HTTP PUT request.
If saving fails, this is not reported, Gemse claims that saving
was succcessful! You are not warned when you save such a document
that already exist or when the document has changed since you loaded
it.
You can load all other documents that can be loaded by Firefox. It is not possible to save them.
If you have installed Gemse as Firefox extension, you can type
chrome://gemse/content/editor.xul in the address bar in
order to start Gemse. Like this, the Gemse window is embedded in the
browser window. This also allows you to run Gemse in a tab.
If you have installed Gemse as Firefox extension, the contextmenu
has an additional entry called Open in Gemse
. Open a
document which contains equations in Firefox. Then you can open the
context menu on an equation and hit Open in Gemse
. This loads
the equation in Gemse. If an instance of Gemse is alerady running,
the equation is loaded in it, otherwise Gemse is started.
You can do the same on any element of the document. All equations which are descendants of the element you opened the contex menu on are loaded. If you select part of the document, all equations which are (partially) part of the selection are loaded.
When you save an equation which has been loaded using this method, the respective document is serialized and saved.
Danger: Be careful with documents whose DOM gets altered in some way. This means, you must deactivate scripts that alter the document. When loading the equation, Gemse simply remembers a reference to the document in Firefox's memory. When you save, the new equation is put directly in this document and then the document is saved to disk. So all changes of the document are saved whether they come from Gemse or not.
Lets assume you installed Gemse as a Firefox extension. (It works
along the same lines if you use XULRunner.) Then you can invoke Gemse
on the command line by calling firefox with at least one
of the following arguments:
-gemse-gemse-load URI-gemse-do COMMANDSIf an instance of Gemse is already running, no new instance is started. Instead, the running instance is informed and executes your whishes.
Somehow you must be able to insert all the unicode characters you need. For example, if you need a ∀ in a formula, you must be able to insert it. There are several ways to do that. If your keyboard has a key for the character you need and you have configured your opperating system correctly, you only need to press the key, of course. But what to do if you do not have such a key? There are at least three ways:
One way is to copy the character from somewhere else and then paste it into the input box. But I am sure, nobody wants to do that.
The best and recommended way is to configure your operating system so it allows you to input such characters by hitting a sequence of keys. For example if you hit \forall it inserts ∀. I do not know about Windows or Mac, but for Linux, I can provide one way to do that.
There is another way implemented
in Gemse directly. To use it, you have first to activate it. Open the
file editor.xul and watch out for the line containing
]]>. If it is
commented out, i.e. if it is surrounded by <!-- and
-->, you must remove those comment signs. It may be
that the comment signs are not there from the beginning, in this case
you do not need to change this file. The first
line below shows how it may look like and the second one how it has to
look like afterwards:
-->]]>
]]>
Save the file and open inputSubstitution/core.js. At
the beginning of the file, set inputSubstitutionActive
to true if it not already is. This means that you must replace
inputSubstitutionActive = false; with
inputSubstitutionActive = true;. Now you are ready to use
the input substitution feature of Gemse.
The input substitution allows you to enter a character by
its unicode codepoint. Additionally, it allows you to enter characters
by name using an internal lookup table, called the input substitution table.
By default, this table is created by importing the names from the file
inputSubstitution/w3centities-f.ent which is a copy of
the
large set of DTD entity declarations
out of the (at time of writing) working draft of the W3C about
XML Entity
Definitions. If you want to extend this table, you can add more
entries into the object inputSubstitutionTable at the
beginning of the file inputSubstitution/core.js.
The actual substitution works similarly to XML entities. First you
have to insert a &. Then you have two chioces. The
first is to enter #x followed by the codepoint (in
hexadecimal notation) of the character you need. The second is to
enter its name as it is defined in the substitution table. In any way,
you have to terminate with a ;. If Gemse does not know
what todo with your input (for example because you entered a name not
present in the substitution table), your input simply gets removed
without placing a character, so you can try again.
To clarify the whole procedure, here some examples:
α becomes α.
α yields α too. If you need a
∉, use ∉ or ∉.
Gemse requires Mozilla. That means, you either need Firefox 3 or you have to use XULRunner 1.9.
Basically, there are three variants how to use Gemse.
For this variant you need at least Firefox 3. Run the demo on
Gemse's website or download the minimal version and open
editor.xul in Firefox. This allows you to check out
Gemse without risk, since Firefox prevents it from accessing your
system. However, because of the same reason, not all features
work.
You can install Gemse as a Firefox extension, if you have at least Firefox 3. This works as easy as for all Firefox extensions, you can directly install it from Gemse's website.
In order to run Gemse, go to
chrome://gemse/content/editor.xul. If you want to read
the documentation, use the command :help or go to
chrome://gemse/content/editor.xul.
Running as an extension, Gemse can access your file system, so you can load and save files on your filesystem. Gemse also provides an overlay for the browser. When you open the context menu on a website, you can select the new entry "open in Gemse". If you do that on a MathML element, it gets opened in Gemse. If you do it on a selection, all selected MathML elements get opened in Gemse, including the ones that are only partially selected. If you do it on an element that is not part of an equation, All MathML elements that it contains are loaded.
If you do not like Firefox or you want to have Gemse separated from
Firefox, you can run it as a XULRunner application. Just download the
XULRunner version from Gemse's website, unzip it in an empty folder
and run xulrunner-1.9 application.ini.
Running Gemse as XULRunner application, it can access your file system, so you can save and load files from your filesystem.
If you want to modify Gemse, you can also download the source
package which contains Gemse in a directory structure as I use it for
development. The directory src_common contains the main code
and documentation. src_FirefoxExtension and
src_XULRunner contain files only needed by the Firefox
extension or the XULRunner application respectively. The
test_* directories contain symbolic links to the
src_* directories. In
test_XULRunnerApplication you can run xulrunner-1.9
application.ini. test_FirefoxExtension can be used
as a firefox extension directly. For this you can create a text file
called Gemse@andonyar.com
in the extension folder of your Firefox profile directory, which
contains the full path to the test_FireforxExtension
directory. After restarting Firefox, the Gemse extension should be
installed. Like this, you can modify Gemse and see the changes
directly in Firefox, without removing, repackageing and reinstalling
the extension.
The author of Gemse is Urs Holzer, you can contact him via urs@andonyar.com.