Merge pull request #18 from hugbubby/userguide

Fix grammar and and wording in user-guide.

docs/user-guide/configuration.md

@@ -1,17 +1,18 @@
 i2pd configuration
 ==================
 
-i2pd can be configured via command-line arguments and config files. 
-Options are the same, for example, running i2pd with argument `--port=10123` and setting
-option `port = 10123` in config file will have same effect.
+i2pd can be configured via either command-line arguments or config files. 
+Modifying `i2pd.conf` is just a way of passing command line arguments to i2pd at boot; 
+for example, running i2pd with argument `--port=10123` and setting option `port = 10123` in config file will have 
+the same effect.
 
-There are two separate config files `i2pd.conf` and `tunnels.conf`. `i2pd.conf` is main configuration file, where
-you configure all options. `tunnels.conf` is I2P tunnel configuration file, where you configure I2P hidden services
-and client tunnels for you needs. `tunnels.conf` options are documented [here](tunnels.md).
+There are two separate config files: `i2pd.conf` and `tunnels.conf`. `i2pd.conf` is the main configuration file, where
+you configure all options. `tunnels.conf` is the tunnel configuration file, where you configure I2P hidden services
+and client tunnels. the `tunnels.conf` options are documented [here](tunnels.md).
 
-INI-like, syntax is the following : <key> = <value>.
-Comments are "#", not ";" as you may expect. See [boost ticket](https://svn.boost.org/trac/boost/ticket/808)
-All command-line parameters are allowed as keys, but note for those which contains dot (.).
+`i2pd.conf` accets INI-like syntax, such as the following : <key> = <value>.
+Comments are "#", not ";" as you might expect. See [boost ticket](https://svn.boost.org/trac/boost/ticket/808)
+All command-line parameters are allowed as keys, but for those which contains dot (.), there is a special syntax.
 
 For example:
 
@@ -28,7 +29,7 @@ i2pd.conf:
     [sam]
     enabled = true
 
-See also commented config with examples of all options in ``contrib/i2pd.conf``.
+You are also encouraged to see the commented config with examples of all options in ``contrib/i2pd.conf``.
 
 Options specified on the command line take precedence over those in the config file.
 If you are upgrading your very old router (< 2.3.0) see also [this](config_opts_after_2.3.0.md) page.
@@ -229,6 +230,7 @@ exploratory.outbound.quantity          | Exploratory outbound tunnels length. 3
 Local addressbook
 -----------------
 
-There is also a special addressbook config file in working directory `addressbook/local.csv`.
-It is used to map long I2P destinations to short, human readable domain names. The syntax is csv.
+There is also a special addressbook config file in the working directory at `addressbook/local.csv`.
+It is used to map long I2P destinations to short, human readable domain names. The syntax is csv and
+it can be modified manually if the user wishes.
 

docs/user-guide/family.md

@@ -1,27 +1,27 @@
 Family configuration
 ====================
 
-Your might want to specify a family, your router belongs to.
-There are two possibilities: create new family or joining to existing.
+Your might want to specify a family your router belongs to.
+There are two ways to do this: create a new family or join to an existing one.
 
 New family
 -----------
 
-You must create family self-signed certificate and key.  
+To create a new family, you must first create a family self-signed certificate and key.  
 The only key type supported is prime256v1.
-Use the following list of commands:  
+Use the following list of commands to do this through openssl:  
 
     openssl ecparam -name prime256v1 -genkey -out <your family name>.key  
     openssl req -new -key <your family name>.key -out <your family name>.csr  
     touch v3.ext
     openssl x509 -req -days 3650 -in <your family name>.csr -signkey <your family name>.key -out <your family name>.crt -extfile v3.ext  
 
-Specify <your family name>.family.i2p.net for CN (Common Name) when requested.
+Specify <your family name>.family.i2p.net for the CN (Common Name) when requested.
 
-Once you are done with it place <your-family-name>.key and <your-family-name>.crt to <ip2d data>/family folder (for exmple ~/.i2pd/family).
+Once you are done generating it place <your-family-name>.key and <your-family-name>.crt in the <ip2d data>/family folder (for example ~/.i2pd/family).
 You should provide these two files to other members joining your family.
-If you want to register you family and let I2P network recognize it, create pull request for you .crt file into contrib/certificate/family.
-It will appear in i2pd and I2P next releases packages. Don't place .key file, it must be shared between you family members only.
+If you want to register your family and let the I2P network recognize it, create a pull request for your .crt file into contrib/certificate/family.
+Certificates added into the public repository this way will appear in i2pd and I2P next releases packages. Don't place .key file, it must be shared between you family members only.
 
 How to join existing family
 ---------------------------
@@ -31,6 +31,8 @@ Once you and that family agree to do it, they must give you .key and .crt file a
 Publish your family
 -------------------
 
-Run i2pd with parameter 'family=<your-family-name>', make sure you have <your-family-name>.key and <your-family-name>.crt in your 'family' folder.
+Run i2pd with the parameters 'family=<your-family-name>', and make sure you have <your-family-name>.key and <your-family-name>.crt in your 'family' folder.
 If everything is set properly, you router.info will contain two new fields: 'family' and 'family.sig'.
-Otherwise your router will complain on startup with log messages starting with "Family:" prefix and severity 'warn' or 'error'.
+If not, your router will complain on startup with log messages starting with "Family:" prefix and severity 'warn' or 'error'.
+
+TODO: List common errors

docs/user-guide/run.md

@@ -4,9 +4,9 @@ Running i2pd
 Starting, stopping and reloading configuration
 ----------------------------------------------
 
-This chapter explains how to start and manage i2pd daemon under \*nix operation systems.
+This chapter explains how to start and manage the i2pd daemon under \*nix operation systems.
 
-After you have built i2pd from source, just run a binary:
+After you have built i2pd from source, just run the binary:
 
     ./i2pd
 
@@ -14,29 +14,29 @@ To display all available options:
 
     ./i2pd --help
 
-i2pd can be controlled with signals. Process ID by default is written to file `~/.i2pd/i2pd.pid` or `/var/run/i2pd/i2pd.pid`.
-You can use `kill` utility to send signals like this:
+i2pd can be controlled with signals. The process ID by is written to the file `~/.i2pd/i2pd.pid` or 
+`/var/run/i2pd/i2pd.pid` by default. You can use `kill` utility to send signals like this:
 
     kill -INT $( cat /var/run/i2pd/i2pd.pid )
 
 i2pd supports the following signals:
 
-* INT - Graceful shutdown. i2pd will wait for 10 minutes and stop. Send second INT signal to shutdown i2pd immediately.
+* INT - Graceful shutdown. i2pd will wait for up to 10 minutes and stop. Send a second INT signal to shutdown i2pd immediately.
 * HUP - Reload configuration files.
 
 
 ### systemd unit
 
-Some Linux packages have a systemd control unit, so it is possible to manage i2pd with it.
+Some i2pd packages come with a systemd control unit, and for those that use systemd, it is possible to manage i2pd with it.
 
-Start/stop i2pd:
+To start/stop i2pd:
 
     sudo systemctl start i2pd.service
     sudo systemctl stop i2pd.service --no-block
 
-Stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes).
+The stop command initiates a graceful shutdown process, i2pd stops after finishing to route transit tunnels (maximum 10 minutes).
 
-Enable/disable i2pd to be started on bootup:
+To enable/disable autostart of i2pd upon bootup:
 
     sudo systemctl enable i2pd.service
     sudo systemctl disable i2pd.service
@@ -45,7 +45,8 @@ Enable/disable i2pd to be started on bootup:
 Recommended way to run i2pd built from source
 ---------------------------------------------
 
-This way all i2pd-related files will be stored at `$HOME/dist`.
+The following commands display the recommended way to build i2pd from source, without a package manager. Installing i2pd this 
+way will ensure all i2pd-related files are stored at `$HOME/dist`.
 
     mkdir $HOME/dist
     cp i2pd $HOME/dist
@@ -53,5 +54,8 @@ This way all i2pd-related files will be stored at `$HOME/dist`.
     cp contrib/i2pd.conf $HOME/dist
     cd $HOME/dist
     ulimit -n 4096  # only on Linux, increasing open file limit
+
+Then, to run i2pd, simply travel to the installation directory and type:
+
     ./i2pd --datadir .
 

docs/user-guide/tunnels.md

@@ -4,14 +4,15 @@ I2P tunnel configuration
 Overview
 --------
 
-tunnels.conf is designed to support multiple I2P tunnels. Must be located in ``~/.i2pd`` (per-user) or ``/var/lib/i2pd`` (system-wide).
+`tunnels.conf` is designed to support multiple I2P tunnels. The configuration file must be located in 
+``~/.i2pd`` (per-user) or ``/var/lib/i2pd`` (system-wide).
 
-This file uses .ini file format. It consists of multiple sections with unique name each.
+This file uses the .ini file format. It consists of multiple sections each with a unique name.
 
 Tunnel types
 ------------
 
-Section type is specified by *type* parameter. 
+Section type is specified by the *type* parameter. 
 
 Available tunnel types:
 
@@ -33,9 +34,9 @@ Client tunnels
 
 Mnemonic: we can connect to someone as client
 
-Must contain few mandatory parameters, some optional parameters might be also presented.
+Each client tunnel must contain a few mandatory parameters, along with some optional ones.
 
-Example of client tunnel:
+Here is an example of a client tunnel:
 
     [irc-out]
     type = client
@@ -44,8 +45,9 @@ Example of client tunnel:
     destination = irc.echelon.i2p
     keys = irc.dat
 
-If *keys* is empty, transient keys will be created on every restart. If keys file is not found, new keys will be created and stored into specified file. If *keys* is equal to *transient*, new keys will be created, but not stored into a file.  
-Client tunnels might share same local destination, if keys file contains same identity.
+If *keys* is empty, transient keys will be created on every restart. If the keys file is not found, new keys will be created and stored into the specified file. 
+If *keys* is set to *transient*, new keys will be created, but not stored into a file.  
+Client tunnels might share the same local destination, if the keys file contains the same identity.
 
 Optional parameters:
 
@@ -54,14 +56,14 @@ Optional parameters:
 * crytotype       -- crypto type for new keys. Experimental. Should be alway 0  
 * destinationport -- connect to particular port at destination. 0 by default
 
-So, with example above, if you telnet to 127.0.0.1:6668 on localhost, i2pd will connect to irc.echelon.i2p:6668
+So, given the example above, if you connected to to 127.0.0.1:6668 on localhost, i2pd would tunnel that to irc.echelon.i2p:6668
 
 Server/generic tunnels
 ----------------------
 
 Mnemonic: we serving some service to others in network
 
-Example of server tunnel:
+Here is an example of a server tunnel:
 
     [smtp-in]
     type = server
@@ -69,7 +71,8 @@ Example of server tunnel:
     port = 25
     keys = smtp-in.dat
 
-*keys* must be presented, LeaseSet of address from keys file will be published. Server tunnel must use its own local destination.
+The file in *keys* must be present, and the LeaseSet of address from keys file will be published. 
+The server tunnel must use its own local destination such as host 127.0.0.1 and port 80.
 
 Optional parameters:
 
@@ -83,10 +86,10 @@ Optional parameters:
 Server/http tunnels
 -------------------
 
-*http* tunnel works same way as server tunnel, but replace 'Host:' field in HTTP header to address provided in configuration.
-Also resolves it if necessary.
+*http* tunnels are configured just like regular server tunnels, except the the 'Host:' field 
+must be assigned to the address provided in configuration. i2pd will also resolve it if necessary.
 
-Example of http tunnel:
+Here's an example of an http tunnel:
 
     [http-in]
     type = http
@@ -143,9 +146,9 @@ There are 2 types of UDP tunnels: `udpclient` and `udpserver`
 Socks proxy
 -----------
 
-Socks proxy interface can be defined in ``tunnels.conf``.
+The SOCKS proxy interface can be defined in ``tunnels.conf``.
 
-Example of Socks proxy:
+Here's an example of a Socks proxy:
 
     [alt-socks]
     type = socks
@@ -160,7 +163,7 @@ Example of Socks proxy:
 I2CP parameters
 ---------------
 
-I2CP parameter are common for all tunnel types and specify setting for a local destination.
+These I2CP parameter are common for all tunnel types and specify settings for a local destination.
 
 * inbound.length    -- number of hops of an inbound tunnel. 3 by default;  lower value is faster but dangerous
 * outbound.length   -- number of hops of an outbound tunnel. 3 by default; lower value is faster but dangerous