Providing documentation for a Unix command

Question

I made a Unix command called macmac2unix, which converts a Word file from Mac to Unix.

How can I provide documentation for my command?

I want to read about my command with man:

man macmac2unix

Answer 1

I recommend Perl's POD format. Despite the name, you can use it outside of Perl scripts, and the pod2man command ships with OS X. It's a lot more sensible than troff. It reminds me of Markdown.

Here's an example POD document and the conversion script.