4 ms·

But the various man source formats aren't semantic markup of any particular use. Yeah, you can ensure that all of your arguments are typeset as italic or someth

But the various man source formats aren't semantic markup of any particular use. Yeah, you can ensure that all of your arguments are typeset as italic or something, but it's not consistent because there are different source macro packages and they do different things. If there was useful semantic markup, it'd be great, because you could imagine, for example, tools allowing you to generate commands on the user's behalf. But the man source formats are mostly, at core, typesetting for 70's typesetting machines, not intended for modern reference documentation.

bentley 1y ago
mdoc(7), which is the primary macro set used on BSD systems, is a 90s language (as opposed to a 70s language) with useful semantics that support both hyperlinking and featureful search, both on the web and in the terminal. For example, here’s a search for “C functions beginning with ‘str’ and with return type size_t”: https://man.openbsd.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropos=1&sec=3 https://man.openbsd.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropo... On OpenBSD you can do the same from a terminal: $ apropos -s 3 Ft=size_t -a Nm~^str But the biggest value of manpages to me is somewhat independent of the underlying format: its quality as documentation. BSD systems have a strong tradition of cohesive usability, including good manpages. A lot of the manpage alternatives I see advertised in Linux circles (such as tldr pages or bro pages) are of little use to me, because OpenBSD manuals are thoughtfully written, clear, concise, complete, and have useful examples. The difference is very noticeable when I try reading manpages for programs I’ve installed from packages, which are often incredibly sparse or incredibly verbose, and lack examples in both cases. The nifty features that come from the modern language and tooling used by BSD manpages are really just symptomatic of the overall care that BSD communities put into their documentation generally. I wish it were more widespread in the free software world.
- juped 1y ago
  "whatis -O In [some c library function]" is a very handy one
  - bentley 1y ago
    That’s way better than my example!

bentley 1y ago

mdoc(7), which is the primary macro set used on BSD systems, is a 90s language (as opposed to a 70s language) with useful semantics that support both hyperlinking and featureful search, both on the web and in the terminal. For example, here’s a search for “C functions beginning with ‘str’ and with return type size_t”: https://man.openbsd.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropos=1&sec=3 https://man.openbsd.org/?query=Ft%3Dsize_t+-a+Fn~^str&apropo... On OpenBSD you can do the same from a terminal: $ apropos -s 3 Ft=size_t -a Nm~^str But the biggest value of manpages to me is somewhat independent of the underlying format: its quality as documentation. BSD systems have a strong tradition of cohesive usability, including good manpages. A lot of the manpage alternatives I see advertised in Linux circles (such as tldr pages or bro pages) are of little use to me, because OpenBSD manuals are thoughtfully written, clear, concise, complete, and have useful examples. The difference is very noticeable when I try reading manpages for programs I’ve installed from packages, which are often incredibly sparse or incredibly verbose, and lack examples in both cases. The nifty features that come from the modern language and tooling used by BSD manpages are really just symptomatic of the overall care that BSD communities put into their documentation generally. I wish it were more widespread in the free software world.

juped 1y ago
"whatis -O In [some c library function]" is a very handy one
- bentley 1y ago
  That’s way better than my example!