# Compatibililty 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 work in progress.

## Known compatibility bugs

None right now

### Upstream bugs

- Bleeding edge pikepdf is required to deal properly with dictionary keys (duplicate keys and keys which cannot be converted to UTF-8).

## 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. 
