From b9dbc793089192e6c1c252d86854e7b2f59c0736 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Wed, 14 Dec 2016 20:28:24 -0500 Subject: [PATCH] doc: Add more `awful.spawn` documentation It was lacking --- lib/awful/spawn.lua | 55 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/lib/awful/spawn.lua b/lib/awful/spawn.lua index 339049fdf..78249eefb 100644 --- a/lib/awful/spawn.lua +++ b/lib/awful/spawn.lua @@ -6,6 +6,61 @@ -- program after it has been launched. This requires currently that the -- applicaton supports them. -- +-- **Understanding clients versus PID versus commands versus class**: +-- +-- A *process* has *PID* (process identifier). It can have no, one or many *window*s. +-- +-- A *command* if what is used to start *process*(es). It has no direct relation +-- with *process*, *client* or *window*. When a command is executed, it will +-- usually start a *process* which keeps running until it exits. This, however, +-- isn't always true as some applications use scripts as command and some other +-- use various single instance mechanism (usually client/server) and merge with +-- an existing process. +-- +-- A *client* correspond to a *window*. It is owned by a process. It can have +-- both a parent and one or many children. A *client* has a *class*, an +-- *instance*, a *role*, and a *type*. See `client.class`, `client.instance`, +-- `client.role` and `client.type` for more information about these properties. +-- +-- **The startup notification protocol**: +-- +-- The startup notification protocol is an optional specification implemented +-- by X11 applications to bridge the chain of knowledge between the moment a +-- program is launched to the moment its window (client) is shown. It can be +-- found [on the FreeDesktop.org website](https://www.freedesktop.org/wiki/Specifications/startup-notification-spec/). +-- +-- Awesome has support for the various events that are part of the protocol, but +-- the most useful is the identifier, usually identified by its `SNID` acronym in +-- the documentation. It isn't usually necessary to even know it exists, as it +-- is all done automatically. However, if more control is required, the +-- identifier can be specified by an environment variable called +-- `DESKTOP_STARTUP_ID`. For example, let us consider execution of the following +-- command: +-- +-- DESKTOP_STARTUP_ID="something_TIME$(date '+%s')" my_command +-- +-- This should (if the program correctly implements the protocol) results in +-- `c.startup_id` to at least match `something`. +-- This identifier can then be used in `awful.rules` to configure the client. +-- +-- Awesome can automatically set the `DESKTOP_STARTUP_ID` variable. This is used +-- by `awful.spawn` to specify additional rules for the startup. For example: +-- +-- awful.spawn("urxvt -e maxima -name CALCULATOR", { +-- floating = true, +-- tag = mouse.screen.selected_tag, +-- placement = awful.placement.bottom_right, +-- }) +-- +-- This can also be used from the command line: +-- +-- awesome-client 'awful=require("awful"); +-- awful.spawn("urxvt -e maxima -name CALCULATOR", { +-- floating = true, +-- tag = mouse.screen.selected_tag, +-- placement = awful.placement.bottom_right, +-- })' +-- -- @author Julien Danjou <julien@danjou.info> -- @author Emmanuel Lepage Vallee <elv1313@gmail.com> -- @copyright 2008 Julien Danjou