rename and simplification

1 files changed, 19 insertions, 1 deletions

diff --git a/docs/guide.md b/docs/guide.md
index 43a7a1e..adcacc8 100644
--- a/docs/guide.md
+++ b/docs/guide.md
@@ -37,11 +37,29 @@ server. A capability does not guarantee every related action: Cocoa currently
 returns false for interactive resize and window-menu requests even though
 it advertises CSD. Check each result and provide an application fallback.
 
+## Window creation and callbacks
+
+Open the display with application-wide options and notifications in
+`yasl_display_spec`. Create each toplevel with `yasl_window_spec`, including its
+title, logical size, optional `yasl_window_cbs` table in `cbs`, and userdata in
+`ud`. One display can own multiple windows with separate callback tables.
+
+The window copies its callbacks during creation. Its callbacks cannot run before
+creation returns, so the application can store the returned surface first.
+Userdata stays borrowed until callbacks are replaced or the surface is destroyed.
+Read initial geometry with `yasl_surface_geometry()`; creation does not guarantee
+an initial `configure` notification. Request the first redraw once application
+state is ready. `yasl_surface_set_callbacks()` replaces callbacks later and also
+installs popup callbacks; the setter does not invoke the callbacks.
+
+When using `yasl_run()`, its runner installs callbacks for windows on its display.
+Use `yasl_app_desc.event` and `.frame` rather than `yasl_window_spec.cbs` and `.ud`.
+
 ## Geometry and scaling
 
 | Value | Units |
 | --- | --- |
-| Toplevel `yasl_surface_spec.size` | Logical pixels |
+| Toplevel `yasl_window_spec.size` | Logical pixels |
 | `yasl_geometry.size`, framebuffer size | Device pixels |
 | Pointer position, caret, window-menu position | Device pixels, relative to the surface |
 | Damage rectangles | Device pixels, relative to the draw target |