diff --git a/CHANGES b/CHANGES
index 53ef92e..1742439 100644
--- a/CHANGES
+++ b/CHANGES
@@ -158,6 +158,10 @@ Documentation:
 	Corrected lots of misspelling and typos.
 	Thanks to Mario de Weerd for reporting these issues.
 
+	Improved README file.
+
+	Better explained benefit of UDP-DATAGRAM address type.
+
 ####################### V 1.8.0.2:
 
 Security:
diff --git a/README b/README
index c48c095..0605138 100644
--- a/README
+++ b/README
@@ -58,8 +58,15 @@ Rocky 9
 Cygwin 10.0
 
 
-install
--------
+build
+-----
+
+You need at least gcc and make.
+A few libraries are required for full features:
+Debian:     libssl-dev    libreadline-dev libwrap0-dev
+Red Hat:    openssl-devel readline-devel  tcp_wrappers-libs
+Arch Linux: openssl       readline
+
 
 Get the tarball and extract it:
 	tar xzf socat.tar.gz
@@ -69,7 +76,7 @@ Get the tarball and extract it:
 	su
 	make install	# installs socat, filan, and procan in /usr/local/bin
 
-For compiling socat, gcc (or clang) is recommended.
+For compiling socat, gcc or a compatible compiler (e.g. clang) is recommended.
 If gcc (or a compiler with similar front end) is not available, the configure
 script might fail to determine some features
 
diff --git a/doc/socat.yo b/doc/socat.yo
index 4690543..9994e99 100644
--- a/doc/socat.yo
+++ b/doc/socat.yo
@@ -1429,7 +1429,8 @@ label(ADDRESS_UDP_SENDTO)dit(bf(tt(UDP-SENDTO:<host>:<port>)))
    link(pf)(OPTION_PROTOCOL_FAMILY). It sends packets to and receives packets
    from that peer socket only.  
    This address effectively implements a datagram client.
-   It works well with socat UDP-RECVFROM and UDP-RECV address peers.nl()
+   It works well with socat UDP-RECVFROM and UDP-RECV address peers.
+   When the peer might send data first, link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM) is preferable.nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6) nl()
    Useful options:
    link(ttl)(OPTION_TTL),
@@ -1467,7 +1468,8 @@ label(ADDRESS_UDP_RECVFROM)dit(bf(tt(UDP-RECVFROM:<port>)))
    label(NOTE_RECVFROM)Note: When the second address fails before entering the transfer loop the
    packet is dropped. Use option link(retry)(OPTION_RETRY) or
    link(forever)(OPTION_FOREVER) on the second address to avoid data loss.
-   nl()
+   When you know the peer address, link(UDP-DATAGRAM)(ADDRESS_UDP_DATAGRAM) is
+   preferable.nl()
    Option groups: link(FD)(GROUP_FD),link(SOCKET)(GROUP_SOCKET),link(IP4)(GROUP_IP4),link(IP6)(GROUP_IP6),link(CHILD)(GROUP_CHILD),link(RANGE)(GROUP_RANGE) nl()
    Useful options:
    link(fork)(OPTION_FORK),
@@ -2996,6 +2998,8 @@ label(OPTION_NOFORK)dit(bf(tt(nofork)))
    it() the first socat address cannot be OPENSSL or READLINE
    it() socat options -b, -t, -D, -l, -v, -x become useless
    it() for both addresses, options ignoreeof, cr, and crnl become useless
+   it() for both addresses, address specific end/shutdown handling (e.g.,
+   graceful socket shutdown) and related options become useless
    it() for the second address (the one with option nofork), options 
       append, metaCOMMENT(async,) cloexec, flock, user, group, mode, nonblock,
       perm-late, setlk, and setpgid cannot be applied. Some of these could be
@@ -3543,7 +3547,8 @@ label(TYPE_COMMAND_LINE)dit(command-line)
    A string specifying a program name and its arguments, separated by single
    spaces. 
 label(TYPE_DATA)dit(data)
-   This is a more general data specification. The given text string contains
+   This is a more general data specification, "dalan" (low level data
+   description language). The given text string contains
    information about the target data type and value. Generally a leading
    character specifies the type of the following data item. In its specific
    context a default data type may exist.nl()
@@ -3559,12 +3564,12 @@ label(TYPE_DATA)dit(data)
    dit(b)  A signed byte (signed char).nl()
    dit(B)  An unsigned byte (unsigned char).nl()
    dit(x)  Following is an even number of hex digits, stored as sequence of
-   bytes.nl()
+   bytes, the data length is the resulting number of bytes.nl()
    Example:    bf(x7f000001) (IP address 127.0.0.1)
    dit(")  Following is a string that is used with the common conversions 
    \n \r \t \f \b \a \e \0; the string must be closed with '"'. Please note
    that the quotes and backslashes need to be escaped from shell and socat()
-   conversion.nl()
+   conversion. No implicit \0 is appended.nl()
    Example:    bf("Hello world!\n")
    dit(')  A single char, with the usual conversions. Please note that the
    quotes and backslashes need to be escaped from shell and socat() conversion.