About this online version

This is a conversion of the Morpho manual from the original LyX/TeX to an mdBook format.

Morpho is designed by Prof. Timothy J. Atherton at Tufts University. This conversion is my hobby-work done during my time at Tufts as a postdoctoral scholar with him.

Here are my few design goals for this conversion. Some are already met, some are a work in progress:

  • Faithfully reproduce all the content of the manual (done)
  • Emphasize accessibility, especially of the math content (wip)
  • Ensure easy extension in the future by streamlining the automation. (some portions are very much not streamlined right now!)

I found mdBook very easy to use and was able to set-up the basic website without any use of HTML/CSS. I am open to suggestions to move this to another tool.

To build the book, you need to have mdbook installed. You can install it with cargo:

cargo install mdbook

Then, you need to generate the figures and the reference section by running the build.py script:

python build.py

(Make sure to change the libmorphofolder path to your local libmorpho folder in the build.py script. In the future, we will auto-download the help from GitHub.)

Finally, you can build the book by running mdbook:

mdbook build

This will generate the HTML files in the book directory. You can view the book by opening the index.html file in your browser.

To preview the book, you can run the following command:

mdbook serve --open

Authoring Guidelines

The general guidelines for writing a book with mdBook can be found in their user guide.

Equations are handled using slightly modified MathJax:

  • Inline equations are delimited by \\( and \\) (same as mdBook default).

  • Block equations are delimited by $$ and $$.

  • Auto-numbering and cross-referencing support is limited, numbering not including chapter and section numbers, and cross-referencing limited to within a single .md file.

    • Labeling an equation is same as in TeX:
        $$
    \begin{equation}
    y = m x + c
    \label{eq:linear}
    \end{equation}
    $$
    • Cross-referencing within the document can be done by \eqref:
        The linear equation is given by Eq. \eqref{eq:linear}.

  • Morpho code is syntax-highlighted using the JavaScript syntax for now:

```javascript
    var a = 1
```

renders to

    var a = 1

Generating the MarkDown files from the original manual

This mdBook was generated by a series of conversions of the original LyX file.

  1. Export the LyX file as a .tex file
  2. Convert it to markdown with MathJax using Pandoc using the following command:
    pandoc -s -f latex -t markdown --mathjax manual.tex -o morpho-manual.md
  1. Replace $...$ with \\(...\\) within this MarkDown file to make the inline math compatible with MathJax (I used a small re script available on the GitHub repository under src/replacedollars.py).

Contributing

Contributions are absolutely welcome! Check out the Issues on GitHub or make a pull request!