Some small documentation fixes

README.md

@@ -2,20 +2,20 @@
 
 ![Travis Build Status](https://api.travis-ci.org/dermesser/libsocket.png )
 
-(Pre-built documentation can be found on [my
- server](http://lbo.spheniscida.de/doc/libsocket/doxygen/index.html))
+(Pre-built documentation for libsocket developers can be found on [my
+ server](http://lbo.spheniscida.de/doc/libsocket/doxygen/html/))
 
 ## WHAT IS libsocket AND WHY SHOULD I USE IT?
 
 libsocket is a library with a C part and a C++ part making sockets usage easy and clean.
 
-Using the C part:
+[Using the C part:](doc/libsocket/DOCUMENTATION.mkd)
 
 - Link against `libsocket.so`
 - Functions combining more than one operation on sockets (e.g. create and connect TCP socket)
 - Main principle: "One function to connect a socket, one to close it."
 
-[Using the C++ part:](http://lbo.spheniscida.de/doc/libsocket/doxygen/usage.html)
+[Using the C++ part:](doc/libsocket++/DOCUMENTATION++.mkd)
 
 - Link against `libsocket++.so`
 - Classes representing the different socket types, e.g. TCP client sockets, UNIX DGRAM "server"

doc/libsocket++/DOCUMENTATION++.html

@@ -7,7 +7,7 @@ <h2>Introduction and General Information for Devs</h2>
 
 <h3>Practical Usage</h3>
 
-<p>libsocket++ uses the namespace <code>libsocket</code>, so you either have to construct the classes as this:</p>
+<p>libsocket++ uses the namespace <code>libsocket</code>, so you either have to construct the classes like this:</p>
 
 <pre><code>libsocket::inet_stream sock;
 </code></pre>

doc/libsocket++/DOCUMENTATION++.mkd

@@ -7,7 +7,7 @@ and maintain it twice, libsocket++ calls the functions from libsocket.
 
 ### Practical Usage
 
-libsocket++ uses the namespace `libsocket`, so you either have to construct the classes as this:
+libsocket++ uses the namespace `libsocket`, so you either have to construct the classes like this:
 
 	libsocket::inet_stream sock;
 

doc/libsocket/DOCUMENTATION.html

@@ -15,7 +15,7 @@ <h2>Introduction/Explanations</h2>
 socket(2)
 </code></pre>
 
-<p>This are "links" to manpages. They can be reached by the following commands:</p>
+<p>Those are "links" to manpages. They can be reached by the following commands:</p>
 
 <pre><code>$ man 3 getaddrinfo
 $ man 2 socket
@@ -70,7 +70,7 @@ <h2>Static</h2>
 
 <p>Static linking is <strong>not</strong> recommended. That means, copy a checkout of the library files (C/, headers/) to the source tree of your application. Then, simply compile the files together with the other files (as they would be normal part of your application).</p>
 
-<p><em>Details about dependancies:</em> The actual code is in <code>libinetsocket.c</code> resp. <code>libunixsocket.c</code>. Every file of your application which wants to use this functions has to include the header files, e.g.:</p>
+<p><em>Details about dependancies:</em> The actual code is in <code>libinetsocket.c</code> resp. <code>libunixsocket.c</code>. Every file of your application that wants to use these functions has to include the header files, e.g.:</p>
 
 <pre><code># include "../headers/libinetsocket.c"
 # include &lt;stdio.h&gt;
@@ -142,7 +142,7 @@ <h3><code>create_inet_dgram_socket()</code></h3>
 
 <ul>
 <li><code>proto_osi3</code> is <code>LIBSOCKET_IPv4</code> (<code>AF_INET</code>) or <code>LIBSOCKET_IPv6</code> (<code>AF_INET6</code>).</li>
-<li><code>flags</code> may be the flags specified in <code>socket(2)</code>, i.e. <code>SOCK_NONBLOCK</code> and/or <code>SOCK_CLOEXEC</code>. More than one flags may be ORed. <strong>This argument is only sensible on Linux >= 2.6.27!</strong></li>
+<li><code>flags</code> may be the flags specified in <code>socket(2)</code>, i.e. <code>SOCK_NONBLOCK</code> and/or <code>SOCK_CLOEXEC</code>. More than one flags may be ORed. <strong>This argument only has an effect on Linux >= 2.6.27!</strong></li>
 </ul>
 
 <p>Like the function before, this function also has different prototypes on different platforms.</p>

doc/libsocket/DOCUMENTATION.mkd

@@ -13,7 +13,7 @@ Sometimes, there are expressions in the text looking like this:
 	getaddrinfo(3)
 	socket(2)
 
-This are "links" to manpages. They can be reached by the following commands:
+Those are "links" to manpages. They can be reached by the following commands:
 
 	$ man 3 getaddrinfo
 	$ man 2 socket
@@ -24,23 +24,23 @@ Note: The manpage extracts come from the manpages delivered with Debian (Linux m
 
 ### Compile time configuration
 
-If the macro `LIBSOCKET_VERBOSE` is defined, libsocket prints verbose error messages on STDERR device. The error messages come from functions like `strerror` or `gai_strerror`. This is **VERY** useful when there are problems in your program or the library itself. Typically, you specify it in the Makefile (the variable already exists):
+If the macro `VERBOSE` is defined, libsocket prints verbose error messages on STDERR device. The error messages come from functions like `strerror` or `gai_strerror`. This is **VERY** useful when there are problems in your program or the library itself. Typically, you specify it in the Makefile (the variable already exists):
 
 	...
-	CCFLAGS=-DLIBSOCKET_VERBOSE
+	CCFLAGS=-DVERBOSE
 	...
 
 Usually, you'll use this option during development, but disable it when you finished the application. If you use the shared library, specify `-DVERBOSE` in the make variable `CFLAGS`  in `C/Makefile`.
 
-Another compile-time option is `_TRADITIONAL_RDNS`. It's also a macro (like `LIBSOCKET_VERBOSE`) and specifies if the library should use `getnameinfo()` or `gethostbyaddr()` for rDNS queries. The latter possibility may be sensible e.g. on FreeBSD systems or on other systems were getnameinfo is not an option.
+Another compile-time option is `_TRADITIONAL_RDNS`. It's also a macro (like `VERBOSE`) and specifies if the library should use `getnameinfo()` or `gethostbyaddr()` for rDNS queries. The latter possibility may be sensible e.g. on FreeBSD systems or on other systems were getnameinfo is not an option.
 
 ### Usage of flags
 
 The usage of the flags for some functions is described for every function. If you don't need any flags (you think), you may specify `0` for every flag argument without errors.
 
 ### Errors and return values
 
-If you don't enable the `LIBSOCKET_VERBOSE` macro, the library knows another way to notify you if there was an error: The return value. If anything went wrong, the return value is always `-1`. **Every** function behaves this way, so it's
+If you don't enable the `VERBOSE` macro, the library knows another way to notify you if there was an error: The return value. If anything went wrong, the return value is always `-1`. **Every** function behaves this way, so it's
 strongly recommended to check the return values of the API functions. To obtain more information about what went wrong, check `errno`; the man pages of the used syscalls (described in this document) contain information
 about possible `errno` values.
 
@@ -64,7 +64,7 @@ Build and install the library following the instructions in `README.md` and link
 ## Static
 Static linking is **not** recommended. That means, copy a checkout of the library files (C/, headers/) to the source tree of your application. Then, simply compile the files together with the other files (as they would be normal part of your application).
 
-*Details about dependancies:* The actual code is in `libinetsocket.c` resp. `libunixsocket.c`. Every file of your application which wants to use this functions has to include the header files, e.g.:
+*Details about dependancies:* The actual code is in `libinetsocket.c` resp. `libunixsocket.c`. Every file of your application that wants to use these functions has to include the header files, e.g.:
 
 	# include "../headers/libinetsocket.c"
 	# include <stdio.h>
@@ -122,7 +122,7 @@ To send and receive data from this socket, please use `read(2)` and `write(2)`.
 Returns an integer describing a DGRAM (UDP) socket.
 
 * `proto_osi3` is `LIBSOCKET_IPv4` (`AF_INET`) or `LIBSOCKET_IPv6` (`AF_INET6`).
-* `flags` may be the flags specified in `socket(2)`, i.e. `SOCK_NONBLOCK` and/or `SOCK_CLOEXEC`. More than one flags may be ORed. **This argument is only sensible on Linux >= 2.6.27!**
+* `flags` may be the flags specified in `socket(2)`, i.e. `SOCK_NONBLOCK` and/or `SOCK_CLOEXEC`. More than one flags may be ORed. **This argument only has an effect on Linux >= 2.6.27!**
 
 Like the function before, this function also has different prototypes on different platforms.
 

doxyconf.conf

@@ -1357,7 +1357,7 @@ RTF_EXTENSIONS_FILE    =
 # If the GENERATE_MAN tag is set to YES (the default) Doxygen will
 # generate man pages
 
-GENERATE_MAN           = YES
+GENERATE_MAN           = NO
 
 # The MAN_OUTPUT tag is used to specify where the man pages will be put.
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be
@@ -1386,7 +1386,7 @@ MAN_LINKS              = NO
 # generate an XML file that captures the structure of
 # the code including all documentation.
 
-GENERATE_XML           = YES
+GENERATE_XML           = NO
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put.
 # If a relative path is entered the value of OUTPUT_DIRECTORY will be

doxymain.dox

@@ -1,29 +1,24 @@
 /**
 @mainpage The libsocket documentation
 
+<b>This documentation is targeted at people who want to gain deeper insight into the libsocket source code.
+Normal library users should use the documentation provided in the doc/libsocket and doc/libsocket++ directories!</b>
+
 This is the documentation for the C and C++ library libsocket. libsocket is intended to simplify the use of internet and
 UNIX sockets. Information about how to build libsocket are placed <a href="building.html">here</a>, and <a href="usage.html">this page</a>
 tells you how to use libsocket in your applications.
 
 @section libsocket libsocket for C
 
-To get started with *libsocket for C*, take a look at <a href="group__libinetsocket.html">the libinetsocket</a> and the <a
-href="group__libunixsocket.html">libunixsocket</a> documentation.
-
-@subsection lsconcepts Basic concepts
+To get started with *libsocket for C*, take a look at [the hand-crafted documentation](https://github.com/dermesser/libsocket/blob/master/doc/libsocket/DOCUMENTATION.mkd).
 
-All functions are documented in the links mentioned above; you don't need to know more about them than that they return -1 if
-something goes wrong. If you want to enable errors on STDERR, define in the Makefiles the macro `VERBOSE` using the
-compiler switch `-DVERBOSE`.
+Detailed documentation is available here: <a href="group__libinetsocket.html">libinetsocket</a>; <a
+href="group__libunixsocket.html">libunixsocket</a>.
 
 @section libsocketpp libsocket for C++
 
 libsocket++ should also be easy to understand but it has a <a href="classlibsocket_1_1socket.html">quite sophisticated class hierarchy</a>.
 
-@subsection lppconcepts Basic concepts
-
-You don't have to know too much to be able to use libsocket++; nevertheless you should know the basics.
-
 libsocket++ consists of many C++ classes. Only the following are intended for use in external applications:
 
 - inet_stream, inet_stream_server (TCP/IP client and server)
@@ -45,6 +40,8 @@ void f(xyzsocket&&);
 
 @endcode
 
+Detailed documentation can be found in this doxygen documentation; easier documentation is available [here](https://github.com/dermesser/libsocket/blob/master/doc/libsocket%2B%2B/DOCUMENTATION%2B%2B.mkd)
+
 */
 
 /************************************** BUILDING **********************************************/