• View
• Edit
• History
• Attach
• Print
• Backlinks

ASCIIMath

Question addressed by this recipe

Would you (or your students) like to easily produce good-looking math formulas on wiki pages using a simple calculator-style syntax ?

Description

asciimath.zipΔ will help you incorporating mathematical formulas on PmWiki pages with a minimum of fuss.

Notes and Comments

ASCIIMath recipe is based on ASCIIMathPHP by Steven Chan -> mailto:kc56 [snail] cornell [period] edu, a PHP port of ASCIIMathML.js from Peter Jipsen.

Installation

1. Download and extract asciimath.zipΔ to the PmWiki's root directory.
2. Make sure you have:
   • cookbook/asciimath.php file and cookbook/asciimath directory,
   • pub/asciimath directory (note to updaters: the pub/xsl directory is no more used).
3. In your local/config.php file, you must include the asciimath.php script:

    include_once('cookbook/asciimath.php');
   

Optionally, you may keep the provided Cookbook text pages content (including this one) for further references.

Markup

Once installed, the following markups are available:

{$ %<parameters...>% formula $}

(:eqn <parameters...> :) [=
formula
=]

(:eqn <parameters...> :) 
formula
(:eqnend:)

with the following optional parameters:

• height=PIXELS to set the height reserved for the formula,
• num(=VALUE) to display (and eventually set) an equation number,

The markup parameters are filtered and all +... and -... unhandled options are silently discarded. All other parameters are forwarded to the MathML style definition.

Syntax

(Excerpt from ASCIIMathML.js : Syntax and List of Constants. Please refer to original site for complete references):

The syntax is very permissive and does not generate syntax errors. This allows mathematically incorrect expressions to be displayed, which is important for teaching purposes. It also causes less frustration when previewing formulas.

The parser uses no operator precedence and only respects the grouping brackets, subscripts, superscript, fractions and (square) roots. This is done for reasons of efficiency and generality. The resulting MathML code can quite easily be processed further to ensure additional syntactic requirements of any particular application.

The sample given on ASCIIMathML.js home page will be rendered with following page content:

'''Example:''' Solving the quadratic equation.

Suppose {$ %height=70px% ax^2+bx+c=0 text( with ) a!=0 $}

We first divide by ''a'' to get
{$ %num=1% x^2+b/ax+c/a=0 $}

Then we complete the square and obtain
{$ %num% x^2+b/ax+(b/(2a))^2-(b/(2a))^2+c/a=0 $}

The first three terms factor to give
{$ %num% (x+b/(2a))^2=(b^2)/(4a^2)-c/a $}

Now we take square roots on both sides and get
{$ %num% x+b/(2a)=+-sqrt((b^2)/(4a^2)-c/a) $}

Finally we move {$ b/(2a) $} to the right and simplify to
get the two solutions:
{$ %num=5% x_(1,2)=(-b+-sqrt(b^2-4ac))/(2a) $}

Implementation considerations, Limitations

Currently, formulas are handled in a two step process:

1. Generate formulas as XML files of MathML code into the pub/asciimath directory.
2. Render generated formulas in wiki page via some <iframe> tags with the help of the pmathml.xsl and pmathmlcss.xsl stylesheets provided in the pub/asciimath directory.

A formula file is generated only if it didn't previously exist or if formula text has changed. In edition mode (?action=edit) formulas are inconditionnally generated to handle preview feedback.

An extra ?action=purgeqns is made available to allow some clean up of the pub/asciimath directory if needed.

Each formula is anchored no its own page with the name eqn_<number> (the order of apparition in the page).

Nota

ASCIIMathPHP is based on an outdated version of ASCIIMathML.js (v1.3). Despite the current version has been patched to support more ASCIIMathML.js features, some of them are still lacking or non-functional. You may ask the author for upgrades.

See also

Contributors

• Dfaure

Releases Notes

• 2005-06-07 Initial version
• 2005-08-20 Updated to modified ASCIIMathPHP v1.10 (patch submitted to the author), and fixed typo bugs.
• 2005-09-04 Fixed <:vspace> hint with 2.0.0 and above.
• 2006-01-30 Added missing stylesheet and reduced pub/ directory pollution. Minor tweaks.
• 2006-03-07 Merging unreleased enhancements.
• 2006-10-26 Add RecipeInfo data. Cleaned code.
• 2006-10-28 Minor tweaks.
• 20190209 Update for PHP 7, requires PHP 5 or newer and PmWiki 2.2.58 or newer.

Comments

See discussion at ASCIIMath-Talk