moving content for wallet devs into doc/

2 files changed, 212 insertions, 0 deletions

diff --git a/doc/dev-wallet-wx.rst b/doc/dev-wallet-wx.rst
new file mode 100644
index 000000000..8ba299750
--- /dev/null
+++ b/doc/dev-wallet-wx.rst
@@ -0,0 +1,212 @@
+..
+  This file is part of GNU TALER.
+  Copyright (C) 2014, 2015, 2016 INRIA
+  TALER is free software; you can redistribute it and/or modify it under the
+  terms of the GNU General Public License as published by the Free Software
+  Foundation; either version 2.1, or (at your option) any later version.
+  TALER is distributed in the hope that it will be useful, but WITHOUT ANY
+  WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
+  A PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
+  You should have received a copy of the GNU Lesser General Public License along with
+  TALER; see the file COPYING.  If not, see <http://www.gnu.org/licenses/>
+
+  @author Florian Dold
+
+=====================
+WebExtensions Wallet
+=====================
+
+------------
+Introduction
+------------
+
+The WebExtensions Wallet (*wxwallet*) can be used to pay with GNU Taler on web
+sites from within modern web browsers.  The `WebExtensions
+<https://wiki.mozilla.org/WebExtensions>`_ API enables the development of
+cross-browser extensions.  Google Chrome / Chromium, Mozilla Firefox, Opera and
+Microsoft Edge will all offer support for WebExtensions and thus be able to support Taler.
+
+Currently Chrome hast the best support for WebExtensions (since the API is a
+superset of Chrome's extension API).
+
+-----------------------
+Development Environment
+-----------------------
+
+The *wxwallet* mainly written in the `TypeScript
+<http://www.typescriptlang.org/>`_ language, which is a statically typed
+superset of JavaScript.
+
+While the *wxwallet* is mainly intended to be run from inside a browser, the
+logic is implemented in browser-independent modules that can also be called
+from other environments such as `nodejs <https://nodejs.org>`_.  This is
+especially useful for automatically running unit tests.
+
+
+-----------------
+Project Structure
+-----------------
+
+.. parsed-literal::
+
+  **manifest.json**               extension configuration
+  **package.json**                node.js package configuration
+  **tsconfig.json**               TypeScript compiler configuration
+  **gulpfile.js**                 Build tasks script
+  **lib/**
+      **vendor/**                 3rd party libraries
+      **wallet/**                 actual application logic
+      **emscripten/**             emscripten object file and glue
+  **test/**
+       **run_tests.js**           nodejs entry point for tests
+       **tests/**                 test cases
+  **content_scripts/notify.ts**   wallet<->website signaling
+  **backgrond/main.ts**           backend entry point
+  **img/**                        static image resources
+  **style/**                      CSS stylesheets
+  **pages/**                      pages shown in browser tabs
+  **popup/**                      pages shown the extension popup
+
+
+-------------------
+Building the Wallet
+-------------------
+
+To build the extension for use during development, simply run the TypeScript compiler
+from the extension directory:
+
+.. code-block:: sh
+
+  $ cd wallet.git/wallet_webextension/extension/
+  $ tsc
+
+This will use the ``tsconfig.json`` with development options such as `source map`_ support.
+
+.. _`source map`: https://docs.google.com/document/d/1U1RGAehQwRypUTovF1KRlpiOFze0b-_2gc6fAH0KY0k/edit
+
+When TypeScript source files are added or deleted to the project, make sure that the
+globs in ``gulpfile.js`` match them so that they will be compiled.  The ``tsconfig.json``
+is generated by running:
+
+
+.. code-block:: sh
+
+  $ gulp tsconfig
+
+.. caution::
+
+  Do not edit the ``tsconfig.json`` manually.  The source files should be defined in
+  one place, and that is ``gulpfile.js``.
+
+To pack the extension in a format that can be uploaded to the Google Webstore, run:
+
+.. code-block:: sh
+
+  $ gulp package
+
+This will build the wallet without source maps, copy resource files (which also need to be
+specified in ``gulpfile.js``) and create an archive.
+
+
+----------
+Emscripten
+----------
+
+`Emscripten <https://kripken.github.io/emscripten-site/index.html>`_ is C/C++
+to JavaScript compiler.  Emscripten is used in the *wxwallet* to access
+low-level cryptography from *libgcrypt*, and miscellaneous functionality from
+*libgnunetutil* and *libtalerwallet*.
+
+TODO: say things about wrappers
+
+
+--------------------------------------
+Target Environments and Modularization
+--------------------------------------
+
+Modules in the wallet are declared in TypeScript with
+the ES6 module syntax.  These modules are then compiled
+to `SystemJS <https://github.com/systemjs/systemjs>`_ `register` modules.
+
+SystemJS modules can be loaded from the browser as well as from nodejs.
+However they require special entry points that configure the module system,
+load modules and execute code.  Examples are `backgrond/main.ts` for the
+browser and `test/run_tests.js` for nodejs.
+
+Note that special care has to be taken when loading the Emscript code,
+as it is not compatible with the SystemJS module, even in the `globals`
+compatibility mode.
+
+The TypeScript sources in the *wxwallet* are compiled down to ES5, both to
+enable running in node.js without transpilers and to avoid a `bug
+<https://github.com/Microsoft/TypeScript/issues/6426>`_ in the TypeScript
+compiler.
+
+----------------------------
+IndexedDB Query Abstractions
+----------------------------
+
+The *wxwallet* uses a fluent-style API for queries on IndexedDB.
+
+TODO: say more about this
+
+
+-------
+Testing
+-------
+
+Test cases for the wallet are written in TypeScript and
+run with `mochajs <http://mochajs.org/>`_ and the `better-assert <https://github.com/tj/better-assert>`_ assertion
+library.
+
+Run the default test suite with ``npm run test``, which will
+call `mocha` with the right parameters.
+
+
+--------------------
+Internationalisation
+--------------------
+
+Strings in the JavaScript code are internationalised using the following functions:
+
+- *i18n*: translate string with arbitrary arguments, the result is returned as string.
+
+.. code-block:: js
+
+  i18n`You have ${n} coins.`
+
+- *i18n.parts*: Interpolate i18nized values with arbitrary objects.
+  Useful for example to include HTML elements.
+
+.. code-block:: js
+
+  i18n.parts`Visit ${link} to get more coins.`
+
+- *i18n.pluralize*: translate with plural form.
+  The i18n.number() function returns a ``PluralNumber`` object
+  that specifies the argument that determines the plural form,
+  if not present the first numeric argument is used.
+
+.. code-block:: js
+
+  i18n.pluralize(
+    i18n`${i}: you have ${i18n.number(n)} coin.`,
+        `${i}: you have ${i18n.number(n)} coins.`);
+
+These functions are defined in ``lib/i18n.ts``.
+Include ``lib/vendor/jed.js``, ``lib/i18n.js``, ``lib/i18n-strings.js`` to use them.
+
+To extract strings from sources and update the .po files, run:
+
+.. code-block:: sh
+
+  $ make i18n
+
+In static HTML files the ``lang`` attribute is used for language-specific strings:
+
+.. code-block:: html
+
+  <p lang="en">Hello World!</p>
+  <p lang="de">Hallo Welt!</p>
+
+``lib/i18n.js`` and ``style/lang.css`` needs to be included for this to work.
diff --git a/web-common b/web-common
-Subproject a8bff2e27b89feb3696cf0e3a49fc00155d92de
+Subproject fd80260fce96df674111f9100fa2d91c83a9a3b