doc: Add more `awful.spawn` documentation

It was lacking

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