Doc: more polishing

- add description of syncing limitations
- update out-of-date comments

Fixes #788

doc/accountsetup.rst

@@ -0,0 +1,37 @@
+Setting up an Account
+=====================
+
+If no account has been configured, ownCloud Client will automatically assist
+you in connecting to your ownCloud Server after the application has been
+started.
+
+As a first step, specify the URL to your Server, just
+like you would when you open your ownCloud instance inside a browser.
+
+.. image:: images/wizard_url.png
+   :scale: 50 %
+
+.. note:: Make sure to use ``https://`` if the server supports it. Otherwise,
+   your password and all data will be transferred to the server unencrypted.
+   This makes it easy for third parties to intercept your communication, and
+   getting hold of your password!
+
+Next, you are prompted for your username and password. Again, use the same
+credentials that you would use to log on via the web interface.
+
+.. image:: images/wizard_user.png
+   :scale: 50 %
+
+Finally, choose the folder that ownCloud Client is supposed to sync the
+contents of your ownCloud account with. By default, this is a folder
+called `ownCloud`, which will reside in your home directory.
+
+.. image:: images/wizard_targetfolder.png
+   :scale: 50 %
+
+After pressing `Connect`, ownCloud Client will commence with the syncing
+process. The next screen will give you the opportunity to review your
+settings:
+
+.. image:: images/wizard_overview.png
+   :scale: 50 %

doc/advancedusage.rst

@@ -0,0 +1,14 @@
+Advanced Usage
+==============
+
+.. index:: Advanced Usage
+
+Options
+-------
+.. index:: command line switches, command line, options, parameters
+.. include:: options.rst
+
+Config File
+-----------
+.. index:: config file
+.. include:: conffile.rst

doc/architecture.rst

@@ -1,5 +1,6 @@
-Architecture
+Appendix B: Architecture
-============
+========================
+
 .. index:: architecture 
 
 The ownCloud project provides desktop sync clients to synchronize the
@@ -11,11 +12,10 @@ csync was written to synchronize with ownCloud’s built-in WebDAV server.
 
 The ownCloud sync client is based on a tool called mirall initially written by
 Duncan Mac Vicar. Later Klaas Freitag joined the project and enhanced it to work
-with ownCloud server. Both mirall and ownCloud Client (oCC) build from the same
+with ownCloud server.
-source, currently hosted in the ownCloud source repo on gitorious.
 
-oCC is written in C++ using the `Qt Framework`_. As a result oCC runs on the
+ownCloud Client is written in C++ using the `Qt Framework`_. As a result, the
-three important platforms Linux, Windows and MacOS.
+ownCloud Client runs on the three important platforms Linux, Windows and MacOS.
 
 .. _csync: http://www.csync.org
 .. _`Qt Framework`: http://www.qt-project.org
@@ -23,8 +23,8 @@ three important platforms Linux, Windows and MacOS.
 The Sync Process
 ----------------
 
-First it is important to recall what syncing is. Syncing tries to keep the files
+First it is important to recall what syncing is: It tries to keep the files
-on both repositories the same. That means if a file is added to one repository
+on two repositories the same. That means if a file is added to one repository
 it is going to be copied to the other repository. If a file is changed on one
 repository, the change is propagated to the other repository. Also, if a file
 is deleted on one side, it is deleted on the other. As a matter of fact, in
@@ -34,10 +34,10 @@ server is always master.
 This is the major difference to other systems like a file backup where just
 changes and new files are propagated but files never get deleted.
 
-The oCC checks both repositories for changes frequently after a certain time
+The ownCloud Client checks both repositories for changes frequently after a
-span. That is refered to as a sync run. In between the local repository is 
+certain time span. That is refered to as a sync run. In between the local
-monitored by a file system monitor system that starts a sync run immediately
+repository is monitored by a file system monitor system that starts a sync run
-if something was edited, added or removed.
+immediately if something was edited, added or removed.
 
 Sync by Time versus ETag
 ------------------------
@@ -62,16 +62,18 @@ machines.
 Since this strategy is rather fragile without NTP, ownCloud 4.5 introduced a
 unique number, which changes whenever the file changes. Although it is a unique
 value, it is not a hash of the file, but a randomly chosen number, which it will
-transmit in the Etag_ field. Since the file number is guaranteed to change if the 
+transmit in the Etag_ field. Since the file number is guaranteed to change if
-file changes, it can now be used to determine if one of the files has changed.
+the file changes, it can now be used to determine if one of the files has
+changed.
 
-.. note:: oCC 1.1 and newer require file ID capabilities on the ownCloud server,
+.. note:: ownCloud Client 1.1 and newer require file ID capabilities on the
-  hence using them with a server earlier than 4.5.0 is not supported.
+   ownCloud server, hence using them with a server earlier than 4.5.0 is
+   not supported.
 
-Before the 1.3.0 release of the client the sync process might create faux conflict 
+Before the 1.3.0 release of the client the sync process might create faux
-files if time deviates. The original and the conflict files only differed in the 
+conflict files if time deviates. The original and the conflict files only
-timestamp, but not in content. This behaviour was changed towards a binary check 
+differed in the timestamp, but not in content. This behaviour was changed
-if the files are different.
+towards a binary check if the files are different.
 
 Just like files, directories also hold a unique id, which changes whenever
 one of the contained files or directories gets modified. Since this is a
@@ -105,7 +107,8 @@ are involved and one of them is not in sync with NTP time.
 .. _Etag: http://en.wikipedia.org/wiki/HTTP_ETag
 
 Comparison and Conflict Cases
-----------------------------
+-----------------------------
+
 In a sync run the client first has to detect if one of the two repositories have
 changed files. On the local repository, the client traverses the file
 tree and compares the modification time of each file with the value it was 
@@ -118,25 +121,41 @@ For the remote (ie. ownCloud) repository, the client compares the ETag of each
 file with it's previous value. Again the previous value is queried from the
 database. If the ETag is still the same, the file has not changed.
 
-So what happens if a file has changed on both, the local and the remote repository 
+In case a file has changed on both, the local and the remote repository since
-since the last sync run? That means it can not easily be decided which version
+the last sync run, it can not easily be decided which version of the file is
-of the file is the one that should be used. Moreover, changes to any side must
+ the one that should be used. However, changes to any side must not be lost.
-not be lost. That is called the conflict case and the client solves it by creating 
+
-a conflict file of the older of the two files and save the newer one under the 
+That is called a **conflict case**. The client solves it by creating a conflict
-original file name. Conflict files are always created on the client and never on
+file of the older of the two files and save the newer one under the original
-the server. The conflict file has the same name as the original file appended
+file name. Conflict files are always created on the client and never on the
-with the timestamp of the conflict detection.
+server. The conflict file has the same name as the original file appended with
+the timestamp of the conflict detection.
+
+
+.. _ignored-files-label:
+
+Ignored Files
+-------------
+
+ownCloud Client will refuse to sync the following files:
+
+* Files matched by one of the pattern in :ref:`ignoredFilesEditor-label`
+* Files containing characters that do not work on certain file systems.
+  Currently, these characters are: `\, :, ?, *, ", >, <, |`
+* Files starting in ``.csync_journal.db`` (reserved for journalling)
 
 The Sync Journal
 ----------------
-The client stores the ETag number in a per-directory database, called the journal. 
-It is located in the application directory (until version 1.1) or as a hidden file 
-right in the directory to be synced (later versions). 
 
-If the journal database gets removed, oCC's CSync backend will rebuild the database
+The client stores the ETag number in a per-directory database,
-by comparing the files and their modification times. Thus it should be made sure 
+called the journal.  It is a hidden file right in the directory
-that both server and client synchronized to NTP time before restarting the client 
+to be synced.
-after a database removal. 
 
-The oCC also provides a button in the Settings Dialog that allows to "reset" the 
+If the journal database gets removed, ownCloud Client's CSync backend will
-journal. That can be used to recreate the journal database.
+rebuild the database by comparing the files and their modification times. Thus
+it should be made sure that both server and client synchronized with NTP time
+before restarting the client after a database removal.
+
+Pressing ``F5`` in the Account Settings Dialog that allows to "reset" the
+journal. That can be used to recreate the journal database. Use this only
+if advised to do so by the developer or support staff.

doc/building.rst

@@ -1,5 +1,7 @@
-Building the Client
+.. _building-label:
-===================
+
+Appendix A: Building the Client
+===============================
 
 This section explains how to build the ownCloud Client from source
 for all major platforms. You should read this section if you want

doc/glossary.rst

@@ -4,8 +4,8 @@ Glossary
 .. glossary::
    :sorted:
 
+   ownCloud Sync Client
    ownCloud Client
-   oCC
      Name of the official ownCloud syncing client for desktop, which runs on
      Windows, Mac OS X and Linux. It is based Mirall, and uses the CSync
      sync engine for synchronization with the ownCloud server.
@@ -23,6 +23,7 @@ Glossary
      exist in the client directory.
 
    unique id
+   ETag
      ID assigned to every file starting with ownCloud server 4.5 and submitted
      via the HTTP ``Etag``. Used to check if files on client and server have
      changed.

doc/index.rst

@@ -6,9 +6,11 @@ Contents
 .. toctree::
    :maxdepth: 2
 
-   install
+   introduction
-   userinterface
+   accountsetup
-   usage 
+   visualtour
+   advancedusage
+
    building 
    architecture
    troubleshooting

doc/install.rst

@@ -1,36 +0,0 @@
-Installation
-============
-
-General
--------
-
-The latest version of ownCloud client can be obtained at
-http://owncloud.org/sync-clients/.
-
-Windows
--------
-
-ownCloud client for Windows is provided as a NSIS-based setup file for
-machine-wide install.
-
-Mac OS X
---------
-
-Installing the ownCloud client on your Mac follows the normal app installation
-pattern: 
-
-1. Download the installation file Click ownCloud-x.y.z.dmg, a window with the
-2. ownCloud icon opens In that window, drag the ownCloud application into the
-3. ‘Applications’ folder on the right hand side From ‘Applications’, choose
-   ownCloud
-
-Linux
-------
-
-The ownCloud client is provided as in a convenient repository for a wide range
-of popular Linux distributions. If you want to build the sources instead.
-
-Supported distributions are CentOS/RHEL, Fedora, SLES, openSUSE, Ubuntu and
-Debian.
-
-To support other distributions, a source build is required.

doc/introduction.rst

@@ -0,0 +1,37 @@
+Introduction
+============
+
+This is the documentation for the ownCloud Sync Client, also referred to as
+the ownCloud Client.
+
+The ownCloud Sync Client is a desktop program you install on your computer.
+Specify one ore more directories on the local machine to sync your ownCloud
+server, and always have your latest files wherever you are. Make a change to the
+files on one computer, it will flow across the others using these desktop sync
+clients.
+
+ownCloud Client is available for Windows, Mac OS X and various Linux
+distributions. See below for details on how to obtain the Client.
+
+Obtaining the Client
+--------------------
+
+The latest version of the ownCloud Client can be obtained at
+http://owncloud.org/sync-clients/.
+
+ownCloud client for **Windows** is provided as a NSIS-based setup file for
+machine-wide install. Installing the ownCloud client on **Mac OS** follows
+the normal app bundle installation pattern:
+
+1. Download the installation file: Click ``ownCloud-x.y.z.dmg``, a window with
+   the ownCloud icon opens.
+2. In that window, drag the ownCloud application into the ``Applications``
+   folder.
+3. On the right hand side From ``Applications``, choose ``ownCloud``.
+
+The ownCloud Client is also provided as in a convenient repository for a wide
+range of popular **Linux distributions**. If you want to build the sources
+instead.
+
+Supported distributions are Fedora, openSUSE, Ubuntu and Debian.
+To support other distributions, a is required, see :ref:`building-label`

doc/options.rst

@@ -15,9 +15,6 @@ ownCloud Client supports the following command line switches:
 ``--logflush``
         flush the log file after every write.
 
-``--monoicons``
-        Use black/white pictograms for systray.
-
 ``--confdir`` `<dirname>`
         Use the given configuration directory.
 

doc/troubleshooting.rst

@@ -1,5 +1,5 @@
-Troubleshooting
+Appendix C: Troubleshooting
-===============
+===========================
 
 If the client fails to start syncing it basically can have two
 basic reasons: Either the server setup has a problem or the client
@@ -55,6 +55,12 @@ ownCloud is not shared with other syncing apps.
           not be attempted. In the worst case, doing so can result in data
           loss.
 
+If some files do not get take a look at the sync protocol. Some files are
+automatically automatically being ignored because they are system files,
+others get ignored because their file name contains characters that cannot
+be represented on certain file systems. See :ref:`_ignored-files-label` for
+details.
+
 If you are operating your own server and use the local storage backend (the
 default), make sure that ownCloud has exclusive access to the directory.
 
@@ -65,13 +71,15 @@ If you are using a different backend, you can try to exclude a bug in the
 backend by reverting to the local backend.
 
 Logfiles
-========
+--------
 
 Doing effective debugging requires to provide as much as relevant logs as
 possible. The log output can help you with tracking down problem, and if you 
 report a bug, you're advised to include the output.
 
-:Client Logfile:
+Client Logfile
+~~~~~~~~~~~~~~
+
 Start the client with ``--logwindow``. That opens a window providing a view
 on the current log. It provides a Save button to let you save the log to a 
 file.
@@ -97,11 +105,14 @@ given expiry period.
 
 For example, for a long running test where you intend to keep the log data of the
 last two days, this would be the command line:
+
 ```
 owncloud --logdir /tmp/owncloud_logs --logexpire 48
 ```
 
-:ownCloud server Logfile:
+ownCloud server Logfile
+~~~~~~~~~~~~~~~~~~~~~~~
+
 The ownCloud server maintains an ownCloud specific logfile as well. It can and
 must be enabled through the ownCloud Administration page. There you can adjust
 the loglevel. It is advisable to set it to a verbose level like ``Debug`` or
@@ -110,7 +121,9 @@ the loglevel. It is advisable to set it to a verbose level like ``Debug`` or
 The logfile can be viewed either in the web interface or can be found in the
 filesystem in the ownCloud server data dir.
 
-:Webserver Logfiles:
+Webserver Logfiles
+~~~~~~~~~~~~~~~~~~
+
 Also, please take a look at your webservers error log file to check if there
 are problems. For Apache on Linux, the error logs usually can be found at
 ``/var/log/apache2``. A file called ``error_log`` shows errors like PHP code

doc/usage.rst

@@ -1,95 +0,0 @@
-Usage
-=====
-.. index:: usage, client sync usage
-
-To start ownCloud Client, click on the desktop icon or start it from the
-application menu. In the system tray, an ownCloud icon appears.
-
-.. index:: start application
-
-Overview
---------
-
-ownCloud is represented by an icon in the Desktop's system tray, also known
-as notification area.
-
-The clients menu is accessed with a right click (Windows, Linux) or left click
-(Mac OS).
-
-The status of the current sync can be observed in the Status dialog, available
-trough the ``Open status...`` option. On Windows, a left click on the tray icon
-also opens the status dialog.
-
-.. note:: Until the intial setup has finished, the Connection Wizard will be
-          shown instead when left-clicking on Windows.
- 
-The dialog provides an overview on the configured sync folders and allows to add
-and remove more sync folder connections as well as pausing a sync connection.
-
-Changing Your Password and Account Settings
--------------------------------------------
-
-In the ``Settings`` Dialog, choose ``Account`` -> ``Modify Account``. It will open
-Setup Wizard, which next to reconfiguring your connection to use a different
-user or server also will allow to change the password for the local account,
-or to switch from HTTP to HTTPS.
-
-Setting up a Proxy
-------------------
-
-By default, the configured system proxy will be picked up. This may not be
-working reliably on some Linux distributions, as only the ``http_proxy``
-variable gets picked up. You can configure a proxy different from your
-system default in the ``Network`` section of the ``Settings`` dialog.
-
-The default settings  assume an HTTP proxy, which is the typical use case.
-If you require SOCKS 5 proxy, pick ``SOCKS5 proxy`` instead of ``HTTP(S) proxy``
-from the drop down menu. SOCKS 5 proxies are typically provided by some
-SSH implementations, for instance OpenSSH's ``-D`` parameter. This is
-useful for scenarios where SSH is employed to securely tunnel a client
-to the network running the ownCloud server.
-
-Limiting Bandwidth
-------------------
-
-Starting with Version 1.4, the Client provides bandwidth limiter.
-This option can be found in the ``Network`` section of the
-``Settings Dialog``.
-
-You will find two settings for ``Download Bandwidth`` and
-``Upload Bandwidth``.
-
-Upload Bandwidth
-~~~~~~~~~~~~~~~~
-
-The default is to automatically limit the upload. The rationale
-for this default is that typically, Computers and laptops are
-not directly connected to the server, but via a Cable Modems
-or DSL lines, which provide significantly more downstream than
-upstream bandwith. Sataurating the upstream bandwidth would
-interfere with other applications, especially Voice-Over-IP or
-Games.
-
-The automatic limiter will throttle the speed to about 75%
-of the available upstream bandwidth. If you are communicating
-with the server via a fast, symetric connection, you can set the
-Limiter to ``No Limit`` instead. If want a stronger limitation,
-choose ``Limit to`` and specify a limit manually.
-
-
-Download Bandwidth
-~~~~~~~~~~~~~~~~~~
-
-Because the download bandwidth is usually no concern, it is not
-automatically limited. Should you find that the Client is taking
-up too much bandwidth, you can manually specify a limit (in KB).
-
-Options
--------
-.. index:: command line switches, command line, options, parameters
-.. include:: options.rst
-
-Config File
------------
-.. index:: config file
-.. include:: conffile.rst

doc/visualtour.rst

@@ -1,43 +1,7 @@
-The User Interface
+Visual Tour
-==================
+===========
 
-Setting up an Account
+.. index:: visual tour, usage
----------------------
-
-If no account has been conimaged, ownCloud Client will assist you in connecting
-to your ownCloud Server. As a first step, specify the URL to your Server, just
-like you would when you open your ownCloud instance inside a browser.
-
-.. image:: images/wizard_url.png
-   :scale: 50 %
-
-.. note:: Make sure to use ``https://`` if the server supports it. Otherwise,
-   your password and all data will be transferred to the server unencrypted.
-   This makes it easy for third parties to intercept your communication, and
-   getting hold of your password!
-
-Next, you are prompted for your username and password. Again, use the same
-credentials that you would use to log on via the web interface.
-
-.. image:: images/wizard_user.png
-   :scale: 50 %
-
-Finally, choose the folder that ownCloud Client is supposed to sync the
-contents of your ownCloud account with. By default, this is a folder
-called `ownCloud`, which will reside in your home directory.
-
-.. image:: images/wizard_targetfolder.png
-   :scale: 50 %
-
-After pressing `Connect`, ownCloud Client will commence with the syncing
-process. The next screen will give you the opportunity to review your
-settings:
-
-.. image:: images/wizard_overview.png
-   :scale: 50 %
-
-Overview of the ownCloud Client Interface
------------------------------------------
 
 ownCloud Client stays in the background, and is visible as an
 icon in your system tray (Windows, KDE), status bar (Mac OS X)
@@ -73,21 +37,23 @@ The settings dialog is split up in three categories: ``Account Settings``,
 Account Settings
 ~~~~~~~~~~~~~~~~
 
+.. index:: account settings, user, password, Server URL
+
 The ``Account Settings`` tab provides an executive summary about the synced
 folders in your account and allows to modify them. It also provides a more
 detailed report about the storage usage. Finally, it allows to change
 the files that ownCloud Client should ignore (for details, see the
 ``Ignored Files Editor`` section below), and to modify various aspects
-of the current account settings.
+of the current account settings, such as user name, password and server URL.
-
 
 .. image:: images/settings_account.png
    :scale: 50 %
 
-
 General Settings
 ~~~~~~~~~~~~~~~~
 
+.. index:: general settings, auto start, startup, desktop notifications
+
 The tab provides several useful options:
 
 .. image:: images/settings_general.png
@@ -108,6 +74,8 @@ when filing a bug report.
 Network Settings
 ~~~~~~~~~~~~~~~~
 
+.. index:: proxy settings, SOCKS, bandwith, throttling, limiting
+
 This tab consollidates ``Proxy Settings`` and ``Bandwith Limiting``:
 
 .. image:: images/settings_network.png
@@ -155,6 +123,8 @@ will finish using the old settings.
 The Sync Protocol
 ~~~~~~~~~~~~~~~~~
 
+.. index:: sync protocol
+
 The ``Sync Protocol`` window, which can be invoked from either from the main
 menu (``Recent Changes`` -> ``Details...``) or the ``Account Settings``
 (``Info`` button), will provide you with an in-depth summary of the recent
@@ -167,19 +137,27 @@ characters that cannot be stored on certain file systems.
 .. image:: images/sync_protocol.png
    :scale: 50 %
 
+.. _ignoredFilesEditor-label:
+
 The Ignored Files Editor
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
+.. index:: ignored files, exclude files, pattern
+
 The ignored files editor allows adding patterns for files or directories
 that should be excluded from the sync process. Next to normal characters,
 wildcards can be used to match an arbitrary number of characters, designated
 by an asterisk (``*``) or a single character, designated by a question mark
 (``?``).
 
-Global defaults cannot be directlly modified within the editor. Hovering
+Global defaults cannot be directly modified within the editor. Hovering
 with the mouse will reveal the location of the global exclude definition
 file.
 
+In addition to this list, ownCloud Client always excludes files with
+characters that cannot be synched down to other file systems,
+see :ref:`ignored-files-label`.
+
 .. note:: Modifying the global exclude definition file might render the
    client unusable or cause undesired behavior.