logo

drewdevault.com

[mirror] blog and personal website of Drew DeVault git clone https://hacktivis.me/git/mirror/drewdevault.com.git

scdoc.md (2526B)

    

  1. ---
  2. date: 2018-05-13
  3. layout: post
  4. title: Introducing scdoc, a man page generator
  5. tags: [scdoc, announcement]
  6. ---
  8. A man page generator is one of those tools that I've said I would write for a
  9. long time, being displeased with most of the other options. For a while I used
  10. asciidoc, but was never fond of it. There are a few things I want to see in a
  11. man page generator:
  13. 1. A syntax which is easy to read and write
  14. 2. Small and with minimal dependencies
  15. 3. Designed with man pages as a first-class target
  17. All of the existing tools failed some of these criteria.
  18. [asciidoc](http://asciidoc.org/) hits #1, but fails #2 and #3 by being written
  19. in XSLT+Python and targetting man pages as a second-class citizen.
  20. [mdocml](http://mandoc.bsd.lv/) fails #1 (it's not much better than writing raw
  21. roff), and to a lesser extent also fails criteria #2[^1]. Another option,
  22. [ronn](https://github.com/rtomayko/ronn) meets criteria #1 and #3, but it's
  23. written in Ruby and fails #2. All of these are fine for the niches they fill,
  24. but not what I'm looking for. And as for GNU info... ugh.
  26. [![](https://sr.ht/nemf.png)](https://xkcd.com/912/)
  28. So, after tolerating less-than-optimal tools for too long, I eventually wrote
  29. the man page generator I'd been promising for years:
  30. [scdoc](https://git.sr.ht/~sircmpwn/scdoc). In a nutshell, scdoc is a man page
  31. generator that:
  33. - Has an easy to read and write syntax. It's inspired by Markdown, but
  34.   importantly it's not *actually* Markdown, because Markdown is designed for
  35.   HTML and not man pages.
  36. - Is less than 1,000 lines of POSIX.1 C99 code with no dependencies and weighs
  37.   78 KiB statically linked against musl libc.
  38. - Only supports generating man pages. You can post-process the roff output if
  39.   you want it converted to something else (e.g. html).
  41. I recently migrated [sway's manual](https://github.com/swaywm/sway/pull/1958) to
  42. scdoc after adding support for generating tables to it (a feature from asciidoc
  43. that the sway manual took advantage of). This change also removes a blocker to
  44. localizing man pages - something that would have been needlessly difficult to do
  45. with asciidoc. Of course, scdoc has full support for UTF-8.
  47. My goal was to make a man page generator that had no more dependencies than man
  48. itself and would be a no-brainer for projects to use to make their manual more
  49. maintainable. Please give it a try!
  51. [^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.