Merge pull request #1274 from Elv13/more_spawn_doc

More spawn doc

docs/90-FAQ.md

@@ -381,6 +381,27 @@ multi-screen support to existing configs, see how
 `awful.screen.connect_for_each_screen` is used in the new `rc.lua` or rebuild
 your config on a newer revision of `rc.lua`.
 
+### Can I have a client or the system tray on multiple screens at once?
+
+No. This is an X11 limitation and there is no sane way to work around it.
+
+### Can a client be tagged on different screens at once?
+
+While it is not impossible to partially implement support for this, many
+Awesome components frequently query the client's screen.
+Since a client can only be in one screen at once, this will cause side effects.
+So by default Awesome avoids, but does not prevent, having clients in multiple
+tags that are not on the same screen.
+
+### Can a tag be on multiple screens?
+
+No. See the previous two questions. However, it is possible to swap tags across
+screens using `t:swap(t2)` (assuming `t` and `t2` are valid `tag` objects).
+
+This can be used to emulate a tag being on multiple screens. Note that this will
+break support for multi-tagged clients. For this reason it isn't implemented by
+default.
+
 ## Development
 
 ### How to report bugs?

lib/awful/spawn.lua

@@ -6,6 +6,146 @@
 -- program after it has been launched.  This requires currently that the
 -- applicaton supports them.
 --
+-- **Rules of thumb when a shell is needed**:
+--
+-- * A shell is required when the commands contain `&&`, `;`, `||`, `&` or
+--  any other unix shell language syntax
+-- * When shell variables are defined as part of the command
+-- * When the command is a shell alias
+--
+-- Note that a shell is **not** a terminal emulator. A terminal emulator is
+-- something like XTerm, Gnome-terminal or Konsole. A shell is something like
+-- `bash`, `zsh`, `busybox sh` or `Debian ash`.
+--
+-- If you wish to open a process in a terminal window, check that your terminal
+-- emulator supports the common `-e` option. If it does, then something like
+-- this should work:
+--
+--    awful.spawn(terminal.." -e my_command")
+--
+-- Note that some terminals, such as rxvt-unicode (urxvt) support full commands
+-- using quotes, while other terminal emulators require to use quoting.
+--
+-- **Understanding clients versus PID versus commands versus class**:
+--
+-- A *process* has a *PID* (process identifier). It can have 0, 1 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 is
+-- not always the case as some applications use scripts as command and others
+-- use various single-instance mechanisms (usually client/server) and merge
+-- with an existing process.
+--
+-- A *client* corresponds 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) result 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,
+--      })'
+--
+-- **Getting a command's output**:
+--
+-- First, do **not** use `io.popen` **ever**. It is synchronous. Synchronous
+-- functions **block everything** until they are done. All visual applications
+-- lock (as Awesome no longer responds), you will probably lose some keyboard
+-- and mouse events and will have higher latency when playing games. This is
+-- also true when reading files synchronously, but this is another topic.
+--
+-- Awesome provides a few ways to get output from commands. One is to use the
+-- `Gio` libraries directly. This is usually very complicated, but gives a lot
+-- of control on the command execution.
+--
+-- This modules provides `with_line_callback` and `easy_async` for convenience.
+-- First, lets add this bash command to `rc.lua`:
+--
+--    local noisy = [[bash -c '
+--      for I in $(seq 1 5); do
+--        date
+--        echo err >&2
+--        sleep 2
+--      done
+--    ']]
+--
+-- It prints a bunch of junk on the standard output (*stdout*) and error
+-- (*stderr*) streams. This command would block Awesome for 10 seconds if it
+-- were executed synchronously, but will not block it at all using the
+-- asynchronous functions.
+--
+-- `with_line_callback` will execute the callbacks every time a new line is
+-- printed by the command:
+--
+--    awful.spawn.with_line_callback(noisy, {
+--        stdout = function(line)
+--            naughty.notify { text = "LINE:"..line }
+--        end,
+--        stderr = function(line)
+--            naughty.notify { text = "ERR:"..line}
+--        end,
+--    })
+--
+-- If only the full output is needed, then `easy_async` is the right choice:
+--
+--    awful.spawn.easy_async(noisy, function(stdout, stderr, reason, exit_code)
+--        naughty.notify { text = stdout }
+--    end)
+--
+-- **Default applications**:
+--
+-- If the intent is to open a file/document, then it is recommended to use the
+-- following standard command. The default application will be selected
+-- according to the [Shared MIME-info Database](https://specifications.freedesktop.org/shared-mime-info-spec/shared-mime-info-spec-latest.html)
+-- specification. The `xdg-utils` package provided by most distributions
+-- includes the `xdg-open` command:
+--
+--    awful.spawn({"xdg-open", "/path/to/file"})
+--
+-- Awesome **does not** manage, modify or otherwise influence the database
+-- for default applications. For information about how to do this, consult the
+-- [ARCH Linux Wiki](https://wiki.archlinux.org/index.php/default_applications).
+--
+-- If you wish to change how the default applications behave, then consult the
+-- [Desktop Entry](https://specifications.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html)
+-- specification.
+--
 -- @author Julien Danjou <julien@danjou.info>
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2008 Julien Danjou

lib/awful/util.lua

@@ -32,6 +32,7 @@ local floor = math.floor
 local util = {}
 util.table = {}
 
+--- The default shell used when spawing processes.
 util.shell = os.getenv("SHELL") or "/bin/sh"
 
 local displayed_deprecations = {}