Re: [STUMP] additions to the info manual

[Eric Abrahamsen]

David Bjergaard <address@hidden> writes:

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

Cool, will do. I'll remove mentions of Xinerama. Is there some generic
term for the programs that do on-the-fly monitor addition/removal and
configuration?

I haven't used github pull requests before (and also need to format the
patch as texinfo), so this might take a bit.

E

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