fix #113: Add filename to error message when reading metdata blocks fail

.gitignore

@@ -2,6 +2,7 @@
 ~*
 *.swp
 *.bak
+*.log
 
 documentation/api-doc
 .yardoc

Dockerfile

@@ -1,7 +1,7 @@
 FROM ruby:3.2
 ENV LANG C.UTF-8
 RUN apt-get update \
-  ; apt-get install -y --no-install-recommends wget \
+  ; apt-get install -y --no-install-recommends wget groff ghostscript \
   ; wget -q https://github.com/jgm/pandoc/releases/download/3.1.8/pandoc-3.1.8-1-amd64.deb \
   ; apt-get install ./pandoc-3.1.8-1-amd64.deb \
   ; useradd -ms /bin/bash pandocomatic-user

Gemfile

@@ -1,2 +1,2 @@
-source "https://rubygems.org"
+source 'https://rubygems.org'
 gemspec

README.md

@@ -3,11 +3,11 @@ Version](https://badge.fury.io/rb/pandocomatic.svg)](https://badge.fury.io/rb/pa
 
 # Pandocomatic—Automate the use of pandoc
 
-Pandocomatic is a tool to automate the use of
-[pandoc](https://pandoc.org/). With pandocomatic you can express common
-patterns of using pandoc for generating your documents. Applied to a
-directory, pandocomatic can act as a static site generator. For example,
-this manual is generated with pandocomatic!
+Pandocomatic automates the use of [pandoc](https://pandoc.org/). With
+pandocomatic you can express common patterns of using pandoc for
+generating your documents. Applied to a directory, pandocomatic acts as
+a static site generator. For example, this manual is generated with
+pandocomatic!
 
 Pandocomatic is [free
 software](https://www.gnu.org/philosophy/free-sw.en.html); pandocomatic
@@ -21,10 +21,6 @@ source code of pandocomatic in its
 [paru](https://github.com/htdebeer/paru), which is a wrapper around
 pandoc.
 
-**Note.** If you’re using pandoc 3, use pandocomatic version 1.1.x or
-higher; pandocomatic 1.0.x doesn’t work with pandoc 3. If you’re still
-using pandoc version 2, use pandocomatic version 1.0.x instead.
-
 **Note.** As I am a GNU/Linux user, I do not officially support other
 operating systems like Mac OSX or Windows. Fixes and patches for those
 operating systems are welcome.
@@ -157,12 +153,12 @@ guide](https://pandoc.org/installing.html) for more information about
 installing pandoc.
 
 You can also download the latest gem,
-[pandocomatic-1.1.0](https://github.com/htdebeer/pandocomatic/blob/master/releases/pandocomatic-1.1.0.gem),
+[pandocomatic-1.1.1](https://github.com/htdebeer/pandocomatic/blob/master/releases/pandocomatic-1.1.1.gem),
 from Github and install it manually as follows:
 
 ``` bash
 cd /directory/you/downloaded/the/gem/to
-gem install pandocomatic-1.1.0.gem
+gem install pandocomatic-1.1.1.gem
 ```
 
 ## Examples

Rakefile

@@ -1,13 +1,13 @@
-require "rake/testtask"
-require "rubocop/rake_task"
-require "yard"
+require 'rake/testtask'
+require 'rubocop/rake_task'
+require 'yard'
 
 Rake::TestTask.new do |t|
-    t.libs << "lib"
-    t.libs << "lib/pandocomatic"
-    t.test_files = FileList["test/test_helper.rb", "test/unit/*.rb", "test/spec/*.rb"]
-    t.warning = false
-    t.verbose = true
+  t.libs << 'lib'
+  t.libs << 'lib/pandocomatic'
+  t.test_files = FileList['test/test_helper.rb', 'test/unit/*.rb', 'test/spec/*.rb']
+  t.warning = false
+  t.verbose = true
 end
 
 RuboCop::RakeTask.new(:rubocop) do |t|
@@ -16,24 +16,24 @@ RuboCop::RakeTask.new(:rubocop) do |t|
 end
 
 YARD::Rake::YardocTask.new do |t|
-    t.files = ['lib/**/*.rb']
-    t.stats_options = ["--list-undoc"]
+  t.files = ['lib/**/*.rb']
+  t.stats_options = ['--list-undoc']
 end
 
 task :generate_docs do
-    sh %{
+  sh %(
     cd documentation;
     ../test/pandocomatic.rb --data-dir data-dir --config config.yaml --input manual.md --output ../index.md;
     ../test/pandocomatic.rb --data-dir data-dir --config config.yaml --input README.md --output ../README.md
-    }
+    )
 end
 
 task :build do
-    Rake::Task[:rubocop].execute
-    Rake::Task[:test].execute
-    Rake::Task[:yard].execute
-    sh "gem build pandocomatic.gemspec; mv *.gem releases"
-    Rake::Task["generate_docs"].execute
+  Rake::Task[:rubocop].execute
+  Rake::Task[:test].execute
+  Rake::Task[:yard].execute
+  sh 'gem build pandocomatic.gemspec; mv *.gem releases'
+  Rake::Task['generate_docs'].execute
 end
 
-task :default => :test
+task default: :test

documentation/acknowledgements.md

@@ -1,6 +1,6 @@
 ## Acknowledgements
 
-I would like to thank [Ian](https://github.com/iandol) for his contribution of
-patches, bug reports, fixes, and suggestions. With your help pandocomatic is
-growing beyond a simple tool for personal use into a useful addition to the
-pandoc ecosystem.
+Thanks to [Ian](https://github.com/iandol) for his contribution of patches,
+bug reports, fixes, and suggestions. With your help pandocomatic is growing
+beyond a simple tool for personal use into a useful addition to the pandoc
+ecosystem.

documentation/configuration.md

@@ -1,41 +1,69 @@
-Pandocomatic is configured by command-line options and configuration files.
+Pandocomatic is configured by a combination of command-line options and
+configuration files.
+
 Each input file that is converted by pandocomatic is processed as follows:
+
+
+    START
+        ⇢   setup₀ 
+            … 
+            setupᵣ
+    input_file  →   preprocessor₀ 
+                    … 
+                    preprocessorₙ 
+
+                →   pandoc
 
-    input_file -> 
-      preprocessor(0) -> ... -> preprocessor(N) ->
-        pandoc -> 
-          postprocessor(0) -> ... -> postprocessor(M) -> 
-            output_file
+                →   postprocessor₀ 
+                    … 
+    output_file ←   postprocessorₘ
+        ⇢   cleanup₀ 
+            … 
+            cleanupₚ
+    END
 
-The preprocessors and postprocessors used in the conversion process are
-configured in pandocomatic templates. Besides processors, you can also specify
-pandoc options to use to convert an input file. These templates are specified
-in a configuration file. Templates can be used over and over, thus automating
-the use of pandoc.
+You specify the cleanup script, the preprocessors scripts, postprocessors
+scripts, and cleanup scritps to use in the conversion process in pandocomatic
+templates. Besides processors, you can also specify pandoc options to use to
+convert an input file. You specify these templates in a configuration file.
+Templates can be used over and over, thus automating the use of pandoc.
 
-Configuration files are [YAML](http://www.yaml.org/) files and can contain the
-following properties:
+Write your configuration files in [YAML](http://www.yaml.org/). These
+configuration files contain the following properties:
 
 -   **settings**:
-    -   **skip**: An array of glob patterns of files and directories to not
-        convert. By default, hidden files (starting with a ".") and
-        "pandocomatic.yaml" are skipped.
-    -   **recursive**: A boolean telling pandocomatic to convert the
-        subdirectories of a directory as well. By default this setting is
+    -   **skip**: An array of
+        [glob](https://en.wikipedia.org/wiki/Glob_(programming)) patterns of
+        files and directories that pandocomatic will not touch or convert. By
+        default, pandocomatic skips hidden files, i.e. files with a name
+        starting with a ".", and the default pandocomatic configuration file
+        "pandocomatic.yaml".
+    -   **recursive**: A boolean property instructing pandocomatic to convert
+        the subdirectories of a directory as well. By default this setting is
         `true`.
-    -   **follow_links**: A boolean telling pandocomatic to follow symbolic
-        links. By default, this option is `true`. Note, links that point outside the input
-        source's directory tree will not be visited.
+    -   **follow_links**: A boolean property telling pandocomatic to follow
+        symbolic links. By default, this option is `true`. Note, pandocomatic
+        will *never* visit links that point outside the input source's
+        directory tree.
 -   **templates**:
-    -   **glob**: An array of glob patterns of files to convert using this
-        template.
+    -   **glob**: An array of glob patterns of filenames that pandocomatic
+        converts automatically using this template.
+    -   **setup**: An array of scripts to run before the preprocessors start
+        working on the input. These startup scripts typically setup the
+        environment wherein the conversion takes place. For example, creating
+        a temporary working directory, copying static assets like images, and
+        so on.
     -   **preprocessors**: An array of scripts to run on an input file before
         converting the output of those scripts with pandoc.
+    -   **metadata**: 
     -   **pandoc**: Pandoc options to use when converting an input file using
         this template.
     -   **postprocessors**: An array of scripts to run on the result of the
         pandoc conversion. The output of these scripts will be written to the
         output file.
+    -   **cleanup**: An array of scripts that run after the conversion process
+        and postprocessors have finished. These cleanup scripts typically
+        clean up the environment.
 
 Each file and directory that is converted can contain a configuration YAML
 metadata block or a YAML configuration file respectively. In a file, the

documentation/data-dir/filters/insert_code_block.rb

@@ -1,15 +1,15 @@
 #!/usr/bin/env ruby
-require "paru/filter"
+require 'paru/filter'
 
-Paru::Filter.run do 
-  with "CodeBlock" do |code_block|
-    command, path, *classes = code_block.string.strip.split " "
-    if command == "::paru::insert"
-        # prepend a space for each line to prevent pandocomatic to interpret
-        # YAML code blocks as pandoc YAML metadata
-        code_lines = File.readlines path.gsub(/\\_/, "_")
-        code_block.string = code_lines.map {|l| " " + l}.join()
-        classes.each {|c| code_block.attr.classes.push c}
+Paru::Filter.run do
+  with 'CodeBlock' do |code_block|
+    command, path, *classes = code_block.string.strip.split ' '
+    if command == '::paru::insert'
+      # prepend a space for each line to prevent pandocomatic to interpret
+      # YAML code blocks as pandoc YAML metadata
+      code_lines = File.readlines path.gsub('\\_', '_')
+      code_block.string = code_lines.map { |l| ' ' + l }.join
+      classes.each { |c| code_block.attr.classes.push c }
     end
   end
 end

documentation/data-dir/filters/insert_document.rb

@@ -1,15 +1,14 @@
 #!/usr/bin/env ruby
-require "paru/filter"
+require 'paru/filter'
 
-Paru::Filter.run do 
-  with "Para" do |paragraph|
+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(/\\_/, "_")
+      command, path = paragraph.inner_markdown.strip.split ' '
+      if command == '::paru::insert'
+        markdown = File.read path.gsub('\\_', '_')
         paragraph.outer_markdown = markdown
       end
     end
   end
 end
-

documentation/data-dir/filters/insert_pandocomatic_version.rb

@@ -1,26 +1,25 @@
 #!/usr/bin/env ruby
-# A filter to insert paru's version. All occurrences of 
+# A filter to insert paru's version. All occurrences of
 # '::paru::version' are replaced by paru's version.
-require_relative "../../../lib/pandocomatic/pandocomatic"
-require "paru/filter"
+require_relative '../../../lib/pandocomatic/pandocomatic'
+require 'paru/filter'
 
 # Get pandocomatic's version
 def version(str)
-    str.gsub "::pandocomatic::version", Pandocomatic::Pandocomatic::VERSION.join(".")
+  str.gsub '::pandocomatic::version', Pandocomatic::VERSION.join('.')
 end
 
-Paru::Filter.run do 
-  with "Str" do |str|
-      str.string = version(str.string)
+Paru::Filter.run do
+  with 'Str' do |str|
+    str.string = version(str.string)
   end
 
-  with "CodeBlock" do |code|
-      code.string = version(code.string)
+  with 'CodeBlock' do |code|
+    code.string = version(code.string)
   end
 
-  with "Link" do |link|
-      link.target.url = version(link.target.url)
-      link.target.title = version(link.target.title)
+  with 'Link' do |link|
+    link.target.url = version(link.target.url)
+    link.target.title = version(link.target.title)
   end
-
 end