My Story of Linux man page writing

Man pages are essential parts of Linux platform. Existence of the man pages started with Unix and then it moved to Linux. They are especially useful to get some quick information about commands and tools to getting things started.

I have been always curious about how to write a man page and more importantly, how to create my own man page and being able to use it system wide like other man pages. I must admit that I was quite reluctant to do a simple Googling to get answer to my curiosity.

Then suddenly after 4 years one night that I couldn’t go to sleep, I just remembered and did a quick search on the internet and the results fascinated me. I have found man page has own markup language, however, with some special tools you can write your man page in Markdown first and then convert to man markup. For example on the tools are introduced in this link,

https://www.linux.com/learn/tutorials/866136-write-once-output-multiple-formats-with-sphinx

But I was eager to learn man markup. I found the best way is to get a sample and customize it based on my need. I have found my old audio player console application that was written in C for Linux platform in Github and decided to write a man page for it. Because I wanted to make a real thing even though it was a learning curve for me.

Finally, I have found two great links which are in below and started writing my own man page. I followed the guideline and did little bit of Googling. That’s why I don’t explain here. I believe the links are sufficient enough.

http://www.cyberciti.biz/faq/linux-unix-creating-a-manpage/

http://www.cyberciti.biz/faq/howto-read-file-as-manpage-with-man-command/

I completed my man page for my player application after around 1.5 hours and then end result look like this,

mylist2

I must admit that I am very satisfied to be able to write a man page but one last thing had remained and that one was how to deploy it system wide. To do that, I did little bit of search and finally found a way for it. I ended up writing some commands to copy and zip the man page in the system man path in Makefile. It makes the task easy. While user is installing the application with “make install” command, the man page will automatically copy to man path. On uninstalling, the reverse process will be occurred. The commands I used in Makefile are these,

For those that are unaware which location in file system man pages are stored, you just simple type this command to get to know where your system keeps man pages,

$ man path

Lastly, if you want to access to the code of the man page I have written, you can refer to the link in below,

https://github.com/kasramp/CISAP/blob/v0.1/man/cisap

Leave a Reply