Metadata-Version: 2.1
Name: mmtpygments
Version: 0.2.0
Summary: Pygments plugin for MMT surface syntax (lexer & style)
Home-page: https://github.com/ComFreek/mmtpygments
Author: ComFreek
Author-email: comfreek@outlook.com
Maintainer: ComFreek
Maintainer-email: comfreek@outlook.com
License: UNKNOWN
Keywords: pygments highlighting mmt minted
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: ISC License (ISCL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Multimedia :: Graphics :: Presentation
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: pygments

![PyPI](https://img.shields.io/pypi/v/mmtpygments) [![Build Status](https://travis-ci.org/ComFreek/mmtpygments.svg?branch=master)](https://travis-ci.org/ComFreek/mmtpygments)
[![Codacy Badge](https://api.codacy.com/project/badge/Grade/32b61ca59aba4a79ae4ab5582f210572)](https://app.codacy.com/app/ComFreek/mmtpygments?utm_source=github.com&utm_medium=referral&utm_content=ComFreek/mmtpygments&utm_campaign=Badge_Grade_Dashboard)
![GitHub License](https://img.shields.io/github/license/ComFreek/mmtpygments.svg)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com)
&nbsp;&nbsp; | [GitHub Repo](https://github.com/ComFreek/mmtpygments) | [Collection of rendered codes](https://comfreek.github.io/mmtpygments/mmtpygments/test/index.html)

# mmtpygments: Pygments plugin for MMT surface syntax

To support syntax highlighting of the [MMT Surface Syntax](https://uniformal.github.io/doc/language/) from the [MMT project](https://uniformal.github.io/) this package is a Pygments plugin including

- a Pygments lexer (`mmt`)
- a recommended Pygments style for it (`mmtdefault`)
- and experimentally a Pygments lexer for MMT relational data (`mmtrel`).

**Collection of rendered codes:** [click here](https://comfreek.github.io/mmtpygments/mmtpygments/test/index.html)<br>
**Screenshot:**<br>
![Screenshot of highlighted MMT code](https://user-images.githubusercontent.com/1827709/59698193-7523c300-91ef-11e9-8c4b-80ec2d3e4a40.png)

## Installation

### Via Pip (recommended)

1. `pip install Pygments mmtpygments`
2. Use as you wish with Pygments, e.g. run on CLI:

   `pygmentize -f html -l mmt -O full,style=mmtdefault -o test.html test.mmt`

   This tells Pygments to use the HTML formatter (`-f`), the MMT lexer (`-l`) and to output a full HTML file using the `mmtdefault` style (`-O`) rendered of `test.mmt` into `test.html` (`-o`).

## Usage in LaTeX with minted

[minted](https://ctan.org/pkg/minted) is a LaTeX package rendering codes with Pygments as the backend.

```tex
% You MUST USE XeLaTeX (or any other LaTeX-derivative which supports Unicode)
\usepackage{fontspec}

% Download GNU Unifont from http://unifoundry.com/unifont/index.html
% And save it, say, as "fonts/unifont-12.1.02.ttf"
\newfontfamily\unifont{unifont-12.1.02.ttf}[Path=./fonts/,NFSSFamily=unifont]

% Disable caching for debugging purposes (increases compilation times!)
\usepackage[cache=false]{minted}
\setminted{
	fontfamily=unifont
}

\newminted[mmtcode]{mmt}{}
\newmintinline[mmtinline]{mmt}{}
\newmintedfile[mmtfile]{mmt}{}

\begin{document}
	% Variant 1: Code given in LaTeX, rendered in display mode
	\begin{mmtcode}
		theory MyTheory = c : type ❘ # abc ❙❚
	\end{mmtcode}

	% Variant 2: Code given in LaTeX, rendered inline
	% You can use any delimiter you like, here we use /
	\mmtinline/theory MyTheory = c : type ❘ # abc ❙❚/

	% Variant 3: Code given externally in file, rendered in display mode
	\mmtfile{your-mmt-file.mmt}
\end{document}
```

**LaTeX Beamer**: Use the `fragile` option for frames embedding codes: `\begin{frame}[fragile] ... \end{frame}`

See the [minted manual](https://ctan.org/pkg/minted) for more information on how to customize it.

#### Common Error: Rendered PDF shows tab characters of source

If you tab characters in the MMT source being highlighted and they are shown in the PDF rendered by XeLaTeX, you face a known bug of XeLaTeX ([\[1\]](https://tex.stackexchange.com/a/36872/38074), [\[2\]](https://tex.stackexchange.com/a/14776/38074)). It can be solved by passing `-8bit` to XeLaTeX.

![image](https://user-images.githubusercontent.com/1827709/59755955-23c81200-9289-11e9-92c5-1659b60d03d1.png)

## Development

1. Install [pipenv](https://github.com/pypa/pipenv), which provides a consistent Python, pip and package environment locked in the committed `Pipfile` and `Pipfile.lock` files.
2. `git submodule init`
3. `git submodule update`

### Testing

1. `cd mmtpygments/test`
2. `pipenv run python test.py ./` (returns non-zero exit code on failure)
3. Open `index.html` in a browser to see failures visually (red rectangles).

This [`test.py`](mmtpygments/test/test.py) runs the lexer on large MMT archives containing a lot of MMT surface syntax. It recursively searches for MMT files in `mmtpygments/test/data`, on which it then runs the provided lexer and Pygment's HtmlFormatter. The rendered versions are written next to the original `*.mmt` files with an `.html` extension. Furthermore, `index.html` and `amalgamation.html` are generated to link and display the results, respectively.

The Travis build automatically runs [`test.py`](mmtpygments/test/test.py) and deploys the results on the `gh-pages` branch, see <https://comfreek.github.io/mmtpygments/> and especially <https://comfreek.github.io/mmtpygments/mmtpygments/test/index.html>.

## Development

For tinkering and testing the lexer, it is recommended to employ the same testing infrastructure as described above. Even though the Travis build fails on lexing error, [`test.py`](mmtpygments/test/test.py) actually doesn't -- it just returns a non-zero exit code. In fact, it even generates the HTML renderings with red rectangles around lexing errors. Hence, while tinkering with the lexer, just regularly run [`test.py`](mmtpygments/test/test.py) and look at the `index.html` locally in your browser to see any errors.

## Publishing

```bash
# Packaging
$ pipenv run python setup.py sdist bdist_wheel

# Checking if packages are okay (PyPi server will do the same)
$ pipenv run twine check dist/*

# Upload to Test PyPi repository
$ pipenv run twine upload --repository-url https://test.pypi.org/legacy/ dist/*

# Upload to real PyPi repository
$ pipenv run twine upload dist/*
```

## For future maintainers: necessary changes in case of repository movement

In case you wish to host this repository or a fork thereof somewhere else, these are the places where you have to make changes:

  - `README.md`: Change all links to deployed `gh-pages` branch render results accordingly.
  - `.travis.yml`: Change the base path with which `python test.py` is run to your hosting URI.


