Saturday, April 12, 2014

Linking Between Books

In the mathbook-xml-support Google group, Duane Nykamp, Rob Beezer, and I had an interesting exchange which touches on the themes of some previous OpenMathBook blogs. The main issues are described below.

References across books

Problem 1: Author A has previously written Document A, and Author B is in the midst of writing Document B. Author B wants to refer to an equation in Document A.

Since Author A supports our vision of open textbooks, the source of the latest version of Document A is publicly available, as is a human-readable manifestation of the work. Furthermore, Document A has an "identifier" associated to it, which allows people to refer to it unambiguously. Suppose that identifier is:
beezerXfcla .

Also suppose the equation of interest in Document A has label
eqn:FE_real_case .

The solution

All Author B needs to do is to put this in the LaTeX source of Document B:
That is it.  Everything else is technical issues.

Supplementary material for a book

Problem 2: Someone has developed an applet which is relevant to Section 3.2 of Document A. The online version of Document A would like to include a link to the applet, provided that the applet has been judged to be of high quality.

The solution

If there were an authoritative source, X, of good applets, then the author could just indicate (in the source or metadata of their book) that "I trust X." Then their book will automatically contain links in the appropriate locations to the appropriate resources.

There are technical issues of course, but no more than the solution to Problem 1. But without a central resource of documents and metadata, none of this can happen.

Some questions:

  1. Will Jim Hefferon's suggestion of an Archive for Open Math support a database of metadata for open texts (at a minimum providing identifiers for documents)?
  2. Will the Archive contain both source and human-readable versions of documents? Or will it just point to the "official" versions?
  3. Will the Archive, or some other source, provide a means of labeling supplementary material as "approved"?
  4. How will approved supplementary material indicate which documents it supports?

David Farmer
American Institute of Mathematics


  1. I had in mind the second choice in case (2).

    Holding material is a big job. Just to name one aspect, in CTAN's time there have successively been source control systems RCS, CVS, Subversion, and git and Mercurial. Another is that the legal landscape is tougher every year.

    I'm not sure how hard it would be to handle where the canonical version is a moving target, as it often is in a repo. I haven't thought about it, I'm afraid.

    Jim Hefferon

  2. It is fine with me if the archive only contains pointers to the official source and human readable versions, especially if it provides the database mentioned in (1).

    Maybe the official source(s) can be on GitHub?

  3. Yes, GitHub or Google Code is natural. But many mathematicians may need persuading to use a repo of any kind. (Of course, a person would want to think about what to do when those go away.)