Merge pull request #538 from mhameed/master

Documentation fixes

docs/src/cdist-best-practice.rst

@@ -97,7 +97,7 @@ Including a possible common base that is reused across the different sites::
     git merge common
 
 
-The following **.git/config** is taken from a a real world scenario::
+The following **.git/config** is taken from a real world scenario:
 
     # Track upstream, merge from time to time
     [remote "upstream"]
@@ -142,7 +142,7 @@ implement this scenario with a gateway host and sudo:
 - Setup the ssh-pubkey for this user that has the right to configure all hosts
 - Create a wrapper to update the cdist configuration in ~cdist/cdist
 - Allow every developer to execute this script via sudo as the user cdist
-- Allow run of cdist as user cdist on specific hosts on a per user/group base
+- Allow run of cdist as user cdist on specific hosts on a per user/group basis.
 
     - f.i. nico ALL=(ALL) NOPASSWD: /home/cdist/bin/cdist config hostabc
 
@@ -171,7 +171,7 @@ Templating
     }
     EOF
 
-* in the manifest, export the relevant variables and add the following lines in your manifest:
+* in the manifest, export the relevant variables and add the following lines to your manifest:
 
 .. code-block:: console
 
@@ -213,11 +213,11 @@ Other content in cdist repository
 Usually the cdist repository contains all configuration
 items. Sometimes you may have additional resources that
 you would like to store in your central configuration
-repositiory (like password files from KeepassX,
+repository (like password files from KeepassX,
 Libreoffice diagrams, etc.).
 
 It is recommended to use a subfolder named "non-cdist"
 in the repository for such content: It allows you to
-easily distinguish what is used by cdist and what not
+easily distinguish what is used by cdist and what is not
 and also to store all important files in one
 repository.

docs/src/cdist-explorer.rst

@@ -3,8 +3,8 @@ Explorer
 
 Description
 -----------
-Explorer are small shell scripts, which will be executed on the target
-host. The aim of the explorer is to give hints to types on how to act on the
+Explorers are small shell scripts, which will be executed on the target
+host. The aim of each explorer is to give hints to types on how to act on the
 target system. An explorer outputs the result to stdout, which is usually
 a one liner, but may be empty or multi line especially in the case of
 type explorers.

docs/src/cdist-features.rst

@@ -8,7 +8,7 @@ Simplicity
 
 Design
     + Type and core cleanly separated
-    + Sticks completly to the KISS (keep it simple and stupid) paradigma
+    + Sticks completely to the KISS (keep it simple and stupid)  paradigm
     + Meaningful error messages - do not lose time debugging error messages
     + Consistency in behaviour, naming and documentation
     + No surprise factor: Only do what is obviously clear, no magic
@@ -40,9 +40,9 @@ Requirements, Simplicity
 UNIX
     Reuse of existing tools like cat, find, mv, ...
 
-UNIX, familar environment, documentation
+UNIX, familiar environment, documentation
     Is available as manpages and HTML
 
-UNIX, simplicity, familar environment
+UNIX, simplicity, familiar environment
     cdist is configured in POSIX shell
 

docs/src/cdist-hacker.rst

@@ -4,7 +4,7 @@ Hacking
 Welcome
 -------
 Welcome dear hacker! I invite you to a tour of pointers to
-get into the usable configuration mangament system, cdist.
+get into the usable configuration management system, cdist.
 
 The first thing to know is probably that cdist is brought to
 you by people who care about how code looks like and who think
@@ -21,18 +21,18 @@ subject prefixed with "[BUG] " or create an issue on github.
 
 Coding conventions (everywhere)
 -------------------------------
-If something should be better done or needs to fixed, add the word FIXME
+If something should be improved or needs to be fixed, add the word FIXME
 nearby, so grepping for FIXME gives all positions that need to be fixed.
 
-Indention is 4 spaces (welcome to the python world).
+Indentation is 4 spaces (welcome to the python world).
 
 
 How to submit stuff for inclusion into upstream cdist
 -----------------------------------------------------
-If you did some cool changes to cdist, which you value as a benefit for
-everybody using cdist, you're welcome to propose inclusion into upstream.
+If you did some cool changes to cdist, which you think might be of benefit to other
+cdist users, you're welcome to propose inclusion into upstream.
 
-There are though some requirements to ensure your changes don't break others
+There are some requirements to ensure your changes don't break other peoples
 work nor kill the authors brain:
 
 - All files should contain the usual header (Author, Copying, etc.)
@@ -130,7 +130,7 @@ use **git stash** to stash your changes away::
     git fetch -v origin
     git merge origin/master
 
-Similar when you want to develop another new feature, you go back
+Similarly when you want to develop another new feature, you go back
 to the master branch and create another branch based on it::
 
 .. code-block:: sh

docs/src/cdist-install.rst

@@ -7,7 +7,7 @@ Requirements
 Source Host
 ~~~~~~~~~~~
 
-This is the machine you use to configure the target hosts.
+This is the machine from which you will configure target hosts.
 
  * /bin/sh: A posix like shell (for instance bash, dash, zsh)
  * Python >= 3.2

docs/src/cdist-manifest.rst

@@ -51,7 +51,7 @@ The **initial manifest** is the entry point for cdist to find out, which
 **objects** to configure on the selected host.
 Cdist expects the initial manifest at **cdist/conf/manifest/init**.
 
-Within this initial manifest you define, which objects should be
+Within this initial manifest you define which objects should be
 created on which host. To distinguish between hosts, you can use the
 environment variable **__target_host** and/or **__target_hostname** and/or
 **__target_fqdn**. Let's have a look at a simple example::
@@ -114,7 +114,7 @@ requirements can be added white space separated.
 Above the "require" variable is only set for the command that is 
 immediately following it. Dependencies should always be declared that way.
 
-On line 4 you can see that the instantion of a type "\__link" object needs
+On line 4 you can see that the instantiation of a type "\__link" object needs
 the object "__file/etc/cdist-configured" to be present, before it can proceed.
 
 This also means that the "\__link" command must make sure, that either
@@ -149,7 +149,7 @@ All objects that are created in a type manifest are automatically required
 from the type that is calling them. This is called "autorequirement" in
 cdist jargon.
 
-You can find an more in depth description of the flow execution of manifests
+You can find a more in depth description of the flow execution of manifests
 in `cdist execution stages <cdist-stages.html>`_ and of how types work in `cdist type <cdist-type.html>`_.
 
 

docs/src/cdist-stages.rst

@@ -3,8 +3,7 @@ Execution stages
 
 Description
 -----------
-Starting the execution of deployment with cdist, cdist passes
-through different stages.
+When cdist is started, it passes through different stages.
 
 
 Stage 1: target information retrieval
@@ -67,5 +66,5 @@ The cache stores the information from the current run for later use.
 
 Summary
 -------
-If, and only if, all the stages complete without an errors, the configuration
+If, and only if, all the stages complete without errors, the configuration
 will be applied to the target.

docs/src/cdist-why.rst

@@ -40,9 +40,9 @@ call cdist types, the result is always the same.
 Zero dependency configuration management
 ----------------------------------------
 
-Cdist requires very litte on a target system. Even better,
+Cdist requires very little on a target system. Even better,
 in almost all cases all dependencies are usually fulfilled.
-Cdist does not require an agent or a high level programming
+Cdist does not require an agent or high level programming
 languages on the target host: it will run on any host that
 has a **ssh server running** and a posix compatible shell
 (**/bin/sh**). Compared to other configuration management systems,
@@ -52,7 +52,7 @@ Push based distribution
 -----------------------
 
 Cdist uses the push based model for configuration. In this
-scenario, one (or more) computers connect the target hosts
+scenario, one (or more) computers connect to the target hosts
 and apply the configuration. That way the source host has
 very little requirements: Cdist can even run on a sysadmin
 notebook that is loosely connected to the network and has

docs/src/man1/cdist.rst

@@ -72,7 +72,7 @@ Configure/install one or more hosts.
 
 .. option:: -b, --beta
 
-    Enable beta functionalities.
+    Enable beta functionality.
     
     Can also be enabled using CDIST_BETA env var.
 
@@ -88,8 +88,8 @@ Configure/install one or more hosts.
 
 .. option:: -f HOSTFILE, --file HOSTFILE
 
-    Read additional hosts to operate on from specified file
-    or from stdin if '-' (each host on separate line).
+    Read specified file for a list of additional hosts to operate on
+    or if '-' is given, read stdin (one host per line).
     If no host or host file is specified then, by default,
     read hosts from stdin. For the file format see below.
 
@@ -134,12 +134,13 @@ Configure/install one or more hosts.
 
 HOSTFILE FORMAT
 ~~~~~~~~~~~~~~~
-HOSTFILE contains hosts per line. 
-All characters after and including '#' until the end of line is a comment.
-In a line, all leading and trailing whitespace characters are ignored.
+The HOSTFILE contains one host per line.
+A comment is started with '#' and continues to the end of the line.
+Any leading and trailing whitespace on a line is ignored.
 Empty lines are ignored/skipped.
 
-Hostfile line is processed like the following. First, all comments are
+
+The Hostfile lines are processed as follows. First, all comments are
 removed. Then all leading and trailing whitespace characters are stripped.
 If such a line results in empty line it is ignored/skipped. Otherwise,
 host string is used.
@@ -244,7 +245,7 @@ CDIST_REMOTE_COPY
     Use this command for remote copy (should behave like scp).
 
 CDIST_BETA
-    Enable beta functionalities.
+    Enable beta functionality.
 
 EXIT STATUS
 -----------
@@ -275,10 +276,10 @@ options. For more details refer to :strong:`sshd_config`\ (5).
 When requirements for the same object are defined in different manifests (see
 example below), for example, in init manifest and in some other type manifest
 and those requirements differ then dependency resolver cannot detect
-dependencies right. This happens because cdist cannot prepare all objects first
+dependencies correctly. This happens because cdist cannot prepare all objects first
 and run all objects afterwards. Some object can depend on the result of type
 explorer(s) and explorers are executed during object run. cdist will detect
-such case and write warning message. Example for such a case:
+such case and display a warning message. An example of such a case:
 
 .. code-block:: sh