Authoring in ActiveMath

[ working with MBases ] [ TOCEdit ] [ Searchable-item-list ]

About this document

This document describes the currently prototypical authoring facilities provided within ActiveMath. It is neither a manual (it should be more complete), nor an advertisement (it is too technical). It shall be kept small so as to be updated often.

Authors interested in writing content for ActiveMath are encouraged to have a look at the jEditOQMath project gradually integrating all the facilities described here.

Working with MBase(s)

As you know, ActiveMath is currently using a home-growned RAM based solution to serve the OMDocs to be presented within ActiveMath called OmdocJdomMBase. In the near future, the MBase should be connected.

OmdocJdomMBase is launched using bin/mbaseStartup, the messages it produces can then be read using tail -f logs/mbase.log. These messages are of importance for authors as ActiveMath's and OmdocJdomMBase's behaviour may be unpredictable in case of errors as it will be based on heuristics. Reading this message should be done after the (essential as well) bin/validateXML. The messages contain such information as:

OMDoc files that could not be parsed (that is, the XML is not well-formed)
items that do not have IDs (hence will not be able to be served by the database
relations from items that point to non-existing items or elements: this includes metadata/extradata/depends-on, the for attribute, xref of the ref element or the argstr of the omlet element.

OmdocJdomMBase is mostly created using configurations, the ones in the properties are most commonly used, in particular, they are used when invoked using bin/mbaseStartup. For a complete description of the options please refer to the javadoc of MBaseBuilder.
OmdocJdomMBase also offers these messages using the command-line bin/OmdocJdomMBase whose syntax can be read using bin/OmdocJdomMBase --help. It can then offer a javascript console which allows you to manipulate and find items stored in the database.

OmdocJdomMBase is based on OMDoc files. The bin/mbaseStartup command uses reads the files indicated by the configurations (in conf/ActiveMath.properties, in the content-descriptors, and in conf/ActiveMath-individual.properties). The files loaded within OmdocJdomMBase can be modified and reloaded using bin/XMLRPCtests http://localhost:27000/ reload & ; tail -f logs/mbase.log (pressing CTRL-C when done). The table of items will then be rebuilt and error messages will be provided again. (this method of talking to the server is actually richer, see the javadoc for more)

As OmdocJdomMBase loads everything in memory, it may be a problem to use it on a smaller machine Thanks to remote connection, this is not an issue and the configuration can be adjusted to use a remote machine: for all the ActiveMath component, this involves modifying the property mbaseRef.url (which is, by default, http://localhost:27000/). You can, hence, add a line in conf/ActiveMath-individual.properties like
mbaseRef.url = http://mymonster.mydomain.tv:27000/ which will make all future start-ups of ActiveMath (or the user-model) use the MBase running there. The URL mentionned previously in the reload function should also be changed accordingly of course.

This solution is only adequate if the access to the monster's file is easy (for example, a shared file-system is in use). To allow lightweight OmdocJdomMBases to be run even on smaller machines, a cascading MBaseRef has been written: it is built using a list of MBases and each request will first look through the list, giving priority to the first. This allows an author to develop his content on his local file-system, loading in his OmdocJdomMBase only the set of OMDocs he is currently working on, leaving for his monster machine, the OMDocs he is not touching.

To achieve this, the properties have to be adjusted in something along the lines of the following (lines starting with # are comments, leading space is not important):

      # use the cascading-mbaseref class
      mbaseRef.class = org.activemath.abstractcontent.CascadingMBaseRef
      # list the MBaseRefs being used (the alphabetical order will be used)
        # use an XML-RPC MBaseRef to my local OmdocJdomMBase
        mbaseRef.mbases.aa_Local.class = org.activemath.omdocjdom.mbase.OJXmlRpcMBaseRef
        mbaseRef.mbases.aa_Local.url = http://localhost:27000/
        # use an XML-RPC MBaseRef to my server
        mbaseRef.mbases.bb_Monster.class = org.activemath.omdocjdom.mbase.OJXmlRpcMBaseRef
        mbaseRef.mbases.bb_Monster.url = http://mymonster.mydomain.tv:27000/
        # use the friends' MBase for their content
        mbaseRef.mbases.bb_Janet.class = org.activemath.omdocjdom.mbase.OJXmlRpcMBaseRef
        mbaseRef.mbases.bb_Janet.url = http://janet.my.dear.info:27000/

This capability provides already an amount of flexibility. However, we expect to ship something more elaborate (called MultiMBase) for dispatching between MBases based on the collection part of the ID, Other MBases include a CachedMBaseRef (please see the javadoc) and a connection to the real MBase.

The table-of-contents-editor

The table of contents editor is meant to edit recorded books and planning groupings. It is documented in the TOCEdit README.

The Searchable Item List

This little control is in a primitve state but seems to be useful for authors manipulating large collections of content. It is started using bin/SearchableItemList. A window should pop-up with a little text-field where you can type-in the substring you expect to find in an ID. The searchable-item-list will the connect to MBase (as provided by the configurations see above) and list the IDs found.

Selecting one or more IDs will then allow you to perform on action on them. Currently, you can only edit the document containing the given ID, copy the ID (note, it may copy garbage aside), or view the item in the ActiveMath dictionary. The default command to launch the edit is emacsclient, configure this with the property searchableItemList.editorOpenCommand (the jedit command for example goes well also). The default command to view the item in the dictionary is the remote connection to Mozilla remote openURL command, re-using the top-level window (works on XWindows Unices only); this and the URL to the ActiveMath for this (supposed to be running local) can be changed with the other properties starting with searchableItemList.

This command should soon support drag'n'drop of items (as in the dictionary) as well as finer editing where the editor is told to go to the appropriate line. Moreover, it shall become an applet.

Revision number , last modified on . Comments or Questions, tell them !