docs: Apply review feedback

Clarify some points in the coordinate overview.

diff --git a/docs/reference/gtk/coordinates.md b/docs/reference/gtk/coordinates.md
index ac6f209f585740e8d1cf90a0b4eb2494a53b68cc..fe0e8be429092d6863cc47ba86c120910ffd8ca9 100644 (file)
--- a/docs/reference/gtk/coordinates.md
+++ b/docs/reference/gtk/coordinates.md
@@ -15,11 +15,15 @@ When it comes to rendering, GTK follows the CSS box model as far as practical.
 
 The CSS stylesheet that is in use determines the sizes (and appearance) of the
 margin, border and padding areas for each widget. The size of the content area
-is determined by GTKs layout algorithm using each widgets measure() and
-size_allocate() vfuncs.
+is determined by GTKs layout algorithm using each widgets [vfunc@Gtk.Widget.measure]
+and [vfunc@Gtk.Widget.size_allocate] vfuncs.
 
 You can learn more about the CSS box model by reading the
-[CSS specification](https://www.w3.org/TR/css-box-3/#box-model).
+[CSS specification](https://www.w3.org/TR/css-box-3/#box-model) or the
+Mozilla [docs](https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/The_box_model).
+
+To learn more about where GTK CSS differs from CSS on the web, see the
+[CSS overview](css-overview.html).
 
 ## Widgets
 
@@ -33,31 +37,28 @@ The transform to go from one widgets coordinate system to another one can be obt
 with [method@Gtk.Widget.compute_transform].
 
 When widget APIs expect positions or areas, they need to be expressed in this coordinate
-system, typically called *widget coordinates*. GTK provides a number of APIs to translate
+system, typically called **_widget coordinates_**. GTK provides a number of APIs to translate
 between different widgets' coordinate systems, such as [method@Gtk.Widget.compute_point]
 or [method@Gtk.Widget.compute_bounds].
 
-Another area that is occasionally relevant are the widgets *bounds*, which is the area
+Another area that is occasionally relevant are the widgets **_bounds_**, which is the area
 that a widgets rendering is typically confined to (technically, widgets can draw outside
 of this area, unless clipping is enforced via the [property@Gtk.Widget:overflow] property).
 In CSS terms, the bounds of a widget correspond to the border area.
 
-During GTK's layout algorithm, a parent widget needs to assign size and position to its
-child widgets, by calling [method@Gtk.Widget.allocate] or one of its variants. The size
-that is passed to this function corresponds to the margin area of the child widget in
-the CSS box model.
+During GTK's layout algorithm, a parent widget needs to measure each visible child and
+allocate them at least as much size as measured. These functions take care of respecting
+the CSS box model and widget properties such as align and margin. This happens in the
+parent's coordinate system.
 
 ## Events
 
-Some types of events that are coming from the windowing system have positions associated
-with them (e.g. the pointer position). Such positions are expressed in *surface coordinates*
-which have their origin at the top left corner of the surface.
-
-When interpreting such positions with respect to widgets, you need to keep in mind that
-there is an offset between the top left corner of the surface and the top left corner of
-the topmost widget (typically either a [class@Gtk.Window] or [class@Gtk.Popover]). This
-offset can be obtained with [method@Gtk.Native.get_surface_transform].
+Some types of events have positions associated with them (e.g. the pointer position).
+Such positions are expressed in **_surface coordinates_**, which have their origin at
+the top left corner of the surface.
 
-This translation is only necessary when dealing with raw events in the form of
-[class@Gdk.Event] structs. Event controllers such as [class@Gtk.GestureClick] report
-positions in the coordinate system of the widget they are attached to.
+Event controllers and gestures report positions in the coordinate system of the widget
+they are attached to. But if you are dealing with raw events in the form of [class@Gdk.Event]
+struts, you need to translate from surface to widget coordinates, by applying the offset
+from the top left corner of the surface to the top left corner of the topmost
+widget. This offset can be obtained with [method@Gtk.Native.get_surface_transform].