5 ms·

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference ma

Man is like javadocs: useless unless you already know what you are doing, and then usually a wordy paraphrase of the method signature :( Even as a reference manual, man is bad though. If I'm looking for option "-e" of the test command, why can't I do $ man test -e -e file True if file exists (regardless of type). That seems more efficient, more unix-friendly and not too much to ask. I get this is an historical tool that only cares about displaying the output of nroff. We would need a new tool with more empathy ($ woman? )

kleiba 9y ago
De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of course, you could also just define a bash function for the functionality you're after like so: mano() { man "$1" | grep -A1 -- "$2" } and then do $ mano test -e or something along those lines.
- jmfayard 9y ago
  That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.
  - kleiba 9y ago
    Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly. You could always make your function more clever, e.g.: function mano() { man "$1" | grep -A1 -- "$2\\b" } or function mano() { man "$1" | grep -A1 -- "$2 " } but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".
  - nathyong 9y ago
    You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.
vram22 9y ago
I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me: m, a Unix shell utility to save cleaned-up man pages as text: https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-save-cleaned-up.html https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s... This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.
wang_li 9y ago
If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.
- Annatar 9y ago
  Indeed!
Annatar 9y ago
man test | grep -- ‘ -e’ UNIX already has that as you can see. You just need to learn the target substrate you’re using.
explainplease 9y ago
> If I'm looking for option "-e" of the test command, why can't I do... https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-mangle https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-... $ man test -e STRING1 != STRING2 the strings are not equal INTEGER1 -eq INTEGER2 INTEGER1 is equal to INTEGER2 INTEGER1 -ge INTEGER2 INTEGER1 is greater than or equal to INTEGER2 -- INTEGER1 -ne INTEGER2 INTEGER1 is not equal to INTEGER2 FILE1 -ef FILE2 FILE1 and FILE2 have the same device and inode numbers FILE1 -nt FILE2 FILE1 is newer (modification date) than FILE2 -- -d FILE FILE exists and is a directory -e FILE FILE exists -f FILE FILE exists and is a regular file

kleiba 9y ago

De gustibus non est disputandum. I've found javadocs enormously helpful when I was learning Java 20 years ago. But then again, I also like man pages and use them a lot. If I'm looking for option "-e" of the test command, here's what I would do: $ man test and then "/-e". Searching within a document is a commonly required skill in so many situations that I don't even think twice when applying it in man pages. Of course, you could also just define a bash function for the functionality you're after like so: mano() { man "$1" | grep -A1 -- "$2" } and then do $ mano test -e or something along those lines.

jmfayard 9y ago
That's full text search, not having directly the argument definition. If you search "-l" in "man ls", it will be only your 8th occurence.
- kleiba 9y ago
  Sure, you're right, it's not the same thing. I just gave a simple example of something that's close, but I'm not even using a bash function like that myself. If I did, though, I guess the 8th occurrence wouldn't be so bad in my book, since the results can be scanned rather quickly. You could always make your function more clever, e.g.: function mano() { man "$1" | grep -A1 -- "$2\\b" } or function mano() { man "$1" | grep -A1 -- "$2 " } but most probably, you will still run into edge cases that won't work properly. For instance, only one of the two versions above still works with "test -e".
- nathyong 9y ago
  You can actually search for ' -l' (two spaces in front) and abuse the man layout engine to find the point at which the flag itself is defined. Makes the man pages a lot more useful in my opinion.

vram22 9y ago

I agree with your point. There should be easier ways of doing some things in Unix. But since there are not (for some things, anyway, and I say this as a long-time Unix guy), sometimes, scripts can help. Here is one example by me: m, a Unix shell utility to save cleaned-up man pages as text: https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-save-cleaned-up.html https://jugad2.blogspot.in/2017/03/m-unix-shell-utility-to-s... This tiny script lets you generate man pages as cleaned-up text, saves them in a ~/man directory, and you can from then on, open them in your favorite text editor or even pager (less/more/pg/etc.) and view them. Created it out of real-life personal need some years ago, on a Unix system, but is still useful on Linux and other Unix-like systems today.

wang_li 9y ago

If your idea of what man is comes from using Linux, then you really haven't had a good exposure to what good documentation can be. Try Solaris or FreeBSD.

Annatar 9y ago
Indeed!

Annatar 9y ago

man test | grep -- ‘ -e’ UNIX already has that as you can see. You just need to learn the target substrate you’re using.

explainplease 9y ago

> If I'm looking for option "-e" of the test command, why can't I do... https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-mangle https://gist.github.com/alphapapa/3cba3ff196147ad42bac#file-... $ man test -e STRING1 != STRING2 the strings are not equal INTEGER1 -eq INTEGER2 INTEGER1 is equal to INTEGER2 INTEGER1 -ge INTEGER2 INTEGER1 is greater than or equal to INTEGER2 -- INTEGER1 -ne INTEGER2 INTEGER1 is not equal to INTEGER2 FILE1 -ef FILE2 FILE1 and FILE2 have the same device and inode numbers FILE1 -nt FILE2 FILE1 is newer (modification date) than FILE2 -- -d FILE FILE exists and is a directory -e FILE FILE exists -f FILE FILE exists and is a regular file