general refinements to the builder page

docs/flatpak-builder.rst

@@ -1,9 +1,9 @@
 Flatpak Builder
 ===============
 
-If an application requires additional dependencies that aren't provided by its runtime, Flatpak allows them to be bundled as part of the app itself. This requires building each module inside the application build directory, which can be a lot of work. The ``flatpak-builder`` tool can automate this multi-step build process.
+Most applications require additional dependencies that aren't provided by their runtimes. Flatpak allows these dependencies to be bundled as part of the application itself. In order to do this, each dependency must be built inside the application build directory. The ``flatpak-builder`` tool automates this multi-step build process, making it possible to build all application modules with a single command. 
 
-flatpak-builder takes care of the routine commands used to build an app and any bundled libraries, thus allowing application building to be automated. To do this, it expects modules to be built in a standard manner by following what is called the `Build API <https://github.com/cgwalters/build-api/>`_. If any modules don't conform to this API, they will need to be modified.
+flatpak-builder expects modules to be built in the standard manner by following what is called the `Build API <https://github.com/cgwalters/build-api/>`_. If any modules don't conform to this API, they will need to be modified.
 
 Manifests
 ---------
@@ -36,35 +36,37 @@ The GNOME Dictionary manifest is short, because the only module is the applicati
     ]
   }
 
+As can be seen, this manifest includes basic information about the application before specifying a single .tar file to be downloaded and built. More complex manifests include a sequence of modules.
+
 Cleanup
 -------
 
-flatpak-builder performs a cleanup phase after the build, which can be used to remove headers and development docs, among other things. Two properties in the manifest file can be used for this. First, a list of filename patterns can be included::
+After building has taken place, flatpak-builder performs a cleanup phase. This can be used to remove headers and development documentation, among other things. Two properties in the manifest file are used for this. First, a list of filename patterns can be included::
 
   "cleanup": [ "/include", "/bin/foo-*", "*.a" ]
 
 The second cleanup property is a list of commands that are run during the cleanup phase::
 
   "cleanup-commands": [ "sed s/foo/bar/ /bin/app.sh" ]
 
-Cleanup properties can be set on a per-module basis, and will then only match filenames that were created by that particular module.
+Cleanup properties can be set on a per-module basis, in which case only filenames that were created by that particular module will be matched.
 
 File renaming
 -------------
 
-Files that are exported by a flatpak must be named using the application ID. However, application's source files will typically not follow this convention. To get around this, flatpak-builder allows renaming application icons, desktop files and AppData files as a part of the build process, using the ``rename-icon``, ``rename-desktop-file`` and ``rename-appdata`` properties.
+Files that are exported by a flatpak must be prefixed using the application ID. If an application's source files are not named using this convention, flatpak-builder allows them to be renamed as part of the build process. To rename application icons, desktop files and AppData files, use the ``rename-icon``, ``rename-desktop-file`` and ``rename-appdata`` properties.
 
 Splitting things up
 -------------------
 
-By default, flatpak-builder splits off translations into a separate .Locale runtime, and debuginfo into a .Debug runtime, and adds these 'standard' extension points to the application metadata. You can turn this off with the ``separate-locales`` and ``no-debuginfo`` keys, but there shouldn't be any reason for it.
+By default, flatpak-builder splits off translations and dubug information into separate .Locale and .Debug extensions. These 'standard' extension points are then added to the application's metadata file. You can turn this off with the ``separate-locales`` and ``no-debuginfo`` keys, but there shouldn't be any reason for it.
 
-When flatpak-builder exports the build into a repository, it automatically includes the .Locale and .Debug runtimes. If you do the exporting manually, don't forget to include them.
+When flatpak-builder exports the build into a repository, it automatically includes the .Locale and .Debug extensions. If you do the exporting manually, don't forget to include them.
 
 Example
 -------
 
-You can try flatpak-builder for yourself, using the repository that was created in the previous section. To do this, place the manifest json from above into a file called ``org.gnome.Dictionary.json`` and run the following command::
+You can try flatpak-builder for yourself, using the repository that was created in the `previous section <building-simple-apps>`_. To do this, place the manifest json from above into a file called ``org.gnome.Dictionary.json`` and run the following command::
 
   $ flatpak-builder --repo=repo dictionary2 org.gnome.Dictionary.json