Oops! Sorry again to have a duplicated post… a post on the same topic is in pandoc-discuss/support arguments on filters.

To compensate, let me wrote a combined summary of both posts (please expand or correct if incomplete/incorrect):

Current method

1. pipe it through
   • Cons:
     • the filter would not know the output format without duplication
       • related question: how to pass output format when using pandoc -t json | filter1 ... | ...? e.g. I often see filters checking the output format from the json rather than the 1st arg.
     • ugly, “unnecessary” pipe
   • Questions: how about Windows users? Does it work the same way?
2. Metadata, either through YAML or -M command line option
   • Cons:
     • treated as Markdown
     • metadata key collision (e.g. hierarchy of metadata key is needed, which make it uglier)
3. panzer
   • Cons:
     • extra dependency
     • written in Python (for filter not written in Python it is not desirable)
     • it has its own rules (which some might not like)
4. environmental variables
   • Cons: suffer the same deficiency of -M option in (2)
   • Questions: how about Windows users? Does it work the same way? (@bpj has mentioned it is a pain to do so.)

Comments:

As as filter writer, one would want their filter as easy to use as possible, and as few extra dependencies as possible. These criteria eliminates (1, 4) for easiness and (3) for dependencies. This leaves (2) as the only viable solution, which still has some cons needed to be dealt with. I personally don’t worry too much about things treated as Markdown, but metadata key collision is unavoidable if one want short, easy to remember keys (e.g. pantable -s -t csv, anyone used to pandoc will almost be able to remember this.).

In addition, the above discussion hasn’t covered the case that one might want to write a program that can acts as both a filter and a standalone cli. e.g. I am thinking about using -s to indicate it is a standalone cli (and without it, a pandoc filter). Using -M means the options is parsed differently (and duplicated) in these 2 cases.

Suggested method

1. -O key=value/--filter-option=KEY:VAL/--filter-args/--filter-arguments
   • Cons
     • what if there’s multiple filters? special ordering is needed.
2. -F "filter --split --on --hyphens"/-F filter --split --on --space
   • Cons:
     • pandoc is already passing the output format as the 1st arg
     • potentially break existing ill-named filters

Comments:

Just for the sake of letting the -F option be backward compatible, (1) might be better. But either way it will be fine with me.