doc: shuffled around some sections, fixes.

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

1 files changed, 101 insertions, 96 deletions

diff --git a/doc/WindowManagerTMC.txt b/doc/WindowManagerTMC.txt
index c272299..6446396 100644
--- a/doc/WindowManagerTMC.txt
+++ b/doc/WindowManagerTMC.txt
@@ -12,7 +12,7 @@ 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.
+who 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
@@ -55,7 +55,7 @@ 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.
+The client library is built together with the window manager itself.
 
 == Concepts
 The window manager implements a couple of concepts in order to allow
@@ -64,9 +64,7 @@ efficient implementation.
 === Layers
 Layers are entities that are stacked on top of each other. Each layer
 has an ID which is used for the ivi-controller interface, but this ID
-also implicitly specifies its stacking order. That is, the screen render
-order will be set according to the layer stacking which is determined by
-the layer IDs.
+also implicitly specifies its stacking order, from lowest to highest.
 
 Layers are always full-screen. We do not use layer dimensions as a way
 to setup the scene, rather - each layer has a layout attached to it,
@@ -76,15 +74,99 @@ Additionally, layers will generally leave surfaces on below layers
 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 `DeactivateSurface` API
-call.
+It is possible to deactivate these surfaces on lower layers explicitly
+using the `DeactivateSurface` API call.
 
 === Surfaces
 Surfaces are _placed_ on layers according to their name. The surface
 will then be resized to dimensions, according to the layer's layout
 configuration.
 
+== Binding API
+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. The notation used has the following meaning:
+
+------
+FunctionName(argument_name: argument_type)[: function_return_type]
+------
+
+Where the return type may be omitted if it is void.
+
+* `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
+  exits). Each surface that is managed by the window manager needs to
+  call this function first!
+* `ActivateSurface(drawing_name: string)`
+  This function requests the activation of a surface. It usually is not
+  called by the application, but rather by the application framework or
+  the HomeScreen.
+* `DeactivateSurface(drawing_name: string)`
+  Request deactivation of a surface. This function is not usually called
+  by applications themselves, but rather by the application framework or
+  the HomeScreen.
+* `EndDraw(drawing_name: string)`
+  Signals the window manager, that the surface is finished drawing. This
+  is useful for consistent flicker-free layout switches, see the
+  Architecture document for details.
+
+There are a couple of non-essential (mostly for debugging and
+development) API calls:
+
+* `list_drawing_names(): json`
+  List known surface _name_ to _ID_ associations.
+* `ping()`
+  Ping the window manager. Does also dispatch pending events if any.
+* `debug_status(): json`
+  Returns a json representation of the current layers and surfaces known
+  to the window manager. This represents the wayland-ivi-extension
+  object's properties.
+* `debug_surfaces(): json`
+  Returns a json representation of all surfaces known to the window
+  manager. This represents the wayland-ivi-extension properties of the
+  surfaces.
+* `debug_layers(): json`
+  Returns the current layer configuration, as configured through
+  _layers.json_.
+* `debug_terminate()`
+  Terminates the afb-daemon running the window manager binding, if the
+  environment variable `WINMAN_DEBUG_TERMINATE` is set.
+
+=== Events
+The window manager broadcasts certain events (to all applications) that
+signal information on the state of the surface regarding the current
+layout.
+
+* `Active(drawing_name: string)`
+  Signal that the surface with the name `drawing_name` is now active.
+* `Inactive(drawing_name: string)`
+  Signal that the surface with the name `drawing_name` is now inactive.
+  This usually means, the layout got changed, and the surface is now
+  considered inactive (or sleeping).
+* `Visible(drawing_name: string)`
+  Signal applications, that the surface with name `drawing_name` is now
+  visible.
+* `Invisible(drawing_name: string)`
+  Signal applications that the surface with name `drawing_name` is now
+  invisible.
+* `SyncDraw(drawing_name: string)`
+  Signal applications, that the surface with name `drawing_name` needs
+  to redraw its content - this usually is sent when the surface geometry
+  changed.
+* `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 geometry).
+
+=== Binding API Usage
+For a detailed description on how the binding API is supposed to be
+used, refer to the Architecture document.
+
 == Configuration
 The window manager is configured with the _layers.json_ configuration
 file, by default it is searched in `/etc/layers.json` but through the
@@ -194,16 +276,19 @@ actual_height = screen_height + 1 + height
 ------
 
 Or in other words, to leave an `N` wide border around a surface, the
-actual value in the configuration needs to be `-N - 1`.
+actual value in the dimension configuration needs to be `-N - 1`, and
+appropriate offsets need to be set for `x` and `y`.
 
 ===== split_layouts
-this configuration item allows the specification of split-screen layouts
-on layers for certain surfaces. A split screen layout always has a
-_main_ surface and a _sub_ surface. In order to enter a split screen
-layout, first the _main_ surface of the layout must be activated, and
-then the _sub_ surface. In order to disable the split layout, one of the
-two participating surface must be deactivate (or a surface on a layer
-below the current one must be activated).
+This configuration item allows the specification of split-screen layouts
+on layers for certain surfaces.
+
+A split screen layout always has a _main_ surface and a _sub_
+surface. In order to enter a split screen layout, first the _main_
+surface of the layout must be activated, and then the _sub_ surface. In
+order to disable the split layout, one of the two participating surface
+must be deactivated (or a surface on a layer below the current one
+must be activated).
 
 ------
 "split_layouts": [
@@ -234,85 +319,6 @@ this layout.
 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
-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
-  exits). Each surface that is managed by the window manager needs to
-  call this function first!
-* `ActivateSurface(drawing_name: string)`
-  This function requests the activation of a surface. It usually is not
-  called by the application, but rather by the application framework or
-  the HomeScreen.
-* `DeactivateSurface(drawing_name: string)`
-  Request deactivation of a surface. This function is not usually called
-  by applications themselves, but rather by the application framework or
-  the HomeScreen.
-* `EndDraw(drawing_name: string)`
-  Signals the window manager, that the surface is finished drawing. This
-  is useful for consistent flicker-free layout switches, see the
-  Architecture document for details.
-
-There are a couple of non-essential (mostly for debugging and
-development) API calls:
-
-* `list_drawing_names(): json`
-  List known surface _name_ to _ID_ associations.
-* `ping()`
-  Ping the window manager. Does also dispatch pending events if any.
-* `debug_status(): json`
-  Returns a json representation of the current layers and surfaces known
-  to the window manager. This represents the wayland-ivi-extension
-  object's properties.
-* `debug_surfaces(): json`
-  Returns a json representation of all surfaces known to the window
-  manager. This represents the wayland-ivi-extension properties of the
-  surfaces.
-* `debug_layers(): json`
-  Returns the current layer configuration, as configured through
-  _layers.json_.
-* `debug_terminate()`
-  Terminates the afb-daemon running the window manager binding, if the
-  environment variable `WINMAN_DEBUG_TERMINATE` is set.
-
-=== Events
-The window manager broadcasts certain events (to all applications) that
-signal information on the state of the surface regarding the current
-layout.
-
-* `Active(drawing_name: string)`
-  Signal that the surface with the name `drawing_name` is now active.
-* `Inactive(drawing_name: string)`
-  Signal that the surface with the name `drawing_name` is now inactive.
-  This usually means, the layout got changed, and the surface is now
-  considered inactive (or sleeping).
-* `Visible(drawing_name: string)`
-  Signal applications, that the surface with name `drawing_name` is now
-  visible.
-* `Invisible(drawing_name: string)`
-  Signal applications that the surface with name `drawing_name` is now
-  invisible.
-* `SyncDraw(drawing_name: string)`
-  Signal applications, that the surface with name `drawing_name` needs
-  to redraw its content - this usually is sent when the surface geometry
-  changed.
-* `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 geometry).
-
-=== Binding API Usage
-For a detailed description on how the binding API is supposed to be
-used, refer to the Architecture document.
-
 == Building and Running
 
 === Dependencies
@@ -479,5 +485,4 @@ The implementation is loosely split across the following source files:
   wrapper. It is instanced in `main.cpp` and handles all our wayland
   needs.
 
-
 // vim:set ft=asciidoc tw=72 spell spelllang=en_US: