# AsciiMath
ifndef::env-site[:status:]

An http://asciimath.org[AsciiMath] parser and MathML/LaTeX generator written in pure Ruby.

ifdef::status[]
[discrete]
## Status

image:https://travis-ci.org/pepijnve/asciimath.svg?branch=master["Linux Build Status", link="https://travis-ci.org/asciidoctor/asciimath"]
image:https://img.shields.io/gem/v/asciimath.svg?label=gem%20version[Gem Version, link=https://rubygems.org/gems/asciimath]
endif::status[]

## Installation

Add this line to your application's Gemfile:

[source,ruby]
----
gem 'asciimath'
----

And then execute:

    $ bundle

Or install it yourself as:

    $ gem install asciimath

## Usage

### Library

First require the library.

[source,ruby]
----
require 'asciimath'
----

Then parse an AsciiMath string.

[source,ruby]
----
parsed_expression = AsciiMath.parse(asciimath)
----

The parsed expression is a set of nested Array and Hash objects.

This expression can then be converted to MathML, HTML (experimental) or LaTeX.

[source,ruby]
----
math_ml = parsed_expression.to_mathml
html = parsed_expression.to_html
latex = parsed_expression.to_latex
----

The MathML, HTML or LaTeX code is returned as a String.

### Command line

The AsciiMath parser and converters can be invoked via the command line as follows:

.MathML Generation
[source]
----
asciimath "an asciimath string"

or

asciimath mathml "an asciimath string"
----

.HTML Generation
[source]
----
asciimath html "an asciimath string"
----

.LaTeX Generation
[source]
----
asciimath latex "an asciimath string"
----

This command will print out the generated code on stdout.

## Extentions and Customization

The parser can be extended by passing a custum tokenization table:

[source, ruby]
----
my_tokens_table = AsciiMath::SymbolTableBuilder.new
AsciiMath::Parser.add_default_parser_symbols(my_tokens_table)
my_tokens_table.add('mysymbol', :mysymbol, :symbol)

AsciiMath::parse("a + mysymbol + b", my_tokens_table.build)
----

Furthermore, the behaviour of the tokenizer be customized by altering the value 
associated with a token in `AsciiMath::Tokenizer::DEFAULT_PARSE_SYMBOL_TABLE`:

[source, ruby]
----
my_tokens_table = AsciiMath::SymbolTableBuilder.new
AsciiMath::Parser.add_default_parser_symbols(my_tokens_table)
my_tokens_table.add('alpha', :beta, :symbol)

# Now "alpha + beta" is equivalent to "beta + beta"
AsciiMath::parse("alpha + beta", my_tokens_table.build)
----

The same behaviour applies to each individual render (`MathMLBuilder`, 
`HTMLBuilder` and `LatexBuilder`). By adding entries to a rendere's rendering 
table (or modifying exisisting entries), users can customize it's output:

[source, ruby]
----
my_rendering_table = AsciiMath::SymbolTableBuilder.new
AsciiMath::MarkupBuilder.add_default_display_symbols(my_rendering_table)
my_rendering_table.add('alpha', '\u03b2', :identifier)

# Now "alpha + beta" is equivalent to "beta + beta"
AsciiMath::parse("alpha + beta").to_mathml(my_rendering_table.build)
----

## Notes on the HTML Output

The HTML output is still regarded somewhat experimental - for basic usage it is fine, but it is not yet complete.
Known issues are as follows:

 * `sqrt` function does not generate sane output
 * Use of font commands (e.g. `bb`) will result in broken output.
 * Accents do not extend to match what they cover.
 * Rendering of "integrals" uses a generic path that does not look amazing.
 * The size of braces does not account for complex content - so a matrix will render with the right sized braces if all of its elements are single-height text, but braces around e.g. fractions will render at the incorrect height.

Rendering the HTML output correctly requires the inclusion of `style/math.css` in the html document.
There is currently no specific required font for this output, it simply selects a `serif` font family - change the `@font-family` attribute in the `.math-inline` class to select something specific.

## Notes on the LaTeX Output

All LaTeX commands and environments used in the output are coverved by 
https://ctan.org/pkg/amsmath[`amsmath`] and `amssymb`, with a few exceptions:

 * `\color`
 * `\cancel`
 * `\mathscr`
 * `\twoheadrightarrowtail`

The `\color` command is supported by the 
https://www.ctan.org/pkg/xcolor[`xcolor`] package, which is included in most 
LaTeX distributions. The `\cancel` command is supported by the 
https://www.ctan.org/pkg/cancel[cancel] package, also included in most LaTeX 
distributions. The other commands are supported by the 
https://ctan.org/pkg/stix[`stix`] package.

## Contributing

. Fork it (https://github.com/pepijnve/asciimath/fork)
. Create your feature branch (`git checkout -b my-new-feature`)
. Commit your changes (`git commit -am 'Add some feature'`)
. Push to the branch (`git push origin my-new-feature`)
. Create a new Pull Request