Some manual refinements

doc/manual/advanced-options.xml

@@ -277,7 +277,7 @@ ZipcodeService = {
 			</callout>
 			<callout arearefs='co-multi-containers'>
 				<para>
-					It also possible to map a service to multple containers on multiple machines. This line states that the <varname>StaffTracker</varname> service should be deployed
+					It also possible to map a service to multiple containers on multiple machines. This line states that the <varname>StaffTracker</varname> service should be deployed
 					to both the first and second Apache Tomcat container on machine <varname>test1</varname>.
 				</para>
 			</callout>

doc/manual/architecture.xml

@@ -5,7 +5,7 @@
 	<title>Architecture</title>
 
 	<para>
-		Disnix is not a self-contained toolset and has a modular and extensible architecture.
+		Disnix is not a self-contained toolset. Instead, it has a modular and extensible architecture.
 		This chapter describes the architecture of Disnix and shows how certain low-level
 		activities can be performed.
 	</para>

doc/manual/basicusage.xml

@@ -62,7 +62,7 @@
 			a <emphasis>data layer</emphasis>, <emphasis>service layer</emphasis> and <emphasis>presentation layer</emphasis>.
 			The database layer contains MySQL databases,
 			storing data records such as zipcodes and staff members.
-			The web service layer contains web service components, which expose
+			The web service layer contains web service components exposing
 			create, read, update and delete operations for each data set
 			(the <code>GeolocationService</code> uses GeoIP to track a location).
 			In the presentation layer, the <code>StaffTracker</code>
@@ -78,7 +78,7 @@
 			the <code>StaffTracker</code> web application front-end.
 			The arrows denote inter-dependency relationships. Inter-dependency
 			correspond to network links between services. In this particular example, they
-			are SOAP/HTTP or plain TCP connections.
+			are SOAP/HTTP or "plain" TCP connections.
 		</para>
 	</section>
 
@@ -194,8 +194,8 @@ stdenv.mkDerivation { <co xml:id='co-mkDerivation' />
 
 				<callout arearefs='co-meta'>
 					<para>
-						We can also specify some meta data for a package, so that we have a description
-						and other useful information, such as the homepage and a license. These properties are not used
+						We can also specify meta data attributes for a package, so that we have a description
+						and other kinds of useful information, such as the homepage and a license. These properties are not used
 						while building the package.
 					</para>
 				</callout>
@@ -248,7 +248,7 @@ rec { <co xml:id='co-rec' />
 				<callout arearefs='co-importHello'>
 					<para>
 						Here, the expression defined in <xref linkend="ex-hello" /> is imported and called
-						with the its required function parameters. The corresponding dependencies are
+						with its required function parameters. The corresponding dependencies are
 						composed in the same composition expression shown in <xref linkend="ex-all-packages" />.
 					</para>
 					<para>
@@ -347,7 +347,7 @@ stdenv.mkDerivation { <co xml:id='co-mkDerivation-service' />
 			<para>
 				<xref linkend="ex-zipcode-service" /> shows a Disnix expression for
 				a particular web service component of the <code>StaffTracker</code>
-				system, called <code>ZipcodeService</code>, which provides access
+				system, called <code>ZipcodeService</code>, providing access
 				to records in the <code>zipcode</code> database.
 				A Disnix expression is a nested function (having two
 				function headers instead of one).
@@ -363,7 +363,7 @@ stdenv.mkDerivation { <co xml:id='co-mkDerivation-service' />
 						<itemizedlist>
 							<listitem>
 								<simpara>
-									<varname>stdenv</varname> is provides an environment containing
+									<varname>stdenv</varname> provides an environment containing
 									basic UNIX utilities and build environment.
 								</simpara>
 							</listitem>
@@ -405,7 +405,7 @@ stdenv.mkDerivation { <co xml:id='co-mkDerivation-service' />
 					<para>
 						Each target attribute set defines two properties. The <varname>properties</varname> attribute refers to general
 						machine properties and correspond to the properties attribute defined in the infrastructure model.
-						The <varname>container</varname> attribute refers to the set of container properties to which the services
+						The <varname>container</varname> attribute refers to the set of container properties to which the service
 						has been deployed.
 					</para>
 				</callout>
@@ -461,7 +461,7 @@ stdenv.mkDerivation { <co xml:id='co-mkDerivation-service' />
 				Like ordinary Nix expressions, we cannot use the expression in <xref linkend="ex-zipcode-service" /> directly to build the
 				service. We need to <emphasis>compose</emphasis> it by calling the function with its required arguments.
 				With Disnix, we need to compose a service twice. First, we have to compose this expression locally,
-				by calling it with the required intra-dependency arguments. Later, we have to compose it
+				by calling it with the required intra-dependency arguments. Later, we also have to compose it
 				using the inter-dependency arguments.
 			</para>
 
@@ -590,7 +590,7 @@ rec { <co xml:id='co-rec2' />
   zipcodes = { 
     name = "zipcodes"; 
     pkg = customPkgs.zipcodes; 
-    dependsOn = {};    
+    dependsOn = {};
     type = "mysql-database";
   };
   ...
@@ -698,15 +698,15 @@ rec { <co xml:id='co-rec2' />
 
 				<callout arearefs='co-pkg'>
 					<para>
-						For every service, we must know how to build it and what their intra- and inter-dependencies are. 
+						For every service, we must know how to build it and what their intra- and inter-dependencies are.
 						This attribute refers to the intra-dependency closure of the service, which is composed in
 						<xref linkend="ex-intra-dependency-composition-simplified" />.
 					</para>
 				</callout>
 
 				<callout arearefs='co-dependsOn'>
 					<para>
-						We also need to know for each service what the inter-dependencies actually are. 
+						We also need to know for each service what the inter-dependencies actually are.
 						Inter-dependencies correspond to the arrows shown in <xref linkend="fig-stafftracker" />.
 					</para>
 					<para>
@@ -741,8 +741,8 @@ rec { <co xml:id='co-rec2' />
 					<para>
 						The <code>package</code> type can be used to indicate that the service is an ordinary Nix package
 						that should be deployed remotely. Services of this type will be installed, but no additional deployment
-						steps will be performed, such activation or deactivation. Additional steps besides installing are not
-						necessary for packages. See <xref linkend="chap-packages" /> for more information.
+						steps will be performed, such activation or deactivation. Additional activities beyond installing are not
+						required for packages. See <xref linkend="chap-packages" /> for more information.
 					</para>
 				</callout>
 			</calloutlist>
@@ -854,7 +854,7 @@ rec { <co xml:id='co-rec2' />
 
 			<para>
 				The infrastructure model also allows you to specify a number of advanced system properties. These properties are
-				optional and typically reasonable default values are provided for them. They only need to be specified in special circumstances:
+				optional. In most scenarios, reasonable default values are provided for them. They only need to be specified in special circumstances:
 			</para>
 
 			<calloutlist>
@@ -876,7 +876,7 @@ rec { <co xml:id='co-rec2' />
 					<para>
 						This property is particularly useful when deploying to a heterogeneous network consisting of
 						machines running various kinds of operating systems having various kinds of system architectures.
-						You do not need a dedicated cluster of machines to build for these architecture, but you can
+						You do not need a dedicated cluster of machines to build for these architectures, but you can
 						reuse the existing deployment infrastructure.
 					</para>
 				</callout>

doc/manual/dysnomia-modules.xml

@@ -57,12 +57,8 @@ export prefix=@prefix@
 # Import utility functions
 source @datadir@/@PACKAGE@/util
 
-determineComponentName $2
-checkStateDir
-determineTypeIdentifier $0
-composeSnapshotsPath
-composeGarbagePath
-composeGenerationsPath
+# Sets a number of common utility environment variables
+composeUtilityVariables $0 $2 $3
 
 case "$1" in
     activate) <co xml:id='co-activate' />
@@ -78,10 +74,10 @@ case "$1" in
               fi
             ) | @mysql@ --user=$mysqlUsername --password=$mysqlPassword -N
         fi
-        unmarkStateAsGarbage
+        markComponentAsActive
         ;;
     deactivate) <co xml:id='co-deactivate' />
-        markStateAsGarbage
+        markComponentAsGarbage
         ;;
     snapshot) <co xml:id='co-snapshot' />
         tmpdir=$(mktemp -d)
@@ -102,7 +98,7 @@ case "$1" in
         createGenerationSymlink $snapshotsPath/$hash
         ;;
     restore) <co xml:id='co-restore' />
-        determineLastSnapshot
+        lastSnapshot=$(determineLastSnapshot)
 
         if [ "$lastSnapshot" != "" ]
         then
@@ -112,10 +108,10 @@ case "$1" in
         fi
         ;;
     collect-garbage) <co xml:id='co-collect-garbage' />
-        if [ -f $garbagePath ]
+        if componentMarkedAsGarbage
         then
             echo "drop database $componentName;" | @mysql@ --user=$mysqlUsername --password=$mysqlPassword -N
-            unmarkStateAsGarbage
+            unmarkComponentAsGarbage
         fi
         ;;
 esac

doc/manual/extensions.xml

@@ -5,7 +5,7 @@
 	<title>Extensions</title>
 
         <para>
-		Although Disnix makes the deployment of a distributed system more convenient and
+		Although Disnix makes it possible to automate the deployment of a service-oriented system and
 		offers various kinds of features to make this process reliable and efficient, some extensions have been
 		developed to make deployment processes more convenient.
         </para>

doc/manual/installation.xml

@@ -23,7 +23,7 @@
 		<para>
 			Deploying NixOS-based configurations is quite straight forward. A coordinator machine simply
 			requires the presence of the Dysnomia and Disnix utilities in the system environment or a Nix user
-			profile. Each target machine requires the Disnix service to be deployed and a number of
+			profile. Each target machine requires the presence of a Disnix service instance and (optionally) a number of
 			container services.
 		</para>
 		<section>
@@ -69,7 +69,7 @@ services.openssh.enable = true;
 
 			<para>
 				Besides SSH it also possible to use other kinds of communication protocols.
-				<xref linkend="chap-advanced-options" /> has more information on this.
+				<xref linkend="chap-advanced-options" /> provides more information on this.
 			</para>
 
 			<para>
@@ -103,8 +103,8 @@ services.tomcat.enable = true;
 			<title>Installing Dysnomia from source</title>
 
 			<para>
-				The <filename>dysnomia</filename> package is GNU Autotools based,
-				which must be installed by executing the following commands:
+				The <filename>dysnomia</filename> package is GNU Autotools based
+				and must be installed by executing the following commands:
 			</para>
 
 <screen>
@@ -163,7 +163,7 @@ $ ./configure --help
 					<link xlink:href="https://www.gnu.org/software/help2man">help2man</link> to generate
 					manual pages and
 					<link xlink:href="http://www.catb.org/esr/doclifter">doclifter</link> to generate
-					docbook pages from the generated manual pages.
+					Docbook pages from the generated manual pages.
 				</para>
 				<para>
 					Since Disnix is built on top of the 
@@ -341,13 +341,13 @@ exit 0
 				<para>
 					Refer to your distribution's <code>init.d</code> script style to see how services
 					are configured and launched. For convenience, a Debian-compatible init.d script named
-					<filename>disnix-service.initd</filename> has been placed in the <filename>$PREFIX/share/doc</filename> folder
-					of this package.
+					<filename>disnix-service.initd</filename> has been placed in the <filename>$PREFIX/share/doc</filename>
+					sub folder of this package.
 				</para>
 				<para>
 					An important aspect to keep in mind is that both Nix and Dysnomia should be in the <envar>PATH</envar>
 					of the <code>init.d</code> script so that the service can execute all required deployment activities.
-					Another important thing is that the Disnix service should be started after the D-Bus system service and stopped
+					Moreover, the Disnix service should be started after the D-Bus system service and stopped
 					in exactly the opposite order.
 				</para>
 				<para>
@@ -387,7 +387,7 @@ $ cygrunsrv -I disnix -p /usr/local/bin/disnix-service.exe \
 
 				<para>
 					The <option>-u</option> parameter specifies under which the Disnix
-					service runs. If a single user Nix installation has been performed, 
+					service runs. If a single user Nix installation has been performed,
 					this username should be substituted by the
 					actual username under which Disnix has been installed.
 					In multi-user Nix installations, the <option>-u</option> parameter should
@@ -497,7 +497,7 @@ type=mysql-database
 			</para>
 
 			<figure xml:id="fig-mysql-database">
-				<title>A Dysnomia container configuration file for a MySQL server</title>
+				<title>A Dysnomia component configuration file for a MySQL server</title>
 
 <programlisting>
 create table author

doc/manual/introduction.xml

@@ -8,8 +8,8 @@
 		Disnix is a distributed service deployment toolset which main
 		purpose is to deploy service-oriented systems (i.e. systems that can be
 		decomposed into "distributable units") into networks of machines
-		having various characteristics (such as operating systems) and is built on top of Nix;
-		a package manager which has some unique features compared to conventional package
+		having various characteristics (such as operating systems). Disnix is built on top of Nix --
+		a package manager that has a number of powerful and unique advantages over conventional package
 		managers to make deployment safe, reliable, and reproducible.
 	</para>
 
@@ -58,7 +58,7 @@
 
 	<para>
 		Moreover, Nix uses a purely functional domain-specific language called the Nix expression language
-		to specify build actions. Using a purely functional language makes builds deterministic and reproducable.
+		to specify build actions. Using a purely functional language makes builds deterministic and reproducible.
 		A garbage collector is included to safely remove packages that are no longer in use.
 	</para>
 
@@ -84,7 +84,7 @@
 			<para>
 				Like the standard Nix deployment system, Disnix uses
 				the Nix expression language, which is used to write
-				specifications for the deployment of distributed
+				specifications for the deployment of service-oriented
 				systems.
 			</para>
 			<para>
@@ -171,7 +171,7 @@
 				Apart from the portability of Disnix itself, Disnix also allows a user to deploy
 				a service oriented system into a heterogeneous network (i.e. a network consisting
 				of various types of machines, running various operating systems). Disnix reuses
-				Nix's delegation mechanism to build a component for an alien target platform.
+				Nix's delegation mechanism to build a package for an alien target platform.
 				Optionally, it can also delegate builds to the target machines in the network.
 			</para>
 		</simplesect>

doc/manual/overview.xml

@@ -5,7 +5,7 @@
 	<title>Overview</title>
 
 	<figure>
-		<title>An overview of Disnix</title>		
+		<title>An overview of Disnix</title>
 		<mediaobject>
 			<imageobject>
 				<imagedata fileref="model.png" format="PNG"/>
@@ -17,7 +17,7 @@
 		The figure above illustrates Disnix's deployment concepts in a nutshell.
 		In the center of the figure the <command>disnix-env</command>
 		command line tool is shown, which takes care of performing a complete deployment
-		process of a distributed system.
+		process of a service-oriented system.
 	</para>
 	<para>
 		This tool requires three models as input parameters shown
@@ -28,7 +28,7 @@
 					The <emphasis>services model</emphasis> describes of which distributable
 					components (called services) the system consists, their inter-dependencies and their types.
 					The service model has a reference to a file named <filename>all-packages.nix</filename>,
-					which captures all the intra-dependency compositions of every service,
+					capturing all the intra-dependency compositions of every service,
 					such as libraries, configuration files and compilers.
 				</simpara>
 			</listitem>
@@ -88,11 +88,11 @@ $ disnix-env -s services.nix -i infrastructure.nix -d distribution.nix
 	</para>
 
 	<para>
-		Optionally, Disnix can also move the state of a service from machine to another.
+		Optionally, Disnix can move the state of a service from machine to another.
 		For example, when deploying databases, Disnix only ensures that they are created with
 		a schema and initial dataset. However, when the structure and contents of a database
 		evolves, their changes are not migrated automatically.
 		As a solution, Disnix has a mechanism that snapshots, moves and restores state of a service
-		if it has been explicitly enabled for that particular service.
+		if state management has been explicitly enabled for that particular service.
 	</para>
 </chapter>

doc/manual/packages.xml

@@ -16,7 +16,7 @@
 		<title>Specifying packages as services</title>
 
 		<para>
-			In Nixpkgs, it it is a common habit to write each package specification as a function in which the parameters
+			In Nixpkgs, it is a common habit to write each package specification as a function in which the parameters
 			denote intra-dependencies. In <xref linkend="chap-basicusage" /> we have shown that
 			Disnix services follow the same convention and extend this approach with nested functions in which the inner
 			function takes inter-dependencies into account.

doc/manual/state.xml

@@ -18,7 +18,7 @@
 	</para>
 	<para>
 		In a large network of machines it can be quite costly to manage state manually. Disnix also provides
-		experimental state management facilities to cope with this. However, they are disabled by default.
+		experimental state management facilities to cope with this. However, state management is disabled by default.
 		To manage state for a specific subset of services, they must be annotated as such in the services model.
 	</para>
 

doc/manual/targetspecific.xml

@@ -352,7 +352,7 @@ builtins.listToAttrs (map (targetName:
     services = {
       nginx-wrapper-test2 = {
         name = "nginx-wrapper-test2";
-	...
+        ...
       };
       webapp3 = ...
       webapp4 = ...

scripts/Makefile.am

@@ -9,7 +9,7 @@ disnix-instantiate.1.xml: disnix-instantiate.1
 	$(SHELL) ../maintenance/man2docbook.bash $<
 
 disnix-manifest.1: disnix-manifest.in
-	$(HELP2MAN) --output=$@ --no-info --name 'Generate a manifest file from Disnix expressions' "$(SHELL) disnix-manifest"
+	$(HELP2MAN) --output=$@ --no-info --name 'Generate a deployment manifest file from Disnix expressions' "$(SHELL) disnix-manifest"
 
 disnix-manifest.1.xml: disnix-manifest.1
 	$(SHELL) ../maintenance/man2docbook.bash $<