.gitlab-ci.yml

@@ -38,6 +38,6 @@ publish:
     - touch ~/.ssh/id_rsa
     - chmod 0600 ~/.ssh/id_rsa
     - echo "$SSH_KEY" >> ~/.ssh/id_rsa
-    - rsync -av -i --stats -e "ssh -l $SSH_USER -i ~/.ssh/id_rsa -p $SSH_PORT" _build/html/ "$RSYNC_TARGET"
+    - rsync -av -I -t -i --stats -e "ssh -l $SSH_USER -i ~/.ssh/id_rsa -p $SSH_PORT" _build/html/ "$RSYNC_TARGET"
   only:
     - master

APIs.rst

@@ -48,7 +48,7 @@ On-Screen Keyboard
 The visibility of the on-screen (virtual) keyboard can be controlled using its
 D-Bus API, exposed on the session bus as the ``sm.puri.OSK0`` service, on the
 ``/sm/puri/OSK0`` object path, with the ``sm.puri.OSK0`` interface, as
-described in the `Virtboard`_ documentation.
+described in the `Squeekboard`_ documentation.
 
 This interface provides the following property:
 

Apps/Examples/Files/Pictures/Source_Code.rst

@@ -108,7 +108,7 @@ The ``show_details`` method loads an image at its full size for display in the d
    :start-at: def show_details
    :end-at: self.pages.show_page
 
-We use the `Gtk.TreePath`_ passed to this method, along with a `Gtk.TreeIter`_ object, to obtain the file name of the image from the model. A good introduction to this class is provided by the `Tree and List Widgets`_ chapter of the `Python GTK+ 3 Tutorial`_.
+We use the `Gtk.TreePath`_ passed to this method, along with a `Gtk.TreeIter`_ object, to obtain the file name of the image from the model. A good introduction to this class is provided by the `Tree and List Widgets`_ chapter of the `Python GTK 3 Tutorial`_.
 
 Summary
 -------

Apps/Examples/General/Simple_Weather/Features/Cascading_Style_Sheets.rst

@@ -64,6 +64,6 @@ Care must be taken to avoid applying too many rules to the widgets in your appli
 Further Reading
 ---------------
 
-The `GTK+ CSS Overview`_ and `GTK+ CSS Properties`_ documents on the GNOME developer site are useful for determining which parts of the standard widgets can be styled, and what changes they support.
+The `GTK CSS Overview`_ and `GTK CSS Properties`_ documents on the GNOME developer site are useful for determining which parts of the standard widgets can be styled, and what changes they support.
 
 .. include:: /links.txt

Apps/Examples/General/Treasure/Details/Main_Program.rst

@@ -24,7 +24,7 @@ We also import modules that allow us to create user interfaces:
    :start-at: import gi
    :end-at: Handy.init
 
-These are standard modules for accessing GTK+ and GNOME features, plus the ``Handy`` module that helps us to create adaptive user interfaces.
+These are standard modules for accessing GTK and GNOME features, plus the ``Handy`` module that helps us to create adaptive user interfaces.
 
 The Application Class
 ---------------------

Apps/Examples/General/Treasure/Details/User_Interface.rst

@@ -39,6 +39,6 @@ Unlike the user interface for the window, the menu's UI file was defined in a te
 
 .. literalinclude:: ../app/src/ui/menus.ui
 
-The actions are defined to be application-wide: each has the ``app.`` prefix. Their strings are marked as translatable so that they will be included in the message catalogs described in :ref:`examples_Treasure_po_dir`. Actions are described in more details in the `Actions section`_ of the `Python GTK+ 3 Tutorial`_.
+The actions are defined to be application-wide: each has the ``app.`` prefix. Their strings are marked as translatable so that they will be included in the message catalogs described in :ref:`examples_Treasure_po_dir`. Actions are described in more details in the `Actions section`_ of the `Python GTK 3 Tutorial`_.
 
 .. include:: /links.txt

Apps/GNOME/GBuilder.rst

@@ -7,33 +7,35 @@ GNOME Builder
           :ref:`flatpak_setup_gnome` section to setup flatpak on your
           workstation.
 
-This section will show you how to use GNOME Builder for developing, building,
-and deploying app flatpaks to a phone shell environment. Apps built from GNOME
-Builder can theoretically be deployed on Plasma Mobile as well.
+GNOME Builder is an Integrated Development Environment (IDE) traditionally used for building GNOME applications. This guide will show you how to set up Builder in preparation for developing, building, and deploying app flatpaks to a phone shell environment.
 
-Builder is a fantastic IDE traditionally used for building GNOME GTK+ apps however the fun doesn't have to stop there. It can build KDE apps as long as there is flatpak metadata for the application - more on that later.
+It may be useful to refer to the `GNOME Builder documentation`_ for more detailed information about setting up and using the IDE.
 
-First, checkout the `GNOME Builder documentation`_.
+Installing Builder
+------------------
 
-**Install the stable version of GNOME Builder**::
+First, ensure that you have set up Flatpak as described in ref:`flatpak_setup_gnome`. This enables installation of up-to-date versions of Builder.
+
+At the command line, run ``flatpak`` to install the latest version of GNOME Builder on the stable branch::
 
    $ flatpak install flathub org.gnome.Builder
 
-**Run GNOME Builder**::
+You may be asked to confirm installation. Once installed, you can run Builder in the following way::
 
    $ flatpak run org.gnome.Builder
 
-**You can later update the stable version of GNOME Builder**::
+You can later update the stable version of Builder using this command::
 
    $ flatpak update org.gnome.Builder
 
-***************************************
-Setting up QEMU on Debian based systems
-***************************************
+See the :ref:`package_management_flatpaks` guide for an overview of commands for installing, updating and uninstalling flatpaks.
+
+Setting up QEMU on Debian-Based Systems
+---------------------------------------
 
-Since Builder relies on statically linked qemu binaries, you will either need to run an OS that already does this for you (like Fedora, Debian Buster, or PureOS) or fix up your Debian stable workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by your OS. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
+Since Builder relies on statically linked `qemu`_ binaries for cross-building, you will either need to run an OS that provides these for you (like Fedora, Debian Buster, or PureOS) or fix up your Debian Stable workstation to enforce static linking before starting Builder. Manually fixing Debian qemu binaries (setting flags: F) is required until a patched version of qemu is distributed by your OS. Without statically linked qemu binaries, you will not be able to build an installable armhf or aarch64 flatpak from Builder.
 
-To perform these operations, you will need to be the root user (sudo is not good enough).
+To perform these operations, you will need to be the ``root`` user (sudo is not good enough).
 
 You can first check what the flags are set to for qemu-arm and then perform a similar operation to see the flags for qemu-aarch64::
 
@@ -71,85 +73,11 @@ qemu-aarch64::
    magic 7f454c460201010000000000000000000200b700
    mask ffffffffffffff00fffffffffffffffffeffffff
 
+Further Reading
+---------------
 
+The `GNOME Builder documentation`_ contains more in-depth information about all aspects of the IDE.
 
-********************************************************
-Building a C/GTK+3 (libhandy) flatpak with GNOME Builder
-********************************************************
-For this example, the `geary <https://gitlab.gnome.org/aplazas/geary/tree/wip/aplazas/stackablebox>`_ application will be built (written in C and available in Debian apt repositories). This build was done on an x86 system running Debian testing.
-
-The `libhandy <https://source.puri.sm/Librem5/libhandy>`_ repository has already been cloned and the master branch checked out.
-
-When you open Builder, select to "Open" a new project and navigate to the libhandy folder.
-
-When Builder opens a project, it immediately tries to build it for your host's architecture. You can see this by clicking the build log (brick wall). If you would like to build for a different architecture, this is a good time to cancel the build. After the build is cancelled, select what architecture you would like to build for from the devices drop down menu:
-
-.. image:: images/devices.png
-   :width: 500px
-   :height: 300px
-   :align: left 
-
-|
-|
-
-As soon as you select a different architecture, a build is started for that architecture. 
-
-|
-|
-|
-|
-|
-|
-|
-|
-
-.. note:: If your build dependencies for the project are not installed you will know from watching the Builder "Build Log" in the bottom panel (brick wall icon) where the unsatisfied dependencies will be complained about until they are resolved.
-
-.. image:: images/build_log.png
-   :width: 500px
-   :height: 300px
-   :align: left 
-
-Builder will stop after configuring the project. To complete the flatpak bundle creation, you can click any of the remaining build steps listed in the "Build Details" drop-down to resolve the build through that step.
-
-|
-|
-|
-|
-
-Alternatively, you can click the omnibar in Builder and select the "Export Bundle" button and patiently wait while Builder progresses through flatpak creation.
-
-.. image:: images/builder_export_bundle.png
-   :width: 500px
-   :height: 300px
-   :align: center
-
-When the flatpak creation is finished, a nautilus window will pop up in the directory where the sm.puri.Handy.Example.flatpak is located. In this example, the flatpak can be found here: ~/.var/app/org.gnome.Builder/cache/gnome-builder/projects/libhandy/flatpak/staging/arm-wip-stackablebox/sm.puri.Handy.Example.flatpak
-
-**********************************************************************
-Deploying a C/GTK+3 (libhandy) flatpak to Phosh running on i.MX6 board
-**********************************************************************
-
-To run this flatpak you must first get the flatpak onto the dev board and install it. 
-The dev board should have a working networking setup and IP address that you can use to ssh/scp. The OS has ssh running and enabled by default (port 22). The system should also have flatpak installed.
-
-Scp the flatpak to the system, install it and run it (from an ssh session)::
-
-   user@workstation:~$ scp ~/.var/app/org.gnome.Builder/cache/gnome-builder/projects/libhandy/flatpak/staging/arm-wip-stackablebox/sm.puri.Handy.Example.flatpak purism@<sut_ip>:~/
-   purism@pureos:~$ sudo flatpak install sm.puri.Handy.Example.flatpak
-   purism@pureos:~$ flatpak run sm.puri.Handy.Example
-
-You will see the application start on the screen connected to the board.
-
-|pic1| |pic2|
-
-.. |pic1| image:: images/libhandy_welcome.jpg
-   :width: 300px
-   :height: 400px
-
-
-.. |pic2| image:: images/libhandy_dialer.jpg
-   :width: 300px
-   :height: 400px
+See the :ref:`tutorial_build_flatpak_gnome_builder` tutorial for a practical guide to building and deploying a flatpak on a development board.
 
 .. include:: /links.txt

Apps/GNOME/Gtk+.rst → Apps/GNOME/GTK.rst

 
 .. _gtk_adaptive_overview:
 
-GTK+
-====
+GTK
+===
 
-`GTK+ <GTK+ website_>`_ is the graphical application framework used to develop all GNOME applications. This guide aims to provide a brief overview of GTK+ applications and tools that can assist in their development.
+Applications (apps) for the Librem 5 will typically be built using the
+`GTK toolkit`_. In fact many of the apps available will have been ported from
+existing apps which are part of the GNOME environment.
+
+This guide aims to provide a brief overview of GTK 3 applications and the tools that can assist in their development. GTK 3.32 is the minimum version that applications on the Librem 5 are expected to use.
 
 .. contents::
    :local:
@@ -57,12 +61,12 @@ Debugging
 
 It can be useful to examine the user interface of a running application for debugging or diagnostic purposes.
 
-The GTK+ Inspector
-~~~~~~~~~~~~~~~~~~
+The GTK Inspector
+~~~~~~~~~~~~~~~~~
 
-The `GTK+ Inspector`_ is a tool giving you direct and dynamic access to the internal state of the user interface of your GTK+ application at runtime. It is similar in concept to a web inspector.
+The `GTK Inspector`_ is a tool giving you direct and dynamic access to the internal state of the user interface of your GTK application at runtime. It is similar in concept to a web inspector.
 
-The GTK+ Inspector is an extremely convenient tool to help with debugging your GTK+ application. To use it you first need to enable it via GSettings::
+The GTK Inspector is an extremely convenient tool to help with debugging your GTK application. To use it you first need to enable it via GSettings::
 
    $ gsettings set org.gtk.Settings.Debug enable-inspector-keybinding true
 
@@ -72,7 +76,7 @@ Alternatively you can set the ``GTK_DEBUG`` environment variable to ``interactiv
 
    $ GTK_DEBUG=interactive your-application
 
-.. note:: For the GTK+ Inspector to work in your flatpaked application, see how to `enable dconf access`_ in the the Flatpak documentation.
+.. note:: For the GTK Inspector to work in your flatpaked application, see how to `enable dconf access`_ in the the Flatpak documentation.
 
 .. include:: /links.txt
 

Apps/GNOME/Glade.rst

@@ -3,7 +3,7 @@
 Glade
 =====
 
-`Glade`_ is a Rapid Application Development (RAD) tool for designing GTK+ based
+`Glade`_ is a Rapid Application Development (RAD) tool for designing GTK based
 user interfaces (UIs). It provides a visual environment that enables developers
 to design UIs for their applications that can be easily accessed by the code
 that handles the application logic.

Apps/GNOME/Resources.rst

 .. _gnome_resources:
 
-GTK+/GNOME Resources
-====================
+GTK/GNOME Resources
+===================
 
 When developing an application for the GNOME environment running on a Librem 5
 phone, the following resources may contain useful information and advice:

Apps/Gnome.rst

@@ -3,14 +3,7 @@
 Developing for GNOME
 ====================
 
-Applications (apps) for the Librem 5 will typically be built using the
-`GTK+ toolkit`_. In fact many of the apps available will have been ported from
-existing apps which are part of the GNOME environment. When you write an app or
-port a current app to the Librem 5, you are likely going to use tools and
-libraries from the GNOME Desktop Environment, building user interfaces
-based on GTK+ using the GObject model. There are many supporting libraries
-like libsoup for HTTP access or GSettings for settings management, D-Bus
-interaction and lower level I/O.
+When you write an app or port a current app to the Librem 5, you are likely going to use tools and libraries from the GNOME Desktop Environment, building user interfaces based on GTK using the GObject model. There are many supporting libraries like libsoup for HTTP access or GSettings for settings management, D-Bus interaction and lower level I/O.
 
 See the :ref:`development_environment` chapter of this manual, and especially
 the :ref:`workstation` section for an overview of the tools that make up
@@ -22,7 +15,7 @@ these tools in more detail.
 
    GNOME/Flatpak_setup
    GNOME/GBuilder
-   GNOME/Gtk+
+   GNOME/GTK
    GNOME/Glade
    GNOME/Application_Resources
    GNOME/Settings

Apps/Guides/Design/Adaptive_UI/index.rst

@@ -17,7 +17,7 @@ Introduction
 
 This library is central to the way that adaptive applications are created using GTK. The following sections show how each of its components are employed to make new or existing GTK-based user interfaces adaptable. The :ref:`porting_gnome_apps_guide` guide covers more specific issues related to converting traditional applications to fit the adaptive paradigm.
 
-For general GTK+ and GNOME development resources please consult the :ref:`gnome_resources` page and the `GTK+ 3 documentation`_.
+For general GTK and GNOME development resources please consult the :ref:`gnome_resources` page and the `GTK 3 documentation`_.
 
 Style Guidelines
 ----------------

Apps/Guides/Porting_GNOME_Applications/index.rst

@@ -29,7 +29,7 @@ A typical developer workflow for porting will involve something like this:
 Hints and Tips
 --------------
 
-There are some UI elements in GTK+ that are touch-friendly, and therefore ready to use on a phone, while others are not.
+There are some UI elements in GTK that are touch-friendly, and therefore ready to use on a phone, while others are not.
 
 A collection of `application mock-ups`_ for GNOME applications should help to give an overview of the presentation and user interface paradigms that developers are using.
 

Apps/Guides/Working_with_UI_Files/index.rst

@@ -54,7 +54,7 @@ Note the ``id`` property on the object describing the `Gtk.ApplicationWindow`_ w
 
 The ``id`` attribute allows the application code to refer to specific widgets. In this case, the main window of the application can be referred to using the ``window`` identifier.
 
-The ``<requires>`` element contains information about the libraries that provide the components specified in the UI file. In the example, all the components can be provided by GTK+ version 3.20.
+The ``<requires>`` element contains information about the libraries that provide the components specified in the UI file. In the example, all the components can be provided by GTK version 3.20.
 
 Creating UI Files
 -----------------

Apps/Kde.rst

@@ -18,4 +18,7 @@ use of these tools and technologies in more detail.
    KDE/Qt_Creator
    KDE/Kirigami
 
+Applications developed using these technologies can also be deployed in the
+:ref:`phosh` environment.
+
 .. include:: /links.txt

Apps/Packaging_Apps/Building_Debian_Packages/index.rst

@@ -3,6 +3,15 @@
 Building Debian Packages
 ========================
 
-For building a deb package, `git-buildpackage`_ is the preferred build method.
+Debian (deb) packages are the standard way to distribute software in
+Debian-based distributions like PureOS. Packages provided in deb format files
+are managed using a suite of command line tools and are also supported by
+various graphical package managers.
+
+The `git-buildpackage`_ tool is the suggested way to build a deb package for
+core application developers who are not specifically targeting Debian or PureOS
+systems, or who are supporting a wider range of platforms. This tool provides a
+way to integrate deb package building with normal development practices if the
+`Git revision control system`_ is used for revision control.
 
 .. include:: /links.txt