doc: documentation update, more examples, some external links

Signed-off-by: Marcus Fritzsch <marcus_fritzsch@mentor.com>

1 files changed, 101 insertions, 47 deletions

diff --git a/doc/WindowManagerTMC.txt b/doc/WindowManagerTMC.txt
index 69182fd..c272299 100644
--- a/doc/WindowManagerTMC.txt
+++ b/doc/WindowManagerTMC.txt
@@ -12,13 +12,24 @@ multiple layers and with different layer layouts.
 
 === Intended audience
 This documentation is intended for developers and system integrators
-that need to know how the window manager works and how it is to be used.
+that need to know, how the window manager works and how it is to be used.
 
 === Scope of this Document
 This document covers the window manager that was implemented for TMC and
 delivered to the Automotive Grade Linux (AGL) project. It includes its
 implementation details, concepts of operation, configuration and usage.
 
+It does not include
+
+* documentation of the underlying architecture, see
+  https://wiki.automotivelinux.org/hmiframework[HMI-Framework].
+* documentation of the AGL application framework and its technologies,
+  see https://wiki.automotivelinux.org/agl-distro/app-framework[AGL
+  Application Framework].
+
+It is highly recommended to have a good understanding of these documents
+and projects before using the window manager.
+
 === Known Issues
 Currently there are a couple of known issues:
 
@@ -35,6 +46,17 @@ Currently there are a couple of known issues:
   library. This is a limitation of how Qt creates surface IDs for the
   ivi-application interface.
 
+=== External libraries
+This project includes a copy of version 2.1.1 the excellent
+https://github.com/nlohmann/json[C++11 JSON library by Niels Lohmann].
+
+=== Client Library
+A client library implementation that internally uses the _libafbwsc_, is
+provided in the subdirectory `client-lib/` with its own documentation
+directory.
+
+The client library is build together with the window manager itself.
+
 == Concepts
 The window manager implements a couple of concepts in order to allow
 efficient implementation.
@@ -55,7 +77,7 @@ activated, and only disable surfaces on layers the are above the
 currently used layer.
 
 In order to deactivate surfaces on lower layer, it is possible to
-deactivate these surfaces explicitly using the `deactivate_surface` API
+deactivate these surfaces explicitly using the `DeactivateSurface` API
 call.
 
 === Surfaces
@@ -70,15 +92,14 @@ use of the environment variable `LAYERS_JSON` the WM can be instructed
 to use different file. Note, that the WM will not run unless this
 configuration is found and valid.
 
+A sample configuration is provided with the window manager
+implementation, this sample is installed to /etc/layers.json.
+
 === Configuration Items
 This section describes configuration items available through
 `layers.json`. It will do this, by first providing an example, and then
 going into its components.
 
-Configuration items can contain `comment` objects, these are unused and
-only for documentation purposes in the json, they can safely be removed
-from the JSON file.
-
 ==== main_surface
 ------
 "main_surface": {
@@ -93,8 +114,7 @@ deactivate it. Placement of this surface on an layer is done by the
 other configuration described below.
 
 * `surface_role` this configuration item specifies the name of the main
-  surface. Set this to e.g. `HomeScreen` if the main surface is called
-  `HomeScreen`.
+  surface. Set this to e.g. `HomeScreen`.
 
 ==== mappings
 This configuration item is a list of surface-name to layer mappings.
@@ -136,7 +156,7 @@ to a layer.
   number of possible split-screen layouts for this layer.
 
 ===== Area
-Areas can be either `full` or `rect`, whereas `full` means a fullscreen
+Areas can be either `full` or `rect`, whereas `full` means a full-screen
 layer, this is mostly useful for the main_surface or HomeScreen layer.
 `rect` declares a layer drawing area specified as a rectangle with
 start coordinates `x` and `y` as well as its dimensions `width` and
@@ -145,7 +165,7 @@ start coordinates `x` and `y` as well as its dimensions `width` and
 The dimensions can be specified relative to the screen dimensions. For
 this negative values for width and height mus be used.
 
-For example, a fullscreen surface can have the following `rect`
+For example, a full-screen surface can have the following `rect`
 definition:
 
 ------
@@ -155,6 +175,16 @@ definition:
           "height": -1 }
 ------
 
+A surface that leaves a 200pixel margin on the top and bottom can use
+the following `rect` definition:
+
+------
+"rect": { "x": 0,
+          "y": 200,
+          "width": -1,
+          "height": -401 }
+------
+
 So the expression for the actual surface dimensions when using
 screen-size-relative values will be:
 
@@ -205,10 +235,14 @@ The names must still match the layer's role match!
 ******
 
 == Binding API
-The binding API consists of a couple of AFB _verbs_ - that is function
+The binding API consists of a couple of AFB _verbs_ - that is; function
 calls to the Window Manager.
 
 === Verbs (Functions)
+Each function returns a reply containing at least a failed or successful
+result of the call, additionally, when calls return something, it is
+noted.
+
 * `RequestSurface(drawing_name: string): int`
   Request a surface ID for the given name. This name and ID association
   will live until the surface is destroyed (or e.g. the application
@@ -273,7 +307,7 @@ layout.
 * `FlushDraw(drawing_name: string)`
   Signal to applications, that the surface with name `drawing_name` can
   now be swapped to its newly drawn content as the window manager is
-  ready to activate a new layout (i.e. a new surface geomtry).
+  ready to activate a new layout (i.e. a new surface geometry).
 
 === Binding API Usage
 For a detailed description on how the binding API is supposed to be
@@ -287,8 +321,9 @@ This project is intended to be build with the 4.0 release of AGL.
 Build dependencies are as follows:
 
 * afb-daemon >= 1.0
-* libsystemd >= 2222
+* libsystemd >= 222
 * wayland-client >= 1.11
+* cmake >= 3.6.1
 
 === Build Configuration
 Use cmake to configure a build tree:
@@ -301,6 +336,17 @@ make
 [sudo] make install
 --------
 
+A couple of build options to configure the build are available:
+
+* `ENABLE_DEBUG_OUTPUT:BOOL` Compiles including very verbose debug
+  output from the window manager, use --verbose three times on an
+  afb-daemon instance to see the debug messages.
+* `ENABLE_SCOPE_TRACING:BOOL` Enables a simple scope tracing mechanism
+  used for a rather small portion of the window manager code. However,
+  it is used quite extensively in the AFBClient implementation.
+
+By default these options will be disabled.
+
 == Utilities
 With the actual window manager implementation, two general utilities are
 provided.
@@ -310,22 +356,48 @@ A shell script, that wraps `afb-client-demo` and issues commands to the
 window manager using the AFB exposed API. It will call synchronously to
 the WM, and output any events that are happening in the meantime.
 Replies are printed to stdout using an failed/success annotation and a
-dump of the actual json reply from the AFB.
-
-==== Commands
-* `wm-request requestsurface $NAME`: request the surface with $NAME,
-  this will succeed only if the surface name is not yet (or anymore)
-  known. The actual call return is in the "response" json object of the
-  reply.
-* `wm-request activatesurface $NAME`: activate the surface with $NAME.
-  This call will only succeed of the surface is available and not
-  currently active. The reply just contains failure/success information,
-  but no actual return value from the API.
-* `wm-request deactivatesurface $NAME`: deactivate the surface with
-  $NAME. This call will only succeed if the surface is currently active,
-  no return value is provided by the API.
-* `wm-request ping`: Just send a *ping* to the window manager, can be
-  sued to check whether the WindowManager is alive or not.
+dump of the actual json reply from the AFB. When found on the system, it
+will use `pygmentize` to apply syntax highlighting to the returned JSON.
+
+==== Examples
+
+------
+$ wm-request list_drawing_names
+ON-REPLY 1:winman/list_drawing_names: OK
+{
+  "response":{
+    "App1":1,
+    "App2":2,
+    "HomeScreen":3,
+    "OnScreen":4
+  },
+  "jtype":"afb-reply",
+  "request":{
+    "status":"success",
+    "info":"success"
+  }
+}
+$ wm-request activatesurface App1
+ON-REPLY 1:winman/activatesurface: OK
+{
+  "response":{
+  },
+  "jtype":"afb-reply",
+  "request":{
+    "status":"success",
+    "info":"success"
+  }
+}
+$ wm-request activatesurface AppThatDoesNotExist
+ON-REPLY 1:winman/activatesurface: ERROR
+{
+  "jtype":"afb-reply",
+  "request":{
+    "status":"failed",
+    "info":"Surface does not exist"
+  }
+}
+------
 
 === redraw_fixer
 This utility is intended to be ran alongside the compositor, it will
@@ -407,23 +479,5 @@ The implementation is loosely split across the following source files:
   wrapper. It is instanced in `main.cpp` and handles all our wayland
   needs.
 
-=== XXX
-a
-
----------------------------
-Some code
----------------------------
-
-The `token` parameter is a string consisting of only alphanumeric
-characters, and with a maximum length of 20 characters. If these
-conditions are not met, the AFBClient instance will not initialize,
-i.e. this call will return `-EINVAL`.
-
-.Note
-******************
-The timeout should be small in order to not block too long, but also a
-0 timeout will not dispatch anything and return immediately (see
-https://linux.die.net/man/2/epoll_wait[epoll_wait(2)]).
-******************
 
 // vim:set ft=asciidoc tw=72 spell spelllang=en_US: