Add some flowcharts to the doc (need review)

[Elv13]

Hello,

In an attempt to fix more of #1373 and because I am adding more client and spawn related commits since last week, I think our process are now too complex to be learnt from reading the doc as it stands now. This issue will be a dumping ground for unfinished flowcharts and will eventually result in a pull request when I am happy.

If anyone think more of the steps deserve to be shown, tell us about it and why. My goal here is not to convert the lua code into a flowchart, it is to guide the new users in the maze of extension points. Eventually I will add colors to the extension points and a legend with proper documentation links.

First one, adding a client

[Elv13]

How is the client placed/screen selected

(assumes that resize_requests_honor feature is added)

[psychon]

First one, adding a client

• This seems to be more about awful.rules than "everything in general".
• Lots of property::foo signals are emitted before awful.rules "goes to work". For example, the screen containing the position that the window was created is set and this already emits property::screen. request::tag is always emitted, even when the rules specify some tags. It's just that the only thing connected to this signal does nothing if the client already has tags (that belong to the same screen as the client).
• "Emit the request::activate signal" is a lie, this only happens if the client has focus=true, but in the default config this is already gated by awful.client.focus.filter. -I think "Resume normal operation" sounds weird, how about "done"?

Here is what the C code does when a new client appears (that is visible from Lua):

1. Create a new client (signal new)
2. Add to the global client list (the client now appears in client.get())
3. Set the screen to whatever screen contains the client's position (property::screen)
4. Set the geometry and only emit signals after all the geometry was set (property::x, ::y, ::width, ::height, ::window (?), ::geometry, in this order)
5. Set the border width (property::border_width)
6. Set size_hints_honor = true (property::size_hints_honor)
7. Fetch lots of properties (in this order and emitting signals): Struts, size hints (without a signal?!), urgent (via ICCCM), [At this point some part of c.focusable is set,] group_window, icon (from ICCCM), transient_for, leader_window (no signal), client_machine, role, pid, icon (from EWMH), name (from ICCCM), name (from EWMH), icon_name (from ICCCM), icon_name (from EWMH), class, protocols (this is purely internal to the C code), motif wm hints, opacity
8. transient_for for other clients pointing to this client is updated/set
9. If the client specifies a tag (_NET_WM_DESKTOP), a state (sticky, skip_taskbar, fullscreen, maximized h/v, above, below, modal, hidden, urgent (via EWMH)), or a window type, this is now fetched and applied (So, clients can actually be tagged before awful.rules runs!)
10. The new client is put on top of the stacking order (but this emits no signals); so, all stacking done before now is ignored/lost
11. startup id becomes available (no signal, but this can complete a SN sequence which then emits some signal; I don't think I remember any Lua code besides awful.startup_notification ever using this)
12. property::list is emitted, just because the client list changed a long time ago.
13. At this point now is manage emitted and the C code is done.

How is the client placed/screen selected

• This misses at least the C code selection done in step 3 above.
• The "was it spawned with" likely refers to rules specified via awful.spawn? If so, this reference could be made more explicit and it might make sense to mention that this requires the client to support SN
• "Does the awful.rules select a X" should be "Is there a rule specifying X in awful.rules" or something like that... or not, dunno
• "Use whatever screen the client has" is not a step; the screen was already set some time ago.
• The detour for "apply geometry" could be made shorter by just saying "apply geometry, if any is specified in a rule"
• Apropos, why is the screen selection separate from the manage picture above?
• This flowchart could be replaced with a list containing each step. Actually, the first one could as well. Dunno if a flowchart really is better...
• This flowchart contains two... flowcharts. The second one just says "If the client requests to be moved, then request::geometry with "ewmh" context is emitted (for historic reasons, no idea what this has to do with EWMH). This signal is handled in awful.ewmh.client_geometry_requests and applied if resize_requests_honor (which needs to be renamed) is true."