Merge commit '297fd54f' into testing

wiki/src/contribute/design/additional_software_packages.mdwn

@@ -6,26 +6,26 @@ Rationale
 =========
 
 Tails includes a coherent but limited set of applications. As the system is
-amnesic, new software packages for Debian can be installed a in a working
-session but they are not installed anymore next time Tails is started.
+amnesic, new software packages for Debian can be installed in a working
+session but they are not reinstalled at next reboot.
 
 Additional Software Packages is a feature to remember a set of Debian Packages
 to be installed automatically from [[persistent
 storage|contribute/design/persistence]] each time Tails is started.
 
-Usecases
-========
+Use cases
+=========
 
-Alice is a geograph working for a NGO in an unstable country. She needs
+Alice is a geographer working for an NGO in an unstable country. They need
 to use Tails but needs the QGis SIG to work. It would make little sense
 to add such a specific software in Tails. But thanks to Additional
-Software Packages, she can have QGis installed every time she boots
-Tails with her persistence enabled.
+Software Packages, Alice can have QGis installed every time when they boot
+Tails with persistent storage enabled.
 
-Bob is a journalist and he wants to publish colleagues videos. He needs
-often needs to convert them and is used to the open source video transcoder
-HandBrake. With Additional Software Packages, he doesn't need to install
-it every time he boots its Tails anymore.
+Bob is a journalist and wants to publish videos made by other
+colleagues. Bob needs to convert these videos and is used to the open
+source video transcoder HandBrake. With Additional Software Packages,
+Bob doesn't need to install it every time when they boot Tails.
 
 Specifications
 ==============
@@ -35,7 +35,7 @@ Goals
 
 - Allow people to choose to:
   - Reinstall a package every time they start Tails.
-  - Stop reinstalling a package every time.
+  - Stop reinstalling a package every time on boot.
 
 - Integrate this in:
   - The usual installation and removal process of a package (through
@@ -44,12 +44,12 @@ Goals
 
 - Ensure packages are installed even offline.
 
-- Ensure packages are updates when connected to the Internet.
+- Ensure packages are updated when the machine is connected to the Internet.
 
 Non-goals
 ---------
 
-- We won't support installing software that are not in Debian
+- We won't support installing software that is not in Debian's official
   repositories.
 
 - We won't provide a way for people to specify which packages to install
@@ -81,15 +81,15 @@ contains a package name per line and install these packages with `apt-get`
 (using `DEBIAN_PRIORITY=critical` and the command line options `--yes` and
 `--option DPkg::Options::=--force-confold`).
 
-In the beginnihg of the process, the user is notified through desktop
-notifications that additional software are being installed:
+In the beginning of the process, the user is notified through desktop
+notifications that additional software is being installed:
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installing.png"/>
 
-In the end, she is informed of success of failure. On the latter case, she is
-offered to open a configuration window or to examine to logs to better
-understand the issue. The notifications with buttons displayed as the desktop
-user are implemented in
+In the end, they are informed of success of failure. In the latter case, they are
+offered to open a configuration window or to examine the logs in order to better
+understand the issue. The notifications with buttons displayed are as the desktop
+user and are implemented in
 [[!tails_gitweb config/chroot_local-includes/usr/local/lib/tails-additional-software-notify]].
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - installation failed.png"/>
@@ -98,7 +98,7 @@ user are implemented in
 Software upgrade on Internet connection
 ---------------------------------------
 
-A network-manager dispatcher hook starts the systemd unit 
+A network-manager dispatcher hook starts the systemd unit
 [[!tails_gitweb config/chroot_local-includes/lib/systemd/system/tails-additional-software-upgrade.path]]
 which waits for `/run/live-additional-software/installed` then starts the
 oneshot service `/usr/local/sbin/tails-additional-software upgrade` after
@@ -108,20 +108,20 @@ if the configuration file
 empty.
 
 [[!tails_gitweb config/chroot_local-includes/usr/local/sbin.tails-additional-software]]
-`update` saves a copy of apt lists, then starts `apt-get update` and launch the
-installation process again, trigerring an upgrade if necessary.
+`update` saves a copy of apt lists, then starts `apt-get update` and launches the
+installation process again, triggering an upgrade if necessary.
 
 If the upgrade is successful, the copy of old apt lists is deleted.
 Else, it would be restored by the installation process next time Tails
 is started, ensuring that a network disconnection or another unexpected
 issue doesn't make the Additional Software Packages unavailable.
 
-In the beginning of the process, the user is notified through desktop
-notifications that additional software are being upgraded.
+In the beginning of the process, the user is notified via desktop
+notifications that additional software is being upgraded.
 
-In the end, she is informed of success of failure. On the latter case,
-she is offered to open a configuration window or to examine to logs to
-better understand the issue.
+In the end, they are informed of success of failure. In the latter case,
+they are offered to open a configuration window or to examine the logs
+in order to better understand the issue.
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - upgrade failed.png"/>
 
@@ -136,25 +136,25 @@ Two APT hooks are configured in
 [[!tails_gitweb config/chroot_local-includes/etc/apt/apt.conf.d/80tails-additional-software.disabled]],
 which are enabled by
 [[!tails_gitweb config/chroot_local-hooks/99-zz-install-ASP-DPKG-hooks]] in the
-end of
-the build process.
+end of the build process.
 
-The first hooks `DPkg::Pre-Install-Pkgs` runs before any actual
+The first hook `DPkg::Pre-Install-Pkgs` runs before any actual
 installation happens and calls
 `/usr/local/sbin/tails-additional-software apt-pre` which saves a list
 of installed and removed packages as JSON in
 `/run/live-additional-software/packages`.
 
-The second hook `DPkg::Post-Invoke` runs in the end of the installation process
-and calls `/usr/local/sbin/tails-additional-software apt-post`. It double forks
-so that APT properly returns, then parses the JSON file written before to check
-which packages were manually installed or removed.
+The second hook `DPkg::Post-Invoke` runs in the end of the installation
+process and calls `/usr/local/sbin/tails-additional-software apt-post`.
+It double forks so that APT properly returns, then parses the JSON file
+written beforehand in order to check which packages were manually
+installed or removed.
 
 ### When a package is installed
 
 <img src="https://labs.riseup.net/code/attachments/download/1925/asp-flow-installed.svg" height="auto" />
 
-#### With a persistent storage unlocked:
+#### With persistent storage unlocked:
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - add.png"/>
 
@@ -163,21 +163,21 @@ When *Add To Persistent Storage* is clicked,
 `tails-persistence-setup` without a GUI to enable the
 `AdditionalSoftware` preset. The new additional packages are then added
 atomically to the `live-additional-software.conf` configuration file
-(this logic is handeled by
+(this logic is handled by
 [[!tails_gitweb submodules/pythonlib/tailslib/additionalsoftware/config.py]])
 
-#### With no persistent storage
+#### Without persistent storage
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - add without persistent storage.png"/>
 
 When *Add To Persistent Storage* is clicked,
 `/usr/bin/tails-persistence-setup` is started as
-`tails-persistence-setup` with a GUI to let the user through the process
+`tails-persistence-setup` with a GUI to lead the user through the process
 of creating a persistent storage. The `AdditionalSoftware` preset is
 automatically enabled. The new additional packages are then added to the
 `live-additional-software.conf` configuration file, which is in this
-case mounted in `/media/tails-persistence-setup/TailsData` instead of
-`/live/persistence/TailsData_unlocked` (this logic in handeled by
+case mounted to `/media/tails-persistence-setup/TailsData` instead of
+`/live/persistence/TailsData_unlocked` (this logic in handled by
 [[!tails_gitweb submodules/pythonlib/tailslib/persistence.py]]).
 
 The systemd service
@@ -185,25 +185,24 @@ The systemd service
 is used to synchronize APT data (lists and cached packages) to the newly
 created persistent storage on Tails shutdown.
 
-#### With a persistent storage locked
+#### With persistent storage locked
 
-No notification is displayed as people
-who have a persistent storage but don't unlock it, probably do this only
-sometimes and for a reason. They probably otherwise unlock their
-persistent storage most of the time. If they install packages with their
-persistent storage locked, they probably do it with their persistent
-storage unlock as well and would learn about this feature when it's most
-relevant for them.
+No notification is displayed as people who have a persistent storage but
+don't unlock it, probably do this only sometimes and for a reason. They
+probably otherwise unlock their persistent storage most of the time. If
+they install packages with their persistent storage locked, they
+probably do it with their persistent storage unlock as well and would
+learn about this feature when it's most relevant for them.
 
-#### When it's impossible to have a persistent storage
+#### When it's impossible to have persistent storage
 
-This happens when
-running from a DVD, virtual machine, or intermediary Tails.
+This happens when running from a DVD, virtual machine, or intermediary
+Tails.
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - impossible persistent storage.png"/>
 
 The state file `/run/live-additional-software/installer-asked` ensures
-this notification in only shown once per session, not to bother people
+this notification is only shown once per session, not to bother people
 too much.
 
 ### When a package is removed
@@ -212,15 +211,15 @@ too much.
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/notification - remove.png"/>
 
-When *Remove* is clicked, the packages are packages removed
-atomically from the `live-additional-software.conf` configuration file
-(this logic is handeled by
+When *Remove* is clicked, the packages are removed atomically from the
+`live-additional-software.conf` configuration file (this logic is
+handled by
 [[!tails_gitweb submodules/pythonlib/tailslib/additionalsoftware/config.py]]).
 
 Additional Software configuration window
 ----------------------------------------
 
-The list of additional software can be open from:
+The list of additional software can be opened from:
 
 - **Applications**&nbsp;▸ **System Tools**&nbsp;▸ **Additional Software**
 - **Applications**&nbsp;▸ **Tails**&nbsp;▸ **Additional Software**
@@ -234,8 +233,8 @@ This application is implemented in the following files:
 - [[!tails_gitweb config/chroot_local-includes/usr/share/tails/additional-software/configuration-window.ui]]
 
 If there is no persistent storage or before any package is added, if the
-persistent storage is locked or if it is impossible to have a persistent
-storage (for example, when running from a DVD or virtual machine) the window
+persistent storage is locked, or if it is impossible to have a persistent
+storage (for example, when running from a DVD or a virtual machine) the window
 shows an explanation text with appropriate pointers:
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - without persistent storage.png"/>
@@ -246,8 +245,8 @@ shows an explanation text with appropriate pointers:
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software - impossible persistent storage.png"/>
 
-When some packages are already added, the window displays a list of
-Additional Software Packages:
+When packages have already been added, the window displays a list of
+these Additional Software Packages:
 
 <img src="https://git.tails.boum.org/ux/plain/additional software/png/additional software.png"/>