Confusion about pandoc --print-default-data-file

[SKPloft]

Explain the problem

Sorry if this discussion probably looks like a misunderstanding on my part and kind of unnessary, and still may include incorrect information — I spent some time reading the docs and experimenting, and I think I now get how it's supposed to work. But I initially found the behavior kind of confusing, so I wanted to share my experience in case it helps improve the docs or UX.

After reading the docs, I now understand the intent: --print-default-data-file looks up pandoc data files by name (inside pandoc's data dir / data path), not arbitrary relative/absolute filesystem paths.

So it's more like a suggestion / UX-doc improvement discussion, because the current failure mode is very easy to misinterpret at first:

• A user sees --print-default-data-file <something.docx> and reasonably assumes <something.docx> can be a path to an existing .docx (e.g. a custom reference docx in the current directory).
• Pandoc responds Could not find data file <something.docx> (exit 97), which doesn’t explicitly say “I only searched the pandoc data directory”.
• The manual does explain data files, but the relevant bit probably looks short and easy to miss; without already knowing about --data-dir / the data directory concept, it’s not obvious what to do next.

If this is considered “working as designed”, I’m fine with closing as “documentation/clarification”; otherwise it could be treated as an upstream usability fix.

Concrete improvement ideas

Any of the following would have prevented my confusion:

1. Improve the error message to explicitly mention the search location, e.g. “Could not find data file … in pandoc data directory (see pandoc --data-dir)”.
2. Add a short note in the option help/man page entry for --print-default-data-file saying it only accepts names of pandoc data files, not filesystem paths.

Exact commands and output (repro)

Even if the file exists in the current directory, pandoc still reports “data file not found”, which is the core of the UX confusion:

printf 'dummy' > cust-ref.docx
pandoc --print-default-data-file cust-ref.docx

Output:

Could not find data file cust-ref.docx

Exit code: 97

I originally hit this while trying variants like:

pandoc -o ref.docx --print-default-data-file 1.docx

Output:

Could not find data file 1.docx

Exit code: 97

Same result with:

pandoc -o ref.docx --print-default-data-file cust-ref.docx
pandoc -o ref-chi.docx --print-default-data-file cust-ref-chi.docx

Adding --verbose doesn’t add more context:

pandoc -o ref.docx --print-default-data-file cust-ref.docx --verbose

What I expected

Either:

1. --print-default-data-file accepts a filesystem path and prints the file, or
2. if it only searches the pandoc data directory, the error message says so explicitly (and/or points to pandoc --data-dir).

Pandoc version?

• OS: Linux Mint 22.2 (base Ubuntu 24.04)
• pandoc --version:

pandoc 3.8.3
Features: +server +lua
Scripting engine: Lua 5.4
User data directory: /home/skp1238/.local/share/pandoc

Workaround / discovered correct usage (what I learned)

To export the bundled reference docx, this works:

pandoc --print-default-data-file reference.docx > <user-defined-docx-name>

or

pandoc -o <user-defined-docx-name> --print-default-data-file reference.docx

as mentioned in the docs.

To see where pandoc's data files live, use:

pandoc --data-dir

[jgm]

Maybe the error message could be: "Pandoc does not have a default data file named foobar.baz"