I find the synopsis of Find's manual difficult to read alt text http://files.getdropbox.com/u/175564/syntax_manual.png
Let's assume that you are finding directories with 777 permissions. Pixelbeat's suggestion is
find -type d ! -perm -777
My OS/X gives the following
find: illegal option -- t
find: illegal option -- y
find: illegal option -- p
find: illegal option -- e
find: d: No such file or directory
Things about which I am not sure when using the synopsis as a help
- unable to see where to put the option
-type
: I can clearly test this, but I want to learn to read manuals better such that I do not need ask help. - unable to understand why we need two lines for synopsis: it seems to emphasize that many PATHs are optional
- why does Pixelbeat use an exclamation mark in the command?
Let's have another example of Grep's manual.
alt text http://files.getdropbox.com/u/175564/grep_manual.png
It has a clear synopsis although I would just use one line for it. I can see directly that we can grep by
grep -r "masi" .
How do you read manuals similar to Find's manual?
The first thing to realize is that not all find commands are created equal. The find you will find on a Linux system is different then what you will have on a BSD-based system like OSX. The reference you are going off is for Linux.
For the find command the '-type' option is an expression and must be after the path. If you read further down the man page it will describe which options are expressions.
The exclamation point is for negation. That is it returns everything except things with permissions of 777.
The command "find -type d ! -perm -777" is invalid because you didn't include a path before the expression. You can use a path of . if want the current directory.
Back to the main question. Sometimes reading just the summary of the man page is not enough, and you actually have to read the rest. Some commands are so powerful, that you won't be able to get a good idea of how to use the command unless you read or at least skim through the entire document. It is also helpful to check out the examples if they are present, or if they are not present go online and look for some examples.
You haven't specified directory
Manual page that you cited states that pathname should come before expression. So in this case a dot "." comes before "-type d ...". The latter are not options per se. In fact -type and -perm are parts of boolean expression that find tries to evaluate for each file.
unable to see where to put the option -type
-type
isn't an option, it's an expression. So it comes at the end of the argument list. If you scroll down the man page you'll find a section titled expressions that details all of the available choices for this argument.unable to understand why we need two lines for synopsis: it seems to emphasize that many PATHs are optional
The program may be called with either the argument
pathname
or-f pathname
. As a rule of thumb any arguments within square brackets is optional. But those which aren't, are mandatory. Which is why your find command doesn't work - because it has "expressions" before any "pathname". The dots indicate that optionally more than one pathname argument may be used.why does Pixelbeat use an exclamation mark in the command?
I can't see the specified command in the link you gave. But..
The exclamation character can be used to negate a following expression. So the command
find . -type d
will find directories andfind . ! -type d
will find everything except directories. It's advisable to escape the exclamation mark with a preceding backslash though, so that your shell doesn't interpret it. It can also be interchanged with-not
.In the synopses, items included in brackets are optional and alternatives are separated by a pipe character (vertical bar). If the alternatives are optional, they would appear in double square brackets separated by pipes. Mandatory arguments appear without any brackets. Arguments that may be repeated are followed by ellipses (
...
).Sometimes the synopsis would be too complicated to collapse into one line. Also, sometimes the result of one version is significantly different to the other one or are mutually exclusive. So in your grep example:
OPTIONS
andFILE
are optional. The first version is the more common. The second version is for special cases where either (-e
) you need to protect a pattern that begins with minus or (-f
) the patterns are in a file. As you can see, these differ from the more basic first version. The synopsis could have been like this:But then it's more difficult to read and this is just a simple case. Imagine one that's more complex like
mount
, for example. And, of course, there areman
pages without synopses because it would be nearly impossible (e.g.bash
).When I read a
man
page, I look for a synopsis that seems to most closely match what I'm looking for. If one is apparent, then I will scan (vgrep) or search for terms or key words from the synopsis or from my knowledge of what I'm trying to accomplish. I haveless
set as myman
reader, so I use the / command to initiate searches. Sometimes, I find that theinfo
documentation is more complete or useful and I use that in a similar way.Yeah the man page for
find
on my Mac OS X install is slightly misleading. The synopsis lists that expressions come at the end, but the section that would logically be headed as "EXPRESSIONS" is instead split in two and headed as "PRIMARIES" and "OPERATORS". I always read the first few lines of the "DESCRIPTION" so it should be noted that they clarify this issue there:This should eventually clue you in to find being odd due to it's non-option parameters starting in "-" are actually expressions which must be preceded by a path.
The most helpful advice I have for man pages is to learn you pager's commands. The default seems to be
less
and here you can use<
to go to the start>
to go to the end, and/
or?
to search for a pattern forwards or backwards (such as "/-type").Control-f
andspace
go forward a page andControl-b
backs up a page. There is alsoxman
where you'd typeControl-s
to search for your manpage titledfind
. I also like theapropos
command.