Pandocomatic 2.0.0

I've added two new features: logging and feature toggles. Because the log is more detailed than the already existing debug information printed when you used pandocomatic's --debug command-line option, I've removed that command-line option. However, as that's a breaking change, I've created a new major version of pandocomatic: 2.0.0.

Logging

Pandocomatic 2.0.0 adds logging to pandocomatic. Use the log to investigate and understand your conversion process in detail. Use new command-line options --log [FILE] and --log-level [LEVEL] to control pandocomatic's logging. Use them as follows:

• -l [FILE], --log [FILE]

  Let pandocomatic log what it is doing to FILE. If FILE is not given, pandocomatic uses 'pandocomatic.log'. Control detail of logging with option '--log-level'.

• --log-level [LEVEL]

  Let pandocomatic log with detail LEVEL. LEVEL should be one of 'fatal', 'error', 'warn', 'info', or 'debug'. By default, pandocomatic logs at detail level info. Choose level 'debug' to see all steps pandocomatic takes to convert every directory and file.

When using the "debug" detail level, pandocomatic will log the full conversion process in a structured way. Using this log, you can see exactly what steps pandocomatic took when converting a file or directory. It'll allow you to perform the same steps manually and investigate the conversion process.

For example, part of the log when running a test looks like:

2024-10-09 07:49:15 INFO : (1)   - convert index.md -> index.html
2024-10-09 07:49:15 DEBUG:   #  Using template 'wiki-page'.
2024-10-09 07:49:15 DEBUG:   #  Selected template mixed with internal template and pandocomatic metadata gives final template:
                                  extends: []
                                  glob:
                                  - "*.md"
                                  setup:
                                  - scripts/create_temp_file.sh
                                  preprocessors:
                                  - preprocessors/now.rb
                                  metadata: {}
                                  pandoc:
                                    from: markdown
                                    to: html5
                                    standalone: true
                                    template: templates/wiki.html
                                  postprocessors:
                                  - postprocessors/branding.rb
                                  cleanup: []
2024-10-09 07:49:15 DEBUG:      #  Running setup:
2024-10-09 07:49:15 DEBUG:      |  /home/pandocomatic-user/example/data-dir/scripts/create_temp_file.sh
2024-10-09 07:49:15 DEBUG:   →  Reading source file: '/home/pandocomatic-user/example/src/setup-cleanup-wiki/index.md'
2024-10-09 07:49:15 DEBUG:      | FileInfoPreprocessor. Adding file information to metadata:
                                     pandocomatic-fileinfo:
                                       from: markdown
                                       to: html5
                                       template: templates/wiki.html
                                       path: '/home/pandocomatic-user/example/src/setup-cleanup-wiki/index.md'
                                       src_path: '/home/pandocomatic-user/example/src/setup-cleanup-wiki'
                                       created: 2024-05-22
                                       modified: 2024-05-04
2024-10-09 07:49:15 DEBUG:      #  Running preprocessors:
2024-10-09 07:49:15 DEBUG:      |  /home/pandocomatic-user/example/data-dir/preprocessors/now.rb
2024-10-09 07:49:15 DEBUG:      #  Changing directory to '/home/pandocomatic-user/example/src/setup-cleanup-wiki'
2024-10-09 07:49:15 DEBUG:      #  Running pandoc
2024-10-09 07:49:15 DEBUG:      |  pandoc       --from=markdown \
                                                --to=html5 \
                                                --standalone \
                                                --template=/home/pandocomatic-user/example/data-dir/templates/wiki.html
2024-10-09 07:49:15 DEBUG:      #  Running postprocessors:
2024-10-09 07:49:15 DEBUG:      |  /home/pandocomatic-user/example/data-dir/postprocessors/branding.rb
2024-10-09 07:49:15 DEBUG:   ←  Writing output to '/tmp/setup_cleanup20241009-42-uqczz2/setup-cleanup-wiki/index.html'.

Feature toggles

From pandocomatic 2.0.0 on, pandocomatic also supports feature toggles. Use command-line option --enable FEATURE to enable a feature.

At the moment, pandocomatic only support feature toggle "pandoc-verbose". By default, pandocomatic does not forward pandoc's "--verbose" option to pandoc when you set it in a template because the output of pandoc's verbose mode might interfere with the working of pandocomatic processors and pandoc's filters. However, if you want, you can force pandocomatic to adhere to the template and pass on the "--verbose" option to pandoc by using command-line option --enable pandoc-verbose.

Support pandoc 3.3

Support pandoc 3.3; No other changes.

Update to support pandoc 3.x

Pandocomatic 1.1 supports pandoc 3.x. No other changes; No new features added.

Note Due to a change in pandoc-types used by pandoc, you need to upgrade to paru 1.1 and pandocomatic 1.1 when you're using pandoc 3.x. Similarly, if you're still using pandoc 2.x, you cannot upgrade paru or pandocomatic beyond version 1.0.

Pandocomatic 1.0!

Over the past years, pandocomatic has grown into a useful tool. I now release version 1.0 to signal that the current state of pandocomatic is stable. Given pandoc's development to include features for which I developed pandocomatic in the first place, like the --defaults file feature, pandocomatic needs to be rethought and rewritten. But that's for version 2.0. If you have any ideas for this future version, let me know in the discussions.

For now, I'll maintain the current state of pandocomatic in version 1.x, fix bugs, ensure compatibility with new pandoc versions, and add useful features to keep improving pandocomatic.

Changes for version 1.0

With version 1.0, pandocomatic's behavior has changed a little, but the conversions themselves should not be affected. Still, given the number and character of changes, see below, I cannot guarantee that pandocomatic hasn't changes some behavior you've come to rely on. If there's something going amiss after upgrading to pandocomatic 1.0, please downgrade to the latest 0.x version and submit a bug report.

Use environment variables in templates (#103)

Pandocomatic now replaces all occurrences of the form $(X)$ in internal and external templates by the value of the environment variable X. You can use these environment variables anywhere in a template, so this is quite a powerful feature. If an environment variable does not exists, pandocomatic halts with an error message.

Output to STDOUT (#71)

Added command-line option --stdout to pandocomatic. If you use this option, pandocomatic writes to STDOUT instead to a file. This option doesn't work together with the --output option, nor when using pandocomatic as a static-site generator and converting whole directories.

For this feature, I changed pandocomatic behavior to be quiet by default. If you want to have verbose output use pandocomatic's --verbose command-line option.

Ignore pandoc's --verbose option (#102)

Pandoc's --verbose option can write to STDOUT. Because pandocomatic uses STDOUT to communicate between processors and pandoc, this option can interfere with the working of pandocomatic. To resolve this issue, pandoc's --verbose option is ignored. Whenever pandocomatic ignores this option, a warning is printed.

Global template inheritance and improved messages (#96)

If you extend or use a template, pandocomatic searches for the first occurrence of that template in the configuration hierarchy. This hierarchy is always:

1. internal template
2. external template in a configuration file
3. external template in pandocomatic.yaml in a data directory
4. external template in pandocomatic.yaml in the user's pandoc configuration directory
5. external template in pandocomatic's default configuration.

If resolution of an inherited template is impossible, an error message is printed pointing to the file with the template reference that cannot be resolved.

Furthermore, the configuration hierarchy is printed for easier debugging of your templates.

Various bug fixes and improvements

Among others:

• #100 Process date properties in YAML
• #98 Properly handle empty YAML properties

Allow empty properties in YAML metadata

In YAML metadata you can specify properties without a value. For example:

number: 3
empty:
string: Hello

In this example, property "empty" does not have a value. When this YAML snippet is parsed by Ruby, that property "empty" gets value nil. In some situations, pandocomatic would crash when it encountered this nil value for a property because pandocomatic did expect all properties to have a value.

From pandocomatic 2.8 onwards, empty properties are properly supported: Pandocomatic now skips empty properties.

This change should not affect working pandocomatic setups.

Minor update to support pandoc 2.14.1 and up

Upgrade to pandocomatic 0.2.7.6 if you are using pandoc version 2.14.1 or later. There are no other changes.

Minor update to support Ruby 3.0.0 + erb 2.2 and anticipate end of life of Ruby 2.5

No functional changes. The latest erb gem with ruby 3.0 was giving warnings, which are resolved in this minor release. Because Ruby 2.5 is end of life at the end of this month (March, 2021), the minimum Ruby version is bumped to 2.6.

Minor update to support pandoc 2.11.0.4 and up

Upgrade to pandocomatic 0.2.7.4 if you are using pandoc version 2.11.0.4 or later.

This new version can handle the updated version string in pandoc 2.11.0.4. There are no other changes.

Minor update to support pandoc 2.11 by default

Upgrade to pandocomatic 0.2.7.3 if you are using pandoc version 2.11.x or later. If you are using pandoc 2.10.x or earlier, please use pandocomatic 0.2.7.2. There is no difference between these two versions except the version of paru that supports pandoc 2.11.

Pandocomatic updated to work with pandoc 2.8

From pandocomatic version 0.2.6, pandocomatic does support pandoc 2.8 and later. If you are using pandoc 2.7.x or earlier, please use pandocomatic 0.2.5.x.