Update paru for use with pandoc 3.x

README.md

@@ -2,22 +2,17 @@
 
 ## Contents
 
--   <a href="#introduction" id="toc-introduction">Introduction</a>
-    -   <a href="#licence" id="toc-licence">Licence</a>
-    -   <a href="#acknowledgements"
-        id="toc-acknowledgements">Acknowledgements</a>
-    -   <a href="#installation" id="toc-installation">Installation</a>
--   <a href="#paru-says-hello-to-pandoc"
-    id="toc-paru-says-hello-to-pandoc">Paru says hello to pandoc</a>
--   <a href="#writing-and-using-pandoc-filters-with-paru"
-    id="toc-writing-and-using-pandoc-filters-with-paru">Writing and using
-    pandoc filters with paru</a>
--   <a href="#documentation" id="toc-documentation">Documentation</a>
-    -   <a href="#manual" id="toc-manual">Manual</a>
-    -   <a href="#api-documentation" id="toc-api-documentation">API
-        documentation</a>
-    -   <a href="#frequently-asked-questions"
-        id="toc-frequently-asked-questions">Frequently asked questions</a>
+- [Introduction](#introduction)
+  - [Licence](#licence)
+  - [Acknowledgements](#acknowledgements)
+  - [Installation](#installation)
+- [Paru says hello to pandoc](#paru-says-hello-to-pandoc)
+- [Writing and using pandoc filters with
+  paru](#writing-and-using-pandoc-filters-with-paru)
+- [Documentation](#documentation)
+  - [Manual](#manual)
+  - [API documentation](#api-documentation)
+  - [Frequently asked questions](#frequently-asked-questions)
 
 [![Gem
 Version](https://badge.fury.io/rb/paru.svg)](https://badge.fury.io/rb/paru)
@@ -39,6 +34,10 @@ real-world use case: generating the manual!
 See also the [paru API
 documentation](https://heerdebeer.org/Software/markdown/paru/documentation/api-doc/).
 
+**Note** If you’re using pandoc 3, use paru version 1.1.x or higher;
+paru 1.0.x doesn’t work with pandoc 3. If you’re still using pandoc
+version 2, use paru version 1.0.x instead.
+
 This README is a brief overview of paru’s features and usages.
 
 ### Licence
@@ -55,11 +54,11 @@ patches, bug reports, fixes, and suggestions. With your help paru is
 growing beyond a simple tool for personal use into a useful addition to
 the pandoc ecosystem.
 
--   [Ian](https://github.com/iandol)
--   [Jonathan Raphaelson](https://github.com/lygaret)
--   [Michael Kussmaul](https://github.com/kusmi)
--   [Xavier Belanche Alonso](https://github.com/xbelanch)
--   [Robert Riemann](https://github.com/rriemann)
+- [Ian](https://github.com/iandol)
+- [Jonathan Raphaelson](https://github.com/lygaret)
+- [Michael Kussmaul](https://github.com/kusmi)
+- [Xavier Belanche Alonso](https://github.com/xbelanch)
+- [Robert Riemann](https://github.com/rriemann)
 
 ### Installation
 
@@ -70,12 +69,12 @@ gem install paru
 ```
 
 You can also download the latest gem
-[paru-1.0.3.gem](https://github.com/htdebeer/paru/blob/master/releases/paru-1.0.3.gem)
+[paru-1.1.0.gem](https://github.com/htdebeer/paru/blob/master/releases/paru-1.1.0.gem)
 and install it by:
 
 ``` bash
 cd /directory/you/downloaded/the/gem/to
-gem install paru-1.0.3.gem
+gem install paru-1.1.0.gem
 ```
 
 Paru, obviously, requires pandoc. See
@@ -251,30 +250,30 @@ Feel free to ask me a question: [send me an
 email](mailto:Huub@heerdebeer.org) or submit a new
 [issue](https://github.com/htdebeer/paru/issues) if you’ve found a bug!
 
--   *I get an error like “Erro: JSON parse error: Error in $:
-    Incompatible API versions: encoded with \[1,20\] but attempted to
-    decode with \[1,21\].”*
-
-    The versions of pandoc and paru you are using are incompatible.
-    Please install the latest versions of pandoc and paru.
-
-    Why does this happen? Internally pandoc uses
-    [pandoc-types](https://hackage.haskell.org/package/pandoc-types) to
-    represent documents its converts and filters. Documents represented
-    by one version of pandoc-types are slightly incompatible with
-    documents represented by another version of pandoc-types. This also
-    means that filters written in paru for one version of pandoc-types
-    are not guaranteed to work on documents represented by another
-    version of pandoc-types. As a result, not all paru versions work
-    together with all pandoc versions.
-
-    As a general rule: Use the latest versions of pandoc and paru.
-
--   *I get an error like “‘values_at’: no implicit conversion of String
-    into Integer (TypeError) from lib/paru/filter/document.rb:54:in
-    ‘from_JSON’”*
-
-    The most likely cause is that you’re using an old version of Pandoc.
-    Paru version 0.2.x only supports pandoc version 1.18 and up. In
-    pandoc version 1.18 there was a breaking API change in the way
-    filters worked. Please upgrade your pandoc installation.
+- *I get an error like “Erro: JSON parse error: Error in \$:
+  Incompatible API versions: encoded with \[1,20\] but attempted to
+  decode with \[1,21\].”*
+
+  The versions of pandoc and paru you are using are incompatible. Please
+  install the latest versions of pandoc and paru.
+
+  Why does this happen? Internally pandoc uses
+  [pandoc-types](https://hackage.haskell.org/package/pandoc-types) to
+  represent documents its converts and filters. Documents represented by
+  one version of pandoc-types are slightly incompatible with documents
+  represented by another version of pandoc-types. This also means that
+  filters written in paru for one version of pandoc-types are not
+  guaranteed to work on documents represented by another version of
+  pandoc-types. As a result, not all paru versions work together with
+  all pandoc versions.
+
+  As a general rule: Use the latest versions of pandoc and paru.
+
+- *I get an error like “‘values_at’: no implicit conversion of String
+  into Integer (TypeError) from lib/paru/filter/document.rb:54:in
+  ‘from_JSON’”*
+
+  The most likely cause is that you’re using an old version of Pandoc.
+  Paru version 0.2.x only supports pandoc version 1.18 and up. In pandoc
+  version 1.18 there was a breaking API change in the way filters
+  worked. Please upgrade your pandoc installation.

documentation/introduction.md

@@ -12,3 +12,7 @@ case: generating the manual!
 
 See also the [paru API
 documentation](https://heerdebeer.org/Software/markdown/paru/documentation/api-doc/).
+
+**Note** If you're using pandoc 3, use paru version 1.1.x or higher; paru
+1.0.x doesn't work with pandoc 3. If you're still using pandoc version 2, use
+paru version 1.0.x instead. 

index.md

@@ -26,6 +26,10 @@ real-world use case: generating the manual!
 See also the [paru API
 documentation](https://heerdebeer.org/Software/markdown/paru/documentation/api-doc/).
 
+**Note** If you're using pandoc 3, use paru version 1.1.x or higher;
+paru 1.0.x doesn't work with pandoc 3. If you're still using pandoc
+version 2, use paru version 1.0.x instead.
+
 ## 1.1 Licence
 
 Paru is [free sofware](https://www.gnu.org/philosophy/free-sw.en.html);
@@ -42,12 +46,12 @@ gem install paru
 ```
 
 You can also download the latest gem
-[paru-1.0.3.gem](https://github.com/htdebeer/paru/blob/master/releases/paru-1.0.3.gem)
+[paru-1.1.0.gem](https://github.com/htdebeer/paru/blob/master/releases/paru-1.1.0.gem)
 and install it by:
 
 ``` bash
 cd /directory/you/downloaded/the/gem/to
-gem install paru-1.0.3.gem
+gem install paru-1.1.0.gem
 ```
 
 Paru, obviously, requires pandoc. See

lib/paru/filter.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016, 2017, 2022 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017, 2022, 2023 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -22,7 +22,7 @@
 
 module Paru
     # Paru filter is a wrapper around pandoc's JSON api, which is based on
-    # {pandoc-types}[https://hackage.haskell.org/package/pandoc-types-1.17.0.4/docs/Text-Pandoc-Definition.html].
+    # {pandoc-types}[https://hackage.haskell.org/package/pandoc-types-1.23/docs/Text-Pandoc-Definition.html].
     # Pandoc treats block elements and inline elements differently. 
     #
     # Pandoc's block elements are:
@@ -44,6 +44,7 @@ module Paru
         "TableBody",
         "Row",
         "Cell",
+        "Figure",
         "Caption",
         "Div",
         "Null"

lib/paru/filter/caption.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2020 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2020, 2023 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,12 +17,15 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 #++
 require_relative "./block.rb"
+require_relative "./inner_markdown.rb"
 require_relative "./short_caption.rb"
 
 module Paru
     module PandocFilter
-        # A table's caption, can contain an optional short caption
+        # A table or figure's caption, can contain an optional short caption
         class Caption < Block
+            include InnerMarkdown
+
             attr_accessor :short  
 
             # Create a new Caption based on the contents

lib/paru/filter/document.rb

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016, 2017, 2020 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017, 2020, 2023 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -36,7 +36,7 @@ module PandocFilter
 
         # The current pandoc type version
         # @see https://hackage.haskell.org/package/pandoc-types
-        CURRENT_PANDOC_VERSION = [1, 22]
+        CURRENT_PANDOC_VERSION = [1, 23]
 
         # Each file that is being filtered by pandoc is represented by a root
         # Document. It is the root node of the AST of the document in the file.

lib/paru/filter/figure.rb

@@ -0,0 +1,65 @@
+#--
+# Copyright 2023 Huub de Beer <Huub@heerdebeer.org>
+#
+# This file is part of Paru
+#
+# Paru is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# Paru is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with Paru.  If not, see <http://www.gnu.org/licenses/>.
+#++
+require_relative "./block.rb"
+require_relative "./attr.rb"
+require_relative "./caption.rb"
+require_relative "./inner_markdown.rb"
+
+module Paru
+    module PandocFilter
+        # A Figure node consisting of an attribute object, a caption, and a list of Block nodes.
+        class Figure < Block
+            include InnerMarkdown
+
+            # A Figure node has an attribute object
+            #
+            # @!attribute attr
+            #   @return [Attr]
+            #
+            # @!attribute caption
+            #   @return Caption
+            attr_accessor :attr, :caption
+
+            # Create a new Figure node based on the contents
+            #
+            # @param contents [Array] 
+            def initialize(contents)
+                @attr = Attr.new contents[0]
+                @caption = Caption.new contents[1]
+                super contents[2]
+            end
+
+            # Create an AST representation of this Figure node.
+            def ast_contents()
+                [
+                    @attr.to_ast,
+                    @caption.to_ast,
+                    super
+                ]
+            end
+
+            # Has this Figure node Blocks as children?
+            #
+            # @return [Boolean] true
+            def has_block?
+                true
+            end
+        end
+    end
+end

lib/paru/filter/node.rb

@@ -68,6 +68,7 @@ class Node
             require_relative './table_foot.rb'
             require_relative './row.rb'
             require_relative './cell.rb'
+            require_relative './figure.rb'
 
             # Inline level nodes
             require_relative './cite.rb'
@@ -386,7 +387,7 @@ def markdown=(markdown)
                     # Only using first block node (paragraph?)
                     if is_inline?
                         temp_doc = temp_doc.children.first
-                        
+
                         if not temp_doc.children.all? {|node| node.is_inline?}
                             raise Error.new "Cannot replace the inline level node represented by '#{self.markdown}' with markdown that converts to block level nodes: '#{markdown}'."
                         end

lib/paru/pandoc_options.yaml

@@ -1,5 +1,5 @@
 #--
-# Copyright 2015, 2016, 2017, 2022 Huub de Beer <Huub@heerdebeer.org>
+# Copyright 2015, 2016, 2017, 2022, 2023 Huub de Beer <Huub@heerdebeer.org>
 #
 # This file is part of Paru
 #
@@ -17,7 +17,7 @@
 # along with Paru.  If not, see <http://www.gnu.org/licenses/>.
 # See http://pandoc.org/README.html for an overview of all options
 #++
-# In order as listed on http://pandoc.org/MANUAL.html (version 2)
+# In order as listed on http://pandoc.org/MANUAL.html (version 3)
 #####
 # General options:
 ##### 
@@ -96,6 +96,7 @@ ascii:                      true
 reference_links:            true
 reference_location:         "block"
 markdown_headings:          "atx"
+list_tables:                true
 atx_headers:                true
 top_level_division:         "section"
 number_sections:            true
@@ -109,7 +110,10 @@ id_prefix:                  ""
 title_prefix:               ""
 css:                        [""]
 reference_doc:              ""
+split_level:                1
+chunk_template:             ""
 epub_cover_image:           ""
+epub_title_page:            true
 epub_metadata:              ""
 epub_embed_font:            ""
 epub_chapter_level:         1

paru.gemspec

@@ -4,7 +4,7 @@ Gem::Specification.new do |s|
   s.name = 'paru'
   s.license = 'GPL-3.0'
   s.version = Paru::VERSION.join "."
-  s.date = '2023-02-04'
+  s.date = '2023-02-08'
   s.authors = ['Huub de Beer']
   s.email = 'Huub@heerdebeer.org'
 

test/pandoc_input/block/Figure.md

@@ -0,0 +1,4 @@
+Pandoc 3.0 added the concept of "complex figure":
+
+![This is a caption](path/some/img.png)
+

test/pandoc_input/figures.md

@@ -1,19 +1,14 @@
 This is a test file for the filter `number_figures.rb`. That filter numbers
 all figures in a file consecutively. Thus, the following four figures are
-numbered 1—4:
+numbered 1---4:
 
-![This is the first](image.png)
-
-![This is the second](image.png)
-
-![This is the third](image.png)
-
-![This is the fourth](image.png)
+First, ![This is the first](image.png), then ![This is the second](image.png),
+followed by ![This is the third](image.png) and finally, ![This is the
+fourth](image.png).
 
 It does not matter if there is text in between or not. Although without the
 newlines in between the figures they are placed on one line when converting
-back to markdown again. 
-
-The fifth figure that follows is numbered correctly as well:
+back to markdown again.
 
-![This is the fifth](image.png)
+The fifth figure that follows is numbered correctly as well: ![This is the
+fifth](image.png)