Convert man pages to scdoc

[pmatilai]

We're using pandoc to convert markdown to man pages, but pandoc is a sledgehammer of a tool for this kind of job and is a really painful build dependency to have (because of its own build dependencies). We should look at alternatives - there's at least

• https://rtomayko.github.io/ronn/
• https://github.com/apjanke/ronn-ng

Compared to pandoc, both of which have the distinct benefit of not being written in Haskell...

Also, maybe markdown isn't the best source format for man pages to begin with. It has the alleged benefit of having unified documentation format for everything, but for man pages the source doesn't look that much like markdown, and the output isn't that great a manpage. There might be better options.

Edit: and obviously we're not the only ones with this need and disliking the options:
https://drewdevault.com/2018/05/13/scdoc.html - this fits our case perfectly.

[Conan-Kudo]

scdoc might be a good choice here? It's markdown-like and is designed to write man pages. It's what I use for my projects.

[Conan-Kudo]

Another option would be to switch to reStructuredText and use Sphinx like DNF does.

[pmatilai]

I really rather like the sound of this (wrt scdoc):

Is less than 1,000 lines of POSIX.1 C99 code with no dependencies and weighs 78 KiB statically linked against musl libc.

Which seems like on-par for the job at hand when you think about it...

Thanks for the pointer @Conan-Kudo , I didn't know about scdoc.

[pmatilai]

Okay, I think I'm in love.

https://raw.githubusercontent.com/swaywm/sway/refs/heads/master/sway/sway.1.scd is beautifully readable without any processing. And scdoc produces a very clean and nice looking roff out of it. Even the GH preview of the sway source renders quite decently - that's not an actual goal here, just a nice side bonus.

[dmnks]

Indeed, seems like exactly the kind of tool we want, thanks @Conan-Kudo!

[pmatilai]

It took a moment for this to sink in:

scdoc is something we can add as a hard build dependency without blinking, it's so trivially simple and light (builds under a second on my laptop, using nothing rpm itself wouldn't require). The pot of gold at the end of that rainbow? We can drop the pre-built source tarballs and just point people to the pristine source from git (so relating to #2702) .

[Conan-Kudo]

scdoc can be detected via pkgconfig too, so CMake can interrogate its location in a relatively standard way.