Re: [STUMP] additions to the info manual

[David Bjergaard]

Hi Eric,

Thanks for your efforts.  I've included my thoughts below where I can.
A few "meta"-comments: 
* It looks like this is the export of some markdown (org-mode?) could
  you either a. distribute the original source or b. send it as close to
  texinfo as possible (it will eventually have to be written as texinfo
  anyway)
* An X11 guru may comment, but I think we could update the docs to
  assume the out-of-the-box  configuration is Xinerama.  Then the
  discussion of "Multiple Screens" is more of a historical curiosity.

In either case, this is a great primer on using StumpWM.  I think it
should be in the manual, and it should be on the wiki with big blinking
arrows saying "New Users READ ME" :)

Cheers,

    Dave

Eric Abrahamsen <address@hidden> writes:

> 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?]
I think StumpWM detects that its Xinerama and reads information about
the heads.  All StumpWM needs to know is the size of the heads and their
relative orientation.  The "location" is mostly superfluous as far as
StumpWM is concerned. 

Commonly-used programs for specifying this (a list from 'apt-cache
search randr'):
+ arandr - Simple visual front end for XRandR
+ kde-workspace-randr - randr tools from kde-workspace
+ lxrandr - LXDE monitor configuration tool
+ resapplet - A small applet to change your screen resolution
I think there was one called grandr, but lxrandr is returned in its
place, it may be called something else in another distro.  
>
>   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.
>
I suspect (though can't prove) that most "modern" distros handle
multiple monitors via Xinerama, so those which aren't are probably in a
monitor nowadays.  I also suspect that multiple monitors handled by (say
nvidia-settings) "external" utilities are actually implementing
Xinerama, or at least following that protocol as far as StumpWM is
concerned. 
>
> 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]
Floating groups are similar to regular groups except that the windows on
assigned to that group "float" like most traditional window managers.
Float support is rather primitive and allows windows to be moved around
by clicking anywhere in the title area.  Windows can be re-sized by right
clicking in the title area.  

I don't know if its possible to focus or "raise" windows.  Some commands
are not available in a tiled group (such as C-n or C-p) .
>
>
> 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.
I might write "only one window is visible at a time." otherwise its
ambiguous as to whether or not you're talking about frames or windows.
>
>
> Windows
> ───────
>
>   Windows are created by programs to display their output. Each window
>   can only belong to a single frame.
I'm not so sure this is exactly clear.  You can have multiple windows
"stacked in a frame" and cycle through them with C-p or C-n
(pull-hidden-*).  It is true that a frame can contain one of
either subframes or a window.
>
>
> Trays and the Mode Line
> ───────────────────────
>
>   [what is a tray? how does the mode line relate to frames? mention the
>   new stumptray.lisp in contrib?]
A System Tray can refer to either a panel or a notification area (in
linux it is usually a notification area). A notification area is an
region of the desktop that follows certain protocols allowing programs
to "dock" themselves using xembed usually through. Applets that dock
here are nm-applet from gnome, or dropbox, skype, or other windows
applications that have linux ports. 

A taskbar, or panel is a region of the desktop that includes a list of
windows that the user can interact with by clicking (I'm paraphrasing
the freedesktop standard here).  

The modeline is a StumpWM concept borrowed from emacs, is a user
configurable string that can provide information about the current state
of the computer (including which group and what windows are currently
available on the current screen).  Many modules in contrib expand the
information that can be displayed in the modeline.  
>
>
> 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.
>
You may want to mention here that StumpWM is heavily inspired by Screen
and Emacs.  This will orient users who have had experience with those
programs, as well as encourage users to explore those programs as well
since they handle these concepts in a very similar way.
>
> 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.
This is as good as any place to plug this: I plan on adding
exchange-direction as "C-t x" and making it intelligent to guess which
two you wanted exchanged.  "C-t X" will prompt for a direction.  I also
want to change `move-window` to utilize a "minor-mode" style movement
that is activated with "C-t C-m <arrow keys>" and then deactivated with
the control key is released.
>
>
> _______________________________________________
> Stumpwm-devel mailing list
> address@hidden
> https://lists.nongnu.org/mailman/listinfo/stumpwm-devel