How can I build a novice-usable (clickable download) installer for a Mac OS X command-line tool, and where should the binary be installed so that a novice user with no knowledge of shell paths can just open the Terminal app and type “foo” to run the freshly installed foo tool?
Can the installer also install documentation so that the user can type “man foo”?
Are there any other options that should be considered to make the use of a pure command-line (stdin, stdout) tool accessible to a novice Mac user?
What’s the minimum version of OS X you’re targeting? 10.6 (and IIRC 10.5) include /usr/local/bin in the default PATH, but 10.4 did not. As long as you don’t need to support 10.4, you should just put the executable in /usr/local/bin and the man page in /usr/local/share/man/man1 (or whatever the appropriate chapter number is).
For building the installer itself, you can use Apple’s PackageMaker utility (part of Xcode). Create a prototype local folder with bin and share/man/man1 subfolders and populate them with your files. Create a package project in PackageMaker, and choose your organization name and minimum target OS. Drag the prototype folder into the project’s Contents sidebar. Set the Destination to /usr/local. Switch to the Contents tab and edit the ownership and permissions the files should be installed with (the owner/group should probably all be root/admin, with rwxrwxr-x perms on the folders and executable, rw-rw-r– on the man page). If any irrelevant files (e.g. .DS_Store) snuck in, exclude them. Look around for any other settings you want to change, then save the project and build the installer. Then test it, to make sure it does what you expect.