Merge pull request #206 from getnikola/latex

Added LaTeX page compiler plugin.
getnikola · Jan 16, 2017 · 114fb97 · 114fb97
2 parents 4acf708 + d2d02b5
commit 114fb97
Show file tree

Hide file tree

Showing 13 changed files with 3,901 additions and 0 deletions.
diff --git a/v7/latex/README.md b/v7/latex/README.md
@@ -0,0 +1,184 @@
+This plugin allows to write posts and pages in a subset of LaTeX. This makes it possible to use the same `.tex` file both as input to this page compiler and as an include for a real LaTeX document.
+
+For Python before 3.4, you need to install the [`enum34` library](https://pypi.python.org/pypi/enum34). From Python 3.4 on, it is part of the language.
+
+
+Supported LaTeX subset
+======================
+
+The posts should contain what usually is contained between `\begin{document}` and `\end{document}` in a LaTeX document.
+
+The following LaTeX or LaTeX-similar constructs can be used:
+
+* Simple formatting such as `\textbf{...}`, `\textit{...}`, `\texttt{...}` and `\emph{...}`.
+* `\begin{center} ... \end{center}` can be used for centered text.
+* `\begin{blockquote} ... \end{blockquote}` can be used for block quotes.
+* Formulae:
+  * Everything of the form `$...$`, `\( ... \)` for inline formulae.
+  * Everything of the form `$$...$$`, `\[ ... \]` for display-style formulae.
+  * `\begin{align} ... \end{align}` and `\begin{align*} ... \end{align*}` for
+    aligned formulae from the AMSMath package. Note that no equation numbers will be used in HTML output, and that you cannot use `\label{...}` and `\ref{...}` with `\begin{align}` environments.
+  * Everything of the form `\begin{pstricks}{...} ... \end{pstricks}`.
+  * Everything of the form `\begin{tikzpicture}[...] ... \end{tikzpicture}`.
+  * There is a special environment for lists of formulae which can be rearranged in multiple columns: `\begin{formulalist} \formula{$1+1$} \formula{$f(x)$} ... \end{formulalist}`
+    The `\begin{formulalist}` can have an optional argument which indicates the number of columns. This is currently not used.
+
+  Please note that the use of align-style formulae, PSTricks images and TikZ pictures requires the [`latex_formula_renderer` plugin](https://plugins.getnikola.com/v7/latex_formula_renderer/); see below for more information.
+
+* Enumerations:
+  * Ordered enumerations with `\begin{enumerate} \item ... \end{enumerate}`.
+  * Unordered enumerations with `\begin{itemize} \item ... \end{itemize}`.
+* Source code:
+  * Inline with `\code{lang}{...}` or `\code{lang}|...|`, where `lang` specifies the language and `|` can also be any other character than `{` and `[` which marks both the beginning and the end of the inline code.
+  * Block with `\begin{codelisting}{lang} ... \end{codelisting}`.
+
+  The language field is currently passed unprocessed to pygments.
+* Controls like `\\` and `\newpar`.
+* Section headers like `\chapter{...}`, `\section{...}`, `\subsection{...}` and `subsubsection{...}`.
+* Theorem environments:
+  * `\begin{definition} ... \end{definition}`;
+  * `\begin{definitions} ... \end{definitions}`;
+  * `\begin{lemma} ... \end{lemma}`;
+  * `\begin{proposition} ... \end{proposition}`;
+  * `\begin{theorem} ... \end{theorem}`;
+  * `\begin{corollary} ... \end{corollary}`;
+  * `\begin{example} ... \end{example}`;
+  * `\begin{examples} ... \end{examples}`;
+  * `\begin{remark} ... \end{remark}`;
+  * `\begin{remarks} ... \end{remarks}`;
+  * `\begin{proof} ... \end{proof}`.
+
+  To add a QED sign at the end of an environment, use `\qed` inside the environment. This is done automatically for `proof` environments.
+
+  Also, the environments have an optional title argument: `\begin{theorem}[Fermat's Last Theorem] ... \end{theorem}`
+* Labels `\label{...}` are recognized in some contexts (section headers and theorem environments) and can be refered to with `\ref{...}` or `\ref[Text]{label}`.
+* URLs can be inserted with `\url{...}` and hyperlinks with `\href{url}{text}`.
+* Short texts in foreign languages can be marked with `\foreignlanguage{language}{text}`.
+* Arbitrary unicode symbols can be inserted with `\symbol{...}`, where the decimal representation must be used.
+* `\noindent` and `\setlength{...}{...}` are ignored.
+* Images can be inserted with `\includegraphics{filename}` or `\includegraphics[...]{filename}`. The optional argument is a comma-separated list of `key=value` pairs, where we support the keys `width`, `height`, and `alt` (for the `<img alt=""` argument in HTML). The width and height values can be of the following forms:
+  * If the unit ends with `\textwidth` resp. `\textheight`, the value before will be interpreted as a fractional value (or 1 if there is nothing before) and converted to a percent value in HTML output.
+  * If the unit ends with `cm`, it will be converted to `em` in HTML output.
+  * Otherwise, the unit will be expected to be a unit-less number and will be taken as pixel size in HTML output.
+* Tables can be set with `\begin{tabular}{...} ... \end{tabular}`. Both `\hline` and `\cline{...}` are supported, and the argument of `\begin{tabular}` can consist out of `|`, `l`, `r` and `c`.
+* Pictures can be grouped with `\begin{picturegroup} \picture{title}{commands} ... \end{picturegroup}`. The `commands` can be `\includegraphics`, TikZ pictures, PSTricks pictures, etc.
+
+
+LaTeX compatibility
+-------------------
+
+Almost everything listed above is compatible to LaTeX, except:
+* The `\begin{blockquote} ... \end{blockquote}` environment.
+* The formula list environment `\begin{formulalist} \formula{...} ... \end{formulalist}`.
+* The picture group environment `\begin{picturegroup} \picture{title}{commands} ... \end{picturegroup}`.
+* The code command `\code` and environment `\begin{codelisting} ... \end{codelisting}`.
+* The pixel width/height and alternative text of `\includegraphics[...]{...}`.
+
+See below how for definitions in LaTeX which will allow to use almost all of these constructs in LaTeX documents.
+
+
+Block quotes
+------------
+
+The block quote environment `blockquote` can be defined in LaTeX as follows:
+
+``` .tex
+\newenvironment{blockquote}%
+  {\begin{quote}}%
+  {\end{quote}}
+```
+
+
+Formula list
+------------
+
+The formula list environment `formulalist` can be defined in LaTeX as follows:
+
+``` .tex
+\usepackage{ifthen}
+\newenvironment{formulalist}[1][1]
+  {%
+    \def\formulalistcols{#1}%
+    \begin{list}{}{\rightmargin-0.5cm\leftmargin+0.5cm}\item[]%
+    \ifnumequal{\formulalistcols}{1}{\begin{flushleft}}{\begin{multicols}{#1}}%
+    \long\def\formula##1{\par\noindent##1}%
+  }%
+  {%
+    \ifnumequal{\formulalistcols}{1}{\end{flushleft}}{\end{multicols}}%
+    \end{list}%
+  }
+```
+
+
+Picture group
+-------------
+
+The picture group environment `picturegroup` can be defined in LaTeX as follows:
+
+``` .tex
+\newenvironment{picturegroup}
+  {%
+    \begin{center}%
+    \renewcommand{\arraystretch}{0.2}%
+    \lineskip=10pt\baselineskip=0pt%
+    \long\def\picture##1##2{\begin{tabular}[b]{c}\mbox{##2}\\\mbox{##1}\end{tabular}}%
+  }%
+  {%
+    \end{center}%
+  }
+```
+
+
+Code listings
+-------------
+
+The `\code` command and the `codelisting` environment can be defined in LaTeX as follows using the [`listings` package](https://www.ctan.org/pkg/listings):
+
+``` .tex
+\usepackage{listings}
+\newcommand{\code}[1]{\lstset{language=#1}\lstinline}
+\lstnewenvironment{codelisting}[1]{\lstset{language=#1}}{}
+```
+
+Note that `listings` is known to have problems with Unicode. Alternatively, you might be able to use the [`minted` package](https://www.ctan.org/pkg/minted).
+
+
+Formulae backend
+================
+
+There are two available formulae backends:
+
+ * one based on the [`latex_formula_renderer` plugin](https://plugins.getnikola.com/v7/latex_formula_renderer/);
+ * one based on [MathJax](https://www.mathjax.org/).
+
+You can choose which one by setting the `LATEX_FORMULA_RENDERER` configuration variable; default is `latex_formula_image_renderer`, which is based on the `latex_formula_renderer` plugin. See `conf.py.sample` for more information.
+
+The first plugin allows special features the second doesn't:
+
+ * `align` environments (see the [AMSMath documentation](ftp://ftp.ams.org/ams/doc/amsmath/amsldoc.pdf));
+ * XY-pic diagrams (see the [XY-Pic user guide](http://texdoc.net/texmf-dist/doc/generic/xypic/xyguide.pdf));
+ * PSTricks graphics (see [here](https://en.wikipedia.org/wiki/PSTricks) for more information);
+ * TikZ pictures (see [here](https://en.wikibooks.org/wiki/LaTeX/PGF/TikZ) for more information).
+
+You need an installed LaTeX distribution for this to work, with some extra tools. See the `latex_formula_renderer` plugin for details.
+
+
+Required Translations
+=====================
+
+You need to add the following translations to your theme if you use theorem environments:
+``` .py
+MESSAGES = {
+    'math_thm_name': 'Theorem',
+    'math_prop_name': 'Proposition',
+    'math_cor_name': 'Corollary',
+    'math_lemma_name': 'Lemma',
+    'math_def_name': 'Definition',
+    'math_defs_name': 'Definitions',
+    'math_proof_name': 'Proof',
+    'math_example_name': 'Example',
+    'math_examples_name': 'Examples',
+    'math_remark_name': 'Remark',
+    'math_remarks_name': 'Remarks',
+}
+```
diff --git a/v7/latex/conf.py.sample b/v7/latex/conf.py.sample
@@ -0,0 +1,16 @@
+# Determines how the formulae are rendered. Possibilities:
+#  - "latex_formula_image_renderer": renders formulae as graphics and includes them.
+#  - "latex_formula_mathjax": inserts MathJax code.
+LATEX_FORMULA_RENDERER = "latex_formula_image_renderer"
+
+# When "latex_formula_image_renderer" is selected as the formula renderer,
+# the formulae colors and scale can be set here:
+#
+# The color must be given as an RGB triple with components in range [0, 1].
+# Here, (0, 0, 0) is black and (1, 1, 1) is white.
+LATEX_FORMULA_COLOR = (0., 0., 0.)
+#
+# The formula scale determines the effective size of the formulae.
+# Check what looks good with your theme's main font.
+LATEX_FORMULA_SCALE = 1.25
+
diff --git a/v7/latex/latex.plugin b/v7/latex/latex.plugin
@@ -0,0 +1,12 @@
+[Core]
+Name = latex
+Module = latex
+
+[Nikola]
+PluginCategory = PageCompiler
+
+[Documentation]
+Author = Felix Fontein
+Version = 0.1
+Website = https://felix.fontein.de
+Description = Compile a subset of LaTeX to HTML