Add informations/refactor update page

source/packaging-guide/optional/updates.rst

@@ -15,14 +15,23 @@ AppImages can be updated:
    :depth: 2
 
 
-Making AppImages updateable via external tools
-----------------------------------------------
+Introduction
+------------
 
 To make an AppImage updateable, you need to embed information that describes where to check for updates and how into the AppImage. Unlike other Linux distribution methods, the information where to look for updates is not contained in separate repository description files such as :code:`sources.list` that need to be managed by the user, but is directly embedded inside the AppImage by the author of the respective AppImage. This has the advantage that the update information always travels alongside the application, so that the end user does not have to do anything special in order to be able to check for updates.
 
+Currently, there is only one backend available to update AppImages : `ZSync2 <https://github.com/AppImage/zsync2>`__. The tool you use to package the AppImage will also generate a .zsync file if you gave it enough data to do so
+
+.. warning:: The .zsync file contains the filename of the AppImage. This mean that you **should not**, as a packager, rename the .AppImage file after it's creation. Else the update will fail because zsync will look for the original filename of the AppImage you host. If you want to rename the AppImage, you should use the options of the tool you use to create the AppImage.
 
-Using appimagetool
-^^^^^^^^^^^^^^^^^^
+.. note:: zsync will not perform any kind of version checking, it will only download the AppImage mentionned in the update information. It doesn't require you to add versions to your AppImages for the updates to work (you should still do it for other purposes)
+
+Making AppImages updateable via external tools
+----------------------------------------------
+
+
+If packaged with appimagetool
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Use :code:`appimagetool -u` to embed update information (as specified in the AppImageSpec) and generate the corresponding :code:`.zsync` file you can upload to the place mentioned in the update information.
 
@@ -42,27 +51,32 @@ is called the *update information*.
 Please see https://github.com/AppImage/AppImageSpec/blob/master/draft.md#update-information for a description of allowable types of update information.
 
 
-Using linuxdeploy
-^^^^^^^^^^^^^^^^^
+If packaged with linuxdeploy
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :ref:`linuxdeploy's <ref-linuxdeploy>` `AppImage plugin <https://github.com/linuxdeploy/linuxdeploy-plugin-appimage>`__ supports an environment variable ``$UPDATE_INFORMATION`` (or short ``$UPD_INFO``) that can be used to set the update information manually.
 
 Please see `the README <https://github.com/linuxdeploy/linuxdeploy-plugin-appimage#optional-variables>`__ for details.
 
 
-Using linuxdeployqt
-^^^^^^^^^^^^^^^^^^^
+If packaged with linuxdeployqt
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :code:`linuxdeployqt` uses :code:`appimagetool` internally. If it recognizes that it is running on Travis CI, then it automatically generates the matching update information.
 
 
-Using electron-builder
-^^^^^^^^^^^^^^^^^^^^^^
+If packaged with electron-builder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 :code:`electron-builder` promotes its own updater scheme rather than the update information described in this documentation, in order to have the same mechanism on Linux as is used on Windows. Unfortunately this means that AppImages generated by :code:`electron-builder` cannot be updated using the usual tools.
 
 One way to inject the update information into the AppImage created with :code:`electron-builder` nevertheless is to extract the AppImage generated with :code:`electron-builder` to an AppDir using the --appimage-extract command line option of the AppImage, and then re-packing it as an AppImage by using :code:`appimagetool -u`.
 
+If packaged with appimage-builder
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Informations can be found on `the appimage-builder documentation <https://appimage-builder.readthedocs.io/en/latest/advanced/updates.html>`__
+
+
 
 Making AppImages self-updateable
 --------------------------------
@@ -198,7 +212,7 @@ See this easy example for an update check:
 
 This is faster and less verbose than an exception based workflow, however, you can't see what caused the update check to fail.
 
-This can be found out using the built in status message system. Every :code:`Updater` instance contains a message queue. All methods within the updater and the systems it uses (like e.g., `ZSync2 <https://travis-ci.org/TheAssassin/zsync2/>`__, which is one of the backends for the binary delta updates) add messages to this queue, which means that all kinds of status messages ever generated by any of the libraries will end up there.
+This can be found out using the built in status message system. Every :code:`Updater` instance contains a message queue. All methods within the updater and the systems it uses (like e.g., `ZSync2 <https://github.com/AppImage/zsync2>`__, which is one of the backends for the binary delta updates) add messages to this queue, which means that all kinds of status messages ever generated by any of the libraries will end up there.
 
 .. note::