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.

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".

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)

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.

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.

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.

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

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.

The general way to set an environment variable is in /etc/profile or ~/.{bash_,,z}profile.

PAM uses /etc/environment, and systemd would prefer to have you set up default environment variables in /etc/systemd/system.conf. You can even pass them directly to Linux from your bootloader (unrecognized arguments on the kernel command line in the form foo=bar become environment variables), but the profiles are the generally accepted way of doing it.

It is a joke? If I want to set some variable to be present for a single user (me) I surely don't want to ever touch /etc/profile or /etc/systemd/system.conf (and I have no idea what /etc/environment is supposed to be). And even less want to change something in a bootloader. The things are surely configurable in my user home directory.

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.

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!

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."

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.

TLDR is a pretty cool project that cuts out the verbosity of man pages.

https://tldr.sh/

Using bash's process substitution, you could also use this:

    lpr <(man -t bash)

See: https://unix.stackexchange.com/a/64011

Here is a function for mac os that outputs a pdf of a man page

    function pman() {
        man -t ${1} | open -f -a /Applications/Preview.app
    }

Lovely!

Thanks for `man -t`!

It's actually 78 pages on my system (Debian, bash 4.4.12).

I've heard that OpenBSD has the best man pages that are more pleasant to read and more informative/concise.

OpenBSD man pages are what engineering documents should be. The contrast with Linux's is astounding.

This reminds me of a writeup by John Carmack. Last year he did a programming retreat where he set up a OpenBSD dev environment and tried to use the base system and the included documentation as much as possible rather than using ports and WWW†. That would probably not be so nice on a Linux system.

https://www.facebook.com/permalink.php?story_fbid=2110408722...

† Anyone else here that remembers the days when man pages and Windows help files used to be referred to as online documentation? As opposed to printed manuals.

The MSDN CDs where an endless source of amusement. The reference manuals were very good and search actually worked well. Did not feel crippled at all.

I don't know.

From `man wc`

    WC(1)                     BSD General Commands Manual                    
    WC(1)

    NAME
         wc -- word, line, character, and byte count

When in actuality `wc` outputs lines, words bytes ...

You probably referring to FreeBSD man, OpenBSD is slightly different: https://man.openbsd.org/wc.1

That still has the order wrong in the name section.

I mean, strictly speaking, the name field doesn’t document the output, but having those aligned makes the documentation much easier to read.

man -t is awesome!

IME it’s easier to focus when reading printed documentation. One can jot down notes and no temptation to go and reload Facebook/Twitter/etc. I haven’t done it often, but some commands are really worth knowing inside and out.

That let me looking into how to read them in an e-reader:

    man --html=calibre bash

Indeed. Never liked reading manpages more then when I was briefly exposed to OpenBSD. Really envied them for the concise and well written documentation they have.

Even better than the man page, just print out the reference manual:

    sudo apt install -y bash-doc && lpr /usr/share/doc/bash-doc/bashref.pdf

178 pages of awesome.

I’d probably add the ps2pdf command before sending it to my non postscript printer. The output of pdf to a non postscript printer would be interesting.

Or, if you're fine with reading it online, but don't want to run the man bash command each time (for whatever reason), and/or want to strip out the formatting characters once and for all, and/or want to use the search and other editing features of your favorite text editor on the contents of the man page, for faster navigation, copying-and-pasting snippets into scripts, etc., you can use this small shell script:

m, a Unix shell utility to save cleaned-up man pages as text:

https://jugad2.blogspot.com/2017/03/m-unix-shell-utility-to-...

Edit: Also check out the stuff about the word mu in the latter part of the post :)

In vim, I can run:

  :r !man bash | col -b

the col utility will strip backspace characters with the -b switch (along with reverse line feeds).

You can also display man pages in vim by default:

    export MANPAGER="/bin/sh -c \"col -b | vim -c 'set ft=man ts=8 nomod nolist nonu noma' -\""

Right. But check what my script called m does :)

It uses col, but also redirects the cleaned-up output to a file named cmd.m (so you don't have to run that man command for the same command - like bash or other - each time), where cmd is the cmd you give to man as an arg. That file cmd.m is stored under your ~/man dir, which gets created first, with mkdir -p. More refinements possible, of course, but this was just a quick and dirty script I whipped up. For example, could check more for permission and other kinds of errors, not create the ~/man dir each time but only once, etc.