7 ms·

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain

by stared 7y ago

I would be happy to see such a thing taking off. Typical man pages are well, like learning a language by studying a dictionary, alphabetically. It may contain all information, but a clear F on UX. Some packages get slightly better with starting from the most common use cases, with examples (and digestible errors). However, I would be even more interested to see what is the actual usage pattern (e.g. from .bash_history / .zsh_history). Do you know any datasets with longer such?

stared 7y ago
Also, I see that there are other similar projects: https://www.ostechnix.com/3-good-alternatives-man-pages-every-linux-user-know/ https://www.ostechnix.com/3-good-alternatives-man-pages-ever...
CaptArmchair 7y ago
Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out. tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for each respective use case. tldr won't explain to you what each individual switch, option or argument does, turning the provided commands into black boxes. Here's the trade off: The former has a steep learning curve and figuring out how a tool works doesn't solve your immediate problem. But if you commit the meaning of switches, options and arguments for common tools such as awk, sed, tar, ls,... to memory, you will become proficient at solving any problem with a few tools over time. The latter has a low learning curve and you just have to copy/paste a command to solve your problem. But tldr won't tell you how those switches and options work. And you will just use them as incantations that magically help you to solve a limited number of cases. If you end up with a use case that isn't listed, you are left in the dark as far as tldr is concerned. So, is tldr a bad tool then? No! If you are confronted with the command line sparingly, then tldr helps to lower the bar and solve your immediate problem. But if you hope to grow into a proficient shell user, then you're still going to have to grok the man pages one switch, option and argument at a time. I'm a polyglot. Studying a language by opening a dictionary and starting alphabetically, is arguably, the worst way to get there. You would start with learning a set of common words and basic grammatical rules, and then expand over time through practice and instruction: speaking, reading and writing. The same applies to command line tools and man pages: they are reference materials first and foremost.
- lordgrenville 7y ago
  I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/grep.md https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't see my use-case in tldr I'll move on to the man page. OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)
  - CaptArmchair 7y ago
    > it's pretty clear from the context I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else. > OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :) And I absolutely have no qualms doing the same when push comes to shove. Ain't nobody always got the time. ;-)
    - thrwaway69 7y ago
      I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc. x - extract | f - file | z - operating on tar.gz or similar. Edit: v - verbose
      - b5n 7y ago
        man tar | awk -F , '/-v,/ {print $2}'
      - anjbe 7y ago
        On OpenBSD (and other systems using mandoc as the default “man” program), I can jump to an unknown flag right away with the pager’s tag support: “:tv” -v Verbose operation mode. If -v is specified multiple times or if the -t option is also specified, tar will use a long format for listing files, similar to ls(1) -l. Or I can tack #v onto the end of the web URL: https://man.openbsd.org/tar.1#v https://man.openbsd.org/tar.1#v
reaperducer 7y ago
It may contain all information, but a clear F on UX. What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew? What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of the newer man pages seem inflated and full of jargon to make themselves seem important or worthy.
- wongarsu 7y ago
  I don't think I've encountered anything on Ubuntu that doesn't have a man page, but it also seems like many of the man pages are created or improved by Debian or Ubuntu/Canonical. Homebrew probably wouldn't have those.
  - ilammy 7y ago
    > I don't think I've encountered anything on Ubuntu that doesn't have a man page Ubuntu pull most of its packages from Debian, and Debian Policy says that every package that provides binaries should provide manpages for them as well. It is not a hard requirement but their absence is considered a bug.
- Athas 7y ago
  I have added packages to Homebrew, and they install man pages when available. Homebrew provides a pretty simple mechanism for doing so. The problem is that many projects just prefer web documents to man pages, likely because the man page tooling is not great.
  - dickeytk 7y ago
    and because it doesn't work on windows
- bauerd 7y ago
  Some ecosystems even eschew manpages. For example, I wouldn't know how to ship manpages as part of a Ruby gem, it's discouraged iirc
lynndotpy 7y ago
I'm also interested in a `.bash_history` kind of dataset. If you become aware of this, I'd love to see such a thing.
downerending 7y ago
It's true that the man pages aren't meant to be the primary method of learning Unix. But they are indeed a spectacular and irreplaceable resource. One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.
- tingletech 7y ago
  I was a bio major who would hang out in rooms with terminals in the early 90s. One day I saw “type ‘man man’” and “apropos” written on a chalk board. That is how I learned Unix.
  - JdeBP 7y ago
    Interestingly, actual bona fide AT&T System 5 Release 3 Unix had a "help" command, which was a full-screen menu-driven interactive help system. * https://unix.stackexchange.com/a/448799/5132 https://unix.stackexchange.com/a/448799/5132 There was also "learn", in BSD as I recall.
deleted 7y ago
[deleted]
chousuke 7y ago
This is sadly the case with lots of Linux tools, but it's not really man's fault. Next time you need help with a UNIX tool, try reading the OpenBSD man page instead and see how it compares.

by stared 7y ago

stared 7y ago

Also, I see that there are other similar projects: https://www.ostechnix.com/3-good-alternatives-man-pages-every-linux-user-know/ https://www.ostechnix.com/3-good-alternatives-man-pages-ever...

CaptArmchair 7y ago

Man pages are intended to be an exhaustive description of the individual options, switches and command arguments and what they do; but they won't tell you how to combine those to be useful in your particular case. It's up to you to figure that out. tldr caters to an entirely different heuristic: I have this use case, give me a list of use cases and the corresponding combination of switches, options and arguments for each respective use case. tldr won't explain to you what each individual switch, option or argument does, turning the provided commands into black boxes. Here's the trade off: The former has a steep learning curve and figuring out how a tool works doesn't solve your immediate problem. But if you commit the meaning of switches, options and arguments for common tools such as awk, sed, tar, ls,... to memory, you will become proficient at solving any problem with a few tools over time. The latter has a low learning curve and you just have to copy/paste a command to solve your problem. But tldr won't tell you how those switches and options work. And you will just use them as incantations that magically help you to solve a limited number of cases. If you end up with a use case that isn't listed, you are left in the dark as far as tldr is concerned. So, is tldr a bad tool then? No! If you are confronted with the command line sparingly, then tldr helps to lower the bar and solve your immediate problem. But if you hope to grow into a proficient shell user, then you're still going to have to grok the man pages one switch, option and argument at a time. I'm a polyglot. Studying a language by opening a dictionary and starting alphabetically, is arguably, the worst way to get there. You would start with learning a set of common words and basic grammatical rules, and then expand over time through practice and instruction: speaking, reading and writing. The same applies to command line tools and man pages: they are reference materials first and foremost.

lordgrenville 7y ago
I frequently use TLDR, and I wouldn't describe it as an incantation. It's for the case where, say, I know there's a grep flag for inverse match or case-insensitive, but don't use it often enough to remember it. It surfaces the (community-driven) top use cases, and it's pretty clear from the context what the flags are doing. (As seen here: https://github.com/tldr-pages/tldr/blob/master/pages/common/grep.md https://github.com/tldr-pages/tldr/blob/master/pages/common/... ) If I don't see my use-case in tldr I'll move on to the man page. OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :)
- CaptArmchair 7y ago
  > it's pretty clear from the context I think that largely depends on who's using the tools and how acquainted they are with command line tools. An absolute beginner likely will not know what tar's 'f' flag does, or assume something else. > OTOH, sometimes I'll copy-paste some perl or awk dark magic from Stack Overflow, and then try modify it piecemeal to fit my case. That's an incantation :) And I absolutely have no qualms doing the same when push comes to shove. Ain't nobody always got the time. ;-)
  - thrwaway69 7y ago
    I will bite - I have been using linux for 4 years. I have used tar a lot and I don't know what v means. I switch between -xvf, -xvz, etc. x - extract | f - file | z - operating on tar.gz or similar. Edit: v - verbose
    - b5n 7y ago
      man tar | awk -F , '/-v,/ {print $2}'
    - anjbe 7y ago
      On OpenBSD (and other systems using mandoc as the default “man” program), I can jump to an unknown flag right away with the pager’s tag support: “:tv” -v Verbose operation mode. If -v is specified multiple times or if the -t option is also specified, tar will use a long format for listing files, similar to ls(1) -l. Or I can tack #v onto the end of the web URL: https://man.openbsd.org/tar.1#v https://man.openbsd.org/tar.1#v

reaperducer 7y ago

It may contain all information, but a clear F on UX. What I find annoying is the number of command line programs that don't even have man pages anymore. Or maybe that's just an artifact of installing them with brew? What I find interesting is that for the most part (there are exceptions), the older the man page, the more useful it is. Realistic examples. Succinct descriptions. User-friendly terminology. Too many of the newer man pages seem inflated and full of jargon to make themselves seem important or worthy.

wongarsu 7y ago
I don't think I've encountered anything on Ubuntu that doesn't have a man page, but it also seems like many of the man pages are created or improved by Debian or Ubuntu/Canonical. Homebrew probably wouldn't have those.
- ilammy 7y ago
  > I don't think I've encountered anything on Ubuntu that doesn't have a man page Ubuntu pull most of its packages from Debian, and Debian Policy says that every package that provides binaries should provide manpages for them as well. It is not a hard requirement but their absence is considered a bug.
Athas 7y ago
I have added packages to Homebrew, and they install man pages when available. Homebrew provides a pretty simple mechanism for doing so. The problem is that many projects just prefer web documents to man pages, likely because the man page tooling is not great.
- dickeytk 7y ago
  and because it doesn't work on windows
bauerd 7y ago
Some ecosystems even eschew manpages. For example, I wouldn't know how to ship manpages as part of a Ruby gem, it's discouraged iirc

lynndotpy 7y ago

I'm also interested in a `.bash_history` kind of dataset. If you become aware of this, I'd love to see such a thing.

downerending 7y ago

It's true that the man pages aren't meant to be the primary method of learning Unix. But they are indeed a spectacular and irreplaceable resource. One of the best things that ever happened in my career was having a desk across from the entire SunOS manual set. I'd pull them down one at a time and read them, cover to cover. It paid off, big time, and I strongly recommend it.

tingletech 7y ago
I was a bio major who would hang out in rooms with terminals in the early 90s. One day I saw “type ‘man man’” and “apropos” written on a chalk board. That is how I learned Unix.
- JdeBP 7y ago
  Interestingly, actual bona fide AT&T System 5 Release 3 Unix had a "help" command, which was a full-screen menu-driven interactive help system. * https://unix.stackexchange.com/a/448799/5132 https://unix.stackexchange.com/a/448799/5132 There was also "learn", in BSD as I recall.

deleted 7y ago

[deleted]

chousuke 7y ago

This is sadly the case with lots of Linux tools, but it's not really man's fault. Next time you need help with a UNIX tool, try reading the OpenBSD man page instead and see how it compares.