Migrating Desktop Client documentation (#12543)

Signed-off-by: Rello <[email protected]>

Author: Rello

user_manual/desktop/autoupdate.rst

@@ -0,0 +1,116 @@
+=====================
+The Automatic Updater
+=====================
+
+The Automatic Updater ensures that you always have the
+latest features and bug fixes for your Nextcloud synchronization client.
+
+The Automatic Updater updates only on macOS and Windows computers; Linux
+users only need to use their normal package managers. However, on Linux systems
+the Updater will check for updates and notify you when a new version is
+available.
+
+Basic Workflow
+--------------
+
+The following sections describe how to use the Automatic Updater on different
+operating systems.
+
+Windows
+^^^^^^^
+
+The Nextcloud client checks for updates and downloads them when available. You
+can view the update status under ``Settings -> General -> Updates`` in the
+Nextcloud client.
+
+If an update is available, and has been successfully downloaded, the Nextcloud
+client starts a silent update prior to its next launch and then restarts
+itself. Should the silent update fail, the client offers a manual download.
+
+.. note:: Administrative privileges are required to perform the update.
+
+macOS
+^^^^^
+
+The macOS client has an autoupdater which uses the Sparkle framework.
+This autoupdater is bundled into the client App Bundle and checks for updates
+on launch, notifying you if an update is available. This will present a pop-up
+that can let you automatically download and install the latest client update
+with one click.
+
+In versions of the client where the Sparkle-based autoupdater is not bundled,
+a clickable notification will appear informing of an update being available.
+Upon clicking on said notification, the download page for the latest version
+of the client will be opened in the system's web browser.
+
+Like on other systems, you can view the update status under
+``Settings -> General -> Updates`` in the Nextcloud client.
+
+Linux
+^^^^^
+
+Linux distributions provide their own update tools, so Nextcloud clients that use
+the Linux operating system do not perform any updates on their own. The client
+will inform you (``Settings -> General -> Updates``) when an update is
+available.
+
+Preventing Automatic Updates
+----------------------------
+
+In controlled environments, such as companies or universities, you might not
+want to enable the auto-update mechanism, as it interferes with controlled
+deployment tools and policies. To address this case, it is possible to disable
+the auto-updater entirely.  The following sections describe how to disable the
+auto-update mechanism for different operating systems.
+
+Preventing Automatic Updates in Windows Environments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Users may disable automatic updates by adding this line to the [General]
+section of their ``nextcloud.cfg`` files::
+
+ skipUpdateCheck=true
+
+Windows administrators have more options for preventing automatic updates in
+Windows environments by using one of two methods. The first method allows users
+to override the automatic update check mechanism, whereas the second method
+prevents any manual overrides.
+
+To prevent automatic updates, but allow manual overrides:
+
+1. Edit these Registry keys:
+
+    a. (32-bit-Windows) ``HKEY_LOCAL_MACHINE\Software\Nextcloud\Nextcloud``
+    b. (64-bit-Windows) ``HKEY_LOCAL_MACHINE\Software\Wow6432Node\Nextcloud\Nextcloud``
+
+2. Add the key ``skipUpdateCheck`` (of type DWORD).
+
+3. Specify a value of ``1`` to the machine.
+
+To manually override this key, use the same value in ``HKEY_CURRENT_USER``.
+
+To prevent automatic updates and disallow manual overrides:
+
+.. note:: This is the preferred method of controlling the updater behavior using
+   Group Policies.
+
+1. Edit this Registry key:
+
+    ``HKEY_LOCAL_MACHINE\Software\Policies\Nextcloud GmbH\Nextcloud``
+
+2. Add the key ``skipUpdateCheck`` (of type DWORD).
+
+3. Specify a value of ``1`` to the machine.
+
+.. note:: branded clients have different key names
+
+
+Preventing Automatic Updates in Linux Environments
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Because the Linux client does not provide automatic updating functionality, there is no
+need to remove the automatic-update check.  However, if you want to disable it edit your desktop
+client configuration file, ``$HOME/.config/Nextcloud/nextcloud.cfg``.
+Add this line to the [General] section::
+
+    skipUpdateCheck=true

user_manual/desktop/conflicts.rst

@@ -0,0 +1,59 @@
+=========
+Conflicts
+=========
+
+Overview
+--------
+
+The Nextcloud desktop client uploads local changes and downloads remote changes.
+When a file has changed on the local side and on the remote between synchronization
+runs the client will be unable to resolve the situation on its own. It will
+create a conflict file with the local version, download the remote version and
+notify the user that a conflict occurred which needs attention.
+
+Example
+-------
+
+Imagine there is a file called ``mydata.txt`` your synchronized folder. It has
+not changed for a while and contains the text "contents" locally and remotely.
+Now, nearly at the same time you update it locally to say "local contents" while
+the file on the server gets updated to contain "remote contents" by someone else.
+
+When attempting to upload your local changes the desktop client will notice that
+the server version has also changed. It creates a conflict and you will now have
+two files on your local machine:
+
+- ``mydata.txt`` containing "remote contents"
+- ``mydata (conflicted copy 2018-04-10 093612).txt`` containing "local contents"
+
+In this situation the file ``mydata.txt`` has the remote changes (and will continue
+to be updated with further remote changes when they happen), but your local
+adjustments have not been sent to the server (unless the server enables conflict
+uploading, see below).
+
+The desktop client notifies you of this situation via system notifications, the
+system tray icon and a yellow "unresolved conflicts" badge in the account settings
+window. Clicking this badge shows a list that includes the unresolved conflicts
+and clicking one of them opens an explorer window pointing at the relevant file.
+
+To resolve this conflict, open both files, compare the differences and copy your
+local changes from the "conflicted copy" file into the base file where applicable.
+In this example you might change ``mydata.txt`` to say "local and remote contents"
+and delete the file with "conflicted copy" in its name. With that, the conflict
+is resolved.
+
+Uploading conflicts (experimental)
+----------------------------------
+
+By default the conflict file (the file with "conflicted copy" in its name that
+contains your local conflicting changes) is not uploaded to the server. The idea
+is that you, the author of the changes, are the best person for resolving the
+conflict and showing the conflict to other users might create confusion.
+
+However, in some scenarios it makes a lot of sense to upload these conflicting
+changes such that local work can become visible even if the conflict won't be
+resolved immediately.
+
+In the future there might be a server-wide switch for this behavior. For now it
+can already be tested by setting the environment variable
+``OWNCLOUD_UPLOAD_CONFLICT_FILES=1``.

user_manual/desktop/faq.rst

@@ -0,0 +1,117 @@
+===
+FAQ
+===
+
+How the "Edit locally" functionality works
+------------------------------------------
+This functionality depends on the desktop client ability to register the mime to handle the nc:// scheme. That is the handler used by the server to open a file locally. This will allow the desktop client to open a document with the local editor when you click on the option "Edit locally" in your Nextcloud instance. 
+
+.. note:: 
+   Without properly registering the mime, independent of the browser and distro being used, the desktop client will fail to open a document with the local editor when you click on the option "Edit locally" in your Nextcloud instance.
+   
+   The browser will warn you of the failure: "Failed to launch 'nc://...' because the scheme does not have a registered handler."
+
+How to enable it
+^^^^^^^^^^^^^^^^^
+
+In order to do that, you need to install the desktop client with the MSI installer on Windows or use a third party software to integrate the AppImage in your system on Linux.
+
+On Linux
+^^^^^^^^
+
+We use AppImage due to its universal compatibility but to take full advantage of the desktop client features you will need a third part software to integrate the AppImage in your system: we have tested `AppImageLauncher <https://github.com/TheAssassin/AppImageLauncher>`_ and alternatively there is `Go AppImage <https://github.com/probonopd/go-appimage>`_.
+
+On Windows
+^^^^^^^^^^
+
+The MSI installer will alter your system registry to register the mime to handle the nc:// scheme. 
+
+Alternatively, you can manually register the mime to handle the nc:// scheme:
+
+1. Save the following content to a .reg file:
+
+.. code-block:: none
+
+   Windows Registry Editor Version 5.00
+   
+   [HKEY_CLASSES_ROOT\nc\shell\open\command]
+   @="\"C:\\Program Files\\Nextcloud\\nextcloud.exe\" \"%1\""
+
+2. Double click on the .reg file to import it into the registry.
+
+See https://nextcloud.com/blog/nextcloud-office-release-solves-document-compatibility-overhauls-knowledge-management/ for more information.
+
+Some Files Are Continuously Uploaded to the Server, Even When They Are Not Modified.
+------------------------------------------------------------------------------------
+
+It is possible that another program is changing the modification date of the file.
+If the file is uses the ``.eml`` extension, Windows automatically and
+continually changes all files, unless you remove
+``\HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\PropertySystem\PropertyHandlers``
+from the windows registry.
+See http://petersteier.wordpress.com/2011/10/22/windows-indexer-changes-modification-dates-of-eml-files/ for more information.
+
+Syncing Stops When Attempting To Sync Deeper Than 100 Sub-directories.
+----------------------------------------------------------------------
+
+The sync client has been intentionally limited to sync no deeper than 100
+sub-directories. The hard limit exists to guard against bugs with cycles
+like symbolic link loops.
+When a deeply nested directory is excluded from synchronization it will be
+listed with other ignored files and directories in the "Not synced" tab of
+the "Activity" pane.
+
+There Was A Warning About Changes In Synchronized Folders Not Being Tracked Reliably.
+-------------------------------------------------------------------------------------
+
+On linux when the synchronized folder contains very many subfolders the
+operating system may not allow for enough inotify watches to monitor the
+changes in all of them.
+
+In this case the client will not be able to immediately start the
+synchronization process when a file in one of the unmonitored folders changes.
+Instead, the client will show the warning and manually scan folders for changes
+in a regular interval (two hours by default).
+
+This problem can be solved by setting the fs.inotify.max_user_watches
+sysctl to a higher value. This can usually be done either temporarily::
+
+    echo 524288 > /proc/sys/fs/inotify/max_user_watches
+
+or permanently by adjusting ``/etc/sysctl.conf``.
+
+I Want To Move My Local Sync Folder
+-----------------------------------
+
+The Nextcloud desktop client does not provide a way to change the local sync directory.
+However, it can be done, though it is a bit unorthodox.
+Specifically, you have to:
+
+1. Remove the existing connection which syncs to the wrong directory
+2. Add a new connection which syncs to the desired directory
+
+.. figure:: images/setup/remove.png
+   :alt: Remove an existing connection
+
+To do so, in the client UI, which you can see above, click the "**Account**" drop-down menu and then click "Remove".
+This will display a "**Confirm Account Removal**" dialog window.
+
+.. figure:: images/setup/confirm.png
+   :alt: Remove existing connection confirmation dialog
+
+If you're sure, click "**Remove connection**".
+
+Then, click the Account drop-down menu again, and this time click "**Add new**".
+
+.. figure:: images/setup/wizard.png
+   :alt: Replacement connection wizard
+
+This opens the Nextcloud Connection Wizard, which you can see above, *but* with an extra option.
+This option provides the ability to either: keep the existing data (synced by the previous connection) or to start a clean sync (erasing the existing data).
+
+.. important::
+
+  Be careful before choosing the "Start a clean sync" option. The old sync folder *may* contain a considerable amount of data, ranging into the gigabytes or terabytes. If it does, after the client creates the new connection, it will have to download **all** of that information again. Instead, first move or copy the old local sync folder, containing a copy of the existing files, to the new location. Then, when creating the new connection choose "*keep existing data*" instead. The Nextcloud client will check the files in the newly-added sync folder and find that they match what is on the server and not need to download anything.
+
+Make your choice and click "**Connect...**".
+This will then step you through the Connection Wizard, just as you did when you setup the previous sync connection, but giving you the opportunity to choose a new sync directory.

user_manual/desktop/images/general_settings_folder_context_menu.png

@@ -2,12 +2,27 @@
 Desktop Clients
 ===============
 
-You can share one or more files and folders on your computer, and synchronize
-them with your Nextcloud server. Place files in your local shared directories,
-and those files are immediately synchronized to the server and to other devices
-using the Nextcloud Desktop Sync Client, Android app, or iOS app. To
-learn more about the Nextcloud desktop client, please refer to:
+Available for Windows, macOS, and various Linux distributions, the Nextcloud
+Desktop Sync client enables you to:
 
+- Specify one or more directories on your computer that you want to synchronize
+  to the Nextcloud server.
+- Always have the latest files synchronized, wherever they are located.
+
+Your files are always automatically synchronized between your Nextcloud server, computer and mobile device.
+
+You can find the old documentation here:
 * `Nextcloud Desktop Client`_
 
 .. _`Nextcloud Desktop Client`: https://docs.nextcloud.com/desktop/latest/
+
+
+.. toctree::
+   :maxdepth: 1
+
+   installation
+   usage
+   macosvfs
+   autoupdate
+   conflicts
+   faq