Pandoc: Treat `--filter pandoc-citeproc` as synonym for `--citeproc`?

[jgm]

Currently if you use pandoc 2.11 with --filter pandoc-citeproc, you'll get a warning that pandoc-citeproc is deprecated in favor of --citeproc. Unless you've self-compiled pandoc-citeproc from master, you'll also get an error that the filter was compiled against an incompatible API version.

@njbart suggested that maybe we should just treat --filter pandoc-citeproc as --citeproc, issuing a warning indicating what we're doing. I was initially resistant, but now I'm coming around to this idea and I wanted to get feedback.

Cons:

• you wouldn't be able to keep using the pandoc-citeproc filter unless you renamed it or used an absolute path (not a big problem I think)
• introduces an inconsistency: --filter NAME doesn't always do the same thing.

Pros:

• smoother upgrade path: people would not need to modify scripts, etc.
• avoids confused queries from people encountering the error

Let me know your thoughts.

[cagix]

I would leave the behavior of pandoc 2.11 as it is now.

Sure, it causes some inconvenience because you have to adapt the scripts (slightly).

On the other hand, it makes it clear that the filter used earlier is no longer available. The error message when using --filter pandoc-citeproc should actually be meaningful enough.

[jgm]

The error message when using --filter pandoc-citeproc should actually be meaningful enough.

Well, I've already had one message on pandoc-discuss from someone who couldn't figure out what to do.

[cagix]

Imho, the error message is concise and helpful. Perhaps it would help if an explanation about the changed behaviour / outdated filter could be added to the documentation (https://pandoc.org/MANUAL.html#citations).

On the other hand, you could leave the old behaviour active for a certain period of time and emit a warning each time, and then switch it off in the next version (pandoc 2.12). But in my experience the confused users / developers will appear then after the release of 2.12 ...

[tarleb]

Using the "Zen of Python" as a guide:

Special cases aren't special enough to break the rules.\
Although practicality beats purity.

I think the current solution is good. Practicality concerns appear satisfied with just the warning.

[Delanii]

From beginner point of view, I would also vote for staying with the current behavior and modifying the documentation as @cagix has proposed.