Providing Documentation for an Unix command?

Question

I made an 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 that troff. Reminds me of Markdown.

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

Answer 2

You can apparently use also DocBook to provide Documentation for an Unix command.