Conversation

Notices

1. muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 08:32:05 UTC muesli

   Remind me again, please. What's stopping us from dropping man-pages and their horrible ROFF format?

   We could at least convert them to Markdown and provide a convenient pager that's not stuck in the 70s.

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 08:35:14 UTC muesli

     in reply to

     • murks

     @murks

     The one standard that's actually being used: https://spec.commonmark.org/0.30/

   • murks@social.tchncs.de's status on Friday, 19-Aug-2022 08:35:15 UTC murks

     in reply to

     • muesli

     @fribbledom Which of the hundred variants of markdown?

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 09:05:00 UTC muesli

     in reply to

     There's a reason nobody reads man pages and nobody provides well written man pages anymore: they're horrible, for authors and users alike. They were literally designed to be printed on paper.

     Features I'd expect from a "modern" man system:

     - cross references
     - syntax highlighting
     - search- & browse-ability
     - actionable items
     - anchors

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 09:09:09 UTC muesli

     in reply to

     • murks

     @murks

     GitHub uses CommonMark plus some (fairly well defined) extensions. I don't think the man system would benefit from these extensions tho.

     RST would be another fine format, I guess. Anything but ROFF, really.

   • murks@social.tchncs.de's status on Friday, 19-Aug-2022 09:09:10 UTC murks

     in reply to

     • muesli

     @fribbledom Wouldn't the one variant being used be github flavored markdown?
     Why not go with RST?

   • Digital Mark λ 📚 🕹 💾 🥃 (mdhughes@appdot.net)'s status on Friday, 19-Aug-2022 09:11:16 UTC Digital Mark λ 📚 🕹 💾 🥃

     in reply to

     • muesli

     @fribbledom The Kids Today™ don't read man pages because they weren't taught to use the command line in the first place. For the original UNIX users, `apropos foo` or `man bar` is your first stop.

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 09:11:16 UTC muesli

     in reply to

     • Digital Mark λ 📚 🕹 💾 🥃

     @mdhughes

     I do consider myself one of the "original UNIX users", but honestly... man pages are my absolute last resort.

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 09:18:02 UTC muesli

     in reply to

     • Wolf480pl

     @wolf480pl

     Oh, but I'm not asking to take man pages to the web. Everything I suggest is doable on the terminal, parsed from documentation that's packaged with the software.

   • Wolf480pl (wolf480pl@mstdn.io)'s status on Friday, 19-Aug-2022 09:18:03 UTC Wolf480pl

     in reply to

     • muesli

     @fribbledom
     I find your take outrageous.
     People still read manpages, and some developers still write good ones (see swaywm).

     For me, manpages have been the most natural way to read documentation for the last 10 years. They're way better than a web browser, because I don't have to leave the terminal, they work offline, they document the version you have installed, etc.

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 10:12:19 UTC muesli

     • Ekaitz Zárraga 👹

     @ekaitz_zarraga

     Less horrible than ROFF, yes, but with pretty much the same limitations.

   • Computer Chronicles Revisited (chronrevisited@mastodon.social)'s status on Friday, 19-Aug-2022 13:13:10 UTC Computer Chronicles Revisited

     in reply to

     • muesli

     @fribbledom So basically HyperCard? 😛

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 14:50:15 UTC muesli

     in reply to

     • Andre

     @PCOWandre

     I'm not suggesting moving away from the terminal.

   • Andre (pcowandre@jauntygoat.net)'s status on Friday, 19-Aug-2022 14:50:17 UTC Andre

     in reply to

     • muesli

     @fribbledom Nah. Keep man pages as man pages. The proper documentation is probably in /usr/share anyway.

     I did too much time in machine rooms with no internet access working from a serial terminal on a crash cart to want to use anything else.

     What we *need* is a return to actual decent man pages. The horror of having to touch Linux after a long bout of UNIX -- man pages are missing, outdated or worse, just a stub pointing to other documentation that doesn't exist on the host.

   • muesli (fribbledom@mastodon.social)'s status on Friday, 19-Aug-2022 14:52:37 UTC muesli

     in reply to

     • Andre

     @PCOWandre

     I'd argue Markdown is pretty human-readable - unlike roff.

   • Andre (pcowandre@jauntygoat.net)'s status on Friday, 19-Aug-2022 14:52:38 UTC Andre

     in reply to

     • muesli

     @fribbledom Is there a reasonable markdown implementation that doesn't have a complex dependency chain?

     It is a reasonable assumption that basic documentation should be accessible without reliance on anything outside of a minimal OS install.

   • der.hans (lufthans@mastodon.social)'s status on Saturday, 20-Aug-2022 07:02:08 UTC der.hans

     in reply to

     • muesli

     @fribbledom I read man pages almost every day. Referred to several today during a call

     I also write man pages by converting AsciiDoc to man page format :)

     Updating them as you suggest would still be a good idea

   • Stewart C. Russell (scruss@mastodon.social)'s status on Saturday, 20-Aug-2022 10:58:16 UTC Stewart C. Russell

     in reply to

     • muesli

     @fribbledom "Now we have n+1 documentation standards!"

     Pet peeve: a package whose only documentation is available under `--help` (and not `-h`, for maximal annoyance should only output "please use `--help`") and then dumps pages of too-wide text to the terminal via stderr so you can't immediately pipe it to less

   • Michela Marie 🇨🇦 (michelamarie@mastodon.social)'s status on Saturday, 20-Aug-2022 15:25:10 UTC Michela Marie 🇨🇦

     in reply to

     • muesli

     @fribbledom I read man pages pretty much every day, and I’ve never felt they were missing any features. They are incredibly useful and effective for me.

     As others have pointed out, many of the features you mentioned are already available. I’m the vast majority of Linux and Unix utilities or other programs that I have checked for man pages on over the years have decent ones written for them. I can’t think of a time when I’ve found that a man page did not exist for a Linux or Unix command.

   • theenquirer@mastodon.social's status on Saturday, 20-Aug-2022 22:09:55 UTC TheEnquirer

     in reply to

     • muesli

     @fribbledom idk, I still use man pages a lot just fine lol. I get your point though; sure some people struggle with them.