4 ms·

I'd argue that (1) manpages are for humans to read, and (2) there is effectively only one presentation style for the conveying the semantic contents. So as long

by tkfu 9y ago

I'd argue that (1) manpages are for humans to read, and (2) there is effectively only one presentation style for the conveying the semantic contents. So as long as the author of the manpage follows the standard conventions for manpage presentation style, they are in fact expressing the semantics. And it's a lot easier to learn the conventions (flags in bold, arguments in italics, etc.) and write them in lightweight markup than it is to learn roff.

opk 9y ago
Semantic markup has more uses than just consistent presentation. For example, most of the BSD's use mandoc rather than groff for rendering which allows you to do more detailed searches with apropos. Note that the linked article refers to the mdoc macros. These aren't especially new and are very well supported but the man macros are still more common. If you dig into the details, the mdoc macros have many advantages.
- deleted 9y ago
  [deleted]
- JdeBP 9y ago
  Using mandoc instead of groff is a bit of a step backwards, note. grotty is capable of ECMA-48:1976 and ISO 8613-6:1994 control sequences, and can actually do proper italicization, boldface, underline, and colour in manual pages; which many terminals nowadays have supported for decades. * https://jdebp.eu/Softwares/nosh/italics-in-manuals.html https://jdebp.eu/Softwares/nosh/italics-in-manuals.html mandoc still only knows the old 1960s TTY-37 control sequences that use overstrike for boldface and underline and that have no notion of italicization or colour. When FreeBSD switched from groff to mandoc, I went looking for any way to have mandoc support ECMA-48:1976 and ISO 8613-6:1994 control sequences. It turned out to be a large amount of work to bring it up to parity with something that the GNU toolchain has had since the 1990s (and is in fact the GNU toolchain's native mode of operation).
  - jwilk 9y ago
    > one has to employ the MANROFFOPT environment variable, setting it to "-P-i". This didn't work for me (Debian unstable), because man called nroff, which doesn't understand the -P option. So I put DEFINE troff groff -mandoc -P-i DEFINE nroff groff -mandoc -P-i in /etc/manpath.config . This did the trick, but I'm not sure it didn't break something else.
    - JdeBP 9y ago
      Aha! A typing error. One should set it to -- -P-i Note the -- option. This causes nroff to just pass the -P-i option straight through to groff.

by tkfu 9y ago

opk 9y ago

Semantic markup has more uses than just consistent presentation. For example, most of the BSD's use mandoc rather than groff for rendering which allows you to do more detailed searches with apropos. Note that the linked article refers to the mdoc macros. These aren't especially new and are very well supported but the man macros are still more common. If you dig into the details, the mdoc macros have many advantages.

deleted 9y ago
[deleted]
JdeBP 9y ago
Using mandoc instead of groff is a bit of a step backwards, note. grotty is capable of ECMA-48:1976 and ISO 8613-6:1994 control sequences, and can actually do proper italicization, boldface, underline, and colour in manual pages; which many terminals nowadays have supported for decades. * https://jdebp.eu/Softwares/nosh/italics-in-manuals.html https://jdebp.eu/Softwares/nosh/italics-in-manuals.html mandoc still only knows the old 1960s TTY-37 control sequences that use overstrike for boldface and underline and that have no notion of italicization or colour. When FreeBSD switched from groff to mandoc, I went looking for any way to have mandoc support ECMA-48:1976 and ISO 8613-6:1994 control sequences. It turned out to be a large amount of work to bring it up to parity with something that the GNU toolchain has had since the 1990s (and is in fact the GNU toolchain's native mode of operation).
- jwilk 9y ago
  > one has to employ the MANROFFOPT environment variable, setting it to "-P-i". This didn't work for me (Debian unstable), because man called nroff, which doesn't understand the -P option. So I put DEFINE troff groff -mandoc -P-i DEFINE nroff groff -mandoc -P-i in /etc/manpath.config . This did the trick, but I'm not sure it didn't break something else.
  - JdeBP 9y ago
    Aha! A typing error. One should set it to -- -P-i Note the -- option. This causes nroff to just pass the -P-i option straight through to groff.