clarify README

Signed-off-by: Kay Sievers <kay.sievers@suse.de>

3 files changed, 78 insertions, 108 deletions

diff --git a/README b/README
index 9891c696d3..19ed4468ea 100644
--- a/README
+++ b/README
@@ -1,107 +1,77 @@
-
-udev - a userspace device manager
-
-For more information on the design, and structure of this project, see the
-files in the docs/ directory.
-
-To use:
-
-- You must be running a 2.6 version of the Linux kernel.
-
-- Your 2.6 kernel must have had CONFIG_HOTPLUG enabled when it was built.
-
-- Make sure sysfs is mounted at /sys. No other location is supported.
-  You can mount it by running:
-  	mount -t sysfs none /sys
-
-- Make sure you integrate udev with your hotplug setup. There is a copy of
-  the rules files for all major distros in the etc/udev folder. You may look
-  there how others are doing it.
-
-- Make sure you integrate with the kernel hotplug events. Later versions of
-  udev are able to listen directly to a netlink socket, older versions used
-  udevsend to feed the udev daemon with the kernel event. The most basic
-  setup to run udev is to let the kernel for the udev binary directly:
-	echo "/sbin/udev" > /proc/sys/kernel/hotplug
-
-  While this may work in some setups, it is not recommended to do. A recent
-  kernel and udev version is able to operate with the event serializing daemon
-  udevd, that makes sure, that no "remove" event will beat a "add" event for
-  the same device.
-
-- Build the project:
-	make
-
-  Note:
-      There are a number of different flags that you can use when building
-      udev.  They are as follows:
-	prefix
-		set this to the default root that you want udev to be
-		installed into.  This works just like the 'configure --prefix'
-		script does.  Default value is ''.  Only override this if you
-		really know what you are doing.
-	USE_KLIBC
-		if set to 'true', udev is built and linked against the
-		included version of klibc.  Default value is 'false'.
-	USE_LOG
-		if set to 'true', udev will emit messages to the syslog when
-		it creates or removes device nodes.  This is helpful to see
-		what udev is doing.  This is enabled by default.  Note, if you
-		are building udev against klibc it is recommended that you
-		disable this option (due to klibc's syslog implementation.)
-	USE_SELINUX
-		if set to 'true', udev will be built with SELinux support
-		enabled.  This is disabled by default.
-	DEBUG
-		if set to 'true', debugging messages will be sent to the syslog
-		as udev is run.  Default value is 'false'.
-	KERNEL_DIR
-		If this is not set it will default to /lib/modules/`uname -r`/build
-		This is used if USE_KLIBC=true to find the kernel include
-		directory that klibc needs to build against.  This must be set
-		if you are not building udev while running a 2.6 kernel.
-	EXTRAS
-		if set, will build the "extra" helper programs as specified
-		as listed (see below for an example.)
-
-      So, if you want to build udev using klibc with debugging messages, you
-      would do:
-	make USE_KLIBC=true DEBUG=true
-
-      If you want to build the udev helper program cdrom_id and scsi_id you
-      would do:
-	make EXTRAS="extras/cdrom_id extras/scsi_id"
-
-      udev will follow the setting of the debug level in udev.conf. Adapt this
-      value to see the debug in syslog.
-
-- Install the project:
-	make install
-
-  This will put the udev binaries in /sbin, create the and /etc/udev
-  directories, and place the udev configuration files in /etc/udev/.  You
-  will probably want to edit the *.rules files to create custom naming
-  rules.  More info on how the config files are set up are contained in
-  comments in the files, and is located in the documentation.
-
-- Add and remove devices from the system and marvel as nodes are created
-  and removed in /dev based on the device types.
-
-- If you later get sick of it, uninstall it:
-	make uninstall
-
-If nothing seems to happen, make sure your build worked properly by
-running the udev-test.pl script as root in the test/ subdirectory of the
-udev source tree. Running udevstart should populate an empty /dev
-directory. You may test, if a node is recreated after running udevstart.
-
-Development and documentation help is very much appreciated, see the TODO
-file for a list of things left to be done.
-
-Any comment/questions/concerns please let me and the other udev developers
-know by sending a message to the linux-hotplug-devel mailing list at:
-	linux-hotplug-devel@lists.sourceforge.net
-
-greg k-h
-greg@kroah.com
+udev - userspace device management
+
+For more information see the files in the docs/ directory.
+
+Important Note:
+  Integrating udev in the system is a whole lot of work, has complex dependencies
+  and differs a lot from distro to distro. All reasonable distros use udev these
+  days, the major ones make it mandatory and the system will not work without it.
+
+  The upstream udev project does not support or recomend to replace a distro's udev
+  installation with the upstream version. The installation of a unmodified upstream
+  version may render your system unusable! There is no "default" setup or a set
+  of "default" rules provided by the upstream udev version.
+
+udev requires:
+  - 2.6 version of the Linux kernel
+
+  - the kernel must have sysfs, netlink, and hotplug enabled
+
+  - proc must be mounted on /proc
+
+  - sysfs must be mounted at /sys, no other location is supported
+
+  - udev creates and removes device nodes in /dev based on events
+    the kernel sends out on device discovery or removal
+
+  - during bootup /dev usually gets a tmpfs mounted which is populated scratch
+    by udev (created nodes don't survive a reboot, it always starts from scratch)
+
+  - udev replaces the hotplug event management invoked from /sbin/hotplug
+    by the udevd daemon, which receives the kernel events over netlink
+
+  - all kernel events are matched against a set of specified rules which
+    make it posible to hook into the event processing
+
+  - there is a copy of the rules files for all major distros in the etc/udev
+    directory (you may look there how others distros are doing it)
+
+Setting which are used for building udev:
+  prefix
+  	set this to the default root that you want to use
+  	Only override this if you really know what you are doing
+  DESTDIR
+  	prefix for install target for package building
+  USE_LOG
+  	if set to 'true', udev will emit messages to the syslog when
+  	it creates or removes device nodes.  This is helpful to see
+  	what udev is doing.  This is enabled by default.  Note, if you
+  	are building udev against klibc it is recommended that you
+  	disable this option (due to klibc's syslog implementation.)
+  DEBUG
+  	if set to 'true', verbose debugging messages will be compiled into
+  	the udev binaries.  Default value is 'false'.
+  USE_SELINUX
+  	if set to 'true', udev will be built with SELinux support
+  	enabled.  This is disabled by default.
+  USE_KLIBC
+  	if set to 'true', udev is built and linked against the
+  	included version of klibc.  Default value is 'false'.
+  KERNEL_DIR
+  	If this is not set it will default to /lib/modules/`uname -r`/build
+  	This is used if USE_KLIBC=true to find the kernel include
+  	directory that klibc needs to build against.  This must be set
+  	if you are not building udev while running a 2.6 kernel.
+  EXTRAS
+  	if set, will build the "extra" helper programs as specified
+  	as listed (see below for an example.)
+
+if you want to build udev using klibc with debugging messages:
+  make USE_KLIBC=true DEBUG=true
+
+if you want to build the udev helper program cdrom_id and scsi_id:
+  make EXTRAS="extras/cdrom_id extras/scsi_id"
+
+Please direct any comment/question/concern to the linux-hotplug-devel mailing list at:
+  linux-hotplug-devel@lists.sourceforge.net
 
diff --git a/docs/udev.xml b/docs/udev.xml
index 02dcd2586a..c98054f8ce 100644
--- a/docs/udev.xml
+++ b/docs/udev.xml
@@ -440,7 +440,7 @@
                 devices of the same type originating from different kernel subsystems.</para>
                 <para>Note: The use of the enumeration facility is unreliable for events that
                 request a number at the same time. The  use  of enumerations in todays setups
-                where devices can come and go at any time is not recomended.</para>
+                where devices can come and go at any time is not recommended.</para>
               </listitem>
             </varlistentry>
 
diff --git a/udev.8 b/udev.8
index 9b74ae23bf..a591a1398e 100644
--- a/udev.8
+++ b/udev.8
@@ -203,7 +203,7 @@ The string returned by the external program requested with PROGRAM. A single par
 \fB%e\fR, \fB$enum\fR
 If a device node already exists with the name, the smallest next free number is used. This can be used to create compatibility symlinks and enumerate devices of the same type originating from different kernel subsystems.
 
-Note: The use of the enumeration facility is unreliable for events that request a number at the same time. The use of enumerations in todays setups where devices can come and go at any time is not recomended.
+Note: The use of the enumeration facility is unreliable for events that request a number at the same time. The use of enumerations in todays setups where devices can come and go at any time is not recommended.
 .TP
 \fB%P\fR, \fB$parent\fR
 The node name of the parent device.