New Posts  All Forums:Forum Nav:

Stupid man pages - Page 2

post #11 of 64
Man pages are not beginner friendly. They have a very specific structure, and there's almost always assumed knowledge.
post #12 of 64
Quote:
Originally Posted by The Hundred Gunner View Post

Well I'm nit-picking because I was only interested in looking for how to list entries, and so I only looked at -a. If they're going to mention "delete" along with "list," then they ought to make a reference to "see option -d," because not everyone reads a man page from top to bottom when they're just looking for one thing... Oh well.
But the usage is very clear at the top of the man page, and if you're in any doubt about the usage than surely it makes more sense to read the top of the man page rather than posting a complaint on a messagebaord and wait 24 hours for the answer.

It seems to me that your complaint consists of "I was too lazy to read the documentation properly so I'll blame the documentation for being substandard"

Quote:
Originally Posted by Ferrari8608 View Post

Man pages are not beginner friendly. They have a very specific structure, and there's almost always assumed knowledge.

That's a fair point. But I'd argue saying that you wouldn't expect anyone to be tinkering with the command line in either OS X nor Linux unless they were given specific direction or had that assumed knowledge to begin with.
post #13 of 64
Quote:
Originally Posted by Ferrari8608 View Post

Man pages are not beginner friendly. They have a very specific structure, and there's almost always assumed knowledge.

I would agree with this for the most part, there is definitely at least some assumed knowledge usually.
post #14 of 64
Thread Starter 
Quote:
Originally Posted by Plan9 View Post

But the usage is very clear at the top of the man page, and if you're in any doubt about the usage than surely it makes more sense to read the top of the man page rather than posting a complaint on a messagebaord and wait 24 hours for the answer.

Where did you get the idea that I was asking a question and waiting for an answer? I was just complaining.
Quote:
Originally Posted by Plan9 View Post

It seems to me that your complaint consists of "I was too lazy to read the documentation properly so I'll blame the documentation for being substandard"
That's a fair point. But I'd argue saying that you wouldn't expect anyone to be tinkering with the command line in either OS X nor Linux unless they were given specific direction or had that assumed knowledge to begin with.

I don't know if "properly" is the right word, but I'm definitely too lazy to read the whole thing. I didn't catch the example in the beginning because instead of reading the whole thing from top to bottom (would that have been "proper?"), I just searched the words "list" and "display." I don't know about you, but I try to cut to the chase and get my information without reading manuals cover to cover. Maybe that's "improper" - I don't know.

This one's for you, by the way: http://www.overclock.net/t/1452868/minor-rant-question-about-the-linux-community-in-general
post #15 of 64
I don't ever read man pages top to bottom. By 'properly' I just meant going back and checking for example usage at either the start or end of the file when it became obvious that the specific line you read didn't give enough detail.

Having written man pages myself, I know how hard it is to give meaningful details about what a flag does, and sometimes a flag can be multipurpose or even not required when other flags are set, so sometimes that detail can be too verbose to fit in a short description. That's why it pays to go back and check you've not missed some important section when it becomes obvious that there's more to the flag than you initially hoped.

I can appreciate that you might get frustrated with man pages from time to time. And I'm sorry if I came across as arrogant before, but your complaint would have been negated if you bothered to re-skim the man page as in your specific example, the man page was actually very clear.

Hence why I said that from my perspective this thread comes across as lazy.

Personally, I'd rather see threads complaining about undocumented features in *nix than those complaining that some man pages require two glances instead of one. At least arp was documented, sadly some tools aren't.
Edited by Plan9 - 1/12/14 at 5:40pm
post #16 of 64
Quote:
Originally Posted by The Hundred Gunner View Post

Where did you get the idea that I was asking a question and waiting for an answer? I was just complaining.
I don't know if "properly" is the right word, but I'm definitely too lazy to read the whole thing. I didn't catch the example in the beginning because instead of reading the whole thing from top to bottom (would that have been "proper?"), I just searched the words "list" and "display." I don't know about you, but I try to cut to the chase and get my information without reading manuals cover to cover. Maybe that's "improper" - I don't know.

This one's for you, by the way: http://www.overclock.net/t/1452868/minor-rant-question-about-the-linux-community-in-general

The entire description kind of screams that it's to be used in conjunction with another flag. It may not say it directly, but it implies it quite well ( at least, in my opinion ). It definitely would have been worth a once over if you didn't quite understand it though. And looking at the given examples in most man pages tend to be a good help in situations like this as well ( as shown by plan9 ).

No need to start throwing out insults ( what that link is meant to be ).
post #17 of 64
Thread Starter 
Quote:
Originally Posted by Plan9 View Post

I don't ever read man pages top to bottom. By 'properly' I just meant going back and checking for example usage at either the start or end of the file when it became obvious that the specific line you read didn't give enough detail.

Again, you're right that I could have looked over the examples, but my point was that the example was ridiculous (which you just admitted didn't give enough detail!) That one line right there says, "This button either gives info on the nuke or launches it."
Quote:
Originally Posted by Plan9 View Post

And I'm sorry if I came across as arrogant before

Hah, no you're not. You're that guy who will restate everything that everyone else just said in a thread pretending that you're the only one who knew the answer. But I guess that's all acceptable these days - the forum isn't what it used to be back in the old days.

Look, I recognize that you're extremely knowledgeable in this area, and I respect that. I could probably do a little bit more reading, and it might help around here if you did a bit less of shoving it in peoples' faces.
post #18 of 64
Where have I said I'm the only one who knew the answer. The very reason I'm dismissing your example is because everyone worked out how to use that flag even without seeing the full man page.

I was the first person to offer up that suggestion though, and the first to post the actual man page with extracts to examples. I actually looked up it's usage and posted it for you. I was trying to be helpful but had you ignoring my posts and throwing hissyfits because you were too lazy or stubborn to go back and do what you should have done to begin with.

To be quite honest, you were being rather ungreatful considering I spoonfed you the answers, which is why I took a blunter approach to talking to you in this thread.
post #19 of 64
Oh, and if your that paranoid about using a command with the potential to "nuke" something, then that's *double* the reason why you should have gone back and double checked it's usage. So you have no excuse what so ever. Sorry, but you just don't.

[edit]

Just to expand on this, there is a lot of inconsistences with the command line. You have GNU where flags can appear in any order where as POSIX does not:
Code:
# correct in GNU, fails in POSIX:
ls /path -lt

You have common flags that change case in different tools (eg the recursive flag and port number flags are big ones that sometimes catch me out).
Code:
ssh -p port user@server
scp -P port user@server:/path destination

Then you have tools which don't even follow the usual rules for flags. eg utilities which have a single hyphen for words (i can't remember any examples for this off hand, but you do occasionally see it) or utilities which don't have hyphens at all
Code:
dd if=src of=dest

This is why if you're in any doubt about a commands usage and there's the potential to take your system offline, then you spend more than a 10 second glance at the man page. Heck, there's some commands I know from memory that I treble check before running (eg dd; i read my dd commands allowed 3 times before hitting [enter] as there's a high potential to mix up if= and of=).

The Linux/UNIX command line is a powerful tool, but there's a high potential for screw ups, so if in doubt, have a double check. And sometimes if you're sure, double check anyway. Otherwise laziness and inexperience will lead to you breaking things.
Edited by Plan9 - 1/13/14 at 1:39am
post #20 of 64
Thread Starter 
The note to "read up and down if you see something odd:" great. The examples: beautiful.

The point: the "-a" option does not, in fact, "display or delete arp entries." It doesn't do what it says! How do I know that's a fact? I type in "arp -a" and get a table. I type it in again and still get a table, i.e. it didn't delete anything. On its own, the line
Code:
-a      The program displays or deletes all of the current ARP entries.

is WRONG. Does anyone care? Probably not. Did it cause me some confusion? Maybe a little. There isn't even anything to be paranoid about - it's just an arp table. So if it's that important to you to defend the man page writers' error, then by all means, keep this going. The statement is wrong and I thought it might be worth a laugh, but I guess this is serious business.
New Posts  All Forums:Forum Nav:
  Return Home
  Back to Forum: Linux, Unix