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?
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.