8 ms·

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentatio

A heartfelt plea: The man pages are community driven, too. If you think they can be improved, instead of investing in rapidly decaying third-party documentation, please take your improvements upstream. The maintainers would be thrilled to have them.

overcast 7y ago
It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.
- vmchale 7y ago
  On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.
- spenczar5 7y ago
  Do you have examples of that refusal? I'm unfamiliar.
  - edw 7y ago
    Based on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed. While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool. I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor. Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.
    - kbenson 7y ago
      The more complex a tool, the less likely a man page is going to be a good way to distill and impart the information of how to use it. Bash's mane page is so large I can almost never find what I'm looking for. At the same time, that means a TL;DR type page is also likely to be useless. For the vast majority of software run from a shell, a man page is sufficient, and examples can be (and often are) added to good effect. I will note that some projects split very large man pages into sub-pages, and that can work well. For example, ip, and much of the man pages on BSDs that explain how different technologies are implemented (for example, follow the references in the man page for ifconfig on OpenBSD).
  - overcast 7y ago
    By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.
- fluidcruft 7y ago
  Doesn't GNU still scoff at man pages and foist texinfo? Honestly who wants to waste their time with roff etc? The focus has been making it easier for the developers to write literally anything. One thing uses sphynx another uses man another uses doxygen or what the hell ever. Users aren't developers. This is why everyone ends up on google and ends up on stackoverflow or random blog or watching youtube. The barrier to entry is much lower with some simple markdown thing. Hell, I was thinking about how to abuse this thing to make my own notes about commands.
  - aktau 7y ago
    I maintain my man pages in markdown format, and convert them to roff at build time. There are plenty of tools that can do that: pandoc(1), ronn(1), ...
- JoshTriplett 7y ago
  The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.
  - overcast 7y ago
    I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.
    - tylerchilds 7y ago
      I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.
      - overcast 7y ago
        Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.
        Darkphibre 7y ago
        Back in 2000-2005 I worked on the SQL Server documentation. If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying on wordy explanations.
        7y ago
- jeltz 7y ago
  Doesn't each project maintain its own man pages? There is a huge variation in quality between them with some being excellent while others are lacking. Have you tried talking to any of the projects?
- b5n 7y ago
  I use manpages frequently, seems easier to learn how to read manpages than create a new project dedicated to adding examples to manpages. I find them incredibly user friendly, but I cared enough to learn how to use them.
- munk-a 7y ago
  I dunno, the TLDR page highlighted tar which seems a bit odd since tar has always gone out of its way to have a very strong and useful manpage - specifically having several examples[1] at the top of the page before diving into all the intricacies of the arguments. 1. Including tar -cf and tar -xf probably the two you want to run in most cases. See: https://linux.die.net/man/1/tar https://linux.die.net/man/1/tar
  - Jaepa 7y ago
    I'd guess this is a xkcd reference. https://www.xkcd.com/1168/ https://www.xkcd.com/1168/
nathias 7y ago
it's not the same use-case, manpages are detailed instructions, tldr is just the 7 most used commands
- hellcow 7y ago
  manpages often have an examples section on OpenBSD showcasing different ways to use programs. It can be done...
Semiapies 7y ago
How is this "rapidly decaying third-party documentation" in any way that man isn't?
- glckr 7y ago
  man is universally known in the industry, and supported (to some extent, at least) by project authors/maintainers; this project will be forgotten by almost everyone (and start decaying) as soon as this post is off the front page here.
  - skybrian 7y ago
    They're often used, but I suspect most people who read them don't know how to write or even modify a man page. (What format is it?) Also, Stack Overflow probably gets more traffic. Whether documentation gets read or not probably depends on its Google ranking more than anything.
  - kick 7y ago
    This is the second time it's been on the front page, and the last time was years ago. Doesn't seem to be decaying. Actually, it seems to be improving.
- tyrust 7y ago
  man pages are first-party, are they not?
  - Semiapies 7y ago
    Documentation by the makers of a program would be first-party. Something definitely can't be both first-party and community.
nebulous1 7y ago
Ideally this information would be controlled by the individual package maintainers, I agree. However, realistically at the moment I don't see man pages competing with the spirit of tldr/bro/whatever, and I suspect that PRs geared towards making them compete would in fact be rejected by most projects.
jlg23 7y ago
Yes. The given example shows exactly what I would expect in the EXAMPLES section of a man page anyways. If not, it's worth a patch.
topspin 7y ago
> The maintainers would be thrilled to have them. Would they? The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion. Should this TLDR thing correct that long standing mistake I'm all for it. Also, info is one of the most hostile TUI programs I've ever encountered and I resent using it. [1] https://unix.stackexchange.com/questions/306189/why-dont-man-pages-have-examples https://unix.stackexchange.com/questions/306189/why-dont-man...
- smhenderson 7y ago
  I'm aware of GBU's preference for info but systems vary. Just to use your example, I'm typing this on Slackware and when I pull up man tar there are three examples, right after Synopsis and Description. Examples for extracting, both gzipped and regular archives, and creating a tar file are given. And when I shell into an OpenBSD server their man page for tar has several examples at the bottom of the page. Man, IMO, is a lot like Linux distros in that they are not all created equal, pull from a lot of different sources and can be inconsistent if you're not looking at the correct ones for whatever system you are on. I too think TLDR is a good idea but that's no reason not to encourage that some of their work be ported back to man pages in their examples' sections.
  - topspin 7y ago
    A quick survey of GNU tar man pages, by program version and the date that appears in the page itself: 1.23 March, 2012: no examples (RHEL 6) 1.26 March, 2015: no examples (OpenSUSE 13.1) 1.26 February, 2016: no examples (CentOS 7) 1.29 March, 2016: limited examples (Ubuntu 1804) The last has no actual "EXAMPLES" section in the man page; only some incidental examples appearing among a discussion of "Option styles." I suspect this is also what you see; it's in the same position in the page. So there is some evidence that examples aren't entirely prohibited in GNU man pages, at least in recent years. Progress, I guess. The latest work on this man page (release 1.32) shows no further progress. TLDR goes well beyond those incidental examples and is far closer to what I'd hope to see; first class, worked example forms eagerly supplied. Without suffering info.
diebeforei485 7y ago
No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense. Improvements to man pages should be made, but not at the cost of beginner-friendly projects.
- joshklein 7y ago
  > they serve two different purposes I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.
  - beefhash 7y ago
    That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere. For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen. Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzonsons.pdf https://www.usenix.org/system/files/login/articles/141-dzons...
    - anjbe 7y ago
      > That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor Sudo supports such systems even though its manuals are written in mdoc. The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format. Then at build time one format or the other will be installed depending on how capable the system manpage formatter is. Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.
Brave-Steak 7y ago
Yeah, no. The use cases for man and tldr are completely different, and trying to convince every single project to make their man pages more friendly to people who just want to get their work done is just ... well, an impossible amount of effort. tldr coalesces a community around a common goal, and they can work towards that goal without fighting hundreds of different maintainers on making man pages more accessible.
mongol 7y ago
It would be interesting to take a step back and consider what man pages actually are. Are they documentation structured in a specific way, dating back to Unix origins, or are they what the user sees if they type "man command" on the command line? Because if we consider the latter, I think it will be much easier to see radical improvement of the "man experience" If I type "man ps" I see Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this) * ps (1) ps (1p) Man: What manual page do you want? What if I instead saw Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this) * ps (1) ps (1.tldr) ps (1p) Man: What manual page do you want? where the man command retrieved that information from the TLDR-pages site? In the last years we have seen many innovative Rust re-implementations of classical commands such as cat, find, grep. Maybe the man command is next up?
- teddyh 7y ago
  man apropos
dylanz 7y ago
+1 ... we should be working on improving "the actual" man pages. There is an "Examples" section in OpenBSD man pages that help out quite a bit. I'd rather have one definitive place for man pages (rather than many), and I'd rather have them be accessible from the OS (and not require an internet connection).
bananamerica 7y ago
manpages would be awesome if more pages had examples. Since they don't, we use bropages, tldr, etc.
jakeogh 7y ago
To really improve them, the man format needs to be changed. For example, those blue underlined words... they arent links. Markdown (or better, a subset) would work.
pwrplus1 7y ago
And many (or most) of the TLDR project pages are wrong because they refer to the GNU-variant reimplementation instead of the actual tool. With a man page you know you're getting the right info because it came bundled with the tool.
TheKarateKid 7y ago
Given the general attitude of the GNU/Linux community, I could see most examples/edits being rejected with elitists saying "RTFM!" Remember, these are the same people that claim the Emacs and Vim are better to code in, and that IDEs are for inexperienced/lazy coders.

overcast 7y ago

It seems like the maintainers of man pages just refuse to bother with something so obvious. It's been decades, and man pages are still archaic and not user friendly.

vmchale 7y ago
On Linux that has been my experience. man pages on Mac are a little better, I've heard the BSDs do better as well.
spenczar5 7y ago
Do you have examples of that refusal? I'm unfamiliar.
- edw 7y ago
  Based on my experience, the problem may be that man pages are often not where one learns how to use a tool. I still remember from long, long ago when I told a greybeard that I was trying to learn sed by reading the man page. He replied, "God help you," and guffawed. While some man pages have examples, I don't know if man page writers see their job as teaching readers how to use a utility. The goal of man pages more often seems to be _reminding_ a person already familiar with the tool how to use a tool. I'm, umm, _reminded_ of project READMEs. I've come to assume that when I go to a project on GitHub, I'm going to get everything I need (or pointers to everything I need) to get started with a project, but often there's a project web site that is intended to serve that purpose. I just ran into this yesterday with Falcor. Not all man pages are like this obviously. Specifically, the section three man pages on C functions do a good job fully documenting functions.
  - kbenson 7y ago
    The more complex a tool, the less likely a man page is going to be a good way to distill and impart the information of how to use it. Bash's mane page is so large I can almost never find what I'm looking for. At the same time, that means a TL;DR type page is also likely to be useless. For the vast majority of software run from a shell, a man page is sufficient, and examples can be (and often are) added to good effect. I will note that some projects split very large man pages into sub-pages, and that can work well. For example, ip, and much of the man pages on BSDs that explain how different technologies are implemented (for example, follow the references in the man page for ifconfig on OpenBSD).
- overcast 7y ago
  By virtue of the fact that TLDR and bropages exist? People are creating 3rd party solutions, because no one does anything with man pages.
fluidcruft 7y ago
Doesn't GNU still scoff at man pages and foist texinfo? Honestly who wants to waste their time with roff etc? The focus has been making it easier for the developers to write literally anything. One thing uses sphynx another uses man another uses doxygen or what the hell ever. Users aren't developers. This is why everyone ends up on google and ends up on stackoverflow or random blog or watching youtube. The barrier to entry is much lower with some simple markdown thing. Hell, I was thinking about how to abuse this thing to make my own notes about commands.
- aktau 7y ago
  I maintain my man pages in markdown format, and convert them to roff at build time. There are plenty of tools that can do that: pandoc(1), ronn(1), ...
JoshTriplett 7y ago
The maintainer of the manpages project, Michael Kerrisk, is quite responsive and interested in improvements. I've generally found the maintainers of other software to be receptive to documentation patches, as well.
- overcast 7y ago
  I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.
  - tylerchilds 7y ago
    I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.
    - overcast 7y ago
      Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.
      - Darkphibre 7y ago
        Back in 2000-2005 I worked on the SQL Server documentation. If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying on wordy explanations.
        7y ago
jeltz 7y ago
Doesn't each project maintain its own man pages? There is a huge variation in quality between them with some being excellent while others are lacking. Have you tried talking to any of the projects?
b5n 7y ago
I use manpages frequently, seems easier to learn how to read manpages than create a new project dedicated to adding examples to manpages. I find them incredibly user friendly, but I cared enough to learn how to use them.
munk-a 7y ago
I dunno, the TLDR page highlighted tar which seems a bit odd since tar has always gone out of its way to have a very strong and useful manpage - specifically having several examples[1] at the top of the page before diving into all the intricacies of the arguments. 1. Including tar -cf and tar -xf probably the two you want to run in most cases. See: https://linux.die.net/man/1/tar https://linux.die.net/man/1/tar
- Jaepa 7y ago
  I'd guess this is a xkcd reference. https://www.xkcd.com/1168/ https://www.xkcd.com/1168/

nathias 7y ago

it's not the same use-case, manpages are detailed instructions, tldr is just the 7 most used commands

hellcow 7y ago
manpages often have an examples section on OpenBSD showcasing different ways to use programs. It can be done...

Semiapies 7y ago

How is this "rapidly decaying third-party documentation" in any way that man isn't?

glckr 7y ago
man is universally known in the industry, and supported (to some extent, at least) by project authors/maintainers; this project will be forgotten by almost everyone (and start decaying) as soon as this post is off the front page here.
- skybrian 7y ago
  They're often used, but I suspect most people who read them don't know how to write or even modify a man page. (What format is it?) Also, Stack Overflow probably gets more traffic. Whether documentation gets read or not probably depends on its Google ranking more than anything.
- kick 7y ago
  This is the second time it's been on the front page, and the last time was years ago. Doesn't seem to be decaying. Actually, it seems to be improving.
tyrust 7y ago
man pages are first-party, are they not?
- Semiapies 7y ago
  Documentation by the makers of a program would be first-party. Something definitely can't be both first-party and community.

nebulous1 7y ago

Ideally this information would be controlled by the individual package maintainers, I agree. However, realistically at the moment I don't see man pages competing with the spirit of tldr/bro/whatever, and I suspect that PRs geared towards making them compete would in fact be rejected by most projects.

jlg23 7y ago

Yes. The given example shows exactly what I would expect in the EXAMPLES section of a man page anyways. If not, it's worth a patch.

topspin 7y ago

> The maintainers would be thrilled to have them. Would they? The tldr.sh site prominently offers a sample of usage examples for a command; tar specifically. If one checks the tar man page there are no examples. This is policy, apparently promulgated by GNU et al. in favor of "info". I haven't the time right now to hunt down the official position, but here[1] is a SO discussion. Should this TLDR thing correct that long standing mistake I'm all for it. Also, info is one of the most hostile TUI programs I've ever encountered and I resent using it. [1] https://unix.stackexchange.com/questions/306189/why-dont-man-pages-have-examples https://unix.stackexchange.com/questions/306189/why-dont-man...

smhenderson 7y ago
I'm aware of GBU's preference for info but systems vary. Just to use your example, I'm typing this on Slackware and when I pull up man tar there are three examples, right after Synopsis and Description. Examples for extracting, both gzipped and regular archives, and creating a tar file are given. And when I shell into an OpenBSD server their man page for tar has several examples at the bottom of the page. Man, IMO, is a lot like Linux distros in that they are not all created equal, pull from a lot of different sources and can be inconsistent if you're not looking at the correct ones for whatever system you are on. I too think TLDR is a good idea but that's no reason not to encourage that some of their work be ported back to man pages in their examples' sections.
- topspin 7y ago
  A quick survey of GNU tar man pages, by program version and the date that appears in the page itself: 1.23 March, 2012: no examples (RHEL 6) 1.26 March, 2015: no examples (OpenSUSE 13.1) 1.26 February, 2016: no examples (CentOS 7) 1.29 March, 2016: limited examples (Ubuntu 1804) The last has no actual "EXAMPLES" section in the man page; only some incidental examples appearing among a discussion of "Option styles." I suspect this is also what you see; it's in the same position in the page. So there is some evidence that examples aren't entirely prohibited in GNU man pages, at least in recent years. Progress, I guess. The latest work on this man page (release 1.32) shows no further progress. TLDR goes well beyond those incidental examples and is far closer to what I'd hope to see; first class, worked example forms eagerly supplied. Without suffering info.

diebeforei485 7y ago

No, they serve two different purposes. Man pages are a reference/spec on all options and parameters, aimed at those who already have use a tool/technology/concept. This is something different. It's a tutorial of how to do the most common things using that tool. It's a bit like learning a programming language: would you read the formal spec, or would you learn from code examples? Unless you've read formal specs for other languages with a similar paradigm before, it's way easier to learn from examples first, which gets you to the level of understanding where the formal specs start to make sense. Improvements to man pages should be made, but not at the cost of beginner-friendly projects.

joshklein 7y ago
> they serve two different purposes I agree, but I'm also painfully aware of man page incompleteness every time I'm on a non-OpenBSD system. I'd be grateful to anyone who chipped away at proper tagging for any GNU software. One should be able to :t to jump to the reference for any flag.
- beefhash 7y ago
  That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor and don't use mandoc (which is... exactly only AIX and HP-UX at this point), so they write all their text in man so that they render correctly everywhere. For tagging, the formatting would need to be redone to be mdoc, which breaks both the OSes mentioned above and would be an immensely arduous task at this point. Probably not going to happen. Note GNU and and the Linux man-pages project are mostly outliers; everyone else that lives in BSD/illumos land has long since moved on to mdoc since like the 80s. See also https://www.usenix.org/system/files/login/articles/141-dzonsons.pdf https://www.usenix.org/system/files/login/articles/141-dzons...
  - anjbe 7y ago
    > That's impossible by means of how they're written. GNU still cares about operating systems that don't bundle the mdoc macros with their troff processor Sudo supports such systems even though its manuals are written in mdoc. The source tarball contains both the original mdoc manuals and man manuals, autogenerated by mandoc (https://mandoc.bsd.lv https://mandoc.bsd.lv) which can convert mdoc to man—easy to do, since mdoc is a semantic format. Then at build time one format or the other will be installed depending on how capable the system manpage formatter is. Any project using mdoc pages could do the same thing. Projects using autotools could even copy Sudo’s autoconf macros for this.

Brave-Steak 7y ago

Yeah, no. The use cases for man and tldr are completely different, and trying to convince every single project to make their man pages more friendly to people who just want to get their work done is just ... well, an impossible amount of effort. tldr coalesces a community around a common goal, and they can work towards that goal without fighting hundreds of different maintainers on making man pages more accessible.

mongol 7y ago

It would be interesting to take a step back and consider what man pages actually are. Are they documentation structured in a specific way, dating back to Unix origins, or are they what the user sees if they type "man command" on the command line? Because if we consider the latter, I think it will be much easier to see radical improvement of the "man experience" If I type "man ps" I see Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this) * ps (1) ps (1p) Man: What manual page do you want? What if I instead saw Man: find all matching manual pages (set MAN_POSIXLY_CORRECT to avoid this) * ps (1) ps (1.tldr) ps (1p) Man: What manual page do you want? where the man command retrieved that information from the TLDR-pages site? In the last years we have seen many innovative Rust re-implementations of classical commands such as cat, find, grep. Maybe the man command is next up?

teddyh 7y ago
man apropos

dylanz 7y ago

+1 ... we should be working on improving "the actual" man pages. There is an "Examples" section in OpenBSD man pages that help out quite a bit. I'd rather have one definitive place for man pages (rather than many), and I'd rather have them be accessible from the OS (and not require an internet connection).

bananamerica 7y ago

manpages would be awesome if more pages had examples. Since they don't, we use bropages, tldr, etc.

jakeogh 7y ago

To really improve them, the man format needs to be changed. For example, those blue underlined words... they arent links. Markdown (or better, a subset) would work.

pwrplus1 7y ago

And many (or most) of the TLDR project pages are wrong because they refer to the GNU-variant reimplementation instead of the actual tool. With a man page you know you're getting the right info because it came bundled with the tool.

TheKarateKid 7y ago

Given the general attitude of the GNU/Linux community, I could see most examples/edits being rejected with elitists saying "RTFM!" Remember, these are the same people that claim the Emacs and Vim are better to code in, and that IDEs are for inexperienced/lazy coders.