Here are three minor gotchas:

  1. To ignore a directory, use -i path/relative/to/the/src/root/ with a "/" at the end (or "" for Windows). You MUST have that trailing slash, otherwise the directive is treated differently (filename match)
  2. To ignore multiple directories, you cannot use multiple -i -directives. If you do, they will overwrite one another, and only the last one will be applied. Instead, use a comma to separate the paths: -i first/path/,second/path/
  3. If you happen to use 1.4.3 and use the "HTML:frames:earthli" template, you will notice that the images and css files won't load because they are missing one character at the end for some reason. Solution: rename or copy the template from a previous version to "./PhpDocumentor/Converters/HTML/frames/earthli".
Really, this is simple but the documentation is rather unclear as to how this works (particularly the point about the significance of the last slash character). I found some comments in the bug tracker which helped me find the correct syntax (here). Both of these things are implied in documentation, but I figure writing this might save someone else some time.

Comments

Jim Lekas: Thanks for the note. Regarding point #3, not only images and .css files have truncated names, but also .tpl files and .js files. Many, but not all, of the template files throughout the Converters tree (not only in PhpDocumentor/Converters/HTML/frames/earthli) are incorrectly named .tp instead of .tpl. Changing the names corrects many problems with the converters.

If you have a file comparison program like WinMerge (http://winmerge.org/), you can compare the .../Converters subtrees from PhpDocumentor 1.4.2 and 1.4.3 to find the misnamed files. The Windows shell program "RENAME" will rename files by pattern (e.g. rename .tp .tpl).

Jim Lekas: In my earlier note I mentioned using "RENAME" to change the file names. A faster way is to use WinMerge to show only the files unique to the 1.4.2 version, select the files to copy, and choose "copy right" or "copy left" as appropriate to install them in 1.4.3. Then show only the files unique to 1.4.3, which should be mostly the broken files, and select and delete them.

Jumper: I gave up on using the phpDocumentor default templates. They're not easy to navigate etc.

Found a good alternative here: http://evolve.crazytje.be