4 ms·

The man pages are the worst form of information ever for anybody trying to really solve any real-life problem which is not specified as "learn all unnecessary s

by acqq 7y ago

The man pages are the worst form of information ever for anybody trying to really solve any real-life problem which is not specified as "learn all unnecessary switches and once-useful but used-by-nobody-today options of a command X." It happened to me often enough that even when I knew what I wanted to achieve and which command X could do that I would first try to read darned man page and fail to find the solution, but then just googling gave enough of material to a) have something to try b) have a discussion of the cases where that "something" doesn't fulfill the use most use cases of those who asked (the "natural need") including, of course, the use case I've had. I have a completely opposite attitude. Bash is horrible on many levels. Bash man page is only a part of horribleness. The main problem for all man pages is that they are mostly as if written for those who already know about every unnecessary detail of both the tool in question and all related tools or environmental issues, but who searches for some even more obscure detail among all obscure details that they already know. Not to mention the descriptions that aren't: e.g. the complete explanation of the option --frob-blonk FILE would be something like "this option uses the FILE as the frob blonk" oh, how helpful. I use bash every day, but I've at least managed to reduce its use to the minimum that keeps me still sane.

mFixman 7y ago
Skimming the bash manpage every once in a while is important to stay out of information bubbles. There are too many developers who rely only on Google/Stack Overflow to find and write answers to questions, and it's common to repeat bad, incomplete, or outdated information. I can think of a lot of times when the most accepted SO answer for many questions was "copy and paste this gigantic block of code" instead of using an existing command.
- acqq 7y ago
  Most of information there is not worth having in my "brain cache" at all, and especially not worth refreshing it regularly. Life is too short to even trying to remember the things like what's the difference between .bash_profile .profile .bashrc .inputrc and .bash_login (bonus point for remembering what is redirected to what in the files themselves in which distribution) or what the hell is a "login shell" and what is not. And there are many such details that are effectively useless for 99.99% of the users but they just have to survive the suffering to fix the darn thing when they have some issue. I'm sure even most of the readers here can't give a one line answer what is the "right" and "general" way to preset a darn variable for a shell. By design of all these artifacts we work with, it necessarily leads to a page-length discussion of which shells exist and what their differences are and whatnot. Such a waste of everybody's mental energy on a global level.
  - 0xADEADBEE 7y ago
    I think it's a bit unfair you're being downvoted because you raise some good points. A lot of people agree POSIX is a mess and you've highlighted a fraction of reasons related to that. Would any of the downvoters care to elucidate? Maybe I'm missing something obvious.
    - __del__ 7y ago
      Not a downvoter, but I assume the reason is that many people do understand these mechanisms without evicting too much from their brain cache. Files like .bash_profile, .bash_login, .profile, .zprofile, /etc/profile, /etc/profile.d/whatever.sh all serve the same purpose, the primary aspect of which is to apply things like environment variables at login. Display managers and [login] shells source these things in a predictable precedence order so that environment variables are correctly inherited by children of GUI environment processes and login shells. Login shells? Well yeah, the point of a login shell is that it invokes login-related tasks like setting environment variables from a profile. That's intentionally separate from the behavior of interactive shells because the environments of interactive shells may have been modified intentionally and shouldn't be "reset" to the values applied at login. edit: also .inputrc is the readline configuration file for things like shortcut keys in all programs which use readline (not just bash) and .bashrc is for customizations specific to interactive shells
      - acqq 7y ago
        You see I’ve read this kind of information in exactly the words you use more than once and I still can’t summarize in one sentence where should one put his variables for things to “just work.” Locally for one user. Provided I just don’t know and don’t even care what the differences between the login and interactive shells are and that I just run the whatever terminal it is default from the GUI menu (whichever GUI it is). And your explanation what the differences are is for me still circular, exactly like in the man pages: login shell is the one which invokes login-related tasks, and I should care about the difference from the interactive shells. I still have no idea what that even means, it is what exactly happens when? Anybody knows some sane explanation of these? I admit I never tried to find it, as I tried to read the man pages, didn't find anything reasonable, but knew that it doesn't matter to me. I just want the darn variables to exists whenever I need them. I don't care about the differences. One single place is enough. But now that you say that you "do understand these mechanisms without evicting too much from" your "brain cache" I'd really like to learn everything about the differences. Specifically, when is one invoked and when another for the user "acqq", let's say, on a default Ubuntu system, and on a default Red Hat system? Are really more different user shells invoked in different forms for a single user, on a single machine, between the booting of the machine, logging in (in GUI) and then starting a few times the terminal with shell inside? When is invoked and which is invoked when? And why shouldn't be a single place for the variables I want to define? No idea, but I would be grateful to read about it now. Thanks in advance.
- frereubu 7y ago
  I see where you're coming from, but I think it's the attitude of the developer that's more important. I've learned a good deal of Bash from places like SO, but I've always tried to learn why the command is like that, and I've found other sources more useful than man. If someone is the kind of developer who blindly copies and pastes chunks of code from SO then there are bigger problems than not using man.
0xADEADBEE 7y ago
I'd agree with this. I can't stand prolix documentation when I'm just trying to get something done (I'll never understand why people extol the Python docs!). I used bropages [0] for a while but it isn't as expansive as it should be, presumably on account of a lack of traffic. I'm happy to read more expansive pages in my own time but when I'm 'in the zone' as it were, the last thing I want to do is read through why something works. Perhaps it's a gap in the market? Or more likely I'm in the minority!
- acqq 7y ago
  The Python docs are, on the contrary, quite good when compared to the GNU man pages. There is an advantage of the context: the GNU *nix tools have to reflect how the things grew, totally independently, accidentaly and ad-hoc. Python is much narrower topic and the development mostly had some concept of the "overall goal."
  - corey_moncure 7y ago
    The Python docs opened the door to programming as a career for me in my late 20s. I/O, concurrency, polymorphism, it's all there. Thanks Python.
jjeaff 7y ago
Sometimes I just want to reach through the monitor and smack the nerd that ends every answer on a forum or SO with, "you just type awk -@dee(++ | grep %%s, man pages are your friend. " When you don't know what to look for, it is not as simple as "looking something up".
- acqq 7y ago
  The worst are these who don’t answer the question at all but “helpfully”’give you the link to the man page. If the answer contains an example which matches the question it is useful. (And I too actually consider awk much simpler than e.g. bash)
semitext 7y ago
TLDR is a pretty cool project that cuts out the verbosity of man pages. https://tldr.sh/ https://tldr.sh/

by acqq 7y ago

mFixman 7y ago

Skimming the bash manpage every once in a while is important to stay out of information bubbles. There are too many developers who rely only on Google/Stack Overflow to find and write answers to questions, and it's common to repeat bad, incomplete, or outdated information. I can think of a lot of times when the most accepted SO answer for many questions was "copy and paste this gigantic block of code" instead of using an existing command.

acqq 7y ago
Most of information there is not worth having in my "brain cache" at all, and especially not worth refreshing it regularly. Life is too short to even trying to remember the things like what's the difference between .bash_profile .profile .bashrc .inputrc and .bash_login (bonus point for remembering what is redirected to what in the files themselves in which distribution) or what the hell is a "login shell" and what is not. And there are many such details that are effectively useless for 99.99% of the users but they just have to survive the suffering to fix the darn thing when they have some issue. I'm sure even most of the readers here can't give a one line answer what is the "right" and "general" way to preset a darn variable for a shell. By design of all these artifacts we work with, it necessarily leads to a page-length discussion of which shells exist and what their differences are and whatnot. Such a waste of everybody's mental energy on a global level.
- 0xADEADBEE 7y ago
  I think it's a bit unfair you're being downvoted because you raise some good points. A lot of people agree POSIX is a mess and you've highlighted a fraction of reasons related to that. Would any of the downvoters care to elucidate? Maybe I'm missing something obvious.
  - __del__ 7y ago
    Not a downvoter, but I assume the reason is that many people do understand these mechanisms without evicting too much from their brain cache. Files like .bash_profile, .bash_login, .profile, .zprofile, /etc/profile, /etc/profile.d/whatever.sh all serve the same purpose, the primary aspect of which is to apply things like environment variables at login. Display managers and [login] shells source these things in a predictable precedence order so that environment variables are correctly inherited by children of GUI environment processes and login shells. Login shells? Well yeah, the point of a login shell is that it invokes login-related tasks like setting environment variables from a profile. That's intentionally separate from the behavior of interactive shells because the environments of interactive shells may have been modified intentionally and shouldn't be "reset" to the values applied at login. edit: also .inputrc is the readline configuration file for things like shortcut keys in all programs which use readline (not just bash) and .bashrc is for customizations specific to interactive shells
    - acqq 7y ago
      You see I’ve read this kind of information in exactly the words you use more than once and I still can’t summarize in one sentence where should one put his variables for things to “just work.” Locally for one user. Provided I just don’t know and don’t even care what the differences between the login and interactive shells are and that I just run the whatever terminal it is default from the GUI menu (whichever GUI it is). And your explanation what the differences are is for me still circular, exactly like in the man pages: login shell is the one which invokes login-related tasks, and I should care about the difference from the interactive shells. I still have no idea what that even means, it is what exactly happens when? Anybody knows some sane explanation of these? I admit I never tried to find it, as I tried to read the man pages, didn't find anything reasonable, but knew that it doesn't matter to me. I just want the darn variables to exists whenever I need them. I don't care about the differences. One single place is enough. But now that you say that you "do understand these mechanisms without evicting too much from" your "brain cache" I'd really like to learn everything about the differences. Specifically, when is one invoked and when another for the user "acqq", let's say, on a default Ubuntu system, and on a default Red Hat system? Are really more different user shells invoked in different forms for a single user, on a single machine, between the booting of the machine, logging in (in GUI) and then starting a few times the terminal with shell inside? When is invoked and which is invoked when? And why shouldn't be a single place for the variables I want to define? No idea, but I would be grateful to read about it now. Thanks in advance.
frereubu 7y ago
I see where you're coming from, but I think it's the attitude of the developer that's more important. I've learned a good deal of Bash from places like SO, but I've always tried to learn why the command is like that, and I've found other sources more useful than man. If someone is the kind of developer who blindly copies and pastes chunks of code from SO then there are bigger problems than not using man.

0xADEADBEE 7y ago

I'd agree with this. I can't stand prolix documentation when I'm just trying to get something done (I'll never understand why people extol the Python docs!). I used bropages [0] for a while but it isn't as expansive as it should be, presumably on account of a lack of traffic. I'm happy to read more expansive pages in my own time but when I'm 'in the zone' as it were, the last thing I want to do is read through why something works. Perhaps it's a gap in the market? Or more likely I'm in the minority!

acqq 7y ago
The Python docs are, on the contrary, quite good when compared to the GNU man pages. There is an advantage of the context: the GNU *nix tools have to reflect how the things grew, totally independently, accidentaly and ad-hoc. Python is much narrower topic and the development mostly had some concept of the "overall goal."
- corey_moncure 7y ago
  The Python docs opened the door to programming as a career for me in my late 20s. I/O, concurrency, polymorphism, it's all there. Thanks Python.

jjeaff 7y ago

Sometimes I just want to reach through the monitor and smack the nerd that ends every answer on a forum or SO with, "you just type awk -@dee(++ | grep %%s, man pages are your friend. " When you don't know what to look for, it is not as simple as "looking something up".

acqq 7y ago
The worst are these who don’t answer the question at all but “helpfully”’give you the link to the man page. If the answer contains an example which matches the question it is useful. (And I too actually consider awk much simpler than e.g. bash)

semitext 7y ago

TLDR is a pretty cool project that cuts out the verbosity of man pages. https://tldr.sh/ https://tldr.sh/