Merge branch 'master' of https://github.com/jgm/pandoc

8 files changed, 478 insertions, 37 deletions

diff --git a/doc/epub.md b/doc/epub.md
index 82c26dcef..c05faf80c 100644
--- a/doc/epub.md
+++ b/doc/epub.md
@@ -141,8 +141,15 @@ Pandoc has an EPUB3 writer.  It renders LaTeX math into MathML, which
 EPUB3 readers are supposed to support (but unfortunately few do).
 
 Of course, this isn't much help if you want EPUB2 output (`pandoc -t epub2`)
-or target readers that don't support MathML. Then you should try using the
-`--webtex` option, which will use a web service to convert the TeX to an image.
+or target readers that don't support MathML. Then you have two options:
+
+1.  Use the [`--webtex`](https://pandoc.org/MANUAL.html#option--webtex) option,
+    which will use a web service to convert the TeX to an image.
+2.  Use the [`--gladtex`](https://pandoc.org/MANUAL.html#option--gladtex) option
+    to convert maths into SVG images on your local machine.
+
+Both GladTeX and WebTeX add the LaTeX source of the formula as alternative text
+of the image,  increasing accessibility for blind users.
 
 [KindleGen]: https://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000765211
 [EPUB]:  https://en.wikipedia.org/wiki/EPUB
diff --git a/doc/faqs.md b/doc/faqs.md
new file mode 100644
index 000000000..2f3368837
--- /dev/null
+++ b/doc/faqs.md
@@ -0,0 +1,128 @@
+% FAQs
+
+::: faqs
+
+## How can I convert a whole directory of files from Markdown to RTF?
+
+On linux or OSX:
+
+    for f in *.txt; do pandoc "$f" -s -o "${f%.txt}.rtf"; done
+
+
+In Windows Powershell:
+
+    gci -r -i *.txt |foreach{$rtf=$_.directoryname+"\"+$_.basename+".rtf";pandoc -f markdown -s $_.name -o $rtf}
+
+## I used pandoc to convert a document to ICML (or OPML or RTF), and when I try to open it I'm told it's invalid.  What have I done wrong?
+
+Be sure to use the `-s` or `--standalone` flag, or you just get a
+fragment, not a full document with the required header:
+
+    pandoc -s -f markdown -t icml -o my.icml my.md
+
+## I get a blank document when I try to convert a markdown document in Chinese to PDF.
+
+By default, pandoc uses pdflatex to generate the PDF, and pdflatex
+doesn't handle Chinese characters. But you can change the default to
+use xelatex instead. You should also make sure you're using a font
+with Chinese glyphs.  For example:
+
+    pandoc -o c.pdf --pdf-engine=xelatex -V mainfont='Adobe Ming Std'
+
+## The Windows installer does a single user install, rather than installing pandoc for all users. How can I install pandoc for all users?
+
+Run the following command as admin:
+
+    msiexec /i pandoc-VERSION.msi ALLUSERS=1
+
+This will put pandoc in `C:\Program Files\Pandoc`.
+You can install Pandoc to a different directory by setting APPLICATIONFOLDER parameter,
+for example:
+
+    msiexec /i pandoc-1.11.1.msi ALLUSERS=1 APPLICATIONFOLDER="C:\Pandoc"
+
+## How do I change the margins in PDF output?
+
+The option
+
+    -V geometry:margin=1in
+
+will set the margins to one inch on each side.  If you don't want uniform
+margins, you can do something like
+
+    -V geometry:"top=2cm, bottom=1.5cm, left=1cm, right=1cm"
+
+Or
+
+    -V geometry:"left=3cm, width=10cm"
+
+For more options, see the documentation for the LaTeX [geometry
+package](https://www.ctan.org/pkg/geometry).
+
+## How does pandoc compare to multimarkdown?
+
+Here is a [wiki
+page](https://github.com/jgm/pandoc/wiki/Pandoc-vs-Multimarkdown)
+comparing the two.
+
+## When I specify an image width of 50% and convert to LaTeX, pandoc sets the height to textheight and the aspect ratio isn't preserved. How can I prevent this?
+
+For example, if you convert an image with `{width="50%"}`, the LaTeX produced
+will be `\includegraphics[width=0.5\textwidth,height=\textheight]`.
+
+This output presupposes the following code in pandoc's default latex
+template:
+
+```
+% Scale images if necessary, so that they will not overflow the page
+% margins by default, and it is still possible to overwrite the defaults
+% using explicit options in \includegraphics[width, height, ...]{}
+\setkeys{Gin}{width=\maxwidth,height=\maxheight,keepaspectratio}
+```
+
+If you don't have this in your custom template, you should
+add it.  If we didn't set the `height` explicitly in this way,
+the image would not be resized correctly unless it was
+being resized to smaller than its original size.
+
+## Pandoc sometimes uses too much memory. How can I limit the memory used by pandoc?
+
+`pandoc +RTS -M30m -RTS` will limit heap memory to 30MB.
+When converting a document requires more than this, an out of
+memory error will be issued.
+
+## When using `--include-in-header` with PDF or LaTeX output, how do I reference tex declarations coming after `$header-includes$` in the default template?
+
+For various reasons, the `$header-includes$` are not at the very
+end of the LaTeX preamble.  This poses a problem when the code
+you are inserting depends on declarations in the preamble coming
+after the `$header-includes$` location. For example, you might
+want to reference the `\author` and `\title` metadata values
+(set at the very bottom of the preamble) and present them in
+margins. In that case you can wrap your code in `etoolbox`'s
+`\AtEndPreamble`.  The technique is demonstrated in [this
+gist](https://gist.github.com/JohnLukeBentley/9dda6166b9ee5c4127afd2b8cd16b70a).
+When using `\AtEndPreamble`, keep any `makeatletter` or
+`makeatother` outside of the `\AtEndPreamble`, as shown in the
+example.
+
+## How can I convert PDFs to other formats using pandoc?
+
+You can't. You can try opening the PDF in Word or Google Docs
+and saving in a format from which pandoc can convert directly.
+
+## Do I really need to install a 1 GB TeX installation to produce a PDF using pandoc?
+
+No.  You can get by with a relatively small TeX installation,
+for example, by starting with MacTeX's Basic TeX distribution
+and using the `tlmgr` tool to install a few packages required by pandoc
+(see https://pandoc.org/MANUAL.html#creating-a-pdf).
+
+Or, you can produce PDFs via HTML and `wkhtmltopdf`,
+or via groff ms and `pdfroff`.  (These don't produce as nice
+topography as TeX, particularly when it comes to math, but they
+may be fine for many purposes.)
+
+
+:::
+
diff --git a/doc/filters.md b/doc/filters.md
index 8b6002467..004a83b7d 100644
--- a/doc/filters.md
+++ b/doc/filters.md
@@ -253,12 +253,15 @@ repository](https://github.com/jgm/pandocfilters).
 
 For a more Pythonic alternative to pandocfilters, see
 the [panflute](https://pypi.org/project/panflute) library.
-Don't like Python?   There are also ports of pandocfilters in
-[PHP](https://github.com/vinai/pandocfilters-php),
-[perl](https://metacpan.org/pod/Pandoc::Filter),
-[javascript/node.js](https://github.com/mvhenderson/pandoc-filter-node),
-[Groovy](https://github.com/dfrommi/groovy-pandoc), and
-[Ruby](https://heerdebeer.org/Software/markdown/paru/).
+Don't like Python? There are also ports of pandocfilters in
+
+- [PHP](https://github.com/vinai/pandocfilters-php),
+- [perl](https://metacpan.org/pod/Pandoc::Filter),
+- TypeScript/JavaScript via Node.js
+  - [pandoc-filter](https://github.com/mvhenderson/pandoc-filter-node),
+  - [node-pandoc-filter](https://github.com/mu-io/node-pandoc-filter),
+- [Groovy](https://github.com/dfrommi/groovy-pandoc), and
+- [Ruby](https://heerdebeer.org/Software/markdown/paru/).
 
 Starting with pandoc 2.0, pandoc includes built-in support for
 writing filters in lua.  The lua interpreter is built in to
@@ -391,6 +394,8 @@ automatically assign it `Just` the target format or `Nothing`.
 
 We compile our script:
 
+    # first, make sure pandoc-types is installed:
+    cabal install --lib pandoc-types --package-env .
     ghc --make handleRuby
 
 Then run it:
@@ -500,7 +505,8 @@ extension.
   ---------------- --------------
   .py              `python`
   .hs              `runhaskell`
-  .pl              `ruby`
+  .pl              `perl`
+  .rb              `ruby`
   .php             `php`
   .js              `node`
   .r               `Rscript`
diff --git a/doc/jats.md b/doc/jats.md
index 362ae3bef..c099e0a04 100644
--- a/doc/jats.md
+++ b/doc/jats.md
@@ -33,6 +33,11 @@ Metadata Values
 
         See [`<given-names>`][elem:given-names].
 
+    `name`
+    :   full name of the author; included only as a fallback if
+        `author.surname` is not available. Tagged with
+        [`<string-name>`][elem:string-name].
+
     `email`
     :   the contributor's email address.
 
@@ -45,6 +50,13 @@ Metadata Values
         list must also occur as the `id` of an affiliation listed in
         the top-level `affiliation` list.
 
+    `equal-contrib`
+    :   boolean attribute used to mark authors who contributed
+        equally to the work. The
+        [`equal-contrib`][attr:equal-contrib] attribute is added
+        to the author's [`<contrib>`] element if this is set to a
+        truthy value.
+
     `cor-id`
     :   identifier linking to the contributor's correspondence
         information. The info itself must be stored in as an item in
@@ -167,12 +179,13 @@ Metadata Values
     pass these components directly.
 
     The publication date is recorded in the document via the
-    [`<pub-date>`][elem:pub-date] element and its sub-elements. The
-    [`pub-type`][attr:pub-type] attribute is always set to `epub`.
+    [`<pub-date>`] element and its sub-elements. The
+    [`publication-format`][attr:publication-format] attribute is
+    always set to `electronic`.
 
     `iso-8601`
     :   ISO-8601 representation of the publication date. Used as the
-        value of the [`pub-date`][elem:pub-date] element's
+        value of the [`<pub-date>`] element's
         [`iso-8601-date`][attr:iso-8601-date] attribute.
 
         This value is set automatically if pandoc can parse the
@@ -186,6 +199,12 @@ Metadata Values
         The values are set automatically if pandoc can parse the
         `date` value as a date.
 
+    `type`
+    :   The type of event marked by this date. The value is set as
+        the [`date-type`][attr:date-type] attribute on the
+        [`<pub-date>`] element and defaults to "pub" if not
+        specified.
+
 `article`
 :   information concerning the article that identifies or describes
     it. The key-value pairs within this map are typically used
@@ -295,12 +314,14 @@ Metadata Values
     `pissn`
     :   ISSN identifier of the publication's print version. Used as
         content of the [`<issn>`][elem:issn] element with the
-        [`pub-type`][attr:pub-type] attribute set to `ppub`.
+        [`publication-format`][attr:publication-format] attribute
+        set to `print`.
 
     `eissn`
     :   ISSN identifier of the publication's electronic version.
         Used as content of the [`<issn>`][elem:issn] element with
-        the [`pub-type`][attr:pub-type] attribute set to `epub`.
+        the [`publication-format`][attr:publication-format]
+        attribute set to `electronic`.
 
     `publisher-name`
     :   name of the publishing entity (person, company, or other).
@@ -340,6 +361,8 @@ Required metadata values:
 
 [Ringgold]: https://ringgold.com/
 [attr:content-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/content-type.html
+[attr:date-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/date-type.html
+[attr:equal-contrib]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/equal-contrib.html
 [attr:fn-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/fn-type.html
 [attr:institution-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/institution-id-type.html
 [attr:iso-8601-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/iso-8601-date.html
@@ -347,7 +370,7 @@ Required metadata values:
 [attr:kwd-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/kwd-group-type.html
 [attr:license-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/license-type.html
 [attr:pub-id-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-id-type.html
-[attr:pub-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/pub-type.html
+[attr:publication-format]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/publication-format.html
 [attr:ref-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/ref-type.html
 [attr:rid]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/rid.html
 [attr:subj-group-type]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/attribute/subj-group-type.html
@@ -372,7 +395,6 @@ Required metadata values:
 [elem:license]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/license.html
 [elem:notes]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/notes.html
 [elem:permissions]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/permissions.html
-[elem:pub-date]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html
 [elem:publisher-loc]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-loc.html
 [elem:publisher-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/publisher-name.html
 [elem:string-name]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/string-name.html
@@ -384,7 +406,9 @@ Required metadata values:
 [`<addr-line>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/addr-line.html
 [`<aff>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/aff.html
 [`<city>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/city.html
+[`<contrib>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/contrib.html
 [`<country>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/country.html
 [`<institution-id>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-id.html
 [`<institution-wrap>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution-wrap.html
 [`<institution>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/institution.html
+[`<pub-date>`]: https://jats.nlm.nih.gov/publishing/tag-library/1.2/element/pub-date.html
diff --git a/doc/libraries.md b/doc/libraries.md
new file mode 100644
index 000000000..397dff83d
--- /dev/null
+++ b/doc/libraries.md
@@ -0,0 +1,63 @@
+---
+title: The pandoc family of libraries
+author: John MacFarlane
+---
+
+The following Haskell libraries have been developed to support
+pandoc:
+
+[skylighting-core] and [skylighting]
+:   Syntax highlighting engine supporting over 140 languages.
+
+[citeproc]
+:   Citation processing using CSL stylesheets.
+
+[texmath]
+:   Conversion of math between tex, Word equation, MathML, and GNU eqn.
+
+[unicode-collation]
+:   Proper Unicode collation (sorting).
+
+[doclayout]
+:   Combinators for laying out a textual document, with support
+    for line wrapping, tabular layout, and more.
+
+[doctemplates]
+:   Supports pandoc's templates.
+
+[commonmark], [commonmark-extensions], and [commonmark-pandoc]
+:   Efficient, standards-compliant parser for commonmark and extensions.
+
+[ipynb]
+:   Representation of Jupyter notebooks and conversion to and
+    from JSON.
+
+[zip-archive]
+:   A pure zip file creator and extractor, used by pandoc for
+    docx, ODT, and EPUB.
+
+[rfc5051]
+:   Simple unicode collation (used for citation sorting).
+
+[emojis]
+:   Conversion between emoji characters and aliases.
+
+[jira-wiki-markup]
+:   Support for parsing Jira wiki syntax.
+
+[skylighting]: https://hackage.haskell.org/package/skylighting
+[skylighting-core]: https://hackage.haskell.org/package/skylighting-core
+[citeproc]: https://hackage.haskell.org/package/citeproc
+[texmath]: https://hackage.haskell.org/package/texmath
+[doclayout]: https://hackage.haskell.org/package/doclayout
+[doctemplates]: https://hackage.haskell.org/package/doctemplates
+[commonmark]: https://hackage.haskell.org/package/commonmark
+[commonmark-extensions]: https://hackage.haskell.org/package/commonmark-extensions
+[commonmark-pandoc]: https://hackage.haskell.org/package/commonmark-pandoc
+[ipynb]: https://hackage.haskell.org/package/ipynb
+[zip-archive]: https://hackage.haskell.org/package/zip-archive
+[rfc5051]: https://hackage.haskell.org/package/rfc5051
+[emojis]: https://hackage.haskell.org/package/emojis
+[jira-wiki-markup]: https://hackage.haskell.org/package/jira-wiki-markup
+[unicode-collation]: https://hackage.haskell.org/package/unicode-collation
+
diff --git a/doc/lua-filters.md b/doc/lua-filters.md
index b715b8218..e2a65fe1e 100644
--- a/doc/lua-filters.md
+++ b/doc/lua-filters.md
@@ -109,7 +109,7 @@ element filtering function. In other words, filter entries will
 be called for each corresponding element in the document,
 getting the respective element as input.
 
-The return of a filter function must one of the following:
+The return of a filter function must be one of the following:
 
 -   nil: this means that the object should remain unchanged.
 -   a pandoc object: this must be of the same type as the input
@@ -1513,7 +1513,7 @@ with the [`pandoc.Attr`](#pandoc.attr) constructor. For
 convenience, it is usually not necessary to construct the value
 directly if it is part of an element, and it is sufficient to
 pass an HTML-like table. E.g., to create a span with identifier
-"text" and classes "a" and "b", on can write:
+"text" and classes "a" and "b", one can write:
 
     local span = pandoc.Span('text', {id = 'text', class = 'a b'})
 
@@ -3084,7 +3084,8 @@ Clear-out the media bag, deleting all items.
 
 `insert (filepath, mime_type, contents)`
 
-Adds a new entry to pandoc's media bag.
+Adds a new entry to pandoc's media bag. Replaces any existing
+mediabag entry with the same `filepath`.
 
 Parameters:
 
@@ -3092,7 +3093,7 @@ Parameters:
 :   filename and path relative to the output folder.
 
 `mime_type`:
-:   the file's MIME type
+:   the file's MIME type; use `nil` if unknown or unavailable.
 
 `contents`:
 :   the binary contents of the file.
@@ -3176,12 +3177,22 @@ Usage:
 
 ### fetch {#pandoc.mediabag.fetch}
 
-`fetch (source, base_url)`
+`fetch (source)`
 
 Fetches the given source from a URL or local file. Returns two
 values: the contents of the file and the MIME type (or an empty
 string).
 
+The function will first try to retrieve `source` from the
+mediabag; if that fails, it will try to download it or read it
+from the local file system while respecting pandoc's "resource
+path" setting.
+
+Parameters:
+
+`source`:
+:   path to a resource; either a local file path or URI
+
 Returns:
 
 -   the entries MIME type, or nil if the file was not found.
@@ -3190,11 +3201,11 @@ Returns:
 Usage:
 
     local diagram_url = "https://pandoc.org/diagram.jpg"
-    local mt, contents = pandoc.mediabag.fetch(diagram_url, ".")
+    local mt, contents = pandoc.mediabag.fetch(diagram_url)
 
 # Module pandoc.List
 
-The this module defines pandoc's list type. It comes with useful
+This module defines pandoc's list type. It comes with useful
 methods and convenience functions.
 
 ## Constructor
@@ -3376,6 +3387,181 @@ methods and convenience functions.
     `comp`:
     :   Comparison function as described above.
 
+# Module pandoc.path
+
+Module for file path manipulations.
+
+## Static Fields {#pandoc.path-fields}
+
+### separator {#pandoc.path.separator}
+
+The character that separates directories.
+
+### search_path_separator {#pandoc.path.search_path_separator}
+
+The character that is used to separate the entries in the `PATH`
+environment variable.
+
+## Functions {#pandoc.path-functions}
+
+### directory (filepath) {#pandoc.path.directory}
+
+Gets the directory name, i.e., removes the last directory
+separator and everything after from the given path.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   The filepath up to the last directory separator. (string)
+
+### filename (filepath) {#pandoc.path.filename}
+
+Get the file name.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   File name part of the input path. (string)
+
+### is_absolute (filepath) {#pandoc.path.is_absolute}
+
+Checks whether a path is absolute, i.e. not fixed to a root.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   `true` iff `filepath` is an absolute path, `false` otherwise.
+    (boolean)
+
+### is_relative (filepath) {#pandoc.path.is_relative}
+
+Checks whether a path is relative or fixed to a root.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   `true` iff `filepath` is a relative path, `false` otherwise.
+    (boolean)
+
+### join (filepaths) {#pandoc.path.join}
+
+Join path elements back together by the directory separator.
+
+Parameters:
+
+filepaths
+:   path components (list of strings)
+
+Returns:
+
+-   The joined path. (string)
+
+### make_relative (path, root[, unsafe]) {#pandoc.path.make_relative}
+
+Contract a filename, based on a relative path. Note that the
+resulting path will usually not introduce `..` paths, as the
+presence of symlinks means `../b` may not reach `a/b` if it starts
+from `a/c`. For a worked example see [this blog
+post](https://neilmitchell.blogspot.co.uk/2015/10/filepaths-are-subtle-symlinks-are-hard.html).
+
+Set `unsafe` to a truthy value to a allow `..` in paths.
+
+Parameters:
+
+path
+:   path to be made relative (string)
+
+root
+:   root path (string)
+
+unsafe
+:   whether to allow `..` in the result. (boolean)
+
+Returns:
+
+-   contracted filename (string)
+
+### normalize (filepath) {#pandoc.path.normalize}
+
+Normalizes a path.
+
+-   `//` makes sense only as part of a (Windows) network drive;
+    elsewhere, multiple slashes are reduced to a single
+    `path.separator` (platform dependent).
+-   `/` becomes `path.separator` (platform dependent)
+-   `./` -\> ''
+-   an empty path becomes `.`
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   The normalized path. (string)
+
+### split (filepath) {#pandoc.path.split}
+
+Splits a path by the directory separator.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   List of all path components. (list of strings)
+
+### split_extension (filepath) {#pandoc.path.split_extension}
+
+Splits the last extension from a file path and returns the parts. The
+extension, if present, includes the leading separator; if the path has
+no extension, then the empty string is returned as the extension.
+
+Parameters:
+
+filepath
+:   path (string)
+
+Returns:
+
+-   filepath without extension (string)
+
+-   extension or empty string (string)
+
+### split_search_path (search_path) {#pandoc.path.split_search_path}
+
+Takes a string and splits it on the `search_path_separator` character.
+Blank items are ignored on Windows, and converted to `.` on Posix. On
+Windows path elements are stripped of quotes.
+
+Parameters:
+
+search_path
+:   platform-specific search path (string)
+
+Returns:
+
+-   list of directories in search path (list of strings)
+
 # Module pandoc.system
 
 Access to system information and functionality.
diff --git a/doc/org.md b/doc/org.md
index 522ccc23c..edaaa8c50 100644
--- a/doc/org.md
+++ b/doc/org.md
@@ -25,8 +25,7 @@ The following export keywords are supported:
 - LANGUAGE: document language; included as plain-text metadata
   field `lang`. The value should be a [BCP47 language tag].
 
-- SELECT_TAGS: tags which select a tree for export. Currently
-  *unsupported*.
+- SELECT_TAGS: tags which select a tree for export.
 
 - EXCLUDE\_TAGS: tags which prevent a subtree from being
   exported. Fully supported.
@@ -37,6 +36,21 @@ The following export keywords are supported:
   defaults to stdout unless a target has to be given as a command
   line option.
 
+::: {.alert .alert-info}
+Pandoc tries to be compatible with org-mode when exporting an org document. If
+you find some behavior confusing, please do refer to org-mode
+[Export-Settings](https://orgmode.org/manual/Export-Settings.html)
+documentation. For example, a common confusion
+([#3214](https://github.com/jgm/pandoc/issues/3214 "Problem with headers lower
+then 3 in org-mode reader"), [#5169](https://github.com/jgm/pandoc/issues/5169
+"org mode headings past level three converted to numbered outline list"),
+[#6145](https://github.com/jgm/pandoc/issues/6145 "Headers 4 levels deep render
+differently"), [#7236](https://github.com/jgm/pandoc/issues/7236 "In Org mode,
+Header with level > 3 are not recognized as headers")) is treatment of headers
+with level > 3 differently because org-mode sets `org-export-headline-levels`
+(configurable with `#+OPTIONS: H:3`) to 3 by default.
+:::
+
 [BCP47 language tag]: https://tools.ietf.org/html/bcp47
 
 Format-specific options
diff --git a/doc/using-the-pandoc-api.md b/doc/using-the-pandoc-api.md
index df9380313..d44e82e9b 100644
--- a/doc/using-the-pandoc-api.md
+++ b/doc/using-the-pandoc-api.md
@@ -14,7 +14,7 @@ and types is available at
 Pandoc is structured as a set of *readers*, which translate
 various input formats into an abstract syntax tree (the
 Pandoc AST) representing a structured document, and a set of
-*writers*, which render this AST into various input formats.
+*writers*, which render this AST into various output formats.
 Pictorially:
 
 ```
@@ -90,8 +90,14 @@ Some notes:
 Let's look at the types of `readMarkdown` and `writeRST`:
 
 ```haskell
-readMarkdown :: PandocMonad m => ReaderOptions -> Text -> m Pandoc
-writeRST :: PandocMonad m => WriterOptions -> Pandoc -> m Text
+readMarkdown :: (PandocMonad m, ToSources a)
+             => ReaderOptions
+             -> a
+             -> m Pandoc
+writeRST     :: PandocMonad m
+             => WriterOptions
+             -> Pandoc
+             -> m Text
 ```
 
 The `PandocMonad m =>` part is a typeclass constraint.
@@ -133,7 +139,7 @@ report :: PandocMonad m => LogMessage -> m ()
 -- | Fetch an image or other item from the local filesystem or the net.
 -- Returns raw content and maybe mime type.
 fetchItem :: PandocMonad m
-          => String
+          => Text
           -> m (B.ByteString, Maybe MimeType)
 
 -- Set the resource path searched by 'fetchItem'.
@@ -155,6 +161,13 @@ Note that `PandocIO` is an instance of `MonadIO`, so you can
 use `liftIO` to perform arbitrary IO operations inside a pandoc
 conversion chain.
 
+`readMarkdown` is polymorphic in its second argument, which
+can be any type that is an instance of the `ToSources`
+typeclass.  You can use `Text`, as in the example above.
+But you can also use `[(FilePath, Text)]`, if the input comes
+from multiple files and you want to track source positions
+accurately.
+
 # Options
 
 The first argument of each reader or writer is for
@@ -200,8 +213,8 @@ of the Monoid typeclass and can easily be concatenated:
 import Text.Pandoc.Builder
 
 mydoc :: Pandoc
-mydoc = doc $ header 1 (text "Hello!")
-           <> para (emph (text "hello world") <> text ".")
+mydoc = doc $ header 1 (text (T.pack "Hello!"))
+           <> para (emph (text (T.pack "hello world")) <> text (T.pack "."))
 
 main :: IO ()
 main = print mydoc
@@ -248,16 +261,16 @@ import qualified Data.Text as T
 import Data.List (intersperse)
 
 data Station = Station{
-    address        :: String
-  , name           :: String
-  , cardsAccepted  :: [String]
+    address        :: T.Text
+  , name           :: T.Text
+  , cardsAccepted  :: [T.Text]
   } deriving Show
 
 instance FromJSON Station where
     parseJSON (Object v) = Station <$>
        v .: "street_address" <*>
        v .: "station_name" <*>
-       (words <$> (v .:? "cards_accepted" .!= ""))
+       (T.words <$> (v .:? "cards_accepted" .!= ""))
     parseJSON _          = mzero
 
 createLetter :: [Station] -> Pandoc
@@ -315,7 +328,7 @@ users to override the system defaults.  If you want to disable
 this behavior, use `setUserDataDir Nothing`.
 
 To render a template, use `renderTemplate'`, which takes two
-arguments, a template (String) and a context (any instance
+arguments, a template (Text) and a context (any instance
 of ToJSON).  If you want to create a context from the metadata
 part of a Pandoc document, use `metaToJSON'` from
 [Text.Pandoc.Writers.Shared].  If you also want to incorporate
@@ -413,7 +426,7 @@ concatenated together.  Here's an example that returns a
 list of the URLs linked to in a document:
 
 ```haskell
-listURLs :: Pandoc -> [String]
+listURLs :: Pandoc -> [Text]
 listURLs = query urls
   where urls (Link _ _ (src, _)) = [src]
         urls _                   = []