4 ms·

scdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc https://git.sr.ht/~sircmpwn/scdoc

by packetlost 2y ago

blueflow 2y ago
Until i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.
- packetlost 2y ago
  I'm not a fan of Drew's political grandstanding (or views, in some cases) but scdoc is good and packaged in many distros. There's no foundation for him to abuse with it, so it's safe.
  - pkal 2y ago
    The IRC bouncer Soju uses scdoc and this has been personally annoying, as I refuse to install it just to build semantically less expressive documentation than when using the very well documented (https://mandoc.bsd.lv/man/mdoc.7.html https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I asked the maintainer if they were interested in a contribution to translate it, and they just dismissed it out of the box.
    - packetlost 2y ago
      Who cares how expressive it is? It hits all the core pieces of formatting you can realistically do in a terminal using syntax that is familiar to a much wider range of developers. The output is completely usable and reasonable. I'd rather use something closer to markdown than roff macro gunk that is largely irrelevant anywhere else.
homebrewer 2y ago
adoc is fine and is more widely supported. Linux (the kernel) documentation is written in adoc, along with man pages for many projects like git: https://github.com/git/git/blob/master/Documentation/git-rm.adoc?plain=1 https://github.com/git/git/blob/master/Documentation/git-rm....
- packetlost 2y ago
  I wasn't aware AsciiDoc could be used to generate man docs. I'm not a huge fan of AsciiDoc's syntax, but I can see that being preferable to other options.
- WhyNotHugo 2y ago
  Asciidoc doesn't support links in man pages. It can only link to URLs. If you check the repo which you linked, you'll see they use some perl code to actually inject links.
WhyNotHugo 2y ago
I've used it quite a bit. It doesn't support links to other pages nor links to other sections. Which arguably is fine, since man page readers don't render them anyway, but HTML renders also suffer because of this.

scdoc makes writing man pages a lot more pleasant: https://git.sr.ht/~sircmpwn/scdoc https://git.sr.ht/~sircmpwn/scdoc

blueflow 2y ago

Until i use it "wrong" and Drew does the Drew thing with me, like he did with the hyprland guy. No thanks.

packetlost 2y ago
I'm not a fan of Drew's political grandstanding (or views, in some cases) but scdoc is good and packaged in many distros. There's no foundation for him to abuse with it, so it's safe.
- pkal 2y ago
  The IRC bouncer Soju uses scdoc and this has been personally annoying, as I refuse to install it just to build semantically less expressive documentation than when using the very well documented (https://mandoc.bsd.lv/man/mdoc.7.html https://mandoc.bsd.lv/man/mdoc.7.html) mdoc format. I asked the maintainer if they were interested in a contribution to translate it, and they just dismissed it out of the box.
  - packetlost 2y ago
    Who cares how expressive it is? It hits all the core pieces of formatting you can realistically do in a terminal using syntax that is familiar to a much wider range of developers. The output is completely usable and reasonable. I'd rather use something closer to markdown than roff macro gunk that is largely irrelevant anywhere else.

homebrewer 2y ago

adoc is fine and is more widely supported. Linux (the kernel) documentation is written in adoc, along with man pages for many projects like git: https://github.com/git/git/blob/master/Documentation/git-rm.adoc?plain=1 https://github.com/git/git/blob/master/Documentation/git-rm....

packetlost 2y ago
I wasn't aware AsciiDoc could be used to generate man docs. I'm not a huge fan of AsciiDoc's syntax, but I can see that being preferable to other options.
WhyNotHugo 2y ago
Asciidoc doesn't support links in man pages. It can only link to URLs. If you check the repo which you linked, you'll see they use some perl code to actually inject links.

WhyNotHugo 2y ago

I've used it quite a bit. It doesn't support links to other pages nor links to other sections. Which arguably is fine, since man page readers don't render them anyway, but HTML renders also suffer because of this.