Writing manpages in 20XX

Question

I wrote a program, and I'd like to write a manpage for it.

I started to learn Groff, and I really find it awful. The man macros are difficult to understand, difficult to use, and a real obstacle to productivity. The mdoc macros add a nice "semantic" extension, but they still suffer of limitations which make it incredibly hard. The resulting "code" is poor in maintainability.

Of course I know I can convert any modern markup language (say Markdown) into manpages via pandoc, but I dislike the result, and I'm not that fond of adding pandoc as dependency of my project, anyway.

Is there a way to obtain a decent manpage from a reasonable markup language?

Answer 1

I write manpages for the bash and ruby scripts I write.

I format them in markdown, which is a popular and simple text format.

Then I use a ruby gem called ronn to process the markdown into groff format with man macros. Ronn can also output html from the same markdown source.

Answer 2

OP here. After checking some alternatives, I decided to go for Asciidoc.

There are many alternatives indeed. For example, check this other question.

I also realized that there's no good answer to this question, given the fact that many tools can be used, and in the end it is just a matter of taste :) I'll just vote for closing my own question (if anything it will remain as reference).