Update to paru, the Ruby wrapper around pandoc and filters. Now with improved documentation!

Update to paru, the Ruby wrapper around pandoc and filters. Now with improved documentation!

[Huub de Beer]

Dear all,

today I released version 0.2.1 of paru, the ruby wrapper around pandoc and 
filters. This release is compatible with pandoc version >= 1.18 and contains 
also some small bug fixes. Furthermore, I have updated the documentation 
extensively. Automating the use of pandoc with Ruby or writing pandoc filters 
in Ruby was never easier!

See https://heerdebeer.org/Software/markdown/paru/ for more information.

To wet you appetite for writing pandoc filters in Ruby, I give two canonical 
examples here:

1. Inserting markdown files from within other markdown files:

    #!/usr/bin/env ruby
    require "paru/filter"
   
    Paru::Filter.run do 
      with "Para" do |paragraph|
        if paragraph.inner_markdown.lines.length == 1
          command, path = paragraph.inner_markdown.strip.split " "
          if command == "::paru::insert"
            markdown = File.read path.gsub(/\\_/, "_")
            paragraph.outer_markdown = markdown
          end
        end
      end
    end

2. Numbering chapters, sections, and figures in a markdown files:

    #!/usr/bin/env ruby
    require "paru/filter"

    current_chapter = 0
    current_section = 0
    current_figure = 0

    Paru::Filter.run do
      with "Header" do |header|
        if header.level == 1 
          current_chapter += 1
          current_figure = 0
          current_section = 0

          header.inner_markdown = "Chapter #{current_chapter}. 
#{header.inner_markdown}"
        end

        if header.level == 2
          current_section += 1
          header.inner_markdown = 
            "#{current_chapter}.#{current_section} #{header.inner_markdown}"
        end
      end

      with "Header + Image" do |image|
        current_figure += 1
        image.inner_markdown = 
          "Figure #{current_chapter}.#{current_figure} 
#{image.inner_markdown}"
      end
    end

The methods inner_markdown and outer_markdown are quite useful when writing 
filters. Combined with the power of selectors such as "+" (follows), writing a 
filter is quite straightforward,

have fun with pandoc!

with kind regards
-- 
Huub de Beer