Introducing scdoc, a man page generator May 13, 2018 on Drew DeVault's blog

A man page generator is one of those tools that I’ve said I would write for a long time, being displeased with most of the other options. For a while I used asciidoc, but was never fond of it. There are a few things I want to see in a man page generator:

  1. A syntax which is easy to read and write
  2. Small and with minimal dependencies
  3. Designed with man pages as a first-class target

All of the existing tools failed some of these criteria. asciidoc hits #1, but fails #2 and #3 by being written in XSLT+Python and targetting man pages as a second-class citizen. mdocml fails #1 (it’s not much better than writing raw roff), and to a lesser extent also fails criteria #21. Another option, ronn meets criteria #1 and #3, but it’s written in Ruby and fails #2. All of these are fine for the niches they fill, but not what I’m looking for. And as for GNU info… ugh.

So, after tolerating less-than-optimal tools for too long, I eventually wrote the man page generator I’d been promising for years: scdoc. In a nutshell, scdoc is a man page generator that:

I recently migrated sway’s manual to scdoc after adding support for generating tables to it (a feature from asciidoc that the sway manual took advantage of). This change also removes a blocker to localizing man pages - something that would have been needlessly difficult to do with asciidoc. Of course, scdoc has full support for UTF-8.

My goal was to make a man page generator that had no more dependencies than man itself and would be a no-brainer for projects to use to make their manual more maintainable. Please give it a try!


  1. mdocml is small and has minimal dependencies, but it has runtime dependencies - you need it installed to read the man pages it generates. This is Bad. ↩︎

Have a comment on one of my posts? Start a discussion in my public inbox by sending an email to ~sircmpwn/public-inbox@lists.sr.ht [mailing list etiquette]

Articles from blogs I read Generated by openring

Announcing the 2020 Go Developer Survey

Help shape the future of Go Since 2016, thousands of Gophers around the world have helped the Go project by sharing their thoughts via our annual Go Developer Survey. Your feedback has played an enormous role in driving changes to our langu…

via The Go Programming Language Blog October 20, 2020

Status update, October 2020

Hi all, it’s been a while! I’ve been taking some time off this month: I’ve been hiking in Corsica (an island in the south of France) for 2 weeks! The path (called GR20) was very difficult but the gorgeous landscapes made it entirely worth it. :) I’ve uploaded…

via emersion October 16, 2020

What's cooking on Sourcehut? October 2020

Once again we meet to discuss the status of the ongoing SourceHut alpha, which has made progress by leaps and bounds this month. We’re joined by 521 new users this month, bringing our total up to 17,715. As always, please welcome them warmly and show our new…

via Blogs on Sourcehut October 15, 2020