2

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?

kubanczyk
  • 13,812
  • 5
  • 41
  • 55
Léo Léopold Hertz 준영
  • 809
  • 6
  • 22
  • 43
  • 2
    I'd love to say "don't use man, info is better..." but I find the info UI completely disorienting. It doesn't help that I always end up there on accident of course. – Kyle Jul 01 '09 at 18:24
  • 1
    @Kile: You might give pinfo a try. – Dennis Williamson Jul 01 '09 at 18:56
  • @Dennis: How do you search in Pinfo? --- My pinfo goes upset when I search by / – Léo Léopold Hertz 준영 Jul 01 '09 at 19:06
  • @Dennis: this is what I get at the bottom: http://files.getdropbox.com/u/175564/pinfo_bug.png – Léo Léopold Hertz 준영 Jul 01 '09 at 19:31
  • @Masi: check your pinfo configuration files to see if the key bindings are messed up. Try the period "." instead of the slash "/" and see if that makes a difference. Also "s" searches span multiple pages, while slash or period only search the current page. To repeat the search, use "f". Try "s" as well as "." to see if it upsets pinfo. – Dennis Williamson Jul 01 '09 at 19:51
  • @Dennis: I have an empty .pinforc. --- The problem also occurs with the following .pinforc http://serverfault.com/questions/35114/no-info-manual-for-pinfo/35127#35127 – Léo Léopold Hertz 준영 Jul 02 '09 at 16:15

5 Answers5

11

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.

Zoredache
  • 130,897
  • 41
  • 276
  • 420
5

You haven't specified directory

find . -type d ! -perm -777

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.

kubanczyk
  • 13,812
  • 5
  • 41
  • 55
3

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 and find . ! -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.

Dan Carley
  • 25,617
  • 5
  • 53
  • 70
  • I now know what has been my problem. --- I have been reading only OS/X's manuals. The OS/X's manual has no explanation about expressions. It has no title about the main topics. --- It would be great that we could improve those manuals. – Léo Léopold Hertz 준영 Jul 01 '09 at 19:20
  • Is it this - http://developer.apple.com/documentation/Darwin/Reference/ManPages/man1/find.1.html ? It contains more or less the same information, but the terminology is different, slightly confusingly. If you trace through the terms then you can piece it together. For instance it says that expressions are comprised of operands. – Dan Carley Jul 01 '09 at 19:43
1

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:

grep [OPTIONS] PATTERN [FILE...]

grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

OPTIONS and FILE 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:

grep [OPTIONS] [PATTERN | -e PATTERN | -f FILE] [FILE...]

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 are man 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 have less set as my man reader, so I use the / command to initiate searches. Sometimes, I find that the info documentation is more complete or useful and I use that in a similar way.

Community
  • 1
Dennis Williamson
  • 62,149
  • 16
  • 116
  • 151
  • @Dennis: Do you mean that info has different manuals than man? --- Man and info are just readers. --- How can they have different manuals? – Léo Léopold Hertz 준영 Jul 01 '09 at 19:28
  • @Masi: Yes, there are info files and man files. For example, on my system, there's /usr/share/info/sed.info.gz and /usr/share/man/man1/sed.1.gz two completely different files. That's why at the bottom of a lot of man pages, it will refer you to info for more detailed documentation. – Dennis Williamson Jul 01 '09 at 19:39
  • Masi: Info defaults to the man pages only if there is not an info page. Info is another format and another supply of documentation. – dmckee --- ex-moderator kitten Jul 01 '09 at 19:41
0

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: 

DESCRIPTION
     The find utility recursively descends the directory tree for each
     pathname listed, evaluating an expression (composed of the ``primaries''
     and ``operands'' listed below) in terms of each file in the tree.

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 and space go forward a page and Control-b backs up a page. There is also xman where you'd type Control-s to search for your manpage titled find. I also like the apropos command.

dlamblin
  • 939
  • 2
  • 10
  • 20