NEW: For html, equation numbers are now written into a span and justified right. Also: Equation numbers by section in LaTeX/pdf and html.

pandoc-eqnos 0.16

pandoc-eqnos is a pandoc filter for numbering equations and equation references in processed markdown documents. A cross-referencing syntax is added to markdown for this purpose.

Demonstration: Processing demo3.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.

This version of pandoc-eqnos was tested using pandoc 1.15.2 - 1.19.1. It works under linux, Mac OS X and Windows. Older versions and other platforms can be supported on request. I am pleased to receive bug reports and feature requests on the project's Issues tracker.

If you find pandoc-eqnos useful, then please encourage further development by giving it a star on GitHub.

Usage
Markdown Syntax
Customization
Technical Details
Installation
Getting Help

Usage

To apply the filter during document processing, use the following option with pandoc:

--filter pandoc-eqnos

Note that any use of --filter pandoc-citeproc or --bibliography=FILE options should come after the pandoc-eqnos filter call.

Markdown Syntax

The markdown syntax extension used by pandoc-eqnos was developed in pandoc Issue #813 -- see this post by @scaramouche1.

To mark an equation for numbering, add the label eq:id to its attributes:

$$ y = mx + b $$ {#eq:id}

The prefix #eq: is required. id should be replaced with a unique identifier composed of letters, numbers, dashes, slashes and underscores. If id is omitted then the equation will be numbered but unreferenceable.

To reference the equation, use

@eq:id

{@eq:id}

Curly braces around a reference are stripped from the output.

Demonstration: Processing demo.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.

Clever References

Writing markdown like

See eq. @eq:id.

seems a bit redundant. Pandoc-eqnos supports "clever referencing" via single-character modifiers in front of a reference. You can write

 See +@eq:id.

to have the reference name (i.e., "eq.") automatically generated. The above form is used mid-sentence. At the beginning of a sentence, use

 *@eq:id

instead. If clever referencing is enabled by default (see Customization, below), you can disable it for a given reference using¹

!@eq:id

Demonstration: Processing demo2.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.

Note: If you use *eq:id and emphasis (e.g., *italics*) in the same sentence, then you must backslash escape the * in the clever reference; e.g., \*eq:id.

Tagged Equations

You may optionally override the equation number by placing a tag in an equation's attributes block as follows:

$$ y = mx + b $$ {#eq:id tag="B.1"}

The tag may be arbitrary text, or an inline equation such as $\mathrm{B.1'}$ . Mixtures of the two are not currently supported.

Customization

Pandoc-eqnos may be customized by setting variables in the metadata block or on the command line (using -M KEY=VAL). The following variables are supported:

eqnos-cleveref or just cleveref - Set to On to assume "+" clever references by default;
eqnos-plus-name - Sets the name of a "+" reference (e.g., change it from "eq." to "equation"); and
eqnos-star-name - Sets the name of a "*" reference (e.g., change it from "Equation" to "Eq.").

Demonstration: Processing demo3.md with pandoc --filter pandoc-eqnos gives numbered equations and references in pdf, tex, html, epub, md and other formats.

Equation Numbers by Section

The --number-sections option enables section numbers in pandoc. Equation numbers by section (e.g., "Eq. 2.1") can be obtained as follows:

html: Add xnos-section-numbers: On to your YAML metadata or use the -M xnos-section-numbers=On option with pandoc. This variable is ignored for other output formats.
LaTeX/pdf: Add header-includes: \numberwithin{equation}{section} to your YAML metadata. If you need multiple header includes, then add something like this:
```
header-includes:
  - \numberwithin{figure}{section}
  - \numberwithin{equation}{section}
  - \numberwithin{table}{section}
```
Alternatively, write your header includes into FILE, and use the --include-in-header=FILE option with pandoc.

If you set either --top-level-division=part or --top-level-division=chapter then these header includes can be dropped.

LaTeX header-includes are ignored for html output.

Technical Details

TeX/pdf:

The equation environment is used;
Tagged equations make use of the \tag macro;
The \label and \ref macros are used for equation labels and references; and
The clever referencing macros \cref and \Cref are used if they are available (i.e. included in your LaTeX template via \usepackage{cleveref}), otherwise they are faked. Set the meta variable xnos-cleveref-fake to Off to disable cleveref faking.

Html:

The math element and a hard-coded equation number/tag are wrapped in an "outer" span element;
The equation number/tag is wrapped in its own "inner" span and justified right; and
(Clever) references are hard-coded and linked to their target.

Other formats:

Numbers/tags are hard-coded into the equation; and
(Clever) references are hard-coded into the output.

Installation

Pandoc-eqnos requires python, a programming language that comes pre-installed on linux and Mac OS X, and which is easily installed on Windows. Either python 2.7 or 3.x will do.

Standard installation

Install pandoc-eqnos (as root) using the shell command

pip install pandoc-eqnos

To upgrade to the most recent release, use

pip install --upgrade pandoc-eqnos

Pip is a program that downloads and installs modules from the Python Package Index, PyPI. It should come installed with your python distribution.

Troubleshooting

If you are prompted to upgrade pip, then do so. Installation errors may occur with older versions. The command you need to execute (as root) is

python -m pip install --upgrade pip

You may test the installation as a regular user using the shell command

which pandoc-eqnos

This will tell you where pandoc-eqnos is installed. If it is not found, then please submit a report to our Issues tracker.

Installing on linux

If you are running linux, pip may be packaged separately from python. On Debian-based systems (including Ubuntu), you can install pip as root using

apt-get update
apt-get install python-pip

During the install you may be asked to run

easy_install -U setuptools

owing to the ancient version of setuptools that Debian provides. The command should be executed as root. You may now follow the standard installation procedure given above.

Installing on Mac OS X

To install as root on Mac OS X, you will need to use the sudo command. For example:

sudo pip install pandoc-eqnos

Troubleshooting with which should be done as a regular user (i.e., without using sudo).

Installing on Windows

It is easy to install python on Windows. First, download the latest release. Run the installer and complete the following steps:

Install Python pane: Check "Add Python 3.5 to path" then click "Customize installation".
Optional Features pane: Click "Next".
Advanced Options pane: Optionally check "Install for all users" and customize the install location, then click "Install".

Once python is installed, start the "Command Prompt" program. Depending on where you installed python, you may need elevate your privileges by right-clicking the "Command Prompt" program and selecting "Run as administrator". You may now follow the standard installation procedure given above. Be sure to close the Command Prompt program when you have finished.

Getting Help

If you have any difficulties with pandoc-eqnos, or would like to see a new feature, please submit a report to our Issues tracker.

Footnotes

1: The disabling modifier "!" is used instead of "-" because pandoc unnecessarily drops minus signs in front of references.

rowhit / pandoc-eqnos Goto Github PK

pandoc-eqnos's Introduction

pandoc-eqnos 0.16

Contents