Re: [STUMP] additions to the info manual

[David Bjergaard]

Hi Eric, 

Since there hasn't been any new input, could you open a pull request for
the new additions?  I've been doing some more reading on multihead and
dynamic addition of external monitors, and I think its best if we remove
all the Xinerama from the docs.  To that end, could you make sure that
you're new additions don't include any references to it? Anyone still
using Xinerama knows it and doesn't need any of the pedagogy of the
manual, it will just confuse anyone who doesn't.

Cheers,

    Dave

Eric Abrahamsen <address@hidden> writes:

> 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.
>
>
> _______________________________________________
> Stumpwm-devel mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/stumpwm-devel