summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--.travis.yml108
-rw-r--r--Makefile3
-rw-r--r--README625
-rw-r--r--Setup.hs35
-rw-r--r--appveyor.yml5
-rw-r--r--benchmark/benchmark-pandoc.hs11
-rw-r--r--changelog227
m---------data/templates13
-rw-r--r--make_travis_yml.hs210
-rw-r--r--pandoc.cabal8
-rw-r--r--src/Text/Pandoc/Options.hs9
-rw-r--r--src/Text/Pandoc/Readers/Docx.hs4
-rw-r--r--src/Text/Pandoc/Readers/Docx/Parse.hs4
-rw-r--r--src/Text/Pandoc/Readers/LaTeX.hs8
-rw-r--r--tests/Tests/Readers/Docx.hs4
-rw-r--r--tests/docx/special_punctuation.docxbin0 -> 8408 bytes
-rw-r--r--tests/docx/special_punctuation.native2
-rw-r--r--tests/lhs-test.latex10
-rw-r--r--tests/lhs-test.latex+lhs10
-rw-r--r--tests/writer.latex10
20 files changed, 965 insertions, 341 deletions
diff --git a/.travis.yml b/.travis.yml
index 4979593d0..7b91b71d9 100644
--- a/.travis.yml
+++ b/.travis.yml
@@ -1,39 +1,87 @@
-# NB: don't set `language: haskell` here
-
-# Ensures that sudo is disabled, so that containerized builds are allowed
+# This file has been generated -- see https://github.com/hvr/multi-ghc-travis
+language: c
sudo: false
-# The following enables several GHC versions to be tested; often it's enough to test only against the last release in a major GHC version. Feel free to omit lines listings versions you don't need/want testing for.
+cache:
+ directories:
+ - $HOME/.cabsnap
+ - $HOME/.cabal/packages
+
+before_cache:
+ - rm -fv $HOME/.cabal/packages/hackage.haskell.org/build-reports.log
+ - rm -fv $HOME/.cabal/packages/hackage.haskell.org/00-index.tar
+
matrix:
- include:
- - env: CABALVER=1.16 GHCVER=7.4.2 GHCOPTS="-Werror" JOPTS=""
- addons: {apt: {packages: [cabal-install-1.16, ghc-7.4.2], sources: [hvr-ghc]}}
- - env: CABALVER=1.18 GHCVER=7.6.3 GHCOPTS="-Werror" JOPTS="-j2"
- addons: {apt: {packages: [cabal-install-1.18, ghc-7.6.3], sources: [hvr-ghc]}}
- - env: CABALVER=1.18 GHCVER=7.8.4 GHCOPTS="-Werror" JOPTS="-j2"
- addons: {apt: {packages: [cabal-install-1.18, ghc-7.8.4], sources: [hvr-ghc]}}
- - env: CABALVER=head GHCVER=7.10.1 GHCOPTS="" JOPTS="-j2"
- addons: {apt: {packages: [cabal-install-head, ghc-7.10.1],sources: [hvr-ghc]}}
-# - env: CABALVER=head GHCVER=head GHCOPTS="-Werror" JOPTS="-j2"
-# addons: {apt: {packages: [cabal-install-head,ghc-head], sources: [hvr-ghc]}}
-
-# Note: the distinction between `before_install` and `install` is not important.
+ include:
+ - env: CABALVER=1.16 GHCVER=7.4.2 GHCOPTS=-Werror
+ compiler: ": #GHC 7.4.2"
+ addons: {apt: {packages: [cabal-install-1.16,ghc-7.4.2], sources: [hvr-ghc]}}
+ - env: CABALVER=1.16 GHCVER=7.6.3 GHCOPTS=-Werror
+ compiler: ": #GHC 7.6.3"
+ addons: {apt: {packages: [cabal-install-1.16,ghc-7.6.3], sources: [hvr-ghc]}}
+ - env: CABALVER=1.18 GHCVER=7.8.4 GHCOPTS=-Werror
+ compiler: ": #GHC 7.8.4"
+ addons: {apt: {packages: [cabal-install-1.18,ghc-7.8.4], sources: [hvr-ghc]}}
+ - env: CABALVER=1.22 GHCVER=7.10.2 GHCOPTS=
+ compiler: ": #GHC 7.10.2"
+ addons: {apt: {packages: [cabal-install-1.22,ghc-7.10.2], sources: [hvr-ghc]}}
+
before_install:
+ - unset CC
- export PATH=/opt/ghc/$GHCVER/bin:/opt/cabal/$CABALVER/bin:$PATH
install:
- - cabal-$CABALVER update
-# - git clone https://github.com/jgm/pandoc-types && cd pandoc-types && cabal-1.18 install && cd ..
- - cabal-$CABALVER install $JOPTS --only-dependencies --enable-tests
+ - cabal --version
+ - echo "$(ghc --version) [$(ghc --print-project-git-commit-id 2> /dev/null || echo '?')]"
+ - if [ -f $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz ];
+ then
+ zcat $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz >
+ $HOME/.cabal/packages/hackage.haskell.org/00-index.tar;
+ fi
+ - travis_retry cabal update -v
+ - sed -i 's/^jobs:/-- jobs:/' ${HOME}/.cabal/config
+ - cabal install --only-dependencies --enable-tests --enable-benchmarks --dry -v > installplan.txt
+ - sed -i -e '1,/^Resolving /d' installplan.txt; cat installplan.txt
-# Here starts the actual work to be performed for the package under test; any command which exits with a non-zero exit code causes the build to fail.
-script:
- - |
- if [ "${CABALVER}" != "1.16" ]; then
- cabal-$CABALVER sdist --output-directory=build
- cd build
+# check whether current requested install-plan matches cached package-db snapshot
+ - if diff -u installplan.txt $HOME/.cabsnap/installplan.txt;
+ then
+ echo "cabal build-cache HIT";
+ rm -rfv .ghc;
+ cp -a $HOME/.cabsnap/ghc $HOME/.ghc;
+ cp -a $HOME/.cabsnap/lib $HOME/.cabsnap/share $HOME/.cabsnap/bin $HOME/.cabal/;
+ else
+ echo "cabal build-cache MISS";
+ rm -rf $HOME/.cabsnap;
+ mkdir -p $HOME/.ghc $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin;
+ cabal install --only-dependencies --enable-tests --enable-benchmarks;
fi
- - cabal-$CABALVER configure --enable-tests -v2 # -v2 provides useful information for debugging
- - cabal-$CABALVER build $JOPTS --ghc-options=$GHCOPTS # this builds all libraries and executables (including tests/benchmarks)
- - cabal-$CABALVER test
- - cabal-$CABALVER check
+
+# snapshot package-db on cache miss
+ - if [ ! -d $HOME/.cabsnap ];
+ then
+ echo "snapshotting package-db to build-cache";
+ mkdir $HOME/.cabsnap;
+ cp -a $HOME/.ghc $HOME/.cabsnap/ghc;
+ cp -a $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin installplan.txt $HOME/.cabsnap/;
+ fi
+
+# Here starts the actual work to be performed for the package under test;
+# any command which exits with a non-zero exit code causes the build to fail.
+script:
+ - if [ -f configure.ac ]; then autoreconf -i; fi
+ - cabal configure --enable-tests --enable-benchmarks -v2 # -v2 provides useful information for debugging
+ - cabal build --ghc-options=$GHCOPTS # this builds all libraries and executables (including tests/benchmarks)
+ - cabal test
+ - cabal check
+# Test that a source-distribution can be generated
+# (with cabal >= 1.18 'cabal sdist' would work too):
+ - ./dist/setup/setup sdist
+
+# Check that the resulting source distribution can be built & installed.
+# If there are no other `.tar.gz` files in `dist`, this can be even simpler:
+# `cabal install --force-reinstalls dist/*-*.tar.gz`
+ - SRC_TGZ=$(cabal info . | awk '{print $2;exit}').tar.gz &&
+ (cd dist && cabal install --force-reinstalls "$SRC_TGZ")
+
+# EOF
diff --git a/Makefile b/Makefile
index a44085420..7c16418f8 100644
--- a/Makefile
+++ b/Makefile
@@ -34,6 +34,9 @@ dist: man/pandoc.1
cd pandoc-${version}
cabal configure ${CABALARGS} && cabal build && cabal test && cd .. && rm -rf "pandoc-${version}"
+.travis.yml: pandoc.cabal make_travis_yml.hs
+ runghc make_travis_yml.hs $< > $@
+
debpkg: man/pandoc.1
./make_deb.sh
diff --git a/README b/README
index e5812bda6..cff46901d 100644
--- a/README
+++ b/README
@@ -12,25 +12,26 @@ Description
Pandoc is a [Haskell] library for converting from one markup format to
another, and a command-line tool that uses this library. It can read
-[Markdown], [CommonMark], and (subsets of) [Textile],
-[reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
-markup], [Haddock markup], [OPML], [Emacs Org-mode], [DocBook],
+[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
+and (subsets of) [Textile], [reStructuredText], [HTML], [LaTeX], [MediaWiki markup], [TWiki
+markup], [Haddock markup], [OPML], [Emacs Org mode], [DocBook],
[txt2tags], [EPUB], [ODT] and [Word docx]; and it can write plain text,
-[Markdown], [reStructuredText], [XHTML], [HTML 5], [LaTeX] (including
-[beamer] slide shows), [ConTeXt], [RTF], [OPML], [DocBook],
+[Markdown], [CommonMark], [PHP Markdown Extra], [GitHub-Flavored Markdown],
+[reStructuredText], [XHTML], [HTML5], [LaTeX] (including
+[`beamer`] slide shows), [ConTeXt], [RTF], [OPML], [DocBook],
[OpenDocument], [ODT], [Word docx], [GNU Texinfo], [MediaWiki markup],
[DokuWiki markup], [Haddock markup], [EPUB] (v2 or v3),
-[FictionBook2], [Textile], [groff man] pages, [Emacs Org-Mode],
+[FictionBook2], [Textile], [groff man] pages, [Emacs Org mode],
[AsciiDoc], [InDesign ICML], and [Slidy], [Slideous], [DZSlides],
[reveal.js] or [S5] HTML slide shows. It can also produce [PDF] output
on systems where LaTeX is installed.
-Pandoc's enhanced version of markdown includes syntax for footnotes,
-tables, flexible ordered lists, definition lists, fenced code blocks,
-superscript, subscript, strikeout, title blocks, automatic tables of
-contents, embedded LaTeX math, citations, and markdown inside HTML block
-elements. (These enhancements, described below under
-[Pandoc's markdown](#pandocs-markdown), can be disabled using the
+Pandoc's enhanced version of markdown includes syntax for [footnotes],
+[tables], flexible [ordered lists], [definition lists], [fenced code blocks],
+[superscripts and subscripts], [strikeout], [metadata blocks], automatic tables of
+contents, [embedded LaTeX math][Math rendering in HTML], [citations], and [markdown inside HTML block
+elements][Extension: `markdown_in_html_blocks`]. (These enhancements, described below under
+[Pandoc's markdown], can be disabled using the
`markdown_strict` input or output format.)
In contrast to most existing tools for converting markdown to HTML, which
@@ -50,6 +51,44 @@ model. While conversions from Pandoc's Markdown to all formats aspire
to be perfect, conversions from formats more expressive than Pandoc's
Markdown can be expected to be lossy.
+[markdown]: http://daringfireball.net/projects/markdown/
+[CommonMark]: http://commonmark.org
+[PHP Markdown Extra]: https://michelf.ca/projects/php-markdown/extra/
+[GitHub-Flavored Markdown]: https://help.github.com/articles/github-flavored-markdown/
+[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
+[S5]: http://meyerweb.com/eric/tools/s5/
+[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
+[Slideous]: http://goessner.net/articles/slideous/
+[HTML]: http://www.w3.org/html/
+[HTML5]: http://www.w3.org/TR/html5/
+[XHTML]: http://www.w3.org/TR/xhtml1/
+[LaTeX]: http://latex-project.org
+[`beamer`]: https://ctan.org/pkg/beamer
+[ConTeXt]: http://pragma-ade.nl
+[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
+[DocBook]: http://docbook.org
+[txt2tags]: http://txt2tags.org
+[EPUB]: http://idpf.org/epub
+[OPML]: http://dev.opml.org/spec2.html
+[OpenDocument]: http://opendocument.xml.org
+[ODT]: http://en.wikipedia.org/wiki/OpenDocument
+[Textile]: http://redcloth.org/textile
+[MediaWiki markup]: https://www.mediawiki.org/wiki/Help:Formatting
+[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
+[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
+[Haddock markup]: https://www.haskell.org/haddock/doc/html/ch03s08.html
+[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
+[Haskell]: https://www.haskell.org
+[GNU Texinfo]: http://www.gnu.org/software/texinfo/
+[Emacs Org mode]: http://orgmode.org
+[AsciiDoc]: http://www.methods.co.nz/asciidoc/
+[DZSlides]: http://paulrouget.com/dzslides/
+[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx
+[PDF]: https://www.adobe.com/pdf/
+[reveal.js]: http://lab.hakim.se/reveal-js/
+[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
+[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
+
Using `pandoc`
--------------
@@ -69,7 +108,7 @@ document, use the `-s` or `--standalone` flag:
pandoc -s -o output.html input.txt
For more information on how standalone documents are produced, see
-[Templates](#templates), below.
+[Templates], below.
Instead of a file, an absolute URI may be given. In this case
pandoc will fetch the content using HTTP:
@@ -88,7 +127,7 @@ markdown to LaTeX, you could type:
pandoc -f markdown -t latex hello.txt
-To convert `hello.html` from html to markdown:
+To convert `hello.html` from HTML to markdown:
pandoc -f html -t markdown hello.html
@@ -112,7 +151,7 @@ be assumed to be markdown unless explicitly specified.
Pandoc uses the UTF-8 character encoding for both input and output.
If your local character encoding is not UTF-8, you
-should pipe input and output through `iconv`:
+should pipe input and output through [`iconv`]:
iconv -t utf-8 input.txt | pandoc | iconv -f utf-8
@@ -121,26 +160,68 @@ RTF, OPML, DocBook, and Texinfo), information about
the character encoding is included in the document header, which
will only be included if you use the `-s/--standalone` option.
+[`iconv`]: http://www.gnu.org/software/libiconv/
+
Creating a PDF
--------------
-Earlier versions of pandoc came with a program, `markdown2pdf`, that
-used pandoc and pdflatex to produce a PDF. This is no longer needed,
-since `pandoc` can now produce `pdf` output itself. To produce a PDF, simply
-specify an output file with a `.pdf` extension. Pandoc will create a latex
-file and use pdflatex (or another engine, see `--latex-engine`) to convert it
-to PDF:
+To produce a PDF, specify an output file with a `.pdf` extension.
+Pandoc will use LaTeX to convert it to PDF:
pandoc test.txt -o test.pdf
Production of a PDF requires that a LaTeX engine be installed (see
-`--latex-engine`, below), and assumes that the following LaTeX packages are
-available: `amssymb`, `amsmath`, `ifxetex`, `ifluatex`, `listings` (if the
-`--listings` option is used), `fancyvrb`, `longtable`, `booktabs`, `url`,
-`graphicx` and `grffile` (if the document contains images),
- `hyperref`, `ulem`, `babel` (if the `lang` variable is set),
-`fontspec` (if `xelatex` or `lualatex` is used as the LaTeX engine), `xltxtra`
-and `xunicode` (if `xelatex` is used).
+`--latex-engine`, below), and assumes that the following LaTeX packages
+are available: [`amsfonts`], [`amsmath`], [`lm`],
+[`ifxetex`], [`ifluatex`], [`eurosym`], [`listings`] (if the
+`--listings` option is used), [`fancyvrb`], [`longtable`],
+[`booktabs`], [`url`], [`graphicx`] and [`grffile`] (if the
+document contains images), [`color`], [`hyperref`], [`ulem`],
+[`geometry`] (with the `geometry` variable set), [`setspace`] (with
+`linestretch`), and [`babel`] (with `lang`). The use of `xelatex` or
+`lualatex` as the LaTeX engine requires [`fontspec`]; `xelatex` uses
+[`mathspec`], [`polyglossia`] (with `lang`), [`xecjk`], and
+[`bidi`] (with the `dir` variable set). The [`upquote`] and
+[`microtype`] packages are used if available, and [`csquotes`] will
+be used for [smart punctuation] if added to the template. The
+[`natbib`], [`biblatex`], [`bibtex`], and [`biber`] packages can
+optionally be used for [citation rendering]. These are included with
+all recent versions of [TeX Live].
+
+PDF output can be controlled using [variables for LaTeX].
+
+[`amsfonts`]: https://ctan.org/pkg/amsfonts
+[`amsmath`]: https://ctan.org/pkg/amsmath
+[`lm`]: https://ctan.org/pkg/lm
+[`ifxetex`]: https://ctan.org/pkg/ifxetex
+[`ifluatex`]: https://ctan.org/pkg/ifluatex
+[`eurosym`]: https://ctan.org/pkg/eurosym
+[`listings`]: https://ctan.org/pkg/listings
+[`fancyvrb`]: https://ctan.org/pkg/fancyvrb
+[`longtable`]: https://ctan.org/pkg/longtable
+[`booktabs`]: https://ctan.org/pkg/booktabs
+[`url`]: https://ctan.org/pkg/url
+[`graphicx`]: https://ctan.org/pkg/graphicx
+[`grffile`]: https://ctan.org/pkg/grffile
+[`geometry`]: https://ctan.org/pkg/geometry
+[`setspace`]: https://ctan.org/pkg/setspace
+[`color`]: http://ctan.org/pkg/color
+[`xecjk`]: https://ctan.org/pkg/xecjk
+[`hyperref`]: https://ctan.org/pkg/hyperref
+[`ulem`]: https://ctan.org/pkg/ulem
+[`babel`]: https://ctan.org/pkg/babel
+[`bidi`]: https://ctan.org/pkg/bidi
+[`mathspec`]: https://ctan.org/pkg/mathspec
+[`polyglossia`]: https://ctan.org/pkg/polyglossia
+[`fontspec`]: https://ctan.org/pkg/fontspec
+[`upquote`]: https://ctan.org/pkg/upquote
+[`microtype`]: https://ctan.org/pkg/microtype
+[`csquotes`]: https://ctan.org/pkg/csquotes
+[`natbib`]: https://ctan.org/pkg/natbib
+[`biblatex`]: https://ctan.org/pkg/biblatex
+[`bibtex`]: https://ctan.org/pkg/bibtex
+[`biber`]: https://ctan.org/pkg/biber
+[TeX Live]: http://www.tug.org/texlive/
`hsmarkdown`
------------
@@ -150,14 +231,10 @@ a symbolic link to the `pandoc` executable called `hsmarkdown`. When
invoked under the name `hsmarkdown`, `pandoc` will behave as if
invoked with `-f markdown_strict --email-obfuscation=references`,
and all command-line options will be treated as regular arguments.
-However, this approach does not work under Cygwin, due to problems with
+This approach does not work under [Cygwin], due to problems with
its simulation of symbolic links.
-[Cygwin]: http://www.cygwin.com/
-[`iconv`]: http://www.gnu.org/software/libiconv/
-[CTAN]: http://www.ctan.org "Comprehensive TeX Archive Network"
-[TeX Live]: http://www.tug.org/texlive/
-[MacTeX]: http://www.tug.org/mactex/
+[Cygwin]: https://cygwin.com
Options
=======
@@ -170,23 +247,23 @@ General options
: Specify input format. *FORMAT* can be `native` (native Haskell),
`json` (JSON version of native AST), `markdown` (pandoc's
extended markdown), `markdown_strict` (original unextended
- markdown), `markdown_phpextra` (PHP Markdown Extra extended
- markdown), `markdown_github` (github extended markdown),
+ markdown), `markdown_phpextra` (PHP Markdown Extra),
+ `markdown_github` (GitHub-Flavored Markdown),
`commonmark` (CommonMark markdown), `textile` (Textile), `rst`
(reStructuredText), `html` (HTML), `docbook` (DocBook), `t2t`
(txt2tags), `docx` (docx), `odt` (ODT), `epub` (EPUB), `opml` (OPML),
- `org` (Emacs Org-mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki
+ `org` (Emacs Org mode), `mediawiki` (MediaWiki markup), `twiki` (TWiki
markup), `haddock` (Haddock markup), or `latex` (LaTeX). If
`+lhs` is appended to `markdown`, `rst`, `latex`, or `html`, the
input will be treated as literate Haskell source: see [Literate
- Haskell support](#literate-haskell-support), below. Markdown
+ Haskell support], below. Markdown
syntax extensions can be individually enabled or disabled by
appending `+EXTENSION` or `-EXTENSION` to the format name. So, for
example, `markdown_strict+footnotes+definition_lists` is strict
markdown with footnotes and definition lists enabled, and
`markdown-pipe_tables+hard_line_breaks` is pandoc's markdown
without pipe tables and with hard line breaks. See [Pandoc's
- markdown](#pandocs-markdown), below, for a list of extensions and
+ markdown], below, for a list of extensions and
their names.
`-t` *FORMAT*, `-w` *FORMAT*, `--to=`*FORMAT*, `--write=`*FORMAT*
@@ -195,12 +272,12 @@ General options
`json` (JSON version of native AST), `plain` (plain text),
`markdown` (pandoc's extended markdown), `markdown_strict`
(original unextended markdown), `markdown_phpextra` (PHP Markdown
- extra extended markdown), `markdown_github` (github extended
- markdown), `commonmark` (CommonMark markdown), `rst`
- (reStructuredText), `html` (XHTML 1), `html5` (HTML 5), `latex`
+ Extra), `markdown_github` (GitHub-Flavored
+ Markdown), `commonmark` (CommonMark markdown), `rst`
+ (reStructuredText), `html` (XHTML), `html5` (HTML5), `latex`
(LaTeX), `beamer` (LaTeX beamer slide show), `context` (ConTeXt),
`man` (groff man), `mediawiki` (MediaWiki markup), `dokuwiki`
- (DokuWiki markup), `textile` (Textile), `org` (Emacs Org-Mode),
+ (DokuWiki markup), `textile` (Textile), `org` (Emacs Org mode),
`texinfo` (GNU Texinfo), `opml` (OPML), `docbook` (DocBook),
`opendocument` (OpenDocument), `odt` (OpenOffice text document),
`docx` (Word docx), `haddock` (Haddock markup), `rtf` (rich text
@@ -211,13 +288,13 @@ General options
HTML5 + javascript slide show), `revealjs` (reveal.js HTML5 +
javascript slide show), `s5` (S5 HTML and javascript slide show),
or the path of a custom lua writer (see [Custom
- writers](#custom-writers), below). Note that `odt`, `epub`, and
+ writers], below). Note that `odt`, `epub`, and
`epub3` output will not be directed to *stdout*; an output
filename must be specified using the `-o/--output` option. If
`+lhs` is appended to `markdown`, `rst`, `latex`, `beamer`,
`html`, or `html5`, the output will be rendered as literate
Haskell source: see [Literate Haskell
- support](#literate-haskell-support), below. Markdown syntax
+ support], below. Markdown syntax
extensions can be individually enabled or disabled by appending
`+EXTENSION` or `-EXTENSION` to the format name, as described
above under `-f`.
@@ -232,27 +309,27 @@ General options
: Specify the user data directory to search for pandoc data files.
If this option is not specified, the default user data directory
- will be used. This is
+ will be used. This is, in Unix:
$HOME/.pandoc
- in unix,
+ in Windows XP:
C:\Documents And Settings\USERNAME\Application Data\pandoc
- in Windows XP, and
+ and in Windows Vista or later:
C:\Users\USERNAME\AppData\Roaming\pandoc
- in Windows 7. (You can find the default user data directory
- on your system by looking at the output of `pandoc --version`.)
+ You can find the default user data directory on your system by
+ looking at the output of `pandoc --version`.
A `reference.odt`, `reference.docx`, `epub.css`, `templates`,
`slidy`, `slideous`, or `s5` directory
placed in this directory will override pandoc's normal defaults.
-`--bash-completiion`
+`--bash-completion`
-: Generate a bash completion script. to enable bash completion
+: Generate a bash completion script. To enable bash completion
with pandoc, add this to your `.bashrc`:
eval "$(pandoc --bash-completion)"
@@ -338,12 +415,8 @@ Reader options
Filters may be written in any language. `Text.Pandoc.JSON`
exports `toJSONFilter` to facilitate writing filters in Haskell.
Those who would prefer to write filters in python can use the
- module `pandocfilters`, installable from PyPI. See
- <http://github.com/jgm/pandocfilters> for the module and several
- examples. There are also pandoc filter libraries in
- [PHP](https://github.com/vinai/pandocfilters-php),
- [perl](https://metacpan.org/pod/Pandoc::Filter), and
- [javascript/node.js](https://github.com/mvhenderson/pandoc-filter-node).
+ module [`pandocfilters`], installable from PyPI. There are also
+ pandoc filter libraries in [PHP], [perl], and [javascript/node.js].
Note that the *EXECUTABLE* will be sought in the user's
`PATH`, and not in the working directory, if no directory is
@@ -379,7 +452,7 @@ Reader options
`--track-changes=accept`|`reject`|`all`
: Specifies what to do with insertions and deletions produced by the MS
- Word "track-changes" feature. `accept` (the default), inserts all
+ Word "Track Changes" feature. `accept` (the default), inserts all
insertions, and ignores all deletions. `reject` inserts all
deletions and ignores insertions. `all` puts in both insertions
and deletions, wrapped in spans with `insertion` and `deletion`
@@ -395,6 +468,11 @@ Reader options
references in the document so they point to the extracted files.
This option only affects the docx and epub readers.
+[`pandocfilters`]: https://github.com/jgm/pandocfilters
+[PHP]: https://github.com/vinai/pandocfilters-php
+[perl]: https://metacpan.org/pod/Pandoc::Filter
+[javascript/node.js]: https://github.com/mvhenderson/pandoc-filter-node
+
General writer options
----------------------
@@ -408,7 +486,7 @@ General writer options
`--template=`*FILE*
: Use *FILE* as a custom template for the generated document. Implies
- `--standalone`. See [Templates](#templates) below for a description
+ `--standalone`. See [Templates], below, for a description
of template syntax. If no extension is specified, an extension
corresponding to the writer will be added, so that `--template=special`
looks for `special.html` for HTML output. If the template is not
@@ -539,14 +617,14 @@ Options affecting specific writers
`--atx-headers`
-: Use ATX style headers in markdown and asciidoc output. The default is
+: Use ATX-style headers in markdown and asciidoc output. The default is
to use setext-style headers for levels 1-2, and then ATX headers.
`--chapters`
: Treat top-level headers as chapters in LaTeX, ConTeXt, and DocBook
- output. When the LaTeX template uses the report, book, or
- memoir class, this option is implied. If `beamer` is the output
+ output. When the LaTeX document class is set to `report`, `book`, or
+ `memoir`, this option is implied. If `beamer` is the output
format, top-level headers will become `\part{..}`.
`-N`, `--number-sections`
@@ -572,7 +650,7 @@ Options affecting specific writers
: Do not convert quotation marks, apostrophes, and dashes to
the TeX ligatures when writing LaTeX or ConTeXt. Instead, just
use literal unicode characters. This is needed for using advanced
- OpenType features with XeLaTeX and LuaLaTeX. Note: normally
+ OpenType features with `xelatex` and `lualatex`. Note: normally
`--smart` is selected automatically for LaTeX and ConTeXt
output, but it must be specified explicitly if `--no-tex-ligatures`
is selected. If you use literal curly quotes, dashes, and ellipses
@@ -581,7 +659,7 @@ Options affecting specific writers
`--listings`
-: Use listings package for LaTeX code blocks
+: Use the [`listings`] package for LaTeX code blocks
`-i`, `--incremental`
@@ -596,14 +674,14 @@ Options affecting specific writers
slide show into sections; headers below this level create
subheads within a slide. The default is to set the slide level
based on the contents of the document; see
- [Structuring the slide show](#structuring-the-slide-show), below.
+ [Structuring the slide show].
`--section-divs`
: Wrap sections in `<div>` tags (or `<section>` tags in HTML5),
and attach identifiers to the enclosing `<div>` (or `<section>`)
rather than the header itself. See
- [Header identifiers](#header-identifiers), below.
+ [Header identifiers], below.
`--email-obfuscation=none`|`javascript`|`references`
@@ -678,8 +756,7 @@ Options affecting specific writers
`--epub-metadata=`*FILE*
: Look in the specified XML file for metadata for the EPUB.
- The file should contain a series of Dublin Core elements,
- as documented at <http://dublincore.org/documents/dces/>.
+ The file should contain a series of [Dublin Core elements].
For example:
<dc:rights>Creative Commons</dc:rights>
@@ -755,6 +832,9 @@ Options affecting specific writers
If used multiple times, the arguments are provided with spaces between
them. Note that no check for duplicate options is done.
+[Dublin Core elements]: http://dublincore.org/documents/dces/
+[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime
+
Citation rendering
------------------
@@ -785,17 +865,15 @@ Citation rendering
`--natbib`
-: Use natbib for citations in LaTeX output. This option is not for use
+: Use [`natbib`] for citations in LaTeX output. This option is not for use
with the `pandoc-citeproc` filter or with PDF output. It is intended for
- use in producing a LaTeX file that can be processed with pdflatex and
- bibtex.
+ use in producing a LaTeX file that can be processed with [`bibtex`].
`--biblatex`
-: Use biblatex for citations in LaTeX output. This option is not for use
+: Use [`biblatex`] for citations in LaTeX output. This option is not for use
with the `pandoc-citeproc` filter or with PDF output. It is intended for
- use in producing a LaTeX file that can be processed with pdflatex and
- bibtex or biber.
+ use in producing a LaTeX file that can be processed with [`bibtex`] or [`biber`].
Math rendering in HTML
----------------------
@@ -812,7 +890,7 @@ Math rendering in HTML
`--mathml`[`=`*URL*]
-: Convert TeX math to MathML (in `docbook` as well as `html` and `html5`).
+: Convert TeX math to [MathML] (in `docbook` as well as `html` and `html5`).
In standalone `html` output, a small javascript (or a link to such a
script if a *URL* is supplied) will be inserted that allows the MathML to
be viewed on some browsers.
@@ -862,6 +940,14 @@ Math rendering in HTML
not specified, a link to the KaTeX CDN will be inserted. Note that this
option does not imply `--katex`.
+[MathML]: http://www.w3.org/Math/
+[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
+[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
+[MathJax]: https://www.mathjax.org
+[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/
+[mimeTeX]: http://www.forkosh.com/mimetex.html
+[KaTeX]: https://github.com/Khan/KaTeX
+
Options for wrapper scripts
---------------------------
@@ -887,13 +973,6 @@ Options for wrapper scripts
pandoc -o foo.html -s
-[LaTeXMathML]: http://math.etsu.edu/LaTeXMathML/
-[jsMath]: http://www.math.union.edu/~dpvc/jsmath/
-[MathJax]: http://www.mathjax.org/
-[gladTeX]: http://ans.hsh.no/home/mgg/gladtex/
-[mimeTeX]: http://www.forkosh.com/mimetex.html
-[CSL]: http://CitationStyles.org
-
Templates
=========
@@ -901,30 +980,43 @@ When the `-s/--standalone` option is used, pandoc uses a template to
add header and footer material that is needed for a self-standing
document. To see the default template that is used, just type
- pandoc -D FORMAT
+ pandoc -D *FORMAT*
-where `FORMAT` is the name of the output format. A custom template
+where *FORMAT* is the name of the output format. A custom template
can be specified using the `--template` option. You can also override
-the system default templates for a given output format `FORMAT`
-by putting a file `templates/default.FORMAT` in the user data
+the system default templates for a given output format *FORMAT*
+by putting a file `templates/default.*FORMAT*` in the user data
directory (see `--data-dir`, above). *Exceptions:* For `odt` output,
customize the `default.opendocument` template. For `pdf` output,
customize the `default.latex` template.
-Templates may contain *variables*. Variable names are sequences of
-alphanumerics, `-`, and `_`, starting with a letter. A variable name
-surrounded by `$` signs will be replaced by its value. For example,
-the string `$title$` in
+Templates contain *variables*, which allow for the inclusion of
+arbitrary information at any point in the file. Variables may be set
+within the document using [YAML metadata blocks][Extension: `yaml_metadata_block`].
+They may also be set at the
+command line using the `-V/--variable` option: variables set in this
+way override metadata fields with the same name.
- <title>$title$</title>
+Variables set by pandoc
+-----------------------
-will be replaced by the document title.
+Some variables are set automatically by pandoc. These vary somewhat
+depending on the output format, but include metadata fields as well as the following:
-To write a literal `$` in a template, use `$$`.
+`title`, `author`, `date`
+: allow identification of basic aspects of the document.
+ Included in PDF metadata through LaTeX.
+ These can be set through a [pandoc title block][Extension: `pandoc_title_block`],
+ which allows for multiple authors, or through a YAML metadata block:
-Some variables are set automatically by pandoc. These vary somewhat
-depending on the output format, but include metadata fields (such
-as `title`, `author`, and `date`) as well as the following:
+ ---
+ author:
+ - Aristotle
+ - Peter Abelard
+ ...
+
+`abstract`
+: allows for specification of document summary in LaTeX and Word docx
`header-includes`
: contents specified by `-H/--include-in-header` (may have multiple
@@ -944,19 +1036,22 @@ as `title`, `author`, and `date`) as well as the following:
`body`
: body of document
+Language variables
+------------------
+
`lang`
-: The `lang` variable should be set by the user to a language
- code according to [BCP 47] (e.g. `en` or `en-GB`).
- For some output formats, pandoc will convert it to an approriate
+: identifies the main language of the document,
+ using a code according to [BCP 47] (e.g. `en` or `en-GB`).
+ For some output formats, pandoc will convert it to an appropriate
format stored in the additional variables `babel-lang`,
`polyglossia-lang`, `polyglossia-variant` (LaTeX)
and `context-lang` (ConTeXt).
`otherlangs`
-: Should be set to a list of other languages used in the document
+: a list of other languages used in the document
in the YAML metadata, according to [BCP 47]. For example:
`otherlangs: [en-GB, fr]`.
- Currently only used by XeTeX through the generated
+ Currently only used by `xelatex` through the generated
`polyglossia-otherlangs` variable.
`dir`
@@ -968,15 +1063,20 @@ as `title`, `author`, and `date`) as well as the following:
override the base direction in some output formats.
This may not always be necessary if the final renderer
(e.g. the browser, when generating HTML) supports the
- [Unicode Bidirectional Algorithm][uba-basics].
+ [Unicode Bidirectional Algorithm].
- When using LaTeX for bidi documents, only the XeLaTeX engine
- is fully supported (see `--latex-engine`).
- Setting the `dir` variable enables bidirectional text
- handling in LaTeX and ConTeXt, thus even if the base direction
- is the default left-to-right, you should set `dir: ltr` for
- documents that also contain some right-to-left script.
+ LaTeX and ConTeXt assume by default that all text is left-to-right.
+ Setting `dir: ltr` enables bidirectional text handling in a document
+ whose base direction is left-to-right but contains some right-to-left script.
+ When using LaTeX for bidirectional documents, only the `xelatex` engine
+ is fully supported (use `--latex-engine=xelatex`).
+
+[BCP 47]: https://tools.ietf.org/html/bcp47
+[Unicode Bidirectional Algorithm]: http://www.w3.org/International/articles/inline-bidi-markup/uba-basics
+
+Variables for slides
+--------------------
`slidy-url`
: base URL for Slidy documents (defaults to
@@ -995,56 +1095,67 @@ as `title`, `author`, and `date`) as well as the following:
: reveal.js or LaTeX beamer theme
`transition`
-: reveal.js transition
+: reveal.js transition: `cube`, `page`, `concave`, `zoom`, `linear`, `fade`, or `none`
+
+`center`
+: enables vertical centering of slides in reveal.js
+
+`maxScale`
+: bounds for smallest/largest possible content scale in reveal.js (default: 1.5)
+
+`slideNumber`
+: enables display of the page number of the current slide in reveal.js
+
+`colortheme`, `fonttheme`, `innertheme`, `outertheme`
+: themes for LaTeX [`beamer`] documents
+
+Variables for LaTeX
+-------------------
`fontsize`
-: font size (10pt, 11pt, 12pt) for LaTeX documents
+: font size (e.g. `10pt`, `12pt`) for LaTeX documents
`documentclass`
-: document class for LaTeX documents
+: document class for LaTeX documents, e.g. [`article`], [`report`], [`book`], [`memoir`]
`classoption`
-: option for LaTeX documentclass, e.g. `oneside`; may be repeated
+: option for LaTeX document class, e.g. `oneside`; may be repeated
for multiple options
`geometry`
-: options for LaTeX `geometry` class, e.g. `margin=1in`;
+: option for LaTeX [`geometry`] package, e.g. `margin=1in`;
may be repeated for multiple options
`linestretch`
-: adjusts line spacing (requires the `setspace` package)
+: adjusts line spacing in LaTeX documents using the [`setspace`]
+ package, e.g. `1.25`, `1.5`
`fontfamily`
-: font package to use for LaTeX documents (with pdflatex):
- TeXLive has `bookman` (Bookman), `utopia` or `fourier` (Utopia),
- `fouriernc` (New Century Schoolbook), `times` or `txfonts` (Times),
- `mathpazo` or `pxfonts` or `mathpple` (Palatino),
- `libertine` (Linux Libertine), `arev` (Arev Sans),
- and the default `lmodern`, among others.
-
-`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
-: fonts for LaTeX documents (works only with xelatex
- and lualatex). Note that if `CJKmainfont` is used,
- the `xeCJK` package must be available.
-
-`colortheme`
-: colortheme for LaTeX beamer documents
-
-`fonttheme`
-: fonttheme for LaTeX beamer documents
+: font package for LaTeX documents (with `pdflatex`):
+ [TeX Live] includes many options, documented in the [LaTeX Font Catalogue].
+ The default is [Latin Modern][`lm`].
-`linkcolor`
-: color for internal links in LaTeX documents (`red`, `green`,
- `magenta`, `cyan`, `blue`, `black`)
+`fontfamilyoptions`
+: options for package used as `fontfamily`: e.g. `osf,sc` with
+ `fontfamily` set to [`mathpazo`] provides Palatino with old-style
+ figures and true small caps
-`toccolor`
-: color for links in table of contents in LaTeX documents
-
-`urlcolor`
-: color for external links in LaTeX documents
-
-`citecolor`
-: color for citation links in LaTeX documents
+`mainfont`, `sansfont`, `monofont`, `mathfont`, `CJKmainfont`
+: fonts for LaTeX documents (works only with `xelatex` and
+ `lualatex`): takes the name of any system font, using the
+ [`fontspec`] package. Note that if `CJKmainfont` is used,
+ the [`xecjk`] package must be available.
+
+`mainfontoptions`, `sansfontoptions`, `monofontoptions`, `mathfontoptions`, `CJKoptions`
+: options to use with `mainfont`, `sansfont`, `monofont`, `mathfont`,
+ `CJKmainfont` in `xelatex` and `lualatex`. Allows for any choices
+ available through [`fontspec`], such as the OpenType features
+ `Numbers=OldStyle,Numbers=Proportional`.
+
+`linkcolor`, `toccolor`, `urlcolor`, `citecolor`
+: color for internal links, links in table of contents, external links,
+ and citation links in LaTeX documents, using options available through
+ [`color`] package, e.g. `red`, `green`, `magenta`, `cyan`, `blue`, `black`
`links-as-notes`
: causes links to be printed as footnotes in LaTeX documents
@@ -1070,6 +1181,16 @@ as `title`, `author`, and `date`) as well as the following:
`biblio-style`
: bibliography style in LaTeX, when used with `--natbib`
+[`article`]: https://ctan.org/pkg/article
+[`report`]: https://ctan.org/pkg/report
+[`book`]: https://ctan.org/pkg/book
+[`memoir`]: https://ctan.org/pkg/memoir
+[LaTeX Font Catalogue]: http://www.tug.dk/FontCatalogue/
+[`mathpazo`]: https://ctan.org/pkg/mathpazo
+
+Variables for man pages
+-----------------------
+
`section`
: section number in man pages
@@ -1079,9 +1200,18 @@ as `title`, `author`, and `date`) as well as the following:
`footer`
: footer in man pages
-Variables may be set at the command line using the `-V/--variable`
-option. Variables set in this way override metadata fields with
-the same name.
+Using variables in templates
+----------------------------
+
+Variable names are sequences of alphanumerics, `-`, and `_`,
+starting with a letter. A variable name surrounded by `$` signs
+will be replaced by its value. For example, the string `$title$` in
+
+ <title>$title$</title>
+
+will be replaced by the document title.
+
+To write a literal `$` in a template, use `$$`.
Templates may contain conditionals. The syntax is as follows:
@@ -1116,10 +1246,11 @@ an object as its value. So, for example:
If you use custom templates, you may need to revise them as pandoc
changes. We recommend tracking the changes in the default templates,
and modifying your custom templates accordingly. An easy way to do this
-is to fork the pandoc-templates repository
-(<http://github.com/jgm/pandoc-templates>) and merge in changes after each
+is to fork the [pandoc-templates] repository and merge in changes after each
pandoc release.
+[pandoc-templates]: https://github.com/jgm/pandoc-templates
+
Pandoc's markdown
=================
@@ -1172,7 +1303,7 @@ are ignored.
Headers
-------
-There are two kinds of headers, Setext and atx.
+There are two kinds of headers: Setext and ATX.
### Setext-style headers ###
@@ -1186,12 +1317,12 @@ A setext-style header is a line of text "underlined" with a row of `=` signs
------------------
The header text can contain inline formatting, such as emphasis (see
-[Inline formatting](#inline-formatting), below).
+[Inline formatting], below).
-### Atx-style headers ###
+### ATX-style headers ###
-An Atx-style header consists of one to six `#` signs and a line of
+An ATX-style header consists of one to six `#` signs and a line of
text, optionally followed by any number of `#` signs. The number of
`#` signs at the beginning of the line is the header level:
@@ -1748,13 +1879,10 @@ definition:
Note that space between items in a definition list is required.
(A variant that loosens this requirement, but disallows "lazy"
hard wrapping, can be activated with `compact_definition_lists`: see
-[Non-pandoc extensions](#non-pandoc-extensions), below.)
+[Non-pandoc extensions], below.)
[^3]: I have been influenced by the suggestions of [David Wheeler](http://www.justatheory.com/computers/markup/modest-markdown-proposal.html).
-[PHP Markdown Extra]: http://www.michelf.com/projects/php-markdown/extra/
-
-
### Numbered example lists ###
#### Extension: `example_lists` ####
@@ -1986,7 +2114,7 @@ arbitrary block elements (multiple paragraphs, code blocks, lists,
etc.). Alignments are not supported, nor are cells that span multiple
columns or rows. Grid tables can be created easily using [Emacs table mode].
- [Emacs table mode]: http://table.sourceforge.net/
+[Emacs table mode]: http://table.sourceforge.net/
#### Extension: `pipe_tables` ####
@@ -2000,7 +2128,7 @@ Pipe tables look like this:
: Demonstration of pipe table syntax.
-The syntax is [the same as in PHP markdown extra]. The beginning and
+The syntax is identical to [PHP Markdown Extra tables]. The beginning and
ending pipe characters are optional, but pipes are required between all
columns. The colons indicate column alignment as shown. The header
cannot be omitted. To simulate a headerless table, include a header
@@ -2022,9 +2150,6 @@ output, the cells produced by pipe tables will not wrap, since there
is no information available about relative widths. If you want content
to wrap within cells, use multiline or grid tables.
- [the same as in PHP markdown extra]:
- http://michelf.ca/projects/php-markdown/extra/#table
-
Note: Pandoc also recognizes pipe tables of the following
form, as can be produced by Emacs' orgtbl-mode:
@@ -2037,6 +2162,8 @@ The difference is that `+` is used instead of `|`. Other orgtbl features
are not supported. In particular, to get non-default column alignment,
you'll need to add colons as above.
+[PHP Markdown Extra tables]: https://michelf.ca/projects/php-markdown/extra/#table
+
Metadata blocks
---------------
@@ -2235,8 +2362,8 @@ correct output, converting straight quotes to curly quotes, `---` to
em-dashes, `--` to en-dashes, and `...` to ellipses. Nonbreaking spaces
are inserted after certain abbreviations, such as "Mr."
-Note: if your LaTeX template uses the `csquotes` package, pandoc will
-detect automatically this and use `\enquote{...}` for quoted text.
+Note: if your LaTeX template calls for the [`csquotes`] package, pandoc will
+detect this automatically and use `\enquote{...}` for quoted text.
Inline formatting
-----------------
@@ -2320,7 +2447,7 @@ work in verbatim contexts:
#### Extension: `inline_code_attributes` ####
Attributes can be attached to verbatim text, just as with
-[fenced code blocks](#fenced-code-blocks):
+[fenced code blocks]:
`<$>`{.haskell}
@@ -2349,12 +2476,11 @@ them and they won't be treated as math delimiters.
TeX math will be printed in all output formats. How it is rendered
depends on the output format:
-Markdown, LaTeX, Org-Mode, ConTeXt
+Markdown, LaTeX, Emacs Org mode, ConTeXt
~ It will appear verbatim between `$` characters.
reStructuredText
- ~ It will be rendered using an interpreted text role `:math:`, as described
- [here](http://docutils.sourceforge.net/docs/ref/rst/roles.html#math)
+ ~ It will be rendered using an [interpreted text role `:math:`].
AsciiDoc
~ It will be rendered as `latexmath:[...]`.
@@ -2375,8 +2501,8 @@ RTF, OpenDocument, ODT
~ It will be rendered, if possible, using unicode characters,
and will otherwise appear verbatim.
-Docbook
- ~ If the `--mathml` flag is used, it will be rendered using mathml
+DocBook
+ ~ If the `--mathml` flag is used, it will be rendered using MathML
in an `inlineequation` or `informalequation` tag. Otherwise it
will be rendered, if possible, using unicode characters.
@@ -2418,7 +2544,7 @@ HTML, Slidy, DZSlides, S5, EPUB
5. If the `--gladtex` option is used, TeX formulas will be enclosed
in `<eq>` tags in the HTML output. The resulting `htex` file may then
be processed by [gladTeX], which will produce image files for each
- formula and an `html` file with links to these images. So, the
+ formula and an HTML file with links to these images. So, the
procedure is:
pandoc -s --gladtex myfile.txt -o myfile.htex
@@ -2436,6 +2562,8 @@ HTML, Slidy, DZSlides, S5, EPUB
math) and put in `<span>` tags with class `math`.
The [MathJax] script will be used to render it as formulas.
+[interpreted text role `:math:`]: http://docutils.sourceforge.net/docs/ref/rst/roles.html#math
+
Raw HTML
--------
@@ -2643,8 +2771,7 @@ be omitted entirely:
### Internal links ###
To link to another section of the same document, use the automatically
-generated identifier (see [Header identifiers](#header-identifiers),
-below). For example:
+generated identifier (see [Header identifiers]). For example:
See the [Introduction](#introduction).
@@ -2767,17 +2894,35 @@ The bibliography may have any of these formats:
MODS .mods
RIS .ris
-Note that `.bib` can generally be used with both BibTeX and BibLaTeX
-files, but you can use `.bibtex` to force BibTeX.
+Note that `.bib` can be used with both BibTeX and BibLaTeX files;
+use `.bibtex` to force BibTeX.
Note that `pandoc-citeproc --bib2json` and `pandoc-citeproc --bib2yaml`
can produce `.json` and `.yaml` files from any of the supported formats.
-In-field markup: In bibtex and biblatex databases, pandoc-citeproc parses
-(a subset of) LaTeX markup; in CSL JSON databases, an HTML-like markup
-([specs](http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields));
-and in CSL YAML databases, pandoc markdown. `pandoc-citeproc -j` and `-y`
-interconvert these markup formats as far as possible.
+In-field markup: In BibTeX and BibLaTeX databases, pandoc-citeproc parses
+a subset of LaTeX markup; in CSL YAML databases, pandoc markdown; and in CSL JSON databases, an [HTML-like markup][CSL markup specs]:
+
+`<i>...</i>`
+: italics
+
+`<b>...</b>`
+: bold
+
+`<span style="font-variant:small-caps;">...</span>` or `<sc>...</sc>`
+: small capitals
+
+`<sub>...</sub>`
+: subscript
+
+`<sup>...</sup>`
+: superscript
+
+`<span class="nocase">...</span>`
+: prevent a phrase from being capitalized as title case
+
+`pandoc-citeproc -j` and `-y` interconvert the CSL JSON
+and CSL YAML formats as far as possible.
As an alternative to specifying a bibliography file, you can include
the citation data directly in the `references` field of the
@@ -2813,13 +2958,11 @@ YAML-encoded references, for example:
(`pandoc-citeproc --bib2yaml` can produce these from a bibliography file in one
of the supported formats.)
-By default, `pandoc-citeproc` will use the Chicago Manual of Style author-date
-format for citations and references. To use another style, you will need to
-specify a [CSL] 1.0 style file in the `csl` metadata field. A repository of CSL
-styles can be found at <https://github.com/citation-style-language/styles>. See
-also <http://zotero.org/styles> for easy browsing. A primer on creating and
-modifying CSL styles can be found at
-<http://citationstyles.org/downloads/primer.html>.
+Citations and references can be formatted using any style supported by the
+[Citation Style Language], listed in the [Zotero Style Repository].
+These files are specified using the `--csl` option or the `csl` metadata field.
+By default, `pandoc-citeproc` will use the [Chicago Manual of Style] author-date
+format. The CSL project provides further information on [finding and editing styles].
Citations go inside square brackets and are separated by semicolons.
Each citation must have a key, composed of '@' + the citation
@@ -2834,16 +2977,16 @@ characters (`:.#$%&-+?<>~/`). Here are some examples:
Blah blah [@smith04; @doe99].
-`pandoc-citeproc` detects locator terms based on the [CSL locale files].
-Either abbreviated or unabbreviated forms are accepted. In the `en-US` locale,
-locator terms include `book`, `bk.`; `chapter`, `chap.`; `column`, `col.`;
-`figure`, `fig.`; `folio`, `f.`; `number`, `no.`; `line`, `l.`; `note`, `n.`;
-`opus`, `op.`; `page`, `p.`; `paragraph`, `para.`; `part`, `pt.`;
-`section`, `sec.`; `sub verbo`, `s.v.`; `verse`, `v.`; `volume`, `vol.`
-as well as the plural forms of all these. If no locator term is used,
-"page" is assumed.
-
- [CSL locale files]: https://github.com/citation-style-language/locales
+`pandoc-citeproc` detects locator terms in the [CSL locale files].
+Either abbreviated or unabbreviated forms are accepted. In the `en-US`
+locale, locator terms can be written in either singular or plural forms,
+as `book`, `bk.`/`bks.`; `chapter`, `chap.`/`chaps.`; `column`,
+`col.`/`cols.`; `figure`, `fig.`/`figs.`; `folio`, `fol.`/`fols.`;
+`number`, `no.`/`nos.`; `line`, `l.`/`ll.`; `note`, `n.`/`nn.`; `opus`,
+`op.`/`opp.`; `page`, `p.`/`pp.`; `paragraph`, `para.`/`paras.`; `part`,
+`pt.`/`pts.`; `section`, `sec.`/`secs.`; `sub verbo`, `s.v.`/`s.vv.`;
+`verse`, `v.`/`vv.`; `volume`, `vol.`/`vols.`; `¶`/`¶¶`; `§`/`§§`. If no
+locator term is used, "page" is assumed.
A minus sign (`-`) before the `@` will suppress mention of
the author in the citation. This can be useful when the
@@ -2884,12 +3027,19 @@ In this example, the document will contain a citation for `item3`
only, but the bibliography will contain entries for `item1`, `item2`, and
`item3`.
-For LaTeX or PDF output, you can also use NatBib or BibLaTeX
+For LaTeX or PDF output, you can also use [`natbib`] or [`biblatex`]
to render bibliography. In order to do so, specify bibliography files as
outlined above, and add `--natbib` or `--biblatex` argument to `pandoc`
invocation. Bear in mind that bibliography files have to be in respective
format (either BibTeX or BibLaTeX).
+[CSL markup specs]: http://docs.citationstyles.org/en/1.0/release-notes.html#rich-text-markup-within-fields
+[Chicago Manual of Style]: http://chicagomanualofstyle.org
+[Citation Style Language]: http://citationstyles.org
+[Zotero Style Repository]: https://www.zotero.org/styles
+[finding and editing styles]: http://citationstyles.org/styles/
+[CSL locale files]: https://github.com/citation-style-language/locales
+
Non-pandoc extensions
---------------------
@@ -2949,13 +3099,13 @@ See the MultiMarkdown documentation for details. If `pandoc_title_block` or
`yaml_metadata_block` is enabled, it will take precedence over
`mmd_title_block`.
- [MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
+[MultiMarkdown]: http://fletcherpenney.net/multimarkdown/
#### Extension: `abbreviations` ####
Parses PHP Markdown Extra abbreviation keys, like
- *[HTML]: Hyper Text Markup Language
+ *[HTML]: Hypertext Markup Language
Note that the pandoc document model does not support
abbreviations, so if this extension is enabled, abbreviation keys are
@@ -2986,7 +3136,7 @@ after the header but before any trailing `#`s in an ATX header).
#### Extension: `compact_definition_lists` ####
Activates the definition list syntax of pandoc 1.12.x and earlier.
-This syntax differs from the one described [above](#definition-lists)
+This syntax differs from the one described above under [Definition lists]
in several respects:
- No blank line is required between consecutive items of the
@@ -3021,7 +3171,7 @@ variants are supported:
`fenced_code_blocks`, `definition_lists`, `intraword_underscores`,
`header_attributes`, `abbreviations`, `shortcut_reference_links`.
-`markdown_github` (GitHub-flavored Markdown)
+`markdown_github` (GitHub-Flavored Markdown)
: `pipe_tables`, `raw_html`, `tex_math_single_backslash`,
`fenced_code_blocks`, `auto_identifiers`,
`ascii_identifiers`, `backtick_code_blocks`, `autolink_bare_uris`,
@@ -3059,7 +3209,7 @@ Producing slide shows with Pandoc
You can use Pandoc to produce an HTML + javascript slide presentation
that can be viewed via a web browser. There are five ways to do this,
using [S5], [DZSlides], [Slidy], [Slideous], or [reveal.js].
-You can also produce a PDF slide show using LaTeX [beamer].
+You can also produce a PDF slide show using LaTeX [`beamer`].
Here's the markdown source for a simple slide show, `habits.txt`:
@@ -3217,7 +3367,7 @@ using the `-V` option:
Note that header attributes will turn into slide attributes
(on a `<div>` or `<section>`) in HTML slide formats, allowing you
-to style individual slides. In Beamer, the only header attribute
+to style individual slides. In beamer, the only header attribute
that affects slides is the `allowframebreaks` class, which sets the
`allowframebreaks` option, causing multiple slides to be created
if the content overfills the frame. This is recommended especially for
@@ -3257,8 +3407,8 @@ EPUB Metadata
=============
EPUB metadata may be specified using the `--epub-metadata` option, but
-if the source document is markdown, it is better to use a YAML metadata
-block. Here is an example:
+if the source document is markdown, it is better to use a [YAML metadata
+block][Extension: `yaml_metadata_block`]. Here is an example:
---
title:
@@ -3295,7 +3445,7 @@ The following fields are recognized:
`creator`
~ Either a string value, or an object with fields `role`, `file-as`,
and `text`, or a list of such objects. Valid values for `role` are
- [marc relators](http://www.loc.gov/marc/relators/relaterm.html), but
+ [MARC relators], but
pandoc will attempt to translate the human-readable versions
(like "author" and "editor") to the appropriate marc relators.
@@ -3339,7 +3489,10 @@ The following fields are recognized:
`page-progression-direction`
~ Either `ltr` or `rtl`. Specifies the `page-progression-direction`
- spine [attribute][EPUBspine].
+ attribute for the [`spine` element].
+
+[MARC relators]: http://loc.gov/marc/relators/relaterm.html
+[`spine` element]: http://idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
Literate Haskell support
========================
@@ -3352,13 +3505,13 @@ literate Haskell source. This means that
- In markdown input, "bird track" sections will be parsed as Haskell
code rather than block quotations. Text between `\begin{code}`
and `\end{code}` will also be treated as Haskell code. For
- atx-style headers the character '=' will be used instead of '#'.
+ ATX-style headers the character '=' will be used instead of '#'.
- In markdown output, code blocks with classes `haskell` and `literate`
will be rendered using bird tracks, and block quotations will be
indented one space, so they will not be treated as Haskell code.
In addition, headers will be rendered setext-style (with underlines)
- rather than atx-style (with '#' characters). (This is because ghc
+ rather than ATX-style (with '#' characters). (This is because ghc
treats '#' characters in column 1 as introducing line numbers.)
- In restructured text input, "bird track" sections will be parsed
@@ -3391,10 +3544,8 @@ and pasted as literate Haskell source.
Syntax highlighting
===================
-Pandoc will automatically highlight syntax in fenced code blocks that
-are marked with a language name. (See [Extension:
-`inline_code_attributes`] and [Extension: `fenced_code_attributes`],
-above.) The Haskell library [highlighting-kate] is used for
+Pandoc will automatically highlight syntax in [fenced code blocks] that
+are marked with a language name. The Haskell library [highlighting-kate] is used for
highlighting, which works in HTML, Docx, and LaTeX/PDF output.
The color scheme can be selected using the `--highlight-style` option.
The default color scheme is `pygments`, which imitates the default color
@@ -3406,6 +3557,8 @@ To see a list of language names that pandoc will recognize, type
To disable highlighting, use the `--no-highlight` option.
+[highlighting-kate]: https://github.com/jgm/highlighting-kate
+
Custom writers
==============
@@ -3423,6 +3576,8 @@ which you can modify according to your needs, do
pandoc --print-default-data-file sample.lua
+[lua]: http://www.lua.org
+
Authors
=======
@@ -3481,7 +3636,7 @@ Hans-Peter Deifel,
Henry de Valence,
Ilya V. Portnov,
infinity0x,
-Jaime Marquínez Ferrándiz,
+Jaime Marquínez Ferrándiz,
James Aspnes,
Jamie F. Olson,
Jan Larres,
@@ -3556,46 +3711,4 @@ Vincent,
Wikiwide, and
Xavier Olive.
-[markdown]: http://daringfireball.net/projects/markdown/
-[reStructuredText]: http://docutils.sourceforge.net/docs/ref/rst/introduction.html
-[S5]: http://meyerweb.com/eric/tools/s5/
-[Slidy]: http://www.w3.org/Talks/Tools/Slidy/
-[Slideous]: http://goessner.net/articles/slideous/
-[HTML]: http://www.w3.org/TR/html40/
-[HTML 5]: http://www.w3.org/TR/html5/
-[XHTML]: http://www.w3.org/TR/xhtml1/
-[LaTeX]: http://www.latex-project.org/
-[beamer]: http://www.tex.ac.uk/CTAN/macros/latex/contrib/beamer
-[ConTeXt]: http://www.pragma-ade.nl/
-[RTF]: http://en.wikipedia.org/wiki/Rich_Text_Format
-[DocBook]: http://www.docbook.org/
-[OPML]: http://dev.opml.org/spec2.html
-[OpenDocument]: http://opendocument.xml.org/
-[ODT]: http://en.wikipedia.org/wiki/OpenDocument
-[Textile]: http://redcloth.org/textile
-[MediaWiki markup]: http://www.mediawiki.org/wiki/Help:Formatting
-[DokuWiki markup]: https://www.dokuwiki.org/dokuwiki
-[TWiki markup]: http://twiki.org/cgi-bin/view/TWiki/TextFormattingRules
-[Haddock markup]: http://www.haskell.org/haddock/doc/html/ch03s08.html
-[groff man]: http://developer.apple.com/DOCUMENTATION/Darwin/Reference/ManPages/man7/groff_man.7.html
-[Haskell]: http://www.haskell.org/
-[GNU Texinfo]: http://www.gnu.org/software/texinfo/
-[Emacs Org-Mode]: http://orgmode.org
-[AsciiDoc]: http://www.methods.co.nz/asciidoc/
[GPL]: http://www.gnu.org/copyleft/gpl.html "GNU General Public License"
-[DZSlides]: http://paulrouget.com/dzslides/
-[ISO 8601 format]: http://www.w3.org/TR/NOTE-datetime
-[Word docx]: http://www.microsoft.com/interop/openup/openxml/default.aspx
-[PDF]: http://www.adobe.com/pdf/
-[reveal.js]: http://lab.hakim.se/reveal-js/
-[FictionBook2]: http://www.fictionbook.org/index.php/Eng:XML_Schema_Fictionbook_2.1
-[lua]: http://www.lua.org
-[marc relators]: http://www.loc.gov/marc/relators/relaterm.html
-[BCP 47]: https://tools.ietf.org/html/bcp47
-[InDesign ICML]: https://www.adobe.com/content/dam/Adobe/en/devnet/indesign/cs55-docs/IDML/idml-specification.pdf
-[txt2tags]: http://txt2tags.org/
-[EPUB]: http://idpf.org/epub
-[EPUBspine]: http://www.idpf.org/epub/301/spec/epub-publications.html#sec-spine-elem
-[KaTeX]: https://github.com/Khan/KaTeX
-[CommonMark]: http://commonmark.org
-[highlighting-kate]: http://github.com/jgm/highlighting-kate
diff --git a/Setup.hs b/Setup.hs
index 312e1cf47..e2e026014 100644
--- a/Setup.hs
+++ b/Setup.hs
@@ -20,17 +20,14 @@ import Distribution.Simple
import Distribution.Simple.PreProcess
import Distribution.Simple.Setup (ConfigFlags(..))
import Distribution.PackageDescription (PackageDescription(..), FlagName(..))
-import System.Process ( rawSystem )
-import System.FilePath ( (</>) )
-import System.Directory ( findExecutable )
+import Distribution.Simple.Utils ( rawSystemExitCode, findProgramVersion )
+import System.Exit
import Distribution.Verbosity ( Verbosity )
import Distribution.Simple.Utils (info, notice, installOrdinaryFiles)
import Distribution.Simple.Setup
import Distribution.Simple.Program (simpleProgram, Program(..))
import Distribution.Simple.LocalBuildInfo
import Data.Version
-import System.Process (readProcess)
-import Text.ParserCombinators.ReadP (readP_to_S, skipSpaces, eof)
import Control.Monad (when)
import qualified Control.Exception as E
@@ -39,23 +36,11 @@ main = defaultMainWithHooks $ simpleUserHooks {
-- enable hsb2hs preprocessor for .hsb files
hookedPreProcessors = [ppBlobSuffixHandler]
, hookedPrograms = [(simpleProgram "hsb2hs"){
- programFindVersion = findHsb2hsVersion }]
+ programFindVersion = \verbosity fp ->
+ findProgramVersion "--version" id verbosity fp }]
, postCopy = installManPage
}
-findHsb2hsVersion :: Verbosity -> FilePath -> IO (Maybe Version)
-findHsb2hsVersion verb fp = do
- let handleExitFailure :: IOError -> IO (Maybe Version)
- handleExitFailure _ = return Nothing
- E.handle handleExitFailure $ do
- outp <- readProcess fp ["--version"] ""
- case readP_to_S (do v <- parseVersion
- skipSpaces
- eof
- return v) outp of
- ((v,""):_) -> return (Just v)
- _ -> return Nothing
-
ppBlobSuffixHandler :: PPSuffixHandler
ppBlobSuffixHandler = ("hsb", \_ lbi ->
PreProcessor {
@@ -67,11 +52,11 @@ ppBlobSuffixHandler = ("hsb", \_ lbi ->
_ -> False
when embedData $
do info verbosity $ "Preprocessing " ++ infile ++ " to " ++ outfile
- hsb2hsPath <- findExecutable "hsb2hs"
- case hsb2hsPath of
- Just p -> rawSystem p [infile, infile, outfile]
- Nothing -> error "hsb2hs is needed to build this program: cabal install hsb2hs"
- return ()
+ ec <- rawSystemExitCode verbosity "hsb2hs"
+ [infile, infile, outfile]
+ case ec of
+ ExitSuccess -> return ()
+ ExitFailure _ -> error "hsb2hs is needed to build this program"
})
installManPage :: Args -> CopyFlags
@@ -80,6 +65,6 @@ installManPage _ flags pkg lbi = do
let verbosity = fromFlag (copyVerbosity flags)
let copydest = fromFlag (copyDest flags)
let mandest = mandir (absoluteInstallDirs pkg lbi copydest)
- </> "man1"
+ ++ "/man1"
notice verbosity $ "Copying man page to " ++ mandest
installOrdinaryFiles verbosity mandest [("man", "pandoc.1")]
diff --git a/appveyor.yml b/appveyor.yml
index a31bc21b9..00a1aab34 100644
--- a/appveyor.yml
+++ b/appveyor.yml
@@ -1,6 +1,3 @@
-cache:
-- "C:\\Program Files\\Haskell Platform\\2014.2.0.0"
-
install:
- cmd: 'git submodule update --init'
- ps: |
@@ -10,7 +7,7 @@ install:
$env:Path += ";${env:ProgramFiles}\Haskell Platform\2014.2.0.0\bin"
$env:Path += ";${env:ProgramFiles}\Haskell Platform\2014.2.0.0\lib\extralibs\bin"
$env:Path += ";${env:ProgramFiles}\Haskell Platform\2014.2.0.0\mingw\bin"
- choco install wixtoolset
+ # choco install wixtoolset
cabal sandbox init
$env:Path += ";.\.cabal-sandbox\bin"
cabal update
diff --git a/benchmark/benchmark-pandoc.hs b/benchmark/benchmark-pandoc.hs
index 3fc70331f..d86d38f60 100644
--- a/benchmark/benchmark-pandoc.hs
+++ b/benchmark/benchmark-pandoc.hs
@@ -17,9 +17,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-}
import Text.Pandoc
import Criterion.Main
-import Criterion.Config
-import System.Environment (getArgs)
-import Data.Monoid
+import Criterion.Types (Config(..))
import Data.Maybe (mapMaybe)
import Debug.Trace (trace)
import Text.Pandoc.Error
@@ -44,9 +42,6 @@ writerBench doc (name, writer) = bench (name ++ " writer") $ nf
main :: IO ()
main = do
- args <- getArgs
- (conf,_) <- parseArgs defaultConfig{ cfgSamples = Last $ Just 20 }
- defaultOptions args
inp <- readFile "tests/testsuite.txt"
let opts = def{ readerSmart = True }
let doc = handleError $ readMarkdown opts inp
@@ -56,5 +51,5 @@ main = do
let writers' = [(n,w) | (n, PureStringWriter w) <- writers]
let writerBs = map (writerBench doc)
$ writers'
- defaultMainWith conf (return ()) $
- writerBs ++ readerBs
+ defaultMainWith defaultConfig{ timeLimit = 6.0 }
+ (writerBs ++ readerBs)
diff --git a/changelog b/changelog
index 2ceef17ac..c57d6ce4c 100644
--- a/changelog
+++ b/changelog
@@ -1,3 +1,230 @@
+pandoc (1.15.1)
+
+ [TODO - NEEDS ORGANIZING]
+
+ * Allow building with latest versions of http-types,
+ HUnit, criterion, syb, aeson.
+
+ * Revise variables discussion in README (Andrew Dunning).
+
+ * Updated latex template to work better with tufte
+ and other classes that include hyperref or color (Xavier Olive).
+
+ * Docx Reader:
+
+ + Create special punctuation test (Ophir Lifshitz).
+ + Parse soft, no-break hyphen elements (Ophir Lifshit).
+
+ * Templates
+
+ + Beamer: added `innertheme`, `outertheme` variables.
+ + LaTeX: added `mainfontoptions`, `sansfontoptions`,
+ `monofontoptions`, `mathfontoptions`, `fontfamilyoptions`.
+ + LaTeX, ConTeXt, HTML: support handling of bidirectional text
+ (mb21, #2191).
+ + LaTeX, ConTeXt: more specific language variables.
+ Instead of directly using `lang`, we now use `babel-lang` and
+ `polyglossia-lang` and `context-lang`. These variables are set by
+ the writers to the necessary values, based on the `lang` variable
+ (which now always takes a value in BCP47 format).
+
+ * epub.css: added selectors for nested emphasis (Pablo Rodriguez).
+
+ * For markdown_mmd, add: implicit_figures, superscripts, subscripts
+ (#2401).
+
+ * Added appveyor builds.
+
+ * MediaBag: ensure that `/` is always used as path separator.
+
+ * Update KaTeX JS and CSS versions (Emily Eisenberg).
+
+ * Support bidirectional text output with XeLaTeX, ConTeXt and HTML
+ (mb21)
+ closes #2191
+
+ * Document details of citation locator terms (Nick Bart).
+
+ * Correctly recognize book documentclass in metadata (#2395).
+
+ * Markdown reader: handle 'id' and 'class' in parsing key/value
+ attributes (#2396). `# Header {id="myid" class="foo bar"}`
+ is now equivalent to `# Header {#myid .foo .bar}`.
+
+ * LaTeX reader: support longtable (#2411).
+
+ * Org reader: Allow verse blocks to contain empty lines (#2402,
+ Albert Krewinkel).
+
+ * RST Writer: Don't normalize heading levels below input minimum
+ (Nikolay Yakimov).
+
+ * Markdown writer: in TOC, add links to headers (#829).
+
+ * `sample.lua`: define `CaptionedImage`, add newline at end (#2393).
+
+ * Tests: docx writer tests now use `../data` for data directory.
+ This allows tests to be run without installing first.
+
+ * Use user data directory for reference docx archive.
+ This allows the test suite to work without installing pandoc first.
+ It also brings the docx writer in line with the odt writer.
+
+ * Removed obsolete reference to default.csl (#2372).
+
+ * `lang` variable is now in BCP47 format (#1614, mb21).
+ Strings are converted for LaTeX and ConTeXt output.
+
+ * Haddock writer: escape `*` and `^` (G. Bataille).
+
+ * Use real jpg (not empty) for docx tests to avoid warning.
+
+ * RST reader: better handling of indirect roles.
+ Previously the parser failed on this kind of case
+
+ .. role:: indirect(code)
+
+ .. role:: py(indirect)
+ :language: python
+
+ :py:`hi`
+
+ Now it currectly recognizes `:py:` as a code role.
+
+ * Added note to CONTRIBUTING.md about ghc versions and travis.
+
+
+ * Org reader: add auto identifiers if not present on headers
+ (#2354, Juliusz Gonera).
+
+ * RST writer: ensure that `\ ` is inserted when needed
+ before Cite and Span elements that begin with a "complex"
+ element (jgm/pandoc-citeproc#157).
+
+ * Added `--bash-completion` option. This generates a bash completion
+ script. To use: `eval "$(pandoc --bash-completion)"`.
+
+ * Added stack install instructions to INSTALL.
+
+ * Added a stack.yaml.
+
+ * RST writer: Don't insert `\ ` when complex expression in matched pairs.
+ E.g. `` [:sup:`3`] `` is okay; you don't need `` [:sup:`3`\ ] ``.
+
+
+ * EPUB TOC: replace literal "<br/>" with space (#2105).
+
+ * EPUB reader: stop mangling external URLs (#2284).
+
+ * Docx writer: Moved invalid character stripping to `formattedString`.
+ This avoids an inefficient generic traversal (#2356).
+
+ * Text.Pandoc: disable `auto_identifiers` for epub.
+ The epub writer inserts its own auto identifiers;
+ this is more complex due to splitting into "chapter" files.
+
+ * HTML reader: updated for new automatic header attributes.
+
+ * MediaWiki reader: handle unquoted table attributes (#2355).
+
+ * Clarified what is "out of scope" in README and CONTRIBUTING.md.
+
+ * HTML reader: add auto identifiers if not present on headers.
+ This makes TOC linking work properly.
+
+ * DocBook reader: handle `informalexample` (#2319).
+
+ * LaTeX reader: Implement \Cite (#2335).
+
+ * Clarify docs on block quotes. The space after `>` is optional (#2346).
+
+
+ * Fix build failure with `--flags=-https` (Sergei Trofimovich).
+
+ * HTML Reader: Detect `font-variant` with `pickStyleAttrProps`
+ (Ophir Lifshitz).
+
+ * Pipe tables: allow indented columns. Previously the left-hand column
+ could not start with 4 or more spaces indent. This was inconvenient
+ for right-aligned left columns. Note that the first (header column)
+ must still have 3 or fewer spaces indentation, or the table will be
+ treated as an indented code block.
+
+ * README: Added space after backslash in image example (#2329).
+
+ * HTML Reader: Test `<ol>` type, class, and inline list-style(-type) CSS
+ (Ophir Lifshitz).
+
+ * Added ODT reader (MarLinn). Fully implemented features:
+ Paragraphs, Headers, Basic styling, Unordered lists, Ordered lists,
+ External Links, Internal Links, Footnotes, Endnotes, Blockquotes.
+ Partly implemented features: Citations, Tables.
+
+ * Parsing: `toKey`: strip off outer brackets.
+ This makes keys with extra space at the beginning and end
+ work: e.g.
+
+ [foo]: bar
+
+ [ foo ]
+
+ will now be a link to bar (it wasn't before).
+
+ * LaTeX reader: support abstract environment.
+ The abstract populates an "abstract" metadata field.
+
+ * Markdown Reader:
+
+ + Add basic tests for each header style (Ophir Lifshitz).
+ + Add implicit header ref tests for headers with spaces (ophir Lifshitz).
+ + Skip spaces in headers (Ophir Lifsihtz).
+
+ * Fix regression: allow HTML comments containing `--`.
+ Technically this isn't allowed in an HTML comment, but
+ we've always allowed it, and so do most other implementations.
+ It is handy if e.g. you want to put command line arguments
+ in HTML comments.
+
+ * Use newManager instead of withManager in recent http-client.
+ This avoids a deprecation warning.
+
+ * List all styles in manual for `--reference-docx` (Chris Black)
+
+ * DZSlides: Add `role="note"` for speaker notes (#1693).
+
+ * HTML reader: handle type attribute on ol, e.g. `<ol type="i">`
+ (#2313).
+
+ * LaTeX reader: properly handle booktabs lines. Lines aren't
+ part of the pandoc table model, but we can just ignore them (#2307).
+
+ * Don't capitalize header links in man page.
+ Also regenerated man page from latest README.
+
+ * Fixed some internal links in README (#2309).
+
+ * LaTeX writer: Fixed detection of 'chapters' from template.
+ If a documentclass isn't specified in metadata, but the
+ template has a hardwired bookish documentclass, act as if
+ `--chapters` was used. This was the default in earlier
+ versions, but it has been broken for a little while.
+
+ * Docx Reader: Updated headers test (Ophir Lifshitz)
+ Replaced styles.xml in headers.docx with pandoc's current styles.xml, which
+ contains styles for Heading 1 through 6. Added Heading 4 through 7 to the test
+ document. Note that Heading 7 is not parsed as a Heading because there is no
+ Heading 7 style.
+
+ * Reference Docx:
+
+ + Add missing Header 6 style (steel blue) (Ophir Lifshitz).
+ + Correct outlineLvl for Header styles (Ophir Lifshitz).
+
+ * Added section on REPL to CONTRIBUTING.md.
+
+ * Use '=' instead of '#' for atx-style headers in markdown+lhs.
+ (Kristof Bastiaensen)
+
pandoc (1.15.0.6)
* `--self-contained`: Fixed overaggressive CSS minimization (#2301, 2286).
diff --git a/data/templates b/data/templates
-Subproject 2f5f539605782f41b0059c46b2ba0a5dfc72354
+Subproject 159a15c96c7eac5113c3cfb15fc3b69a45871a7
diff --git a/make_travis_yml.hs b/make_travis_yml.hs
new file mode 100644
index 000000000..91916c499
--- /dev/null
+++ b/make_travis_yml.hs
@@ -0,0 +1,210 @@
+#!/usr/bin/env runghc
+
+-- NB: This code deliberately avoids relying on non-standard packages
+
+import Control.Monad
+import Data.List
+import Data.Version
+import System.Environment
+import System.Exit
+import System.IO
+
+import Distribution.PackageDescription.Parse (readPackageDescription)
+import Distribution.PackageDescription (packageDescription, testedWith)
+import Distribution.Compiler (CompilerFlavor(..))
+import Distribution.Version
+import Distribution.Text
+
+putStrLnErr :: String -> IO ()
+putStrLnErr m = hPutStrLn stderr ("*ERROR* " ++ m) >> exitFailure
+
+putStrLnWarn :: String -> IO ()
+putStrLnWarn m = hPutStrLn stderr ("*WARNING* " ++ m)
+
+putStrLnInfo :: String -> IO ()
+putStrLnInfo m = hPutStrLn stderr ("*INFO* " ++ m)
+
+main :: IO ()
+main = do
+ args <- getArgs
+ case args of
+ (cabfn:xpkgs) -> do genTravisFromCabalFile cabfn xpkgs
+ _ -> putStrLnErr (unlines $ [ "expected .cabal file as command-line argument"
+ , "Usage: make_travis_yml.hs <cabal-file> <extra-apt-packages...>"
+ , ""
+ , "Example: make_travis_yml.hs someProject.cabal alex-3.1.4 liblzma-dev > .travis.yml"
+ ])
+
+genTravisFromCabalFile :: FilePath -> [String] -> IO ()
+genTravisFromCabalFile fn xpkgs = do
+ gpd <- readPackageDescription maxBound fn
+
+ let compilers = testedWith $ packageDescription $ gpd
+
+ let unknownComps = nub [ c | (c,_) <- compilers, c /= GHC ]
+ ghcVerConstrs = [ vc | (GHC,vc) <- compilers ]
+ ghcVerConstrs' = simplifyVersionRange $ foldr unionVersionRanges noVersion ghcVerConstrs
+
+ when (null compilers) $ do
+ putStrLnErr "empty or missing 'tested-with:' definition in .cabal file"
+
+ unless (null unknownComps) $ do
+ putStrLnWarn $ "ignoring unsupported compilers mentioned in tested-with: " ++ show unknownComps
+
+ when (null ghcVerConstrs) $ do
+ putStrLnErr "'tested-with:' doesn't mention any 'GHC' version"
+
+ when (isNoVersion ghcVerConstrs') $ do
+ putStrLnErr "'tested-with:' describes an empty version range for 'GHC'"
+
+ when (isAnyVersion ghcVerConstrs') $ do
+ putStrLnErr "'tested-with:' allows /any/ 'GHC' version"
+
+ let testedGhcVersions = filter (`withinRange` ghcVerConstrs') knownGhcVersions
+
+ when (null testedGhcVersions) $ do
+ putStrLnErr "no known GHC version is allowed by the 'tested-with' specification"
+
+ putStrLnInfo $ "Generating Travis-CI config for testing for GHC versions: " ++ (unwords $ map disp' $ testedGhcVersions)
+
+ ----------------------------------------------------------------------------
+ -- travis.yml generation starts here
+
+ putStrLn "# This file has been generated -- see https://github.com/hvr/multi-ghc-travis"
+ putStrLn "language: c"
+ putStrLn "sudo: false"
+ putStrLn ""
+ putStrLn "cache:"
+ putStrLn " directories:"
+ putStrLn " - $HOME/.cabsnap"
+ putStrLn " - $HOME/.cabal/packages"
+ putStrLn ""
+ putStrLn "before_cache:"
+ putStrLn " - rm -fv $HOME/.cabal/packages/hackage.haskell.org/build-reports.log"
+ putStrLn " - rm -fv $HOME/.cabal/packages/hackage.haskell.org/00-index.tar"
+ putStrLn ""
+ putStrLn "matrix:"
+ putStrLn " include:"
+
+ forM_ testedGhcVersions $ \gv -> do
+ let cvs = disp' (lookupCabVer gv)
+ gvs = disp' gv
+ ghcopts = if gv >= Version [7,10,0] []
+ then ""
+ else "-Werror"
+
+ xpkgs' = concatMap (',':) xpkgs
+
+ putStrLn $ concat [ " - env: CABALVER=", cvs, " GHCVER=", gvs,
+ " GHCOPTS=", ghcopts]
+ putStrLn $ concat [ " compiler: \": #GHC ", gvs, "\"" ]
+ putStrLn $ concat [ " addons: {apt: {packages: [cabal-install-", cvs, ",ghc-", gvs, xpkgs'
+ , "], sources: [hvr-ghc]}}" ]
+ return ()
+
+ let headGhcVers = filter isHead testedGhcVersions
+
+ unless (null headGhcVers) $ do
+ putStrLn ""
+ putStrLn " allow_failures:"
+
+ forM_ headGhcVers $ \gv -> do
+ let cvs = disp' (lookupCabVer gv)
+ gvs = disp' gv
+ putStrLn $ concat [ " - env: CABALVER=", cvs, " GHCVER=", gvs ]
+
+ putStrLn ""
+ putStrLn "before_install:"
+ putStrLn " - unset CC"
+ putStrLn " - export PATH=/opt/ghc/$GHCVER/bin:/opt/cabal/$CABALVER/bin:$PATH"
+
+ putStrLn ""
+
+ putStr $ unlines
+ [ "install:"
+ , " - cabal --version"
+ , " - echo \"$(ghc --version) [$(ghc --print-project-git-commit-id 2> /dev/null || echo '?')]\""
+ , " - if [ -f $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz ];"
+ , " then"
+ , " zcat $HOME/.cabal/packages/hackage.haskell.org/00-index.tar.gz >"
+ , " $HOME/.cabal/packages/hackage.haskell.org/00-index.tar;"
+ , " fi"
+ , " - travis_retry cabal update -v"
+ , " - sed -i 's/^jobs:/-- jobs:/' ${HOME}/.cabal/config"
+ , " - cabal install --only-dependencies --enable-tests --enable-benchmarks --dry -v > installplan.txt"
+ , " - sed -i -e '1,/^Resolving /d' installplan.txt; cat installplan.txt"
+ , ""
+ , "# check whether current requested install-plan matches cached package-db snapshot"
+ , " - if diff -u installplan.txt $HOME/.cabsnap/installplan.txt;"
+ , " then"
+ , " echo \"cabal build-cache HIT\";"
+ , " rm -rfv .ghc;"
+ , " cp -a $HOME/.cabsnap/ghc $HOME/.ghc;"
+ , " cp -a $HOME/.cabsnap/lib $HOME/.cabsnap/share $HOME/.cabsnap/bin $HOME/.cabal/;"
+ , " else"
+ , " echo \"cabal build-cache MISS\";"
+ , " rm -rf $HOME/.cabsnap;"
+ , " mkdir -p $HOME/.ghc $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin;"
+ , " cabal install --only-dependencies --enable-tests --enable-benchmarks;"
+ , " fi"
+ , " "
+ , "# snapshot package-db on cache miss"
+ , " - if [ ! -d $HOME/.cabsnap ];"
+ , " then"
+ , " echo \"snapshotting package-db to build-cache\";"
+ , " mkdir $HOME/.cabsnap;"
+ , " cp -a $HOME/.ghc $HOME/.cabsnap/ghc;"
+ , " cp -a $HOME/.cabal/lib $HOME/.cabal/share $HOME/.cabal/bin installplan.txt $HOME/.cabsnap/;"
+ , " fi"
+ , ""
+ , "# Here starts the actual work to be performed for the package under test;"
+ , "# any command which exits with a non-zero exit code causes the build to fail."
+ , "script:"
+ , " - if [ -f configure.ac ]; then autoreconf -i; fi"
+ , " - cabal configure --enable-tests --enable-benchmarks -v2 # -v2 provides useful information for debugging"
+ , " - cabal build --ghc-options=$GHCOPTS # this builds all libraries and executables (including tests/benchmarks)"
+ , " - cabal test"
+ , " - cabal check"
+ , "# Test that a source-distribution can be generated"
+ , "# (with cabal >= 1.18 'cabal sdist' would work too):"
+ , " - ./dist/setup/setup sdist"
+ , ""
+ , "# Check that the resulting source distribution can be built & installed."
+ , "# If there are no other `.tar.gz` files in `dist`, this can be even simpler:"
+ , "# `cabal install --force-reinstalls dist/*-*.tar.gz`"
+ , " - SRC_TGZ=$(cabal info . | awk '{print $2;exit}').tar.gz &&"
+ , " (cd dist && cabal install --force-reinstalls \"$SRC_TGZ\")"
+ , ""
+ , "# EOF"
+ ]
+
+ return ()
+ where
+ knownGhcVersions :: [Version]
+ knownGhcVersions = fmap (`Version` [])
+ [ [7,0,1], [7,0,2], [7,0,3], [7,0,4]
+ , [7,2,1], [7,2,2]
+ , [7,4,1], [7,4,2]
+ , [7,6,1], [7,6,2], [7,6,3]
+ , [7,8,1], [7,8,2], [7,8,3], [7,8,4]
+ , [7,10,1], [7,10,2]
+ , [7,11] -- HEAD
+ ]
+
+ lookupCabVer :: Version -> Version
+ lookupCabVer (Version (x:y:_) _) = maybe (error "internal error") id $ lookup (x,y) cabalVerMap
+ where
+ cabalVerMap = fmap (fmap (`Version` []))
+ [ ((7, 0), [1,16])
+ , ((7, 2), [1,16])
+ , ((7, 4), [1,16])
+ , ((7, 6), [1,16])
+ , ((7, 8), [1,18])
+ , ((7,10), [1,22])
+ , ((7,11), [1,23]) -- HEAD
+ ]
+
+ isHead (Version (_:y:_) _) = odd (y :: Int)
+
+ disp' v | isHead v = "head"
+ | otherwise = display v
diff --git a/pandoc.cabal b/pandoc.cabal
index 9a72eb25b..3818d0bf4 100644
--- a/pandoc.cabal
+++ b/pandoc.cabal
@@ -11,7 +11,7 @@ Bug-Reports: https://github.com/jgm/pandoc/issues
Stability: alpha
Homepage: http://pandoc.org
Category: Text
-Tested-With: GHC == 7.4.2, GHC == 7.6.3, GHC == 7.8.2
+Tested-With: GHC == 7.4.2, GHC == 7.6.3, GHC == 7.8.4, GHC == 7.10.2
Synopsis: Conversion between markup formats
Description: Pandoc is a Haskell library for converting from one markup
format to another, and a command-line tool that uses
@@ -293,7 +293,7 @@ Library
if flag(https)
Build-Depends: http-client >= 0.3.2 && < 0.5,
http-client-tls >= 0.2 && < 0.3,
- http-types >= 0.8 && < 0.9
+ http-types >= 0.8 && < 0.10
cpp-options: -DHTTP_CLIENT
if flag(embed_data_files)
cpp-options: -DEMBED_DATA_FILES
@@ -461,7 +461,7 @@ Test-Suite test-pandoc
test-framework-hunit >= 0.2 && < 0.4,
test-framework-quickcheck2 >= 0.2.9 && < 0.4,
QuickCheck >= 2.4 && < 2.9,
- HUnit >= 1.2 && < 1.3,
+ HUnit >= 1.2 && < 1.4,
containers >= 0.1 && < 0.6,
ansi-terminal >= 0.5 && < 0.7,
executable-path >= 0.0 && < 0.1,
@@ -500,6 +500,6 @@ benchmark benchmark-pandoc
Build-Depends: pandoc,
base >= 4.2 && < 5,
syb >= 0.1 && < 0.7,
- criterion >= 0.5 && < 1.2
+ criterion >= 1.0 && < 1.2
Ghc-Options: -rtsopts -Wall -fno-warn-unused-do-bind
Default-Language: Haskell98
diff --git a/src/Text/Pandoc/Options.hs b/src/Text/Pandoc/Options.hs
index 17eb4a15c..5085785fd 100644
--- a/src/Text/Pandoc/Options.hs
+++ b/src/Text/Pandoc/Options.hs
@@ -224,6 +224,15 @@ multimarkdownExtensions = Set.fromList
, Ext_implicit_header_references
, Ext_auto_identifiers
, Ext_mmd_header_identifiers
+ , Ext_implicit_figures
+ -- Note: MMD's syntax for superscripts and subscripts
+ -- is a bit more permissive than pandoc's, allowing
+ -- e^2 and a~1 instead of e^2^ and a~1~, so even with
+ -- these options we don't have full support for MMD
+ -- superscripts and subscripts, but there's no reason
+ -- not to include these:
+ , Ext_superscript
+ , Ext_subscript
]
strictExtensions :: Set Extension
diff --git a/src/Text/Pandoc/Readers/Docx.hs b/src/Text/Pandoc/Readers/Docx.hs
index 67a97ae85..8b8d1ede1 100644
--- a/src/Text/Pandoc/Readers/Docx.hs
+++ b/src/Text/Pandoc/Readers/Docx.hs
@@ -206,11 +206,15 @@ runElemToInlines :: RunElem -> Inlines
runElemToInlines (TextRun s) = text s
runElemToInlines (LnBrk) = linebreak
runElemToInlines (Tab) = space
+runElemToInlines (SoftHyphen) = text "\xad"
+runElemToInlines (NoBreakHyphen) = text "\x2011"
runElemToString :: RunElem -> String
runElemToString (TextRun s) = s
runElemToString (LnBrk) = ['\n']
runElemToString (Tab) = ['\t']
+runElemToString (SoftHyphen) = ['\xad']
+runElemToString (NoBreakHyphen) = ['\x2011']
runToString :: Run -> String
runToString (Run _ runElems) = concatMap runElemToString runElems
diff --git a/src/Text/Pandoc/Readers/Docx/Parse.hs b/src/Text/Pandoc/Readers/Docx/Parse.hs
index cce80fb48..53af19dfd 100644
--- a/src/Text/Pandoc/Readers/Docx/Parse.hs
+++ b/src/Text/Pandoc/Readers/Docx/Parse.hs
@@ -208,7 +208,7 @@ data Run = Run RunStyle [RunElem]
| InlineDrawing FilePath B.ByteString
deriving Show
-data RunElem = TextRun String | LnBrk | Tab
+data RunElem = TextRun String | LnBrk | Tab | SoftHyphen | NoBreakHyphen
deriving Show
data VertAlign = BaseLn | SupScrpt | SubScrpt
@@ -877,6 +877,8 @@ elemToRunElem ns element
map (\x -> fromMaybe x . getUnicode f . lowerFromPrivate $ x) str
| isElem ns "w" "br" element = return LnBrk
| isElem ns "w" "tab" element = return Tab
+ | isElem ns "w" "softHyphen" element = return SoftHyphen
+ | isElem ns "w" "noBreakHyphen" element = return NoBreakHyphen
| isElem ns "w" "sym" element = return (getSymChar ns element)
| otherwise = throwError WrongElem
where
diff --git a/src/Text/Pandoc/Readers/LaTeX.hs b/src/Text/Pandoc/Readers/LaTeX.hs
index ed0291051..0e144dd0d 100644
--- a/src/Text/Pandoc/Readers/LaTeX.hs
+++ b/src/Text/Pandoc/Readers/LaTeX.hs
@@ -234,7 +234,9 @@ blocks = mconcat <$> many block
getRawCommand :: String -> LP String
getRawCommand name' = do
- rawargs <- withRaw (skipopts *> option "" dimenarg *> many braced)
+ rawargs <- withRaw (many (try (optional sp *> opt)) *>
+ option "" (try (optional sp *> dimenarg)) *>
+ many braced)
return $ '\\' : name' ++ snd rawargs
lookupListDefault :: (Ord k) => v -> [k] -> M.Map k v -> v
@@ -816,10 +818,10 @@ tok :: LP Inlines
tok = try $ grouped inline <|> inlineCommand <|> str <$> count 1 inlineChar
opt :: LP Inlines
-opt = bracketed inline <* optional sp
+opt = bracketed inline
skipopts :: LP ()
-skipopts = skipMany opt
+skipopts = skipMany (opt *> optional sp)
inlineText :: LP Inlines
inlineText = str <$> many1 inlineChar
diff --git a/tests/Tests/Readers/Docx.hs b/tests/Tests/Readers/Docx.hs
index 47292bc99..7e3f1979e 100644
--- a/tests/Tests/Readers/Docx.hs
+++ b/tests/Tests/Readers/Docx.hs
@@ -131,6 +131,10 @@ tests = [ testGroup "inlines"
"docx/tabs.docx"
"docx/tabs.native"
, testCompare
+ "special punctuation"
+ "docx/special_punctuation.docx"
+ "docx/special_punctuation.native"
+ , testCompare
"normalizing inlines"
"docx/normalize.docx"
"docx/normalize.native"
diff --git a/tests/docx/special_punctuation.docx b/tests/docx/special_punctuation.docx
new file mode 100644
index 000000000..8e0bb55c9
--- /dev/null
+++ b/tests/docx/special_punctuation.docx
Binary files differ
diff --git a/tests/docx/special_punctuation.native b/tests/docx/special_punctuation.native
new file mode 100644
index 000000000..304289f44
--- /dev/null
+++ b/tests/docx/special_punctuation.native
@@ -0,0 +1,2 @@
+[Para [Str "Soft",Space,Str "hyphen:",Space,Str "[\173]"]
+,Para [Str "Non-breaking",Space,Str "hyphen:",Space,Str "[\8209]"]]
diff --git a/tests/lhs-test.latex b/tests/lhs-test.latex
index 626a74cfa..2d0373e76 100644
--- a/tests/lhs-test.latex
+++ b/tests/lhs-test.latex
@@ -23,6 +23,8 @@
\usepackage{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
+\makeatletter
+\@ifpackageloaded{hyperref}{}{%
\ifxetex
\usepackage[setpagesize=false, % page size defined by xetex
unicode=false, % unicode breaks when used with xetex
@@ -30,7 +32,13 @@
\else
\usepackage[unicode=true]{hyperref}
\fi
-\usepackage[usenames,dvipsnames]{color}
+}
+\@ifpackageloaded{color}{
+ \PassOptionsToPackage{usenames,dvipsnames}{color}
+}{%
+ \usepackage[usenames,dvipsnames]{color}
+}
+\makeatother
\hypersetup{breaklinks=true,
bookmarks=true,
pdfauthor={},
diff --git a/tests/lhs-test.latex+lhs b/tests/lhs-test.latex+lhs
index 029789ba8..101025c02 100644
--- a/tests/lhs-test.latex+lhs
+++ b/tests/lhs-test.latex+lhs
@@ -23,6 +23,8 @@
\usepackage{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
+\makeatletter
+\@ifpackageloaded{hyperref}{}{%
\ifxetex
\usepackage[setpagesize=false, % page size defined by xetex
unicode=false, % unicode breaks when used with xetex
@@ -30,7 +32,13 @@
\else
\usepackage[unicode=true]{hyperref}
\fi
-\usepackage[usenames,dvipsnames]{color}
+}
+\@ifpackageloaded{color}{
+ \PassOptionsToPackage{usenames,dvipsnames}{color}
+}{%
+ \usepackage[usenames,dvipsnames]{color}
+}
+\makeatother
\hypersetup{breaklinks=true,
bookmarks=true,
pdfauthor={},
diff --git a/tests/writer.latex b/tests/writer.latex
index 8b34777fa..0e5ac8131 100644
--- a/tests/writer.latex
+++ b/tests/writer.latex
@@ -23,6 +23,8 @@
\usepackage{microtype}
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
}{}
+\makeatletter
+\@ifpackageloaded{hyperref}{}{%
\ifxetex
\usepackage[setpagesize=false, % page size defined by xetex
unicode=false, % unicode breaks when used with xetex
@@ -30,7 +32,13 @@
\else
\usepackage[unicode=true]{hyperref}
\fi
-\usepackage[usenames,dvipsnames]{color}
+}
+\@ifpackageloaded{color}{
+ \PassOptionsToPackage{usenames,dvipsnames}{color}
+}{%
+ \usepackage[usenames,dvipsnames]{color}
+}
+\makeatother
\hypersetup{breaklinks=true,
bookmarks=true,
pdfauthor={John MacFarlane; Anonymous},