LMH Workflows

Here we discuss how to set up a local MathHub working copy on Debian-based systems like Ubuntu, for other *NIX systems proceed analogously.

Setup Local MathHub Working Copy

## Installing Repositories

Now, you can install the repositories you want to work on via

where group is the repository group on GL.MathHub.info and repos the repository name (details). For instance for the SMGloM repository:

This will check out the requested repositories and all those they depend on and add them to the local MathHub copy at $(lmh root)/MathHub/group/repo. Note that the actual flexiforms are in the source directory. Note that some repositories are private, and you need to authenticate in the installation process. The most convenient way is to deploy an SSH key, which alleviates the need for passwords. The final step is to generate all auxiliary files with

This generates the sTeX Module Signatures (.sms files) and for each directory the files localpaths.tex for path managements and all.tex that includes all sTeX modules. Now we are ready for working with the repository as shown below.

You can also run the command

which will generate auxiliary files for all repositories.

Generating PDF

The most convenient way of viewing (and proofreading) flexiforms in the local editing workflow is to generate PDF from them. This can be done simply by running pdflatex over them or using an lmh tool:

This will re-generate filename.pdf from filename.tex (and update all the local .sms files accordingly) if necessary. To force regeneration, use the --force argument of lmh pdf. To generate all tex files in the current directory, simply use:

without a filename argument. If a file has dependencies outside of the directory, this command will not generate them and you will have to regenerate them as described in the previous section.

PDF generation may generate logfiles which are called filename.pdflog

Generating OMDOC

The operational flexiformal representation format in MathHub.info is the OMDoc format. It can be generated by using lmh omdoc analogously to the PDF generation above. The log files are called filename.ltxlog.

Generating XHTML

The OMDoc files are content representations cannot be directly viewed and interacted with. But with a local installation of the MMT system, we can generate active (semantically annotated, instrumented) XHTML documents that behave like the active documents on the MathHub portal. lmh xhtml does the trick.

Editing Flexiforms

Before any local edits, the local working copy should be updated via lmh update. After that, the sTeX files can be edited with the editor of your choice or transformed with batch tools. The changes can be validated by generating PDF or OMDoc. New files can be staged (added to the repository) with git add file, changes committed with lmh commit -m "Commit Message", pushed to MathHub with lmh push, and the status queried with lmh status. Note that even though all git commands are possible, they are restricted to the current repository. The lmh actions have the advantage that they transcend repository borders and apply to the current directory in the MathHub working copy, so we recommend using that where possible.

So a typical editing cycle consists of:

mmt lmh pull
# do some editing with your favorite editor
mmt lmh commit
mmt lmh push

If you have done edits on other repositories (or are not sure whether you may have, adding the -a option to the last two will give you peace of mind.

Multi-Repository Actions

The most important mmt lmh actions are the following ones

• mmt lmh pull updates the current subdirectory in the working copy from the respective repositories.
• mmt lmh commit -m "message" commits the current subdirectory in the working copy (lmh commit -a -m "message" the whole working copy)
• mmt lmh push pushes all committed changes from the current directory in the working copy to the respective repositories (mmt lmh push -a the whole working copy).

Creating a new MathHub repository

To create a MathHub repository, you need to:

• log into http://gl.mathhub.info and go to the new projects page and configure the project name (your choice) and the namespace (the project group referred to above). We will use the repository mkohlhase/test as an example below.

• install the repository in the MathHub working copy with lmh install mkohlhase/test. As this is an un-initialized repository, mmt lmh reports some warnings and errors.

• we initialize the repository with mmt lmh init, which generates the files build.msl, serve.msl, META-INF/MANIFEST.MFwhich are needed by MathHub.

• We add them to the repository with git add .. If the repository depends on other MathHub repositories, we can add them in the line starting with dependencies: in META-INF/MANIFEST.MF.

• We commit them with git commit -am "new repository" and push with git push origin master.

The flexiforms in the repository belong into the source subdirectory. Apart from configurations, users should make no changes outside that directory.

Reporting issues

If you find an issue with mmt lmh, please report it at https://github.com/UniFormal/MMT/issues/new. Make sure you have all dependencies installed before filing an issue.