Skip to content

Commit

Permalink
Merge pull request #212 from getnikola/fixing-doc
Browse files Browse the repository at this point in the history 
Fixing LaTeX plugin Markdown
  • Loading branch information
@felixfontein
felixfontein committed Feb 1, 2017
2 parents 7c9fbb8 + 068218c commit d273ed1
Showing 1 changed file with 41 additions and 38 deletions.
79 changes: 41 additions & 38 deletions v7/latex/README.md
View file
Expand Up @@ -14,52 +14,54 @@ The following LaTeX or LaTeX-similar constructs can be used:
* `\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.
* 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.
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}`.
* 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}`.
* 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.

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}`
* `\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.
* 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.

Expand All @@ -68,6 +70,7 @@ 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}`.
Expand Down Expand Up @@ -148,17 +151,17 @@ 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/).
* 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).
* `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.

Expand Down

0 comments on commit d273ed1

Please sign in to comment.