[STUMP] additions to the info manual

[Eric Abrahamsen]

I've been meaning to do this for a while: when I started using stump I
was pretty confused about some of the basic concepts and behaviors (it
was also my first tiling WM), and I thought the manual could use a
little bit more handholding. I've written a manual addition including
what I would have liked to have known in the beginning, and am posting
it here for comments (there are also direct questions in brackets). I
envision this going in the info manual, in the "Introduction" section,
after "Basic Usage", with both "Basic Concepts" and "Manipulating Frames
and Windows" being separate top-level sections.

I haven't posted this as an actual patch because I thought it would be
easier to incorporate comments/additions/corrections in plain text. If
people agree this is useful and we hash out a final version, I can do
the patch then. Or it can go on the wiki, or whatever! Hope this is
helpful.

E

                        ━━━━━━━━━━━━━━━━━━━━━━━━
                         STUMPWM INFO ADDITIONS

                        ━━━━━━━━━━━━━━━━━━━━━━━━


Basic Concepts
══════════════

Screens
───────

  A screen is an Xlib concept representing a section of video memory
  onto which physical monitors (or “heads”) are mapped. Imagine your
  computer’s video output as an abstract rectangle into which all the
  heads are arranged. The actual location of the heads in this rectangle
  is determined not by StumpWM, but by another X-related program such as
  Xrandr. [how does stump arrange them if they’re already plugged in
  when X starts? simple cloning, right? are there other commonly-used
  programs for specifying the location of heads within a screen?]

  What this means in practical terms depends on whether you’re using
  Xinerama or not.

  If you are, you’ll only ever have a single screen no matter how many
  monitors are connected to your computer. Each monitor, or head, will
  have its own frame, and you can move between heads using the normal
  frame movement commands.

  If you’re not using Xinerama, you’ll have multiple screens, with one
  head per screen. That means that you’ll move between heads using
  screen movement commands (`snext’, `sprev’, and `sother’) rather than
  frame movement commands.


Heads
─────

  A head represents a physical monitor connected to the computer. As
  mentioned above, how this plays out depends on whether you’re using
  Xinerama.


Groups
──────

  A group is usually referred to as a “desktop” or “workspace” in other
  window managers. StumpWM starts with a single group, called “Default”.
  Each group has its own configuration of frames and windows that is
  separate from and independent of other groups. You can’t have
  different groups display in different monitors: when you switch
  groups, all monitors switch to that group.

  Each group contains an ordered list of frames.


Floating Groups
───────────────

  [I don’t know enough about what floating groups are or how they work]


Frames
──────

  Frames are the boxes within which windows are displayed. StumpWM
  starts with a single frame per head, meaning that each monitor shows a
  single window, full screen. If you want to see two or more windows
  side-by-side, you can “split” this frame.

  Frames live within a “frame tree”. As you split frames, each new frame
  becomes a child of the frame it was split from. Practically speaking,
  this makes no difference, unless you use the `sibling’ command, which
  will move to the frame from which the current frame was created. [in
  which case, it should probably be called the `parent’ command, no?]

  Each frame has its own ordered list of windows, only one of which is
  visible at time.


Windows
───────

  Windows are created by programs to display their output. Each window
  can only belong to a single frame.


Trays and the Mode Line
───────────────────────

  [what is a tray? how does the mode line relate to frames? mention the
  new stumptray.lisp in contrib?]


Manipulating Frames and Windows
═══════════════════════════════

  By default, StumpWM starts with a single group, called “Default”, that
  contains one full-screen frame per head. You can split individual
  frames horizontally or vertically using the `hsplit’ and `vsplit’
  commands, bound to “C-t S” and “C-t s” by default. See the Frames and
  Windows sections of the manual for a complete listing of commands.

  Both frames and windows exist in ordered lists. In the following
  commands, the terms “next” and “previous” refer to relative positions
  in these lists.


Moving Between Frames
─────────────────────

  Once you have multiple frames, you can move between them in various
  ways:

  • `fnext’ (“C-t o” or “C-t TAB”) jumps to the next frame in the
    current group’s frame list.
  • `fother’ (“C-t M-TAB”) jumps to the last frame that had focus.
  • `fselect’ (“C-t f”) displays numbers on each visible frame: hit a
    number key to move to that frame.
  • `move-focus’ (“C-t <arrow key>”) focus the frame in the direction of
    the arrow key pressed.
  • `sibling’ (unbound by default) focus the frame from which the
    current frame was split.


Manipulating Windows
────────────────────

  Some commands change which window is currently focused, some move
  windows between frames, and some may do both at once.

  There are two general ways to move focus between windows: either
  between windows belonging to the current frame, or between all windows
  within the current group. Within a single frame:

  • `next-in-frame’ (“C-t C-M-n”) focus the next window in the current
    frame’s list of windows.
  • `prev-in-frame’ (“C-t C-M-p”) focus the previous window in the
    current frame’s list of windows.
  • `other-in-frame’ (“C-t M-t”) focus the most recently focused window
    in the current frame’s list of windows.
  • `frame-windowlist’ (unbound by default) display a menu of windows in
    the currently-focused frame, and allow the user to choose one.
    Alternately, the command `frame-windows’ will simply display the
    list of window names, with no menu choice available.

  Within the current group, the following commands will go straight to
  the specified window. They will never move a window from its original
  frame, and so may result in focus switching frames.

  • `next’ (“C-t M-n”) focus the next window in the current group.
  • `prev’ (“C-t M-p”) focus the previous window in the current group.
  • `other’ or `other-window’ (unbound by default) focus the most
    recently focused window in the current group.
  • `next-urgent’ (“C-t C-u”) focus the next window that has marked
    itself “urgent”.
  • `select’ or `select-window’ (“C-t '”) prompt for the title of a
    window and focus it. Works with partial completion of the title.
  • `select-window-by-name’ (unbound by default) prompt for the title of
    a window and focus it. Requires the window title to be entered
    exactly.
  • `select-window-by-number’ (“C-t <number>”) choose a window by
    number.
  • `windowlist’ (“C-t "") display a menu of windows in the
    currently-focused group, and allow the user to choose one.

  The following commands always keep the current frame focused. If the
  selected window is not in the current frame, it will be pulled there
  from wherever it is (hence the “pull” naming scheme).
  • `pull’ or `pull-window-by-number’ (“C-t C-<number>”) pull the
    numbered window into the current frame.
  • `pull-hidden-next’ (“C-t n” or “C-t SPC”) pull the next currently
    undisplayed window in the window list into the current frame.
  • `pull-hidden-previous’ (“C-t p”) pull the previous currently
    undisplayed window in the window list into the current frame.
  • `pull-hidden-other’ (“C-t C-t”) pull the most recently focused,
    currently undisplayed window into the current frame.

  The following commands move the current window from one frame to
  another, bringing focus with them.
  • `move-window’ (“C-t M-<arrow>”) move the currently focused window in
    the direction indicated by the arrow key.
  • `exchange-direction’ (unbound by default) swap the currently focused
    window with the top window of the frame in the direction indicated.