inotify.7: Rewrite introductory section

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man7/inotify.7

@@ -23,7 +23,7 @@
 .\" the source, must acknowledge the copyright and authors of this work.
 .\" %%%LICENSE_END
 .\"
-.TH INOTIFY 7 2014-03-28 "Linux" "Linux Programmer's Manual"
+.TH INOTIFY 7 2014-04-01 "Linux" "Linux Programmer's Manual"
 .SH NAME
 inotify \- monitoring filesystem events
 .SH DESCRIPTION
@@ -36,15 +36,7 @@ When a directory is monitored, inotify will return events
 for the directory itself, and for files inside the directory.
 
 The following system calls are used with this API:
-.BR inotify_init (2)
-(or
-.BR inotify_init1 (2)),
-.BR inotify_add_watch (2),
-.BR inotify_rm_watch (2),
-.BR read (2),
-and
-.BR close (2).
-
+.IP * 3
 .BR inotify_init (2)
 creates an inotify instance and returns a file descriptor
 referring to the inotify instance.
@@ -52,8 +44,10 @@ The more recent
 .BR inotify_init1 (2)
 is like
 .BR inotify_init (2),
-but provides some extra functionality.
-
+but has a
+.IR flags
+argument that provides access to some extra functionality.
+.IP *
 .BR inotify_add_watch (2)
 manipulates the "watch list" associated with an inotify instance.
 Each item ("watch") in the watch list specifies the pathname of
@@ -66,12 +60,19 @@ Each watch has a unique "watch descriptor", an integer
 returned by
 .BR inotify_add_watch (2)
 when the watch is created.
-
+.IP *
+When events occur for monitored files and directories,
+those events are made available to the application as structured data that
+can be read from the inotify file descriptor using
+.BR read (2)
+(see below).
+.IP *
 .BR inotify_rm_watch (2)
 removes an item from an inotify watch list.
-
+.IP *
 When all file descriptors referring to an inotify
-instance have been closed,
+instance have been closed (using
+.BR close (2)),
 the underlying object and its resources are
 freed for reuse by the kernel;
 all associated watches are automatically freed.