True, users can use internal error codes, and that can confuse things.  But that's kind of always been a problem with error codes in general (ie, any program can exit with 3 or 127, even though bash reserves those.)  Still, I think if we're going to use them for debugging at all (and they ARE occasionally very handy) then I think we probably ought to document them.

I see what you're saying though, and I sort of agreed (which is why I didn't document them when I introduced them somewhat haphazardly in 0.10, actually), but @tjfontaine convinced me of the error of my ways.

I'm not at all married to the specific semantics, of course.  I just changed all the `exit(1)` calls once upon a time based on the order in which they appeared in the code.  Documenting them made me realize that we could probably sort them more logically.  But, meh.  I think the important thing is that "generic, unspecified, userland-triggered exit" is exit code 1 (rather than 8), and that the others are documented somewhere.  Also, this isn't the best place for it.  We probably ought to have a "command line" section in the docs.  Maybe this and the command-line args could be moved under the "Synopsis" section?