Re: [STUMP] additions to the info manual

[Eric Abrahamsen]

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.

Next up: the manual section on writing commands!

E

David Bjergaard <address@hidden> writes:

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

Actually I think "relative orientation" is what I meant by "location" --
just the question of which monitor is to the left and which to the
right, etc.

I've done a bit more reading, and it looks like, with no specific
configuration, extra monitors will simply mirror the primary monitor.
That's true from boot to console to X to stumpwm. Multiple monitors can
be arranged relative to one another either on the fly with XRandR and
related programs, or else statically in an xorg config file. Stump will
handle either.

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

Between your and David's comments, it seems clear we should assume
Xinerama or something equivalent, and just mention the
one-head-per-screen arrangement as a secondary possibility.

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

Okay, I'll play with this a little more. I remember I tried this once
and couldn't get anything to resize at all.
>>
>>
>> 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.

Cool.

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

Yes, I'll clarify this. About subframes and the frame tree: I debated
whether to go into it here or not. As far as I can tell, from a user's
point of view the tree structure doesn't make a bit of difference. Users
are simply going to treat frames as an ordered stack. Wouldn't it be
better to skip the tree here, and leave it for the dedicated Frames
section?

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

Okay, that helps. I read up on specifications for system trays as well,
which was interesting. My understanding is that stump's mode line is
totally unrelated to system trays as they are defined in X11 terms.
Maybe I'll make two separate sections.

If anyone has any practical tips on using system trays with stump,
please chime in!
  
>>
>>
>> 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.

Good point.

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

Very cool! One of the first things I tried to hack in stump was
"exchange-direction", and quickly got in over my head. It always annoyed
me that it prompted for a direction even when there was only one
possibility.

This isn't the place for feature requests, but while you're at it would
you consider a `rotate-frames' command, that rotated entire frames (not
just their visible windows) through the current frame tree geometry?

Oooh... also an `exchange-split' which finds the split between the
current frame and its sibling, and toggles that split between horizontal
and vertical.

Okay, I'm done.