Re: [STUMP] additions to the info manual

[Eric Abrahamsen]

Eric Abrahamsen <address@hidden> writes:

> Thanks for all the comments, and I'm glad this seems welcome! I did
> indeed write it in org-mode, because that seemed easiest as a first
> step, but I certainly intend to send a proper texinfo patch when we're
> done. Org will export both to texinfo, and to HTML (for use on the
> wiki). I'll send along the org source as well, for good measure.
>
> I've put some comments on your comments below. I guess I'll give it a
> couple of days to see if anyone else wants to make changes, then send
> along another version.

Okay, here's what I think could be the final version. I rearranged some
things (merged the screens and heads together), and added some stuff.
Right now the only outstanding question is how the frame tree actually works...

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

Screens and Heads
─────────────────

  A screen is an Xlib concept representing a section of video memory
  onto which physical monitors, called “heads”, are mapped. A screen can
  be thought of as an abstract rectangle containing all the heads
  arranged in a particular layout.

  With most modern systems, you’ll only have a single screen no matter
  how many heads are connected to your computer. Each head will have its
  own frame, and you can move between heads using the normal frame
  movement commands.

  The layout of the heads within the screen can be specified in one of
  two ways: either at startup using your system’s Xorg configuration
  files, or on the fly using tools like XRandR or Xinerama. If the
  computer is booted with multiple monitors attached, but without
  specifying a layout for them, they will all show identical output.

  StumpWM will attempt to detect the layout of the heads once at
  startup, or any time a RandR command is issued.

  In rarer setups you may 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.


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
───────────────

  Within a floating group, windows behave more like they do in
  traditional window managers: rather than being arranged into frames,
  they each have their own box, which can be freely resized and
  repositioned, and allowed to overlap. Each window is has a thicker
  border at the top. Left click in this border and drag to move the
  window, or right click and drag to resize it.

  Most of the window-switching commands listed below do not function in
  a floating group. You’re restricted to `other’, the `select-window-*’
  commands, and `windowlist’.


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 windows side-by-side,
  you can “split” this frame in two, either vertically or horizontally.
  These frames can be further split, creating nested boxes.

  Technically speaking, frames live within a “frame tree”. When you
  split a frame, the command actually creates /two/ new frames
  side-by-side within the original parent frame. This makes no practical
  difference, unless you use the `sibling’ command, which will move to
  the other child frame within the parent frame. [Is this paragraph even
  correct? I tested it by splitting a head into left-and-right frames,
  then splitting each of those frames top-and-bottom. Calling `sibling’
  in any of the four frames moved to the top left frame, ie the
  “original” one. On the right-hand side, at least, I would have
  expected `sibling’ to move between top and bottom.]

  Within this frame tree model, all frames either contain other frames,
  or windows. The command `fclear’ will hide all a frame’s windows and
  show the background.


Windows
───────

  Windows are created by programs to display their output. They take the
  shape of the frame in which they are created. The windows within a
  frame are ordered by how recently that window was focused. Only the
  top window in the stack is visible.


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

  Many users choose to sacrifice a little screen real-estate to display
  some generally useful information: the current time and date, wireless
  network connections, the names of open windows, etc. StumpWM allows
  you to display this information in a bar across either the top or the
  bottom of the screen. There are two ways to do this: using external
  programs called system trays, or using StumpWM’s own mode line.

  System trays are a special kind of X window. They advertise to running
  programs that they are available for embedding icons or notifications
  from those programs. They often also display clickable icons for each
  open window. Common tray programs include the GNOME panel or KDE’s
  kicker, or simpler programs such as stalonetray. Simply starting one
  of these programs is usually enough for StumpWM to detect it, place it
  correctly, and allow it to function normally.

  The mode line, a concept borrowed from Emacs, is a built-in part of
  StumpWM. It is essentially a string of text that can include a variety
  of information about your current session, including the names of
  current groups and windows. Several contrib modules provide for
  different types of information. See The Mode Line (and the contrib
  directory) for more.


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

  Frames and windows are concepts borrowed from Emacs and the GNU Screen
  program, and should be familiar to users of those programs. Others may
  find the terms a little confusing. In other window managers, a
  “window” usually refers to a bounded box on the screen, showing output
  from a single program. StumpWM splits this into two concepts: the
  “frame” is the bounded box, the “window” is the visible output of a
  program.

  One frame can contain many windows. As new windows are created, they
  appear at the top of the window-stack of the current frame. This is
  also a little different from other tiling window managers, many of
  which automatically create new frames for new windows.

  Both frames and windows are ordered by when they were last focused. In
  the following commands and documentation, the terms “next” and
  “previous” refer to this order, and “other” refers to the
  most-recently focused object. Calling “other” commands multiple times
  will bounce back and forth between the two most recent objects.

  By default, StumpWM starts with a single group, called “Default”,
  which 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. When a
  frame is split, the next-most-recently-focused window is pulled into
  the new frame. See the Frames and Windows sections of the manual for a
  complete listing of commands.


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) prompt for a direction,
    then swap the currently focused window with the top window of the
    frame in that direction.