Mathematics in PSML

Key point: When to use MathML, LaTex and AsciiMath in PageSeeder.

PageSeeder supports multiple formats to render mathematical symbols and equations. This article explains the different options and compares the three formats available to you: MathML, TeX, and AsciiMath.

Mathematics documents

PageSeeder can render both MathML or TeX documents in any browser as long as they use the correct file extension:

Use the .mml or .mathml file extension for MathML.
Use the .tex file extension for TeX.

Mathematics documents use the media icon .

Using documents is convenient if you have large or complex expressions which are reused throughout your content. You can also give a title, a description, and use metadata so you can find your document using the search. No configuration is necessary to use a document.

However, mathematics documents can only be updated by uploading a new version of the document since non-PSML documents aren’t editable. Also, PageSeeder doesn’t track the history of non-PSML documents. It might also be difficult to find the documents without previewing them if they don’t have a descriptive title or metadata.

PageSeeder doesn’t support AsciiMath documents but supports it in media fragments.

To render mathematics inline stored in separate documents, you need to use math xrefs.

Mathematics fragments

PageSeeder also supports media fragments that contain mathematical expressions in MathML, TeX and AsciiMath format as long as they use the correct media type. For example:

<media-fragment mediatype="application/x-tex">
  \f\relax{x} = \int_{-\infty}^\infty
    \f\hat\xi\,e^{2 \pi i \xi x}
    \,d\xi
</media-fragment>

Using media fragments lets you include mathematical expressions directly in PSML documents so you can see them in context, edit them and track changes. You can also reuse them using math xrefs.

But you cannot give them a title or description. Also, you need to define them in your document template directly or as fragment templates, so they require a little more configuration.

Mathematics labels

Another option is to use specific inline labels to render the mathematical expression within your text content.

PageSeeder supports:

The tex inline label to render TeX expressions.
The asciimathinline label to render asciimath expressions.

Using an inline label is convenient for shorter expressions that users want to display inline with their content, but they cannot be reused or transcluded. This is supported natively – managers only need to define these inline labels, on the project labels (manage) page, so that they are available to end-users.

For example:

<para>This formula
  <inline label="tex">f(x) = x^2</inline> is an example.</para>

Renders as:

This formula f(x) = x^2 is an example.

PageSeeder doesn’t support MathML in inline labels, only in documents.

Mathematics xrefs

They are special xrefs of type math that automatically render the target of the xref as a mathematical expression.

Math xrefs are natively supported by PageSeeder so documents that use them work without any additional configuration. However, to let users select mathematics documents to include in their content, the xref config must include an entry for math xrefs.

For developers

Here is an example of an xref config to include math documents:

<!-- To insert a Math equation from a document -->
<xref-config name="math" title="Math document">
  <xref frag="default" type="math" />
  <target filters="+pssubtype:math" />
</xref-config>

For more information, see PSML xref config in the developer documentation.

Publishing mathematics

PageSeeder can publish AsciiMath, TeX and MathML to both Word and PDF.

AsciiMath and TeX content is converted to MathML automatically as part of the publish process.

TeX conversion to MathML is still experimental.

Microsoft Office supports MathML, so MathML content is directly exported to the Word document.

When publishing PDF documents, PageSeeder first renders your MathML as a PNG image to include in your PDF.

Format comparison

MathML is a markup language to write mathematical expressions to render on the Web. It is comprehensive but verbose and can be difficult to edit. Since MathML is an XML language, PageSeeder is able to produce better diff outputs. MathML expressions can be rendered so that they are accessible.

TeX uses a text-based grammar that is also comprehensive. It is generally shorter than MathML, but complex expressions can be difficult to read.