[gtk/matthiasc/for-master: 10/10] Add to the docs README

[Matthias Clasen <matthiasc src gnome org>]

commit 199b00d537dd2d369108100c5abae0d68095c325
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed May 27 10:55:15 2020 -0400

    Add to the docs README

 docs/reference/README.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 59 insertions(+), 1 deletion(-)
---
diff --git a/docs/reference/README.md b/docs/reference/README.md
index 7cf169e799..f413d9083b 100644
--- a/docs/reference/README.md
+++ b/docs/reference/README.md
@@ -9,7 +9,7 @@ The GTK documentation is divided in two major components:
 In both cases, the contents are parsed, converted into DocBook format, and
 cross-linked in order to match types, functions, signals, and properties.
 From the DocBook output, we generate HTML, which can be used to read the
-documentation both off line and online.
+documentation both offline and online.
 
 In both cases, contributing to the GTK documentation requires modifying
 files tracked in the source control repository, and follows the same steps
@@ -76,6 +76,9 @@ New classes require:
  1. the `get_type` function added to the `.types` file
  1. an `xinclude` element in the `docs.xml` file
 
+The GTK documentation also contains a number of 'freestanding' chapters
+for which the source is in .md files in docs/reference/gtk.
+
 ## Style guide
 
 Like the [coding style][coding], these rules try to formalize the existing
@@ -85,6 +88,29 @@ unrelated reasons.
 
 [coding]: ../CODING-STYLE.md
 
+### Syntax
+
+The input syntax for GTK documentation is markdown, in a flavor that is
+similar to what you see on gitlab or github. The markdown support for
+fragments that are extracted from sources is more limited than for
+freestanding chapters.
+
+As an exception, man pages for tools are currently maintained in docbook,
+since the conversion from markdown to docbook is losing too much of the
+expected formatting.
+
+In addition to typical markdown formatting such as \*emphasis\*, gtk-doc
+supports a few abbreviations for cross-references and formatting:
+
+`#ClassName`
+ : Creates a link to the docs for a class
+
+`function()`
+ : Creates a link to the docs for a function
+
+`%constant`
+ : Generates suitable markup for enum values or constants
+
 ### Sections
 
  - The "section" of each type must contain a name, to be referenced in the
@@ -138,6 +164,19 @@ Checks whether the widget is set to be visible or not.
  - If a method is a signal emitter, link the signal in the method's
    description.
 
+### Signals
+
+ - While GObject can introspect argument and return types for signals,
+   you should *always* document them with an explicit gtk-doc stanza.
+ - The syntax for signal stanzas is similar to functions:
+
+      /**
+       * GtkFoo::signal-name:
+       * @arg1: ...
+       * @arg2: ...
+       *
+       * ...
+
 ### Properties
 
  - While GObject properties contain text that can be extracted
@@ -148,3 +187,22 @@ Checks whether the widget is set to be visible or not.
    purposes.
  - Always note if setting a property has side effects, like causing another
    property to change state.
+ - The syntax for property documentation is:
+
+      /**
+       * GtkFoo:property-name:
+       *
+       * ...
+
+### Actions
+
+ - Actions are new in GTK 4, and gtk-doc had to learn a a new syntax
+   to document them:
+
+     /**
+      * GtkFoo|action-name:
+      * @arg1: ...
+      * @arg2: ...
+      *
+      * ...
+