From be18c2811159787030c2ef32087c9cc66b625246 Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Sun, 17 Feb 2019 12:38:50 +0100
Subject: [PATCH] DOC: How to define LaTeX macros

---
 doc/conf.py              |  5 ++-
 doc/markdown-cells.ipynb | 69 ++++++++++++++++++++++++++++++++++++++--
 2 files changed, 71 insertions(+), 3 deletions(-)

diff --git a/doc/conf.py b/doc/conf.py
index b6337fd1..ec188d79 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -97,7 +97,10 @@
 #}
 
 mathjax_config = {
-    'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},
+    'TeX': {
+        'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True},
+        'extensions': ['newcommand.js', 'begingroup.js'],
+    },
 }
 
 # Additional files needed for generating LaTeX/PDF output:
diff --git a/doc/markdown-cells.ipynb b/doc/markdown-cells.ipynb
index 2d3e9a54..9515add4 100644
--- a/doc/markdown-cells.ipynb
+++ b/doc/markdown-cells.ipynb
@@ -81,6 +81,69 @@
     "```"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Defining LaTeX Macros\n",
+    "\n",
+    "LaTeX users will be familiar with defining new macros by using\n",
+    "`\\newcommand` or the more low-level `\\def` command .\n",
+    "\n",
+    "If you want to use that for both HTML and LaTeX output,\n",
+    "you have to take some extra care.\n",
+    "You should make your definitions like this:\n",
+    "\n",
+    "```\n",
+    "<div hidden>\n",
+    "\n",
+    "$\\gdef\\vec#1{\\boldsymbol{#1}}$\n",
+    "\n",
+    "\\vskip-\\parskip\n",
+    "\\vskip-\\baselineskip\n",
+    "\n",
+    "</div>\n",
+    "```\n",
+    "\n",
+    "<div hidden>\n",
+    "\n",
+    "$\\gdef\\vec#1{\\boldsymbol{#1}}$\n",
+    "\n",
+    "\\vskip-\\parskip\n",
+    "\\vskip-\\baselineskip\n",
+    "\n",
+    "</div>\n",
+    "\n",
+    "This makes sure that the definition itself is not visible in HTML output\n",
+    "(by using `<div hidden>`).\n",
+    "In LaTeX output, the definition creates an empty equation in a new paragraph.\n",
+    "To get rid of the additional vertical spacing, `\\vskip` is used.\n",
+    "\n",
+    "Using `\\def` inside math mode is supported in MathJax,\n",
+    "but in LaTeX, it doesn't have any effect on later math expressions.\n",
+    "Using `\\gdef` works in both.\n",
+    "Sadly, `\\gdef` isn't activated by default in MathJax,\n",
+    "therefore we need some additional configuration in our `conf.py` file:\n",
+    "\n",
+    "```python\n",
+    "mathjax_config = {\n",
+    "    'TeX': {\n",
+    "        'extensions': ['newcommand.js', 'begingroup.js'],\n",
+    "    },\n",
+    "}\n",
+    "\n",
+    "```\n",
+    "\n",
+    "With the above definition and the `conf.py` setting in place,\n",
+    "you can use your new macro like this:\n",
+    "\n",
+    "```\n",
+    "$2 \\vec{a} + \\vec{b}$\n",
+    "```\n",
+    "\n",
+    "... which looks like this: $2 \\vec{a} + \\vec{b}$"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -100,7 +163,9 @@
     "\n",
     "```python\n",
     "mathjax_config = {\n",
-    "    'TeX': {'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True}},\n",
+    "    'TeX': {\n",
+    "        'equationNumbers': {'autoNumber': 'AMS', 'useLabelIds': True},\n",
+    "    },\n",
     "}\n",
     "```\n",
     "\n",
@@ -491,7 +556,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.1"
+   "version": "3.7.2+"
   }
  },
  "nbformat": 4,