From b5dacf577e0fff7d3440d845e487bcd06151fc7a Mon Sep 17 00:00:00 2001
From: Matthias Geier <Matthias.Geier@gmail.com>
Date: Sun, 28 Feb 2016 13:16:04 +0100
Subject: [PATCH] DOC: Mention latexmk

---
 doc/usage.ipynb | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/doc/usage.ipynb b/doc/usage.ipynb
index 8f223994..fb67b3ea 100644
--- a/doc/usage.ipynb
+++ b/doc/usage.ipynb
@@ -70,12 +70,14 @@
     "    \n",
     "Afterwards, you can find the main HTML file in `_build/index.html`.\n",
     "\n",
+    "Subsequent builds will be faster, because only those source files which have changed will be re-built.\n",
+    "To force re-building all source files, use the `-E` option.\n",
+    "\n",
     "To create LaTeX output, use:\n",
     "\n",
     "    sphinx-build <source-dir> <build-dir> -b latex\n",
-    "    \n",
-    "Subsequent builds will be faster, because only those source files which have changed will be re-built.\n",
-    "To force re-building all source files, use the `-E` option."
+    "\n",
+    "If you don't know how to create a PDF file from the LaTeX output, you should have a look at [Latexmk](http://users.phys.psu.edu/~collins/software/latexmk-jcc/) (see also [this tutorial](http://mg.readthedocs.org/latexmk.html))."
    ]
   },
   {
@@ -95,8 +97,20 @@
     "    sphinx-autobuild <source-dir> <build-dir>\n",
     "\n",
     "This will start a local webserver which will serve the generated HTML pages at http://127.0.0.1:8000/.\n",
-    "And whenever you save changes in one of your notebooks, the appropriate HTML page(s) will be re-built and when finished, your browser view will be refreshed automatically.\n",
-    "Neat!"
+    "Whenever you save changes in one of your notebooks, the appropriate HTML page(s) will be re-built and when finished, your browser view will be refreshed automatically.\n",
+    "Neat!\n",
+    "\n",
+    "You can also abuse this to auto-build the LaTeX output:\n",
+    "\n",
+    "    sphinx-autobuild <source-dir> <build-dir> -b latex\n",
+    "\n",
+    "However, to auto-build the final PDF file, you'll need an additional tool.\n",
+    "Again, you can use `latexmk` for this (see [above](#Running-Sphinx)).\n",
+    "Change to the build directory and run\n",
+    "\n",
+    "    latexmk -pdf -pvc\n",
+    "\n",
+    "If your PDF viewer isn't opened because of LaTeX build errors, you can use the option `-f` to *force* creating a PDF file."
    ]
   },
   {