README.rst

   1 *****************************
   2 grauphel - tomboy REST server
   3 *****************************
   4 nextCloud__ application implementing the `Tomboy`__ `REST API`__ for syncing notes.
   5
   6 Pretty stable.
   7
   8 ⚠ `I am looking for a new maintainer / funding <http://cweiske.de/tagebuch/grauphel-maintainer.htm>`_
   9
  10 __ https://nextcloud.com/
  11 __ https://wiki.gnome.org/Apps/Tomboy
  12 __ https://wiki.gnome.org/Apps/Tomboy/Synchronization/REST/1.0
  13
  14
  15 .. contents::
  16
  17 ======
  18 Status
  19 ======
  20
  21 What works
  22 ==========
  23 - Note synchronization
  24 - OAuth token management interface
  25 - Database management interface (reset)
  26 - Viewing notes
  27 - Searching notes
  28 - Downloading notes as HTML and reStructuredText
  29
  30 What is missing
  31 ===============
  32 - Web interface to edit notes. I will probably not implement this.
  33   Patches welcome :-)
  34
  35
  36 =================
  37 Supported clients
  38 =================
  39 * Conboy__ (Nokia N900 Maemo)
  40 * Tomboy__ (Linux, Windows)
  41 * Tomdroid__ (Android)
  42
  43 __ http://conboy.garage.maemo.org/
  44 __ https://wiki.gnome.org/Apps/Tomboy
  45 __ https://github.com/tomboy-notes/tomdroid
  46
  47
  48 Known working versions
  49 ======================
  50 grauphel 0.7.6 is known to work with:
  51
  52 * Tomboy 1.15.2, Linux
  53 * Tomboy 1.15.1, Windows
  54 * Tomdroid 0.7.5, Android 4.4.1
  55
  56 See the HowTo__ document for client-specific configuration instructions.
  57
  58 __ docs/howto.rst
  59
  60
  61 =============
  62 Functionality
  63 =============
  64
  65 Search
  66 ======
  67 You can use nextCloud's global search on the top right.
  68
  69 During search, the note's titles, tags and content are searched.
  70
  71 Search syntax:
  72
  73 ``foo``
  74   Search for notes containing "foo"
  75 ``foo bar``
  76   Search for notes containing "foo" and "bar"
  77 ``"foo bar" baz``
  78   Search for notes containing "foo bar" and "baz"
  79 ``foo -bar``
  80   Search for notes containing "foo" but not "bar"
  81
  82
  83 ============
  84 Dependencies
  85 ============
  86 * PHP
  87 * PHP `oauth extension`__
  88
  89 __ http://pecl.php.net/package/oauth
  90
  91
  92 ============
  93 Installation
  94 ============
  95
  96 .. note::
  97    grauphel needs to be activated for all users.
  98    It will not work with the "enable only for specific groups" setting.
  99
 100 App store installation
 101 ======================
 102 #. Log into nextcloud as administrator
 103 #. Goto "Apps"
 104 #. Enable experimental apps in the settings
 105 #. Click "Productivity"
 106 #. Look for "grauphel - Tomboy sync server"
 107 #. Click "Activate"
 108
 109
 110 Manual installation
 111 ===================
 112
 113 #. SSH onto your web server
 114 #. Navigate to the nextcloud ``apps`` directory, often in ``/var/www/nextcloud/apps``
 115 #. Download the latest release from http://cweiske.de/grauphel.htm#download
 116    and extract it.
 117    For example::
 118
 119      $ wget http://cweiske.de/download/grauphel/grauphel-0.7.6.tar.gz
 120      $ tar xjvf grauphel-0.7.6.tar.gz
 121      $ rm grauphel-0.7.6.tar.gz
 122
 123    You do have a directory ``/var/www/nextcloud/apps/grauphel`` now.
 124 #. Using your browser, login as administrator into nextCloud and click
 125    the "Apps" icon in the main menu ("+" icon).
 126 #. Click on "Grauphel: Tomboy note server" and then on the "Enable" button.
 127 #. In the main menu, click the "Tomboy notes" icon.
 128
 129 It may be that grauphel now shows you an error message::
 130
 131   PHP extension "oauth" is required
 132
 133 You have to install the PHP PECL oauth extension now.
 134 On Debian 9 or higher, do the following::
 135
 136   $ apt install php-oauth
 137   $ phpenmod oauth
 138   $ /etc/init.d/apache2 restart
 139
 140 Reload the nextCloud page in your browser now.
 141
 142 .. note::
 143    ``oauth-1.2.3`` is only needed on PHP 5.x
 144    For PHP 7 simply use ``pecl install oauth``.
 145
 146
 147 ========
 148 Download
 149 ========
 150 .. LATESTRELEASE
 151
 152 See `grauphel downloads page <http://cweiske.de/grauphel-download.htm>`_
 153 for all released versions.
 154
 155 ======
 156 Author
 157 ======
 158 Christian Weiske, cweiske@cweiske.de, http://cweiske.de/
 159
 160
 161 =====
 162 Links
 163 =====
 164 - `Homepage`__
 165 - `grauphel on apps.nextcloud.com`__
 166 - `Source code repository`__
 167 - `Github source code mirror`__
 168
 169 __ http://cweiske.de/grauphel.htm
 170 __ http://apps.nextcloud.com/apps/grauphel
 171 __ http://git.cweiske.de/grauphel.git/
 172 __ https://github.com/cweiske/grauphel
 173
 174
 175 =================
 176 Development hints
 177 =================
 178 * JSON coming from Tomboy: Title is html-escaped already
 179   (e.g. ``>`` is ``&gt;``).
 180   We store it that way in the database, so there is no need to escape the
 181   output.
 182 * ``latest-sync-revision`` sent from Tomboy during PUT sync is already
 183   incremented by 1.
 184
 185
 186 Unit testing
 187 ============
 188 - `ownCloud unit testing documentation`__
 189 - `grauphel on Travis CI`__
 190
 191   .. image:: https://travis-ci.org/cweiske/grauphel.svg
 192      :target: https://travis-ci.org/cweiske/grauphel
 193
 194 __ https://doc.owncloud.org/server/8.0/developer_manual/core/unit-testing.html
 195 __ https://travis-ci.org/cweiske/grauphel
 196
 197
 198 Releasing grauphel
 199 ==================
 200 To release a new version, do the following:
 201
 202 #. Increase version number in ``appinfo/version`` and ``appinfo/info.xml``.
 203 #. Validate ``appinfo/info.xml``::
 204
 205      $ xmllint --noout --schema tools/info.xsd appinfo/info.xml
 206
 207 #. Validate ``appinfo/database.xml``::
 208
 209      $ xmllint --noout --schema tools/database.xsd appinfo/database.xml
 210
 211 #. Fill the ``ChangeLog`` file with the changes since the last release,
 212    mention the new version number.
 213 #. Update ``README.rst`` and increase the version number
 214 #. Create the grauphel release file with::
 215
 216      $ phing
 217
 218    The file will be in ``dist/``
 219 #. Test the release on a server
 220 #. Tag the release in git
 221 #. Upload the release to http://cweiske.de/grauphel.htm with::
 222
 223      $ cd ~/Dev/html/cweiske.de
 224      $ ./scripts/update-grauphel.sh
 225
 226 #. Upload the new release on
 227    https://apps.nextcloud.com/developer/apps/releases/new
 228
 229    Signature::
 230
 231      $ openssl dgst -sha512 -sign ~/.nextcloud/certificates/grauphel.key dist/grauphel-0.7.6.tar.gz | openssl base64