random bits of polish

docs/elements-of-a-flatpak-app.rst

@@ -8,7 +8,7 @@ Standard application elements
 
 The following are some of the Linux desktop conventions that are supported and expected by Flatpak. Application developers are encouraged to use them.
 
-* `AppData <https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps>`_, for providing information that can be used by app stores, such as an application description and screenshots
+* `AppData <https://www.freedesktop.org/software/appstream/docs/chap-Quickstart.html#sect-Quickstart-DesktopApps>`_, for providing application information, such as descriptions and screenshots, that is used by app stores
 * Application icons, as specified by the `Freedesktop icon theme specification <https://standards.freedesktop.org/icon-theme-spec/icon-theme-spec-latest.html>`_
 * `D-Bus <https://www.freedesktop.org/wiki/Software/dbus/>`_, for interaction with the host
 * `Desktop files <https://standards.freedesktop.org/desktop-entry-spec/latest/>`_, for providing basic information about the application
@@ -25,9 +25,16 @@ When an application is built using flatpak, it is outputted with the following s
 * ``/files/bin`` - application binaries
 * ``/export`` - files which the host environment needs access to, such as the application's AppData, .desktop file, icon and D-Bus service files
 
-All the files in the export directory must have the application ID as a prefix (for example: ``org.gnome.App.appdata.xml``, ``org.gnome.App.desktop``, ``org.gnome.App.png``, ``org.gnome.App.service``). Naming files in this way guarantees that applications cannot cause conflicts and that they can’t override any system installed applications.
+All the files in the export directory must have the application ID as their prefix. For example: 
 
-To name exported files in this way, either rename the relevant source files with the application ID, or use flatpak-builder to rename the files at build time (this is explained in more detail in the section on flatpak-builder).
+* ``org.gnome.App.appdata.xml``
+* ``org.gnome.App.desktop``
+* ``org.gnome.App.png``
+* ``org.gnome.App.service``
+
+Naming files in this way prevents naming conflicts and ensures that system installed applications aren't overwritten.
+
+To name exported files in this way, either rename the relevant source files or use flatpak-builder to rename the files at build time (this is explained in more detail in `the section on flatpak-builder <flatpak-builder.html>`_).
 
 Metadata files
 --------------
@@ -53,7 +60,7 @@ An application's ``metadata`` file provides information that allows flatpak to s
   org.extra.name=talk
   org.other.name=own
 
-This specifies the name of the application, the runtime it requires, the SDK that it is built against and the command used to run it. It also specifies file and device access, sets certain environment variables (inside the sandbox, of course), and how to connect to the session bus. Details on how to change these metadata parameters are included in subsequent sections.
+This specifies the name of the application, the runtime it requires, the SDK that it was built against and the command used to run it. It also specifies file and device access, sets certain environment variables (inside the application's sandbox, of course), and how it connects to the session bus. Details on how to change these metadata parameters are included in subsequent sections.
 
 .. note::
   While it is most common to encounter application metadata files, runtimes and extensions also have them.

docs/getting-setup.rst

@@ -3,7 +3,7 @@ Getting Setup
 
 Getting setup to build Flatpaks is quick and easy. First, it is necessary to have the ``flatpak`` and ``flatpak-builder`` packages installed on your system. These are available for most distributions, and the Flatpak website provides `details on how to get them <http://flatpak.org/getting.html>`_.
 
-Once flatpak has been installed, it is necessary to pick a runtime and install the SDK and install it.
+Once flatpak has been installed, it is necessary to pick a runtime and install it, along with the matching SDK.
 
 Installing an SDK
 -----------------
@@ -12,7 +12,7 @@ An SDK is a special type of runtime that is used to build applcations. Typically
 
 The Flatpak website provides a `list of the available runtimes <http://flatpak.org/runtimes.html>`_. Once you have decided which one to use, getting setup is just a matter of installing it and its SDK.
 
-The examples in the rest of the Flatpak documentation uses the GNOME 3.22 runtime and SDK. If you haven't installed these already, download the repository GPG key and then add the repository that contains the runtime and SDK::
+The examples in the rest of the Flatpak documentation use the GNOME 3.22 runtime and SDK. If you haven't installed these already, download the repository GPG key and then add the repository that contains the runtime and SDK::
 
   $ flatpak remote-add --from gnome https://sdk.gnome.org/gnome.flatpakrepo
 
@@ -25,7 +25,7 @@ This same procedure can be used to install any other runtime and SDK.
 Taking a look around
 --------------------
 
-If this is the first time you've used Flatpak, this might be a good time to try installing an application and having a look 'under the hood'. To do this, you need to add a repository that contains applications. We can do this using the gnome-apps repository to install gedit::
+If this is the first time you've used Flatpak, it is a good time to try installing an application and having a look 'under the hood'. To do this, you need to add a repository that contains applications. We can do this using the gnome-apps repository to install gedit::
 
   $ flatpak remote-add --from gnome-apps https://sdk.gnome.org/gnome-apps.flatpakrepo
   $ flatpak install gnome-apps org.gnome.gedit

docs/index.rst

@@ -1,9 +1,9 @@
 Welcome to Flatpak's documentation!
 ===================================
 
-These docs cover everything you need to know to build and/or distribute applications as Flatpaks. They contain a high-level introduction to Flatpak, tutorials on building applications and essential information on how to develop and distribute applications as Flatpaks.
+These docs cover everything you need to know to build and distribute applications as Flatpaks. They contain a high-level introduction to Flatpak, tutorials and essential information on how to develop, build and distribute applications.
 
-The docs are primarily intended for application developers and distributors. However, they might be interesting if you are interested in Flatpak more generally.
+The docs are primarily intended for application developers and distributors. Their content is also relevant to those who have a general interest in Flatpak.
 
 If you are looking for information about how to install and use Flatpak applications, please refer to `the Flatpak website <http://flatpak.org>`_. Otherwise, if you want information about Flatpak internals or how to create runtimes, the `Flatpak wiki <https://github.com/flatpak/flatpak/wiki>`_ is the best place to start.
 

docs/introduction.rst

@@ -7,7 +7,7 @@ Flatpak has been designed and implemented with a number of goals:
 
 * Allow applications to be installed on any Linux distribution.
 * Provide consistent environments for applications, to facilitate testing and reduce bugs.
-* Decouple applications from operating system, so that applications don't depend on specific versions of each distribution.
+* Decouple applications from the operating system, so that applications don't depend on specific versions of each distribution.
 * Allow applications to bundle their own dependencies, so that they can use libraries that aren't provided by a Linux distribution, and so they can depend on specific versions or even patched versions of a library.
 * Increase the security of Linux desktops, by isolating applications in sandboxes.
 
@@ -18,14 +18,14 @@ More information about Flatpak can be found on `flatpak.org <http://flatpak.org/
 How it works
 ------------
 
-Familiarity with a few key concepts is enough to understand how Flatpak works, as well as how it differs from traditional software packages.
+Flatpak can be understood through a small number of key concepts. These also help to explain how it differs from traditional software packages.
 
 .. image:: ../images/diagram.svg
 
 Runtimes
 ^^^^^^^^
 
-Runtimes provide the basic dependencies that applications might require. Various runtimes are available, from more minimal (but more stable) Freedesktop runtimes, to larger runtimes produced by desktops like GNOME or KDE. (The `runtimes page <http://flatpak.org/runtimes.html>`_ on flatpak.org provides an overview of the runtimes that are currently available.)
+Runtimes provide the basic dependencies that are used by applications. Various runtimes are available, from more minimal (but more stable) Freedesktop runtimes, to larger runtimes produced by desktops like GNOME or KDE. (The `runtimes page <http://flatpak.org/runtimes.html>`_ on flatpak.org provides an overview of the runtimes that are currently available.)
 
 Each application must be built against a runtime, and this runtime must be installed on a host system in order for the application to run. Users can install multiple different runtimes at the same time, including different versions of the same runtime.
 
@@ -40,30 +40,27 @@ Bundled libraries
 
 If an application requires any dependencies that aren't in its runtime, they can be bundled along with the application itself. This allows applications to use dependencies that aren't available in a distribution, or to use a different version of a dependency from the one that's installed on the host.
 
-.. note::
-  Both runtimes and app bundles can be installed per-user and system-wide.
-
 SDKs (Software Developer Kits)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-An SDK is a runtime that includes the 'devel' parts which are not needed at runtime, such as build and packaging tools, header files, compilers and debuggers. Each application is built against an SDK, which is typically paired with a runtime (this is the runtime that will be used by the application at runtime).
+An SDK is a runtime that includes the 'devel' parts which are not needed at runtime, such as build and packaging tools, header files, compilers and debuggers. Each application is built against an SDK, which is paired with a runtime (this is the runtime that will be used by the application at runtime).
 
 Extensions
 ^^^^^^^^^^
 
-An extension is an optional add-on for a runtime or application. They are most commonly used to split out translations and debug info from runtimes. For example, ``org.freedesktop.Platform.Locale`` can be added to the ``org.freedesktop.Platform`` runtime in order to enable translations.
+An extension is an optional add-on for a runtime or application. They are most commonly used to split out translations and debug info from runtimes. For example, ``org.freedesktop.Platform.Locale`` can be added to the ``org.freedesktop.Platform`` runtime in order to add translations.
 
 Sandboxes
 ^^^^^^^^^
 
-With Flatpak, each app is built and run in an isolated environment. By default, the application can only 'see' itself and its runtime. Access to user files, network, graphics sockets, subsystems on the bus and devices have to be explicitly granted. (As will be described later, Flatpak provides several ways to do this.) Access to other things, such as other processes, is (deliberately) not possible.
+With Flatpak, each app is built and run in an isolated environment. By default, the application can only 'see' itself and its runtime. Access to user files, network, graphics sockets, subsystems on the bus and devices have to be explicitly granted. (As will be described later, Flatpak provides several ways to do this.) Access to other things, such as other processes, is deliberately not possible.
 
 The flatpak command
 --------------------
 
 ``flatpak`` is the command that is used to install, remove and update runtimes and applications. It can also be used to view what is currently installed, and has commands for building and distributing application bundles. ``flatpak --help`` provides a full list of available commands.
 
-Most flatpak commands are performed system-wide by default. To perform a command for the current user only, use the ``--user`` option.
+Most flatpak commands are performed system-wide by default. To perform a command for the current user only, use the ``--user`` option. This allows runtimes and application bundles to be installed per-user, for instance.
 
 Under the hood
 --------------