This might be the start of a living handbook to author ActiveMath content.
This book intends to contain most of the authoring documentation in one big compendium with varying degree of technicality.
If you never played with ActiveMath, please take the tour by the ActiveMath demo-guide.
If you wish to start authoring very soon, consider Jump-start ActiveMath authoring.
The eXtasy manual might be relevant (though a bit outdated).
This page describes elements of how to start ActiveMath authoring.
Resources will include the authoring handbook as well as the detailed task descriptions.
Comments are welcome.
This is an ongoing translation of the jEditOQMath tutorial.
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:
jEditOQMath is a pack of quite many open-source packages, please see the project home page:. You’ll find there a list of ingredients, their license, and for more technical and legal details.
jEditOQMath has been planned to support authors write content for the ActiveMath learning environment. We thus suppose that you have a copy of ActiveMath running locally on your machine. TODO: need to refer to installation pages here.
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 for readable formula input will be there as well (see math-input).
Do take the time to adjust the path to ActiveMath home within the OQMath plugin settings:
Plugin > Plugin Options… Then click OQMath jEdit then press the Choose…
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:
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
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:
myIdmyTheoryId/myIdmbase://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 attribute
encodes a the relation of being something for a concept
(for example, being an exercise for a theorem).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.
But imports can be more powerful than simply indicating a collection, they
really bring all the names of the imported theory inside this one.
Thus <textref xref="set">set</textref> is actually the same reference.
Moreover, imports elements can be global as in:
Suppose we are within <theory id="A"> and use the imports statement
<imports from="mbase://openmath-cds/set1" type="global"/>.
Then within a theory <theory id="B"> having an import <import from="A">
all the names of the theory A are visible, including the globally imported
ones, so including set which is a reference to the symbol of id
mbase://openmath-cds/set1/set.
Such an approach is particularly nifty to declare names theories that gather all the classical names used within, say, many files of a collection.
To help us insert correct import elements,
they can be automatically generated using the command Plugins >
OQMath_ > Generate Imports.
This command is using heuristics and thus may respond something weird.
Note that Generate Imports 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, you need
to use Generate Imports after
having applied the Ant target OQMath.
For this, in the Ant Farm tab, unfold the icon of our build file (click the little
triangle), select OQMath then press the running man.
Another help to insert references, is the ID-search dialog. Pressing CS-s within a word 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, 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 within the OMS element.
The topic of our next section is, precisely, the input of mathematical formulae
This chapter of the ActiveMath describes the usage and creation of books and groupings for course-generation.
What should a table of contents (TOC) for ActiveMath look like:
The most important points are:
<ref> elements on the same level as
<omgroup> elements.<omgroup> that has a description needs an id attributeMore details: Start with the typical OMDoc stuff:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE omdoc SYSTEM "../dtd/activemath.dtd">
<omdoc id="put_some_Id_here">
Start the table of content and give it a title and description
<omgroup id="put_ID_of_TOC_here">
<metadata>
<Title xml:lang="en">Content for course generation</Title>
<Title xml:lang="de">Inhalte für Kursgenerierung</Title>
<Description xml:lang="en">This is content that illustrates course generation.</Description>
<Creator role="aut">Carsten Ullrich</Creator>
</metadata>
Think of this as the cover of a real book.
Now start with the content. Think of this as the chapters of a book. It`s ok to have only a single chapter:
<omgroup id="grouping_course_generation1">
<metadata>
<Title xml:lang="en">Section for Definition Def1</Title>
<Creator role="aut">Carsten Ullrich</Creator>
<Description xml:lang="en">Here, the definition def1 is explained.</Description>
</metadata>
<ref xref="def1" />
</omgroup>
In the above example, the chapter contains a reference. Alternatively,
you could put one or several <omgroup>s there. Think of them as
sections and subsections. The bottom <omgroup>s need to reference to
actual learning objects (use the <ref> element for this).
Do not put <ref> and <omgroup> elements at the same level. Instead
create a proper <omgroup> for the <ref>s.
Do not forget to add identifiers to each <omgroup>.
A table of content can also be used for course generation. The course
generation uses concepts (definitions and assertions) as a
basis. Hence, it discards examples and exercises occuring in the table
of content. Therefore, if you wish to use a table of content for
course generation, make sure that every bottom <omgroup> element
contains a least one reference to a concept.
Be aware that the course generation selects concepts of the learning context of the learner. This means that you can put references for definitions that define the same symbol, but which are for different learning contexts. The course generator will select the appropriate one. If there isn’t any, then the course generation can not be started.
Formal:
TOC -> <omdoc> <omgroup> SECTION </omgroup> </omdoc>
SECTION -> OMGS | REFS
OMGS -> <omgroup> SECTION </omgroup> OMGS
REFS -> <ref>+
You can mix prerecorded book with dynamically selected elements, i.e, OMDoc exercises and examples that are selected depending on the current competencies of the learner.
Use one of the following tasks:
illustrateWithSingleExample!
trainWithSingleExercise!
train!
illustrate!
The first two insert a single example or exercise resp. The other two tasks insert several examples/exercises. The selection happens according to the pedagogical knowledge as formalized in the course generator.
Such dynamic tasks can be inserted in the omdoc/oqmath source code representing a table of content using jedit for instance, or using the assembly tool. If you insert them manually, it’ easy as the format of a dynamic item is quite intuitive:
<dynamic-item type="dynamicTask" servicename="tutorialControl"
queryname="trainWithSingleExercise!">
<ref xref="theory_of_exercises/def_exercise"/>
</dynamic-item>
The important parts are queryname (the task name) and the xref attribute that references the concept on which the task is to be applied. You can easily retrieve the value needed for the xref attribute by copying the the link of an item in a book, which yield something like: http://localhost:8080/ActiveMath2/search/show.cmd?id=mbase://LeAMcalculus/deriv/defnormal You need the part behind “id”: mbase://LeAMcalculus/deriv/defnormal You can retrieve it within the “more” tab of the additional information in the search view of an item.
You insert that dynamic-item into the table of content just like any other reference.
This page describes precise methods to translate the LeActiveMath content.
See also other pages about translation.
The internationalization of ActiveMath is the result of the deliverable 13 of the LeActiveMath project which can give a good conceptual overview. We provide here detailed concrete instructions.
We wish review of the München team for this page
We centralize the work on a subversion repository. For this purpose the LeAM-calculus subversion repository has been opened, http://svn.activemath.org/LeAM-calculus/LeAM_calculus/ This directory needs to be checked out in the contents directory.
For now, so as to avoid text-merge conflicts, we would have wished
to make use of the svn lock function so that as to ensure
to be alone at work on this file. However, this breaks because of a too old version.
This means that currently translators may, at time of committing their translation,
encounter a lack of up-to-dateness followed by a conflict at update indicating
that svn could not merge your local changes with changes of others.
This will leave visible trace in the source files, in the form of “<<<”, “===”, and “>>>” lines
which need to be removed,
inferring correctly how to mix the conflicting updates.
Each translator runs its own ActiveMath, in its own language, and checks the translations on his own machine. Please avoid comitting files that have errors in it or that you cannot preview. Ask for assistance instead.
In order to obtain comitter-rights for this repository, please register (or re-enter password) on eds.activemath.org and drop me a mail which will enable me to copy your credential to the repository.
In order to test completely, one needs to start translating ActiveMath,
at least adding this language as a choice
(mostly, a change in the ActiveMath.properties).
Explanations for this are in webapps/ActiveMath/i18n/I18n-Readme.txt.
Once logged in and having chosen the new language, the content should appear.
Further refinements of the translation of ActiveMath will be indicated, in particular wrt
to mathematical notations and the names of mathematical symbols (work on
the OMDoc files in omdoc1/cd).
The OQMath files of LeAM_calculus are more or less OMDoc files, and obey its DTD, modifications to the files should be made according to the DTD, jEditOQMath or another XML editing tool will provide you indication when the file is not well-formed or DTD-valid.
OMDoc allows each containers of text to be annotated with an xml:lang
attribute indicating the language encoded according to (ISO-693-2, currently only the two letter form as per XML spec).
OMDoc allows these elements to be repeated in one or different languages.
ActiveMath will try to find a compatible language within the list of available languages.
An exception to this list is the usage of the language x-all which indicates
that the given fragment is considered multi-language.
Elements that can contain text in particular languages include:
CMP elements, children of each items and exercise nodes, supposed to contain the textTitle elements, children of the metadata elements, representing
the title of an item or a nodecommonname elements, children of the symbol elements,
representing the ‘short name’ of the symbolThese elements have the ‘CMP model’ which means a mix of plain-text, mathematical formulae and a few elements which, themselves have the same model, but not carrying a language attribute anymore. The whole content should be translated. A menu-item in jEditOQMath is being worked on to add all these elements needing to be translated.
Do note that the mathematical formulæ,
generally enclosed betweeen two dollar signs as in $gcd(6,4)$,
are considered multinational which means that the formulae should not be changed
but should be copied.
Translation of the formulae presentation is, mostly, an advanced topic of the ActiveMath
translation. Indeed, the expression above will be presented as as ggT(6,4) in German,
similarly, $3.14159$ is input as such but is
presented as 3,14159 is several european languages.
Once translated, saved, and validated, the proofing work can start.
Translators are expected to request the OQMath compilation and the remaining
publishing routines as run by the collection’s build.xml then
to proof the result by previewing in ActiveMath. These previews should be done
in at least the HTML, XHTML+MathML, and PDF medias.
Once ready, a commit of the OQMath and OMDoc files followed by an unlock can be done.
ActiveMath also internationalizes the delivery of pictures and other static resources.
When it receives a request for a given resource,
ActiveMath will look into the file-system whether translations of this resource exist.
A file, say file.png, is considered to be translated if variants postfixed with a
language code exist, e.g. this picture would be considered translated to French if the file
file_fr.png exists.
If there is no translation, i.e. only file.png exists,
it will simply serve the file’s content;
if there are translations it will take in account the user’s language,
as defined in its profile, the surrounding language (e.g. of a containing item),
the browser’s language, or the default language of the server.
It is the decision of the translator to consider the requirement to translate a picture or not.
The applets of LeActiveMath-calculus are internationalized using the simple properties file mechanism. Each applet embedding, in the content, transmits the surrounding language to the applet, hence it is important that the language of the user is a supported language of the applet.
In order to translate applets, similarly to the ActiveMath translation, one needs to duplicate the properties files to files with appropriate names and translate each of the phrases there.
The properties files of the applets are split in a few phrases packs, named
from LeAM_applet_xx_1.properties to LeAM_applet_xx_4.properties
and are stored in the directory applets_src/properties.
For example, if introducing hungarian, one needs to create files
LeAM_applets_hu_1.properties
(and similarly with 2,3, and 4) in applets_src/properties/ as a copy of the source
of translation then translate the messages.
To preview these applets, the applet java-archives need to be re-generated
running the JarApplets target of build.xml in the root directory
of the collection.
Since browsers perfrom very strong caching of applets’ code it is important to restart the browser
then empty cache for each test of the applets. Or to use the appletviewer tool.
Once your previews appear satisfactory, it would be wise to cut a snapshot of it and feed-it
as part of the directory applets/snapshot/. This picture wil be within the pages
and within the print version instead of the applets which are only shown in a new window when
clicked.
For example the applet Trig_funct_Circle, used and declard in
trigonometry.oqmath
has an associated snapshot
applets/snapshot/Trig_funct_Circle.png for English and has translations
applets/snapshot/Trig_funct_Circle.png,
applets/snapshot/Trig_funct_Circle_de.png, and
applets/snapshot/Trig_funct_Circle_zh.png.
OMDoc documents are made of mathematical items which can contain mathematical formulas; the latter may be presented to the screen or print media. The ActiveMath presentation system uses XSLT and Velocity to convert the OMDoc fragments to rendered HTML, XHTML, or PDF. For the mathematical formula to be presented well, an amount of notations are defined which produce XSLT templates.
This handbook page explains by examples how notations are conceived, authored, and used in ActiveMath.
Notations are, traditionally, rules to encode graphically a conceptual construction.
ActiveMath notations are similar, they are made of:
These prototypes are enough for ActiveMath to generate a stylesheet that will render any expression to HTML, MathML, and TeX.
In ActiveMath, notations are provided by any collection that is loaded. To see the notations defined in your current ActiveMath, invoke Tools > Symbol Presentations.
This tool allows you to test the rendering of an OpenMath expression or to get a list of all the notations defined.
Try this on the ActiveMath demo as user eva.
The fact that any collection can contain notations may lead to conflicts... currently, these are not reported but the resulting notation is the "concatenation of the two notations", quite a visible effect!
Let us construct a basic example for the symbol free-group:
<symbolpresentation id="pres-free-group1" xref="free-group">
<notation>
<OMOBJ>
<OMA>
<OMS cd="free-groups" name="free-group"/>
<OMV name="alphabet"/>
</OMA>
</OMOBJ>
<math>
<mrow>
<mo>F(</mo>
<mi>A</mi>
<mo>)</mo>
</mrow>
</math>
</notation>
</symbolpresentation>
This first example will render expressions such as this prototype. Let us try, with the notations of the jEditOQMath tutorial, to render $Fn(S)$. You should obtain something similar to F(S).
If not using SluMBase, ActiveMath needs to be restarted everytime the notations have been changed. Alternatively, one can use the symbol-presentation-tool.
Note the variable names: the OpenMath expression has a variable, named A, which is the same as the content of the MathML's mi element: all variables are replaced this way.
Having the OpenMath in mind is a good idea here since authoring notations involves fine-grained OpenMath matching. But nothing prevents you to use a QMath expression instead of the OpenMath, yielding instead:
<symbolpresentation id="pres-free-group1" xref="free-group">
<notation>$Fn(A)$
<math>
<mrow>
<mo>F(</mo>
<mi>A</mi>
<mo>)</mo>
</mrow>
</math>
</notation>
</symbolpresentation>
Now, what about the formula written down as F(a,b), the free group on two generators?
If you try to input $Fn(a,b)$, you will get a non-presented-symbol free-group(a,b) which is not what one wishes. Actually, this formula does not use the same notation, it has been shortened once more by the removal of the bracket. One needs to add a notation for this:
<symbolpresentation id="pres-free-group2" xref="free-group">
<notation>
<OMOBJ>
<OMA>
<OMS cd="free-groups" name="free-group"/>
<OMA>
<OMS cd="set1" name="set"/>
<OMV name="a"/><OMV name="b"/>
</OMA>
</OMA>
</OMOBJ>
<math>
<mrow>
<mo>F(</mo>
<mi>a</mi>
<mo>,</mo>
<mi>b</mi>
<mo>)</mo>
</mrow>
</math>
</notation>
</symbolpresentation>
The scary bit here is that we would need to introduce a notation for each possible size of the generating set... instead we need n-arity for which a special symbol in the ompe content-dictionary has been defined and a special element in MathML has been allowed:
<symbolpresentation id="pres-free-group2" xref="free-group">
<notation>
<OMOBJ>
<OMA>
<OMS cd="free-groups" name="free-group"/>
<OMA>
<OMS cd="set1" name="set"/>
<OMA><OMS cd="ompe" name="nary"/>
<OMV name="x"/>
</OMA>
</OMA>
<OMV name="alphabet"/>
</OMA>
</OMOBJ>
<math>
<mrow>
<mo>F(</mo>
<nary>
<mi>x</mi>
<mo>,</mo>
</nary>
<mo>)</mo>
</mrow>
</math>
</notation>
</symbolpresentation>
To be continued, about:
This page documents how to set-up things so that one can create content on one machine and upload it to another which runs the ActiveMath. This effort is still at a relatively early stage.
The instructions below have been tested on MacOSX and have many chances to work on Linux but may need tuning to work with Windows.
It is supposed that your user is enabled to login over ssh into the host you want to run on without being asked for a password (i.e. using ssh key-pairs and the authorized_keys2 file) and that you can use the command rsync to copy things (or that you save on a directory that you can also mount on your laptop).
We shall define two properties. These can be included anywhere where the build.xml of the collections read them; this includes the ContentDescr_xx file but is probably best put in a file called build.properties in your home directory. This properties-file is read by all collection-publication-scripts and is not required to be inside the collection as it should.
Let us suppose that you run the authoring environment within your personal laptop and that the ActiveMath server is at the machine nirvana run under the user user within directory amdir.
To use the upload facility, add the following line:
remoteAMsync = user@nirvana:amdirThe publish script will invoke, then,
rsync -av ./ user@nirvana:amdir/content/<collName> before requesting the MBase-reload task from the MBase interface.
If you run your ActiveMath on another host, without tunnels, it must be talked to per http as such, you need to add:
amServerHost=nirvanaOr, if you are also changing ports (as can be done inside
server.xml and ActiveMath-individual.properties) you may need to add:
omdocjdommbase.url = http://nirvana:55007/ activemathRootUrl = http://nirvana:55080/
I am currently considering an XML-RPC-based upload mechanism which would not require all the rsync and ssh fuss (known to be difficult). For this I am still looking at file-synchronization facilities… which could end-up be such as WebDAV facilities.
For some reasons you may be against using jEditOQMath and/or jEdit… But to be correctly integrated you would need to still request ActiveMath reload and error reporting. Here’s a recipe:
../../bin/ant -Djedit.home=${jEditHome} -Dactivemath.home=../..
You can add some ant parameters after that (try ‘-projecthelp’ to see the possible targets).
Among the useful ones might be the ‘-emacs’ option which will avoid putting the ‘[taskname]’ banners hence will make the output clickable, e.g., in the Emacs text editor and most others.
This page describes the two methods to edit interactive exercises.
ActiveMath interactive exercises are also OMDoc documents and can, thus, also be edited in source form with jEditOQMath and its support for the DTD.
This is slightly not optimal if using a DTD that supports old and new encodings of exercises…
This is also less then optimal if authoring complex exercises with many states. Authoring these becomes quickly a strong goto-programming-exercise.
The extasy authoring tries to solve this within a browser-based visual authoring tool. If you are registered as an author (see the tutorial), you can open the URL /ActiveMath2/exercises/repository.cmd which will allow you to create new exercises presenting a graph of the interactions and their transitions. As of this writing the authoring tool requires the Mozilla browsers, with applets, on Windows or Linux.
Once you are done with an exercise in extasy, integrating the content into your collection is done in the following few steps which will try to make a readable OQMath file:
oqmath directory of your collection. Doing so guarantees that you save your files in a directory of “sources” whereas the omdoc directory is on that can be cleaned up from time to time.The resulting file now enters the normal publication process of the collection and should be easily integratable in table-of-contents. Updates to this file can be done in jEditOQMath or extasy, in the latter case, the file should be re-uploaded.
We expect the following enhancements to happen which should shorten this page and better integrate extasy and jeditoqmath: