What is a "PIT file"? Both Heimdall and Odin have options for a PIT file. From Heimdall's option you can find,


  Action: print-pit
  Arguments: [--file &lt;filename&gt;] [--verbose] [--no-reboot] [--stdout-errors] [--usb-log-level &lt;none/error/warning/debug&gt;]
  
  Description: Prints the contents of a PIT file in a human readable format. If a filename is not provided then Heimdall retrieves the PIT file from the connected device.


And, from Odin there is a specific tab for it, when you click on the tab it says,


  Do not use this tab. This tab is for engineers. You device will be changed with the pit in the CSC file.


So what is a PIT file, and where is it documented anywhere? Can I generate one automatically?
PIT stands for Partition Information Table. A PIT file is basically a set of instructions defining the phone partition layout. You should use a it if you want to re-partition the phone with Odin. 

You only need this file when repartitioning the device and you don't need to repartition it unless you mess up the partition table to begin with, or when downgrading/upgrading.

There are tools (commercial) that can genarate PIT files using ADB commands.