Add complete Pandoc 3.1.1 support

README.md

@@ -1,5 +1,5 @@
 
-Pandoc – 🐍 Python Library
+The Pandoc Python Library (PPL)
 ================================================================================
 
 ![Python](https://img.shields.io/pypi/pyversions/pandoc.svg)
@@ -17,27 +17,28 @@ Pandoc – 🐍 Python Library
 🚀 Getting started
 --------------------------------------------------------------------------------
 
-[Pandoc] – the general markup converter (and Haskell library) written by 
-[John MacFarlane] – needs to be available. 
-You may follow the official [installation instructions][pandoc-install] 
-or use [conda]:
+Install [Pandoc] first, for example with [conda]:
 
     $ conda install -c conda-forge pandoc
 
-Then, install the latest stable version of the pandoc Python library with pip:
+Then, install the Pandoc Python Library with pip:
 
     $ pip install --upgrade pandoc
 
 
 🌌 Overview 
 --------------------------------------------------------------------------------
 
-This project brings [Pandoc]'s data model for markdown documents to Python:
+[Pandoc] is the awesome open-source command-line tool that converts documents 
+from one format to another. The project was initiated by [John MacFarlane]; 
+under the hood, it's a [Haskell] library.
+
+The Pandoc Python Library (PPL) brings [Pandoc]'s document model to Python:
 
     $ echo "Hello world!" | python -m pandoc read 
     Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
 
-It can be used to analyze, create and transform documents, in Python :
+It can be used to analyze, create and transform documents, in Python:
 
     >>> import pandoc
     >>> text = "Hello world!"
@@ -56,7 +57,6 @@ It can be used to analyze, create and transform documents, in Python :
 
 For more information, refer to the  [📖 documentation][doc].
 
-
 [Pandoc]: https://pandoc.org/
 [John MacFarlane]: https://johnmacfarlane.net/
 [pandoc-install]: https://pandoc.org/installing.html

environment.yml

@@ -3,7 +3,7 @@ channels:
   - conda-forge
 dependencies:
   - python=3.10
-  - pandoc=2.19.2
+  - pandoc=3.1.1
   - plumbum
   - ply
   - pip
@@ -13,6 +13,6 @@ dependencies:
   - black
   - emoji
   - pip:
-    - strictyaml # conda version if 1.6.0 and doesn't solve https://github.com/crdoconnor/strictyaml/issues/151
-    - mkdocs
-    - mkdocs-material
+      - strictyaml # conda version if 1.6.0 and doesn't solve https://github.com/crdoconnor/strictyaml/issues/151
+      - mkdocs
+      - mkdocs-material==9.1.6

mkdocs.yml

@@ -1,4 +1,4 @@
-site_name: Pandoc (Python)
+site_name: Pandoc (Python Library)
 
 docs_dir: mkdocs
 
@@ -18,7 +18,7 @@ nav:
   - Changelog: changelog.md
   - "Labs 🧪": labs.md
 
-theme: "material" 
+theme: "material"
 
 markdown_extensions:
   - admonition
@@ -33,5 +33,3 @@ markdown_extensions:
 repo_name: "pandoc"
 repo_url: "https://github.com/boisgera/pandoc"
 edit_uri: edit/master/mkdocs/
-
-

mkdocs/api.md

@@ -351,8 +351,8 @@ from pandoc.types import *
     >>> config # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
     {'auto': True, 
      'path': ..., 
-     'version': '2.19.2', 
-     'pandoc_types_version': '1.22.2.1'}
+     'version': '3.1.1', 
+     'pandoc_types_version': '1.23'}
     ```
     To avoid this, call `pandoc.configure(...)` yourself beforehand.
     Alternatively, select manually your pandoc executable afterwards:
@@ -366,8 +366,8 @@ from pandoc.types import *
     >>> pandoc.configure(read=True) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
     {'auto': False, 
      'path': ..., 
-     'version': '2.19.2', 
-     'pandoc_types_version': '1.22.2.1'}    
+     'version': '3.1.1', 
+     'pandoc_types_version': '1.23'}    
     ```
 
     <h5>See also</h5>
@@ -505,13 +505,13 @@ from pandoc.types import *
           | Header(Int, Attr, [Inline])
           | HorizontalRule()
           | Table(Attr, Caption, [ColSpec], TableHead, [TableBody], TableFoot)
+          | Figure(Attr, Caption, [Block])
           | Div(Attr, [Block])
-          | Null()
     ```
 
     <h5>See also</h5>
 
-    <a href="#Attr"><code>Attr</code></a>, <a href="#BlockQuote"><code>BlockQuote</code></a>, <a href="#BulletList"><code>BulletList</code></a>, <a href="#Caption"><code>Caption</code></a>, <a href="#CodeBlock"><code>CodeBlock</code></a>, <a href="#ColSpec"><code>ColSpec</code></a>, <a href="#DefinitionList"><code>DefinitionList</code></a>, <a href="#Div"><code>Div</code></a>, <a href="#Format"><code>Format</code></a>, <a href="#Header"><code>Header</code></a>, <a href="#HorizontalRule"><code>HorizontalRule</code></a>, <a href="#Inline"><code>Inline</code></a>, <a href="#Int"><code>Int</code></a>, <a href="#LineBlock"><code>LineBlock</code></a>, <a href="#ListAttributes"><code>ListAttributes</code></a>, <a href="#Null"><code>Null</code></a>, <a href="#OrderedList"><code>OrderedList</code></a>, <a href="#Para"><code>Para</code></a>, <a href="#Plain"><code>Plain</code></a>, <a href="#RawBlock"><code>RawBlock</code></a>, <a href="#Table"><code>Table</code></a>, <a href="#TableBody"><code>TableBody</code></a>, <a href="#TableFoot"><code>TableFoot</code></a>, <a href="#TableHead"><code>TableHead</code></a>, <a href="#Text"><code>Text</code></a>.
+    <a href="#Attr"><code>Attr</code></a>, <a href="#BlockQuote"><code>BlockQuote</code></a>, <a href="#BulletList"><code>BulletList</code></a>, <a href="#Caption"><code>Caption</code></a>, <a href="#CodeBlock"><code>CodeBlock</code></a>, <a href="#ColSpec"><code>ColSpec</code></a>, <a href="#DefinitionList"><code>DefinitionList</code></a>, <a href="#Div"><code>Div</code></a>, <a href="#Figure"><code>Figure</code></a>, <a href="#Format"><code>Format</code></a>, <a href="#Header"><code>Header</code></a>, <a href="#HorizontalRule"><code>HorizontalRule</code></a>, <a href="#Inline"><code>Inline</code></a>, <a href="#Int"><code>Int</code></a>, <a href="#LineBlock"><code>LineBlock</code></a>, <a href="#ListAttributes"><code>ListAttributes</code></a>, <a href="#OrderedList"><code>OrderedList</code></a>, <a href="#Para"><code>Para</code></a>, <a href="#Plain"><code>Plain</code></a>, <a href="#RawBlock"><code>RawBlock</code></a>, <a href="#Table"><code>Table</code></a>, <a href="#TableBody"><code>TableBody</code></a>, <a href="#TableFoot"><code>TableFoot</code></a>, <a href="#TableHead"><code>TableHead</code></a>, <a href="#Text"><code>Text</code></a>.
 
 <div id="BlockQuote"></div>
 
@@ -898,6 +898,22 @@ from pandoc.types import *
 
 
 
+<div id="Figure"></div>
+
+??? note "`Figure`"
+
+    Concrete data type
+
+    <h5>Signature</h5>
+
+    ``` skip
+    Figure(Attr, Caption, [Block])
+    ```
+
+    <h5>See also</h5>
+
+    <a href="#Attr"><code>Attr</code></a>, <a href="#Block"><code>Block</code></a>, <a href="#Caption"><code>Caption</code></a>.
+
 <div id="Format"></div>
 
 ??? note "`Format`"
@@ -1350,20 +1366,6 @@ from pandoc.types import *
 
     <a href="#Block"><code>Block</code></a>.
 
-<div id="Null"></div>
-
-??? note "`Null`"
-
-    Concrete data type
-
-    <h5>Signature</h5>
-
-    ``` skip
-    Null()
-    ```
-
-
-
 <div id="OneParen"></div>
 
 ??? note "`OneParen`"

mkdocs/api.md.template

@@ -351,8 +351,8 @@ from pandoc.types import *
     >>> config # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
     {'auto': True, 
      'path': ..., 
-     'version': '2.19.2', 
-     'pandoc_types_version': '1.22.2.1'}
+     'version': '3.1.1', 
+     'pandoc_types_version': '1.23'}
     ```
     To avoid this, call `pandoc.configure(...)` yourself beforehand.
     Alternatively, select manually your pandoc executable afterwards:
@@ -366,8 +366,8 @@ from pandoc.types import *
     >>> pandoc.configure(read=True) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
     {'auto': False, 
      'path': ..., 
-     'version': '2.19.2', 
-     'pandoc_types_version': '1.22.2.1'}    
+     'version': '3.1.1', 
+     'pandoc_types_version': '1.23'}    
     ```
 
     <h5>See also</h5>

mkdocs/changelog.md

@@ -1,3 +1,7 @@
+### Version 2.4 (to be released)
+
+  - Add support for Pandoc 3.0.1, 3.1.0 and 3.1.1.
+
 ### Version 2.3 (11/23/2022)
 
   - If the version of Pandoc is not supported, dont throw an error but warn,
@@ -8,6 +12,5 @@
 
 ### Version 2.2 (04/20/2022)
 
-
   - Add support for Pandoc 2.18.
 

mkdocs/configuration.md

@@ -82,8 +82,8 @@ but returns a dictionary whose keys are `auto`, `path`,
 >>> pandoc.configure(read=True) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
 {'auto': True, 
  'path': ..., 
- 'version': '2.19.2', 
- 'pandoc_types_version': '1.22.2.1'}
+ 'version': '3.1.1', 
+ 'pandoc_types_version': '1.23'}
 ```
 
 The `read` option may be combined with other arguments, for example

mkdocs/cookbook.md

@@ -1015,8 +1015,8 @@ Block = ...
       | Header(Int, Attr, [Inline])
       ...
       | Table(Attr, Caption, [ColSpec], TableHead, [TableBody], TableFoot)
-      | Div(Attr, [Block])
       ...
+      | Div(Attr, [Block])
 ```
 
 So we need to target `Code`, `Link`, `Image`, `Span`, `Div`,`CodeBlock`,

mkdocs/document.md

@@ -163,8 +163,8 @@ Block = Plain([Inline])
       | Header(Int, Attr, [Inline])
       | HorizontalRule()
       | Table(Attr, Caption, [ColSpec], TableHead, [TableBody], TableFoot)
+      | Figure(Attr, Caption, [Block])
       | Div(Attr, [Block])
-      | Null()
 ```
 
 Each `"|"` symbol in the signature represents an alternative: blocks are 

mkdocs/getting-started.md

@@ -1,12 +1,13 @@
 Getting started
 ================================================================================
 
-The [Pandoc](https://pandoc.org/) command-line tool needs to be available. 
-You may follow [the official installation instructions](https://pandoc.org/installing.html)
-which are OS-dependent, or if you are a [conda](https://www.google.com/search?client=firefox-b-d&q=conda+python) user, do
+Install [Pandoc] first, for example with [conda]:
 
     $ conda install -c conda-forge pandoc
 
-Then, install the latest stable version of the pandoc Python library with pip:
+Then, install the Pandoc Python Library with pip:
 
     $ pip install --upgrade pandoc
+
+[Pandoc]: https://pandoc.org/
+[conda]: https://docs.conda.io

mkdocs/index.md

@@ -2,7 +2,11 @@
 Overview
 ================================================================================
 
-This project brings [Pandoc]'s data model for markdown documents to Python:
+[Pandoc] is the awesome open-source command-line tool that converts documents 
+from one format to another. The project was initiated by [John MacFarlane]; 
+under the hood, it's a [Haskell] library.
+
+The Pandoc Python Library (PPL) brings [Pandoc]'s document model to Python:
 
     $ echo "Hello world!" | python -m pandoc read 
     Pandoc(Meta({}), [Para([Str('Hello'), Space(), Str('world!')])])
@@ -26,19 +30,18 @@ Para([Str('Hello'), Space(), Str('world!')])
 Hello Python!
 ```
 
-[Pandoc] is the general markup converter (and Haskell library) written by [John MacFarlane].
 
 
 [Pandoc]: http://pandoc.org/
 [John MacFarlane]: http://johnmacfarlane.net/
 [Haskell]: https://www.haskell.org/
 [Python]: https://www.python.org/
-[TPD]: https://hackage.haskell.org/package/pandoc-types-1.20/docs/Text-Pandoc-Definition.html
+[TPD]: https://hackage.haskell.org/package/pandoc-types-1.23/docs/Text-Pandoc-Definition.html
 
 !!! warning
     This documentation is dedicated to the [latest version of the project
     available on github](https://github.com/boisgera/pandoc). 
-    It is automatically tested with Python 3.10 against pandoc 2.19.2.
+    It is automatically tested with Python 3.10 against pandoc 2.1.1.
     At the moment I am writing this,
-    [the latest release of pandoc](https://pandoc.org/releases.html) 
-    is pandoc 3.0.1.
+    [the latest release of pandoc for conda](https://anaconda.org/conda-forge/pandoc) 
+    is pandoc 3.1.1.

mkdocs/manual/manual.py

@@ -24,15 +24,17 @@
 )
 
 # ------------------------------------------------------------------------------
-URL = "https://raw.githubusercontent.com/jgm/pandoc/2.14.2/MANUAL.txt"
-# src = urlopen(URL).read().decode("utf-8")
-src = open("MANUAL-patched.txt").read()
+URL = "https://raw.githubusercontent.com/jgm/pandoc/3.1.1/MANUAL.txt"
+src = urlopen(URL).read().decode("utf-8")
+with open("MANUAL-3.1.1.txt", "tw", encoding="utf-8") as f:
+    f.write(src)
+# src = open("MANUAL-patched.txt").read()
 
 ### TODO: create and insert diff here?
 
 # Hack to avoid having the "links" header title repeated
 # ------------------------------------------------------------------------------
-src = src.replace("#### Links", "#### ???") # remove the links h4 title
+src = src.replace("#### Links", "#### ???")  # remove the links h4 title
 
 # Extract the "Pandoc's Markdown" section
 # ------------------------------------------------------------------------------
@@ -51,8 +53,11 @@
                     in_section = True
                     new_doc[1].append(header)
     else:
-        if isinstance(block, Header) and \
-            block[2] == [Str("Non-default"), Space(), Str("extensions")]:
+        if isinstance(block, Header) and block[2] == [
+            Str("Non-default"),
+            Space(),
+            Str("extensions"),
+        ]:
             in_section = False
             break
         else:
@@ -75,7 +80,7 @@
     list_of_blocks = []
     for term, definitions in definition_list[0]:
         # definitions is a list of list of blocks (several defs are possible)
-        assert len(definitions) == 1 # document-dependent
+        assert len(definitions) == 1  # document-dependent
         blocks = [Plain([Strong(term + [Str(".")])])] + definitions[0]
         list_of_blocks.append(blocks)
 
@@ -86,11 +91,12 @@
 locations = [
     path[-1]
     for elt, path in pandoc.iter(new_doc, path=True)
-    if isinstance(elt, CodeBlock) and "skip" not in elt[0][1] # classes
+    if isinstance(elt, CodeBlock) and "skip" not in elt[0][1]  # classes
 ]
 
+
 def indent(text, lvl=4):
-    return "\n".join(lvl*" " + line for line in text.splitlines)
+    return "\n".join(lvl * " " + line for line in text.splitlines)
 
 
 for holder, i in reversed(locations):
@@ -113,4 +119,4 @@ def indent(text, lvl=4):
 
 # ------------------------------------------------------------------------------
 
-pandoc.write(new_doc, "../mkdocs/markdown.md", format="markdown-raw_attribute")
+pandoc.write(new_doc, "../markdown.md", format="markdown-raw_attribute")