docs: Move to Markdown

The various documentation files are already in formatted in a
Markdown-like fashion, so let's make it official.

6 files changed, 245 insertions, 234 deletions

diff --git a/doc/BACKENDS.md b/doc/BACKENDS.md
new file mode 100644
index 000000000..3612e2f9e
--- /dev/null
+++ b/doc/BACKENDS.md
@@ -0,0 +1,208 @@
+IMPLEMENTING BACKENDS
+===============================================================================
+
+Clutter supports multiple backends for handling windowing systems and
+GL/GLES API on different platforms.
+
+The GL and GLES API are abstracted by the COGL library. The windowing
+system is handled by the ClutterBackend implementations inside Clutter
+itself.
+
+Clutter, at the moment, supports only in-tree backends.
+
+In order to write a new backend for a specific platform you should
+create a new sub-directory under clutter/clutter containing:
+
+  - The subclass of the ClutterBackend abstract class.
+
+    <backend>/clutter-backend-<backend>.h
+    <backend>/clutter-backend-<backend>.c
+
+  - The implementation of the stage window
+
+    <backend>/clutter-stage-<backend>.h
+    <backend>/clutter-stage-<backend>.c
+
+  - The implementation of the input device manager
+
+    <backend>/clutter-device-manager-<backend>.h
+    <backend>/clutter-device-manager-<backend>.c
+
+  - Event-specific code (optional)
+
+    <backend>/clutter-event-<backend>.c
+
+  - A header for the backend-specific API that should be installed
+    by Clutter inside the include directory along with the rest of
+    the public API headers (optional).
+
+    <backend>/clutter-<backend>.h
+
+Implementing ClutterBackend
+-------------------------------------------------------------------------------
+
+Each backend must implement the
+
+```cpp
+GType
+_clutter_backend_impl_get_type (void);
+```
+
+function declared inside clutter/clutter-private.h. The implementation
+of the function must return the same GType of the backend implementation,
+for instance:
+
+```
+GType
+_clutter_backend_impl_get_type (void)
+{
+  return CLUTTER_TYPE_BACKEND_GLX;
+}
+```
+
+The ClutterBackend implementation is a singleton instance, and the
+backend must ensure that every time `g_object_new()` is called the same
+pointer is returned (with its reference count increased). The GObject
+API reference describes how to use the ::constructor virtual function
+to implement a singleton, so you should refer to that.
+
+The `ClutterBackend` implementation should hold a single drawing context
+for its entire lifetime; stage implementations should be "made current"
+when needed.
+
+When implementing the ClutterBackend subclass these virtual functions
+can be overridden:
+
+  - `ClutterBackend::add_options`: Use this function to install new,
+  backend-specific `GOptionEntry` definitions to Clutter's `GOptionGroup`.
+  *This function is guaranteed to be called just once*.
+
+  - `ClutterBackend::pre_parse`: Use this function to check for environment
+  variables or setting up default values before the command line arguments
+  are parsed. *This function is guaranteed to be called just once*.
+
+  - `ClutterBackend::post_parse`: Use this function to prepare the backend
+  with the values either set inside the `pre_parse` virtual function or by
+  the command line options parsing code. *This function is guaranteed to be
+  called just once*.
+
+  - `ClutterBackend::init_events`: Use this function to initialize the event
+  handling. *This function is guaranteed to be called just once*.
+
+  - `ClutterBackend::get_features`: Use this function to retrieve the features
+  detectable at runtime from the GL or GLES implementation, plus the eventual
+  backend-specific features.
+
+  - `ClutterBackend::create_context`: This function is used to create the
+  drawing context to be used by Clutter. Clutter will call this function
+  during the initialization phase. A GL (or GLES) context must always be
+  available after the initialization, so that Cogl and Clutter can query it
+  for capabilities. *This function might be called multiple times* so if a
+  context was successfully created in a previous call, this function should
+  short-circuit early and return `TRUE`.
+
+  - `ClutterBackend::ensure_context`: This function is used to ensure that
+  the backend drawing context is made current for passed `ClutterStage`,
+  using the backend-specific API. *This function is called each time a new
+  stage is going to be painted*. If the Stage is inside its destruction
+  sequence this function should either fall back the drawing context to a
+  default drawing surface or should unset the drawing surface from the
+  drawing context.
+
+  - `ClutterBackend::create_stage`: This function is used to create the
+  stage implementation. It will receive as an argument the ClutterStage
+  instance that is "wrapping" the actual implementation being created.
+  The backend must create its stage implementation, initialise it and
+  then return it; in case of error, the backend must return `NULL` and
+  set the passed `GError` instance.
+
+  - `ClutterBackend::get_device_manager`: This function is used to return
+  the `ClutterDeviceManager` instance that is going to be returned by
+  `clutter_device_manager_get_default()` and that should be used internally
+  by input event translation.
+
+Implementing the stage
+-------------------------------------------------------------------------------
+
+`ClutterStage` acts as a wrapper class relaying all the drawing operations
+to the actual implementation. The underlying implementation of the stage can
+be any `GObject` subclass, as long as it implements the `ClutterStageWindow`
+interface.
+
+The `ClutterStageWindow` interface contains a set of virtual functions that
+should be overridden by backends that support a windowing system, like
+`set_title()`, `set_fullscreen()`, `set_cursor_visible()`, etc.
+
+The stage implementation actor must implement:
+
+  - `ClutterStageWindow::get_wrapper()`
+  - `ClutterStageWindow::realize()` and `unrealize()`
+  - `ClutterStageWindow::show()` and `hide()`
+  - `ClutterStageWindow::resize()`
+  - `ClutterStageWindow::get_geometry()`
+  - `ClutterStageWindow::redraw()`
+
+The `get_wrapper()` implementation should return the pointer to the
+`ClutterStage` actor using the `ClutterStageWindow` implementation.
+
+In the `realize()` virtual function the stage implementation should:
+
+  - create a new native window handle
+  - ensure that there is a GL (or GLES) context
+  - make sure that the native window handle is compatible with
+    the GL (or GLES) context
+
+The return value should be `TRUE` if the stage implementation was
+successfully realized, and `FALSE` otherwise.
+
+Inside the `unrealize()` function the stage implementation should destroy
+the native window handle created in `realize()`.
+
+The `resize()` virtual function implementation should cause an update
+of the Cogl viewport.
+
+The `redraw()` virtual function implementation should contain the platform
+specific drawing logic, and call `_clutter_stage_do_paint()` on the
+`ClutterStage` wrapper instance to cause the scene to be painted.
+
+The stage implementation actor can optionally implement:
+
+  - `ClutterStageWindow::get_pending_swaps()`
+
+The `get_pending_swaps()` implementation should return the number of swap
+buffer requests pending completion. This is only relevent for backends
+that also support `CLUTTER_FEATURE_SWAP_EVENTS`.
+
+If the stage window is supposed to handle events, then it should also implement
+the `ClutterEventTranslator` interface; this interface has a single virtual
+function:
+
+  - `ClutterEventTranslator::translate_event()`
+
+which gets passed a pointer to the native event data structure, and a
+pointer to a newly-allocated, empty `ClutterEvent`. The event translator
+implementation should then decide between three options:
+
+  - translate the native event and return `CLUTTER_TRANSLATE_QUEUE` to
+    let Clutter queue it up in the events queue;
+  - return `CLUTTER_TRANSLATE_CONTINUE` to let other event translators handle
+    the event;
+  - return `CLUTTER_TRANSLATE_REMOVE` to ignore the event.
+
+Implementing ClutterDeviceManager
+-------------------------------------------------------------------------------
+
+Backends with input devices should provide a `ClutterDeviceManager`
+implementation to handle addition, removal and input device event translation
+through the `ClutterEventTranslator` interface.
+
+NOTES
+===============================================================================
+
+ - If the platform is using X11 you should probably subclass `ClutterBackendX11`
+ and `ClutterStageX11`, which will provide you with a ready to use code
+ implementation for event handling and window management.
+
+ - If the platform is natively supported by Cogl, you should subclass the
+ `ClutterStageCogl` class, which will provide you wth a ready to use
+ implementation of the underlying Cogl machinery.
diff --git a/doc/CODING_STYLE b/doc/CODING_STYLE.txt
index b8682c82b..b8682c82b 100644
--- a/doc/CODING_STYLE
+++ b/doc/CODING_STYLE.txt
diff --git a/doc/HACKING b/doc/CONTRIBUTING.md
index a927f012f..ff7ba7053 100644
--- a/doc/HACKING
+++ b/doc/CONTRIBUTING.md
@@ -1,11 +1,20 @@
-GENERAL
-=======
+Contributing to Clutter
+=======================
 
-General notes and rules on clutter core hacking;
+The usual workflow for contributions should be:
 
- - Follow the CODING_STYLE document.
+ 1. Fork the repository
+ 2. Create a branch (`git checkout -b my_work`)
+ 3. Commit your changes (`git commit -am "Added my awesome feature"`)
+ 4. Push to the branch (`git push origin my_work`)
+ 5. Open a new merge request
+ 6. Sit back, relax and wait for feedback and eventual merge
 
- - *Really* follow the CODING_STYLE document.
+General notes and rules on Clutter core hacking;
+
+ - Follow the [CODING STYLE](./CODING_STYLE.txt) document.
+
+ - *Really* follow the [CODING STYLE](./CODING_STYLE.txt) document.
 
  - All non static public API funcs should be documented in the source files
    via gtk-doc. Structures, enumerations and macros should be documented in
@@ -21,50 +30,49 @@ General notes and rules on clutter core hacking;
    to Cogl.
 
  - Properties should use pixels whenever is possible. Dimensional and
-   positional properties can also use ClutterParamSpecUnits to define
+   positional properties can also use `ClutterParamSpecUnits` to define
    the units-based logical values with a unit type.
 
  - The nick and blurb of properties in public classes should be marked for
-   translation by using the P_() macro defined in the clutter-private.h
+   translation by using the `P_()` macro defined in the `clutter-private.h`
    header file.
 
  - Public entry points must always check their arguments with
-   g_return_if_fail() or g_return_val_if_fail().
+   `g_return_if_fail()` or `g_return_val_if_fail()`.
 
- - Private entry points should use g_assert() or g_warn_if_fail() to
-   verify internal state; do not use g_return_if_fail() or
-   g_return_val_if_fail() as they might be compiled out.
+ - Private entry points should use `g_assert()` or `g_warn_if_fail()` to
+   verify internal state; do not use `g_return_if_fail()` or
+   `g_return_val_if_fail()` as they might be compiled out.
 
  - If you need to share some state variable across source files use
-   ClutterContext and a private accessor.
+   `ClutterContext` and a private accessor.
 
  - Private, non-static functions must begin with an underscore and
-   be declared inside clutter-private.h.
+   be declared inside `clutter-private.h`.
 
  - Don't add direct GL calls but add API to Cogl (both GL and GL|ES
    versions if possible).
 
- - Use the CLUTTER_NOTE() macro for debug statements in Clutter, and
-   the COGL_NOTE() macro for debug statements in Cogl. If necessary,
-   add a value inside ClutterDebugFlags or CoglDebugFlags to specify
+ - Use the `CLUTTER_NOTE()` macro for debug statements in Clutter. If
+   necessary, add a value inside `ClutterDebugFlags` to specify
    the debug section.
 
  - New features should also include an exhaustive test unit under
-   tests/conform and, eventually, a user-interactive test under
+   tests/conform and, possibly, a user-interactive test under
    tests/interactive.
 
  - When committing, use the standard git commit message format:
 
-=== begin example commit ===
+```
 Short explanation of the commit
 
 Longer explanation explaining exactly what's changed, whether any
 external or private interfaces changed, what bugs were fixed (with bug
 tracker reference if applicable) and so forth. Be concise but not too
 brief. Don't be afraid of using UTF-8, or even ASCII art.
-=== end example commit ===
+```
 
- - Always add a brief description of the commit to the _first_ line of
+ - Always add a brief description of the commit to the **first** line of
    the commit and terminate by two newlines (it will work without the
    second newline, but that is not nice for the interfaces).
 
@@ -73,21 +81,23 @@ brief. Don't be afraid of using UTF-8, or even ASCII art.
      long description           - Each line MUST be less than 76 characters
 
  - Do NOT put the commit message on the short description line. One line
-   commit messages should be avoided, unless they can be *fully* explained
+   commit messages should be avoided, unless they can be **fully** explained
    in less than 72 characters (e.g. "Fix typo in
-   clutter_actor_create_pango_context() docs").
+   `clutter_actor_create_pango_context()` docs").
 
  - The brief description might optionally have a "tag", i.e. a word or two
    followed by a color, detailing what part of the repository the commit
    affected, e.g.:
 
+```
       alpha: Add :mode property
       text: Emit ::cursor-event only on changes
+```
 
  - The tag counts as part of overall character count, so try using
-   a short word. Optionally, you can also use the "[tag]" form.
+   a short word. Optionally, you can also use the `[tag]` form.
 
- - Build environment fixes should use the "build" tag.
+ - Build environment fixes should use the `build` tag.
 
  - Think of the commit message as an email sent to the maintainers explaining
    "what" you did and, more importantly, "why" you did it. The "how" is not
diff --git a/doc/HACKING.backends b/doc/HACKING.backends
deleted file mode 100644
index 0c8037060..000000000
--- a/doc/HACKING.backends
+++ /dev/null
@@ -1,207 +0,0 @@
-IMPLEMENTING BACKENDS
-===============================================================================
-
-Clutter supports multiple backends for handling windowing systems and
-GL/GLES API on different platforms.
-
-The GL and GLES API are abstracted by the COGL library. The windowing
-system is handled by the ClutterBackend implementations inside Clutter
-itself.
-
-Clutter, at the moment, supports only in-tree backends.
-
-In order to write a new backend for a specific platform you should
-create a new sub-directory under clutter/clutter containing:
-
-  <backend>/clutter-backend-<backend>.h
-  <backend>/clutter-backend-<backend>.c
-
-  -- The subclass of the ClutterBackend abstract class.
-
-  <backend>/clutter-stage-<backend>.h
-  <backend>/clutter-stage-<backend>.c
-
-  -- The implementation of the stage window
-
-  <backend>/clutter-device-manager-<backend>.h
-  <backend>/clutter-device-manager-<backend>.c
-
-  -- The implementation of the input device manager
-
-  <backend>/clutter-event-<backend>.c
-
-  -- Event-specific code (optional)
-
-  <backend>/clutter-<backend>.h
-
-  -- A header for the backend-specific API that should be installed
-     by Clutter inside the include directory along with the rest of
-     the public API headers (optional).
-
-
-Implementing ClutterBackend
--------------------------------------------------------------------------------
-
-Each backend must implement the
-
-  GType
-  _clutter_backend_impl_get_type (void);
-
-function declared inside clutter/clutter-private.h. The implementation
-of the function must return the same GType of the backend implementation,
-for instance:
-
-  GType
-  _clutter_backend_impl_get_type (void)
-  {
-    return CLUTTER_TYPE_BACKEND_GLX;
-  }
-
-The ClutterBackend implementation is a singleton instance, and the
-backend must ensure that every time g_object_new() is called the same
-pointer is returned (with its reference count increased). The GObject
-API reference describes how to use the ::constructor virtual function
-to implement a singleton, so you should refer to that.
-
-The ClutterBackend implementation should hold a single drawing context
-for its entire lifetime; stage implementations should be "made current"
-when needed.
-
-When implementing the ClutterBackend subclass these virtual functions
-can be overridden:
-
-  ClutterBackend::add_options
-  -- Use this function to install new, backend-specific GOptionEntry
-     definitions to the Clutter GOptionGroup. This function is guaranteed
-     to be called just once.
-
-  ClutterBackend::pre_parse
-  -- Use this function to check for environment variables or setting
-     up default values before the command line arguments are parsed.
-     This function is guaranteed to be called just once.
-
-  ClutterBackend::post_parse
-  -- Use this function to prepare the backend with the values either
-     set inside the ::pre_parse virtual function or by the command
-     line options parsing code. This function is guaranteed to be
-     called just once.
-
-  ClutterBackend::init_events
-  -- Use this function to initialize the event handling. This function
-     is guaranteed to be called just once.
-
-  ClutterBackend::get_features
-  -- Use this function to retrieve the features detectable at runtime
-     from the GL or GLES implementation, plus the eventual backend-specific
-     features.
-
-  ClutterBackend::create_context
-  -- This function is used to create the drawing context to be used
-     by Clutter. Clutter will call this function during the initialization
-     phase. A GL (or GLES) context must always be available after the
-     initialization, so that Cogl and Clutter can query it for capabilities.
-     This function might be called multiple times so if a context was
-     successfully created in a previous call, this function should
-     short-circuit early and return TRUE
-
-  ClutterBackend::ensure_context
-  -- This function is used to ensure that the backend drawing context
-     is made current for passed ClutterStage, using the backend-specific
-     API. This function is called each time a new stage is going to
-     be painted. If the Stage is inside its destruction sequence this
-     function should either fall back the drawing context to a default
-     drawing surface or should unset the drawing surface from the
-     drawing context.
-
-  ClutterBackend::create_stage
-  -- This function is used to create the stage implementation. It will
-     receive as an argument the ClutterStage instance that is "wrapping"
-     the actual implementation being created. The backend must create
-     its stage implementation, initialise it and then return it; in case
-     of error, the backend must return NULL and set the passed GError.
-
-  ClutterBackend::get_device_manager
-  -- This function is used to return the ClutterDeviceManager instance
-     that is going to be returned by clutter_device_manager_get_default()
-     and that should be used internally by input event translation.
-
-Implementing the stage
--------------------------------------------------------------------------------
-
-ClutterStage acts as a wrapper object relaying all the drawing operations
-to the actual implementation. The implementation of the stage can be any
-GObject subclass, as long as it implements the ClutterStageWindow interface.
-
-The ClutterStageWindow interface contains a set of virtual functions that
-should be overridden by backends that support a windowing system, like
-::set_title(), ::set_fullscreen(), ::set_cursor_visible(), etc.
-
-The stage implementation actor must implement:
-
-  • ClutterStageWindow::get_wrapper()
-  • ClutterStageWindow::realize() and ::unrealize()
-  • ClutterStageWindow::show() and ::hide()
-  • ClutterStageWindow::resize()
-  • ClutterStageWindow::get_geometry()
-  • ClutterStageWindow::redraw()
-
-The ::get_wrapper() implementation should return the pointer to the
-ClutterStage actor using the ClutterStageWindow implementation.
-
-In the ::realize virtual function the stage implementation should:
-
-  - create a new native window handle
-  - ensure that there is a GL (or GLES) context
-  - make sure that the native window handle is compatible with
-    the GL (or GLES) context
-
-The return value should be TRUE if the stage implementation was successfully
-realized, and FALSE otherwise.
-
-Inside the ::unrealize function the stage implementation should destroy
-the native window handle created in ::realize().
-
-The ::resize() virtual function implementation should cause an update
-of the COGL viewport.
-
-The ::redraw() virtual function implementation should contain the platform
-specific drawing logic, and call _clutter_stage_do_paint() on the ClutterStage
-wrapper instance to cause the scene to be painted.
-
-The stage implementation actor can optionally implement:
-
-  • ClutterStageWindow::get_pending_swaps()
-
-The get_pending_swaps() implementation should return the number of swap
-buffer requests pending completion. This is only relevent for backends
-that also support CLUTTER_FEATURE_SWAP_EVENTS.
-
-If the stage window is supposed to handle events, then it should also implement
-the ClutterEventTranslator interface; this interface has a single virtual
-function:
-
-  • ClutterEventTranslator::translate_event()
-
-which gets passed a pointer to the native event data structure, and a pointer
-to a newly-allocated, empty ClutterEvent. The EventTranslator implementation
-should then decide between three options:
-
-  - translate the native event and return CLUTTER_TRANSLATE_QUEUE to
-    let Clutter queue it up in the events queue;
-  - return CLUTTER_TRANSLATE_CONTINUE to let other event translators handle
-    the event;
-  - return CLUTTER_TRANSLATE_REMOVE to ignore the event.
-
-Implementing ClutterDeviceManager
--------------------------------------------------------------------------------
-
-Backends with input devices should provide a ClutterDeviceManager
-implementation to handle addition, removal and input device event translation
-through the ClutterEventTranslator interface.
-
-NOTES
-===============================================================================
-
-• If the platform is using X11 you should probably subclass ClutterBackendX11
-  and ClutterStageX11, which will provide you with a ready to use code
-  implementation for event handling and window management.
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 74cb30a12..4e50f2470 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -11,6 +11,6 @@ endif
 DIST_SUBDIRS = reference cookbook
 
 EXTRA_DIST = \
-	CODING_STYLE \
-	HACKING \
-	HACKING.backends
+	CODING_STYLE.txt \
+	CONTRIBUTING.md \
+	BACKENDS.md
diff --git a/doc/RELEASING b/doc/RELEASING.md
index d753eb811..d753eb811 100644
--- a/doc/RELEASING
+++ b/doc/RELEASING.md