# Compatibility notes for pdftl

pdftl aspires to be CLI compatible with pdftk and this is an attempt to explain what this might mean, and to note any caveats.

## What is CLI compatibility?

The vague idea is clear: `s/pdftk/pdftl/g` should Just Work.

So the questions are:

1. Which pdftk implementation are we targeting?

2. What is Just Working?

We don't really know the answers. Our approach is to take existing integration tests for various pdftk implementations and to check whether or not pdftl passes them.

Getting pdftl to pass them all is the goal, which at time of writing has been achieved.

## Compatibility tests

We test against:

- A Python translation of `pdftk-java` tests, in `vendor_tests/pdftk-java`, and
- [Mike Haertl's PHP test suite](https://github.com/mikehaertl/php-pdftk), which can be
  installed using [`tools/setup_php_tests.sh`](tools/setup_php_tests.sh) to `vendor_tests/php-pdftk`.

If you know other pdftk test suites we could use, please [let us know](https://github.com/pdftl/pdftl/discussions).

## Known compatibility bugs

None right now. [Please report if you find any](https://github.com/pdftl/pdftl/issues).

## Compatibility caveats and issues

- Order of lines in `dump_data` etc may differ from pdftk, where not semantically important.

- FDF files generated by `generate_fdf` are formatted differently than pdftk's, to be more human-readable.

- `update_info` cannot reset the PdfID1 field in pdftl, but it can in pdftk. In pdftl, the PdfID1 field is generated automatically by the underlying qpdf library on save. pdftl *can* reset both fields to be new, equal IDs, mimicking a "freshly baked" PDF file. 
  See the [`update_info`](https://pdftl.readthedocs.io/en/latest/operations/update_info.html) documentation for details.

- It is not possible to deny the "screenreader" (a.k.a. "accessibility") permission in files saved with pdftl. This is a limitation of the underlying qpdf library, to align with the modern PDF specification.

- `burst` supports multi-page chunks via `split_spec` (page ranges, `level<n>` bookmark splits, `step<n>`, `size<limit>`), whereas pdftk can only burst into single pages. When pdftl bursts into single pages, each output file also preserves that page's ORIGINAL label/number rather than restarting at "1", which pdftk does not do.
