Can you explain the different save options?

[Ryan]

Question: 

There a number of different save options, can you explain what each is, and how to pick them?

Answer:

Compatibility

Save the document in a manner that maximizes compatibility with older PDF consumers (e.g. the file will not use object and compressed xref streams). In particular this means the file will be saved as PDF 1.4 format.

When to Use:

 Only when you know you have to (for some external requirement reason), since the resulting file will most likely be larger.

  

Linearized

Also known as Fast Web View. A linearized PDF file is a PDF file that is structured in a way that allows the first page of the PDF file to be displayed before the entire file is downloaded from the Web server.

When to Use:

If you are saving the PDF fully, then it is generally a good idea to save as Linearized, as it doesn't affect the file much, but allows for the possibility of a better viewing experience over a network. This option also implictly includes removal of unused objects (e_remove_unused)

 

Remove Unused

Full save of a document removing objects that are unused.

 When to Use:

Since Linearized save does this already, then you would use this option if you didn't want a Linearized file.

 

Incremental

Does not modify the original file, but only appends bytes to the file. In other words, all changes are added as additional information.

When to Use:

You must use this option if you are adding Approval Digital Signatures to a PDF, as modifying the original bytes will invalidate the signature.

Otherwise, this is good to use for viewers when modifying annotations, especially as it can assist with the implementation of undo/redo mechanism. Also works great over network, as you can only send the appended bytes back to a server, and not the entire source file.

Note:

This flag is incompatible with the other flags. 

 

So how should I save files then?

In general, the default would be 

PDFDoc.Save(path, e_linearized); // remove unused and save as Fast Web View if not already.

The other options would only be used in the specific cases mentioned above.

What about e_omit_xref  and e_hex_strings?

Don't use these flags unless you have a very specific reason.