eds.activemath.org

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.

Using theories and imports

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.

Supported Reference Management

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