Maintainers: Paul Libbrecht
Table of Contents
jEditOQMath is a package to bundle the jEdit editor along with special facilities to create OMDoc documents for use in the ActiveMath learning environment.
Writing documents with jEditOQMath involves writing OQMath documents. The latter are, almost, OMDoc documents. OMDoc is an XML syntax for mathematical documents which targets both textual and formal content. The difference between OQMath and OMDoc is in the mathematical formulae, where OQMath formulae are readable and user-typable.
The following features are currently provided as part of jEditOQMath:
Automated start and installation of jEditOQMath using the JNLP technologies.
jEditOQMath is a pack of quite many open-source packages, please see the project home page at http://www.activemath.org/projects/jEditOQMath. You'll find there a list of ingredients, their license, and for more technical and legal details.
Table of Contents
jEditOQMath has been planned to support authors write content for the ActiveMath learning environment (see http://www.activemath.org/). We thus suppose that you have a copy of ActiveMath running locally on your machine.
It is possible to use jEditOQMath without ActiveMath, however, the facilities that explicitly target integration will simply not work. The wealth of XML-editing will still be yours, and usage of OQMath and QMath will still work (see math-input).
In the ActiveMath home page, you will see that you can request a copy of ActiveMath and will then have to follow the installation instructions included in the READMEs directory. Make sure your ActiveMath is already running and you can see a little bit of content (e.g. search for "plus" in the dictionary).
Do take the time to adjust the path to ActiveMath home within the OQMath plugin settings:
>
Then click then press the
button and navigate to the directory where you have installed ActiveMath
(the one containing the conf directory).
You should follow the installation instructions and, in particular add
the following lines to your ActiveMath-individual.properties file so that your
ActiveMath reloads for authoring:
mbaseRef.read-only = false OmdocJdomMBase.read-only = false
Setting these properties avoids the need to run buildIndex at every content change which is, however, better for a server-like environment which may need a faster restart.
It may also be wise to declare your preferred user-name to be an author
so that some extra facilities are activated (including search and
instant item opening). Supposing the ActiveMath user-name you use is
poincarre, you should insert the following lines
in ActiveMath-individual.properties:
user.authors = poincarre
user.admins = poincarre
In this tutorial we will work with a baby collection to play with.
Invoke > >
.
A next screen will ask you the name of your collection and will
create it, as well as install its content-descriptor into ActiveMath.
We propose to create a small theory about free groups
as presented, for example, at http://en.wikipedia.org/wiki/Free_group.
As a result, we suggest that you name your collection free_groups.
After this, you need to include the content, that is, you need to
copy the Content-descriptor file ContentDescr_free_groups.properties
into the conf directory. If on a Unix platform, making a symbolic link
is a bit better (but a Macintosh alias is not a symbol link!).
Adding a content-descriptor is a configuration change, as a result,
ActiveMath needs to be restarted after that.
Directing your browser to it (normally http://127.0.0.1:8080/ActiveMath2/main/menu.cmd)
offer you a book called Recbook free_groups Complete
which should just contain a page.
A collection is generally organized as follows:
activemath
|
|
L content
| -- otherCollection
| /
L- -- free_groups
|
| oqmath -- ....
L__ omdoc -- ....
ContentDescr_free_groups.properties
build.xml
pics -- ....
Our authoring task will be to write .oqmath documents
in the oqmath directory.
The build-process
will take over the conversion of them in the omdoc
directory, as well as generate a few more files, and will
´loadª the content into ActiveMath.
Make sure that the collection has been indicated for loading into ActiveMath.
This generally done by simply copying (or, better, making a symbolic link)
of the ContentDescr_free_groups.properties file in the collection into the
conf directory of ActiveMath.
This should be followed by a restart of ActiveMath.
Table of Contents
Authoring documents for ActiveMath in jEditOQMath involves writing OQMath documents. These documents, can, of course, be typed from scratch. For most purposes, however, using templates speeds up quite many things. We take you for a little tour, creating a new document within an the ActiveMath we just created.
First make sure to open the Templates Tree
tab (typically, by clicking on its title on the left of the jEdit window,
or by invoking
> >
).
Now invoke > .
Then, directly, invoke the template “New OMDoc or OQMath document”
(simply by clicking its name or icon in the Templates Tree).
Then save the file (with >
). Save the file in the oqmath
directory, say, as free_groups_def.oqmath.
jEdit should now display you the content of the file with syntax coloring.
And has selected a part of the text, namely, the value of the id
attribute of the omdoc element.
Insert, there, what you think is a good ID for this element, for example
free_groups_omdoc_id.
But what is an ID ? That's a very common question... An ID is nothing more complicate than a file-name. It's a piece of text (typically in plain ASCII and without spaces) that you will probably use to refer, later, to the element in question.
Continue by pressing CTRL-SHIFT-G (COMMAND-SHIFT-G for Macintosh,
jEdit will simply write this (CS-G), and we shall imitate this.)
This command is registred by the OQMath
plugin and is called Select next template zone.
What it does is simply searching forward to find the next piece of text
surrounded by french quotes ´ and ª.
This function can also be accessed using the forelast button in the default
toolbar (with the same icon as “find-again”.
The next template zone is going to be
´Title appearing to the userª.
This will be the title of the page in the generated recorded-book,
as shall be understood in
the build-process.
Insert Basics to free groups.
Continue thus pressing CA-g and filling the ID of the theory.
We are creating a new theory here, thus, you should invent your ID.
A theory is nothing else than a module, that allows references to be
managed. OpenMath content-dictionaries are, in OMDoc, translated as theories.
A theory can be imported so that names in it
are accessible from here.
Let's choose free-groups-thy as theory-name.
See reference section.
Be careful with quotes... this theory ID, just as the ID of the omdoc
element is an XML attribute value and it should be surrounded
by quotes (and preceded by an "=" sign), the quotes can be either single apostrophes (')
or quotes ("), but not french quotes (´ª).
At first it may be misleading to have these double quotes but bear in mind that things
in French quotes are things expected to be replaced, once they are selected, you just start\
typing or inserting a command and it will replace the "template zone".
At the end, the theory opening tag should look like
<theory id="free-groups-thy">
We now reach “use more templates”. Let's say we request
to insert a theorem. Go to the templates-tree tab and click
Theorem. Fill-up the ID and title.
We reach a depends-on/ref.
At this point, just remove the whole part from <depends-on>
till </depends-on>, they will be talked about in
the reference section.
The next template-zone is now the content of our theorem. Why not fill the blanks to look like the following:
<assertion id="thm-free-groups-exist" >
<metadata><Title> Existence of Free Groups </Title>
</metadata>
<CMP>
If $S$ is any set, there always exists a free group on $S$.
</CMP>
</assertion>
You're free to insert any text there, what we are writing here is the
claim of the theorem, the proof(s) will be attached to it by
another element proof.
Save now so as to validate your file for XML-syntax. We thus proceed to the next section about XML-support.
Maintaining XML-validity
If all did go well in the previous section, the status bar will have indicated your the message “XML parsing complete, 0 error(s)”. The status bar is at the bottom of the jEdit window where, for example, one finds line numbers and some information about the mode.
It will otherwise write the number of errors. And you should “see” these errors.
One way to see the errors is to see their location appear underlined red; leaving the mouse over this underline will, after a while, show you a tooltip with the text of the error. Another way is to see the “Error List” tab (on top) which shows you one line per error which can be clicked to be accessed, pressing C-equals also goes to the next-error. Finally, a way to see if there's no error is in the status-bar on the bottom of the window.
Try inserting <blop/> into your buffer, whereever and see the error reporting in action. You can safely, then, > this insertion.
Seeing the XML structure
The following features are only enabled if the document can be parsed as well-formed. That is, more or less, if nesting is correct.
On the left “gutter”, you'll notice some little triangles which are the “folding” handles. Clicking on one of them will fold the content of the element. Folding is a very common action to clean-up your view.
Opening the “Structure Browser” tab (on the left) also shows you the structure. Namely, it shows a tree structure of the document's organization. This tree will open its branches as you walk through your document. Also, if you click on a node, your cursor will go to there. C-clicking on the node, will “Narrow” to this node (as in in the menu, the command will restore the entire view). Folding is linked to the structure-tree and the buffer.
The XML-support is, however, best examplified in its autocompletion
facilities.
Close a element by simply pressing <
followed by /.
For example, inside the CMP element of our theorem,
we can
insert a textref element around the words
free-group, which will provide
a hyperlink around its body. Just go before the word
free then type
< t e then RETURN.
Enter, as value of the xref attribute,
for example, free-group, then press RETURN.
Now go after the words free group, the link's label.
Then press < /, the closing tag
</textref> should be inserted.
Saving should show you no further errors.
In general, to open a new tag type “<” and wait a bit... you then get a pop-up of all possible element names at this place. You can type the start of the name to restrict the search and navigate with the up and down arrow-keys. When chosen, press SPACE to write it by hand or press RETURN to open the “Edit tag” pop-up.
This pop-up displays all possible attributes, and tries to provide choices
for possible values of each.
Be careful that this, as well as most features described here, is using the
information of the DTD attached to your document (see the top of the file).
In the DTD, for technical reasons, there has been the need for some attributes
which an author sould really not look at.
For example, the xmlns attributes should almost never be seen...
We have not, yet, found a way to provide a richer documentation in this pop-up
but I am pretty sure this will happen some day and one will be able to see
a description of the each element and probably attribute.
Using this auto-completion feature, it is easy to grasp the set of all
possible children of a CMP element which one
commonly names the micro-structure
(as opposed to the macro-structure which relates items
together.
Every content-collection, nowadays, comes with a
build-script in the form
of an Ant build.xml file.
Although this should be part of jEditOQMath internals, this script
is currently exposed as an editable script and is, too often,
still manually tweaked.
The goal of this build script is quite multi-faceted:
Apply the OQMath process to convert the OQMath files to OMDoc format
Invoke the creation of an automatic recorded book
Invoke the creation of stylesheets derived from presentation tags
Invoke the reload of the new files by the content-database of ActiveMath
Remove the rendering of the items changed from ActiveMath presentation-cache (so that they get regenerated next time they are requested to be presented).
Many other tasks that are specific to authoring and allow an author to produce a quality content-collection.
This build-file can be inserted into our work environment as follows:
First open the tab “Ant Farm” on the left.
Then press the “+” sign, navigate (you can use the keyboard
to type file or directory names to select them) to the build.xml
of your content-collection, press “Open”.
You should now see something such as free_groups build file.
For a novice user, applying the build script is quite simple: open the Ant-Farm tab, select the build-script (by clicking once), and click the running man (“run”). Do try it for our collection, it should not take very long.
Adventurous users may wish to get into such build-scripts and adapt things. Start in the Apache Ant manual. For example, it is not too hard to adapt the script to make it work for an ActiveMath server running remotely. Be careful, though, it may be needed in the future to update the build-script by running again "Start a collection".
The steps of this script can generate errors and these are important errors that you should take care about. They will be reported in a similar fashion as the XML errors. There are, currently, errors in the mathematical inputs (as produced by the OQMath application) and errors of wrong references.
Build errors appear the same way other errors appear... they
also do so progressively.
If you followed verbatim our tutorial thus far, you should be reported
with an error about the textref xref
attribute value which points to a non-existant item.
The build also produces a log which one can
see in the “console” tab below (which should open automatically).
This log is sometimes useful as the errors displayed may be too little.
The build-process should not take long and you should be able to preview the content being played in your ActiveMath right away. You thus achieve a content writing-and-preview cycle typical of classical writing.
In our freshly created collection, the new content should appear directly when opening the book All the items of free_groups collection in the browser. If this does not happen, please try searching the ActiveMath dictionary, and copying a pasting a piece of text.
Be careful that such previews are limited to your browser (with its bugs and features), your screen-size and colour set-up, and may even be limited to the ActiveMath user you are using to preview it. It may be wise to change the user often, and probably to change the browser from time to time as well.
Another issue may appear here in the form of Transformation Errors
which are any errors related to the presentation of an item and may occur, for
example, when the content database becomes corrupted.
If you experience such, please shut-down ActiveMath, navigate in a file-explorer
to the ActiveMath-home of then to the directory data:
in this directory, remove the directory called lucenedb.
Starting up ActiveMath again will rebuild the index fresh and should
have stopped this corruption. This should only happen with the old "LuceneMBaseRef".
Reference is the general word used to describe a relation between a location in OMDoc documents to another. Sometimes the word dependency is also used although this is old.
References generally point to an element that has an id
attribute (therefore it's useful for you to put good ids that you will remember).
An element with id myId within a theory element
of id myTheoryId, all within a collection of identifier
collectionId
can be referenced as follows:
within the same theory element it is in,
using simply myId
from another theory of the same collection, it can be
referenced using myTheoryId/myId
from another place, using
mbase://myCollectionId/myTheoryId/myId
or using myTheoryId/myId but having,
as children of the containing theory element,
“imports” element with the from
attribute being myTheoryId/myId.
References can be hyperlinks, which one typically inserts
using the textref element such as in
<textref xref="my_first_theory/def_introduction">Do see here</textref>.
In ActiveMath, this is, by default, rendered as a link to open the reference
target into the Dictionary.
References are also used to encode the meaning and pedagogical role of your items:
for several items,
a for attribute
encodes a the relation of being something for a concept
(for example, being an exercise for a theorem).
The metadata element (where the title is also put)
contains relations. For example, the element depends-on,
or relation. In all cases, they have, as children,
ref elements with attribute xref
providing the reference.
These references are used in many places in ActiveMath.
For example, the course generation makes heavy use of depends-on
and for,
added with other metadata information, and with user-model information.
Also, these references can be navigated through using the ActiveMath
dictionary.
It is very hard to check all references by hand but errors can lead to
really disappointing bugs such as an item not being presented in a book,
a prerequisite being missed,
or a link yielding a missing item.
Therefore, the build-scripts come with a reference checker.
As we have described, the OMDoc content is enclosed in theory
elements. For the sake of preserving the set of things we can reference
not too big, and thus avoid typing enormous references, OMDoc supports the
notion of theory imports.
For MBase to resolve correctly a reference like set1/set
it should import the theory set1 and thus indicate that this theory
is part of, say, the openmath-cds collection.
As first child of the theory element, you should thus
insert the element <imports from="mbase://openmath-cds/set1"/>.
And you will thus be able to insert, in the CMP of our
theorem, the reference
<textref xref="set1/set">set</textref>.
Do run the Ant build-script again and see the page of your book with your
file. The word “set” should be linked
to the description of the set symbol of the OpenMath society
or to definitions of it, if available and if the user you use is not an author.
Supported Reference Management
To help us insert correct import elements,
they can be automatically generated using the command >
> .
This command is using heuristics and thus may respond something weird.
Note that works on the OMDoc
files and not on the OQMath files (as it needs to resolve the pointers
in mathematical symbols' usages as well). As a result, it would be
best to use after
having applied the Ant “target” .
For this, in the Ant Farm tab, unfold the icon of our build file (click the little
triangle), select then press the running man.
(FIXME: this is a nuisance!)
Another help to insert references, is the ID-search dialog. Pressing CS-s will pop-up a dialog where one can enter a substring to search among the IDs. The search results can be used to go to the item, view it in the ActiveMath dictionary (using the bundled InfoViewer browser or with your browser, configured in the InfoViewer plugin's options), or simply have their ID copied or inserted.
Finally, ActiveMath dictionary-URLs are a good source as well. Such URLs are in the links on each title in an ActiveMath book or in the dictionary and are in many other places. It is possible to drag such a URL and drop it inside the jEdit text-pane. Depending on where the drop occurs, this should insert a ref-element, a textref-element, simply the reference, or the URL. If dropped outside the pane, it should open the OQMath source file and bring the cursor at the beginning of the item.
One important form of reference has been left aside it is the usage of a mathematical symbol, the topic of our next section.
Table of Contents
As you probably know, OMDoc encodes mathematical formulae as OpenMath or MathML-content. jEditOQMath supports OpenMath by relying on the QMath processor. OpenMath defines a set of symbols which forms the base semantic which should satisfy a large amount of common-usage and an encoding to compose them. The content-dictionaries of OpenMath can be browsed at http://www.openmath.org/cd. These symbols can also be browsed within the ActiveMath dictionary (e.g. see http://localhost:8080/ActiveMath2/search/browse.cmd?coll=openmath-cds) as long as you are browsing as a registered author (see installation configuration). Using these CDs, one can grasp the intended meaning of each symbol though they are not always formally defined.
A symbol in a CD is the hook of this meaning, it can be pointed to
using an OMS element.
For example, one sees that the plus is expressed as follows:
<OMS cd="arith1" name="plus"/>
One should read, in here, the same as
<OMS xref="arith1/plus"/>
and this is, actually, what the MBase does for us, resolving
the imports elements along the way and thus transforming
this into <OMS xref="mbase://openmath-cds/arith1/plus"/>.
Inputting an OMDoc document thus represents, in principle, also inputting all formulae in OpenMath. Conceptually, this task is not hard, it is relatively normal for a mathematician to browse through pre-defined symbols and use them or to define his own ones. Concretely, however, it is barely livable to write the OpenMath elements by hand as the space taken for each formula is very large.
The QMath processor offers a converter from a common and easy to read syntax to OpenMath. Originally, QMath was written to write entire OMDocs, OQMath now wraps it so that it only takes care of mathematical formulae and their extensions and leave the rest as XML. This allows an author to speak OMDoc for most of the content while keeping a readable source-code.
Entering mathematics is as simple as writing
$3a+5b$
or $Hn = set(x | x ∈ Rn ∧ π(n,x) > 0)$.
The expressions, which can be on several lines, are converted during the
build-scripts-run to OpenMath.
This would work well if one would restrict ourselves to the official content-dictionaries for all formulae as is done for the first formula here. We would just need to insert the fact that we use these “notations-context”, before our function (say, after the imports element):
<?QMath Context:"Mathematics/Arithmetic" ?>
as is done in the default templates for a new OQMath file.
These “context declarations” are pointers to files in
the QMath distribution.
They are actually text-files which may be appropriate to read.
One can navigate to them using
>
>
which will open the “File System Browser”. Navigate until the
directory qmath_3, then the directory “context”
then the directory “en”, then “Mathematics”.
Each of the files within the Mathematics directory represent a broad topic of mathematics.
Reading them will reveal you that each import the files of a set of content
dictionaries, located one directory OpenMath below.
The contexts of OpenMath CDs can also be browsed online
at http://www.activemath.org/projects/OQMath/qmath-contexts/.
Inside these files one sees
the definition of the notation of each symbol, how it is written, what is
its priority, and to which OpenMath symbol it correspond.
Usage of Unicode mathematical characters
As you can see in these files, QMath allows the usage of many Unicode characters. This is a wealth which allows formulae that outpass the readability of TeX source files. The trouble is, however, how to input such symbols ?
One short answer is the usage of copy-and-paste from the contexts to your
sources.
A better answer is provided: many pre-defined abbreviations
are defined in jEditOQMath. Try typing SPACE S i g m a C-;
or SPACE R i g h t a r r o w C-;, you will get the corresponding
Σ or ⇒ characters; the space is needed to
mark the beginning of the word, it could also be a period or...).
More or less all TeX macros are included with their corresponding Unicode characters.
Do check Ant-building and see that the formula $3a+5b$
we typed in did work.
(Using the command “Run last build” (CA-l) should speed
up such call). Also try typing, still inside the CMP, $alpha$, you should
end-up with a*l*p*h*a. Why ? Because alpha is not a known symbol, or variable.
Hence QMath converts it to the produce of the variables a*l*p*h*a.
What if we introduce $3!$ in and try to build.
We shall get a reference error but no QMath error.
QMath has this symbol predefined from Arithmetics.qmath,
and maps it, as usual to the application of the factorial symbol.
However, we get a reference error which says that mbase://free_groups/integer1/factorial
cannot be found (where free_groups is the name of our collection).
Indeed such a symbol does not exist in our collection (it could have), but is
one of the OpenMath core content-dictionaries.
And that is what we need to indicate by the usage of an imports
element: we have to insert
<imports from="mbase://openmath-cds/integer1"/>
as one of the first children of the theory.
It says that every-time we use the theory-name integer1
we mean the one of the OpenMath content-dictionaries.
Quick readers will have grasped it, using a mathematical symbol is nothing else then referencing it, more precisely, referencing its meaning, the same way as the sentence “the notion of topological space as defined by PoincarrÈ” does.
In general, it is best to use the symbols commonly in use by other mathematicians. A collection of such symbols is the MathML CD-group specified as part of OpenMath 2 standard (see the MathML CD group's CD. The OpenMath website displays other such content-dictionaries but they are, mostly, contributed or experimental and exposed there as share-points. Sharing a content-dictionary with the most permissive license is a good idea since it allows others to reference the symbol hence mean the same thing you do.
There are times where defining a new mathematical symbol is not a choice. One such situation is when defining a completely new mathematical concept or a particular refinement of an existing symbol. OMDoc supports the creation new mathematical symbols, offering all documents' knowledge representation to support this introduction.
A symbol is declared with the <symbol>
element, it comes with a title (or common-name),
some other metadata, and it may have one or several definitions
outside of it.
Let us insert the concept of free group and, later, a definition of it:
go outside of the assertion element we've created
Invoke Templates Tree > Symbol.
add an id (free-group), a description (no need for a definition here), and a title (free group),
Invoke the run of the build-process...
Then, let's define a QMath notation for this symbol:
Below the symbol declaration, a green line appears starting
with <?QMath, this line should
be moved to the top of the file and should be replaced by something such as
<?QMath Symbol: Fn APPLICATION "free-groups-thy/free-group"?>.
What we have done is to declare that every-time the letters Fn appear, it
should be considered as a function application expecting parameters within
a bracket thereafter and that it should be translated to the application
of the OpenMath-symbol free-group within the content-dictionary
free-groups-thy.
Other types of QMath operators can be read from:
http://www.activemath.org/projects/OQMath/QMathSymbolsOverview.html.
Then let's define an ActiveMath symbol-presentation for this symbol.
(TODO: have a template for symbolpresentation, for now, here's the details):
go outside of the symbol element, insert
<symbolpresentation id="free-group-pres">
then insert a
<notation> element inside it
this notation element should be editable with
>
where you will have to input the QMath expression you wish to render, for example
Fn(k) then type-in the presentation, for example
F_k.
Alternatively, you can input the following made of a MathML presentation element aside of an OpenMath object.
<symbolpresentation id="free-group-pres">
<math><msub><mo>F</mo><mi>k</mi></msub></math>
<OMOBJ><OMA><OMS cd="free-groups-thy" name="free-group"/>
<OMV name="k"/></OMA></OMOBJ>
</symbolpresentation>
What we have created is a way for ActiveMath to present the mathematical
symbol when used within an OMS. Let us use this symbol in a formula
and try it: insert $Fn(S)$
in our theorem, right after free group.
Run the build-process, check errors, and see the page being renewed in ActiveMath. For the new presentation to be taken over, however, you will need to restart ActiveMath. The theorem should now show the symbol of the free-group and make it clickable.
TODO: Discuss the publication of the symbols and content-dictionaries
TODO: Introduce rephrases.
TODO... Try opening > > . You will see a place called TOCedit where you can create a hierarchy which will be the table of contents of a book for ActiveMath. TOCedit also supports dropping ActiveMath dictionary URLs.
Your feedback would be enjoyed at http://eds.activemath.org/.
For example, how about a drop of a symbol or subformula in ActiveMath into the pane which would insert the necessary QMath ?
jEditOQMath may become replaced by a more visual tool. See http://www.activemath.org/projects/OmdocJdomAuthoring/. However, chances remain that such a visual tool will not be quick to provide the necessary paradigms to edit the wealth of OQMath files written thus far and to cover all the knowledge-encoding tasks that XML-editing gives us... as a result, jEditOQMath is still expected to be used by professional authors who wish greater control over the OMDoc content they deliver.