@c -*- texinfo -*- 

@chapter User Documentation for Sawfish 1.5.0

Sorry, this document still needs much expansion.

Todo: describe gtk-style, which is installed, for example, at
@file{/usr/lib/sawfish/1.6.4/x86_64-pc-linux-gnu/gtk-style}

@enumerate

@item Introduction

If you know the basics of X11, you can skip to the next section.

@enumerate
@item What is that X11 thing?

In the 80s at MIT a graphical system for computers was developed. Some
of the idea behind it was to be multiplattform, have network
transparency and provide the means to have graphics, but not enforce
rules like how things should look or behave. The solution found was
creating a protocol (think ``language'') that defined how programs and
computers should communicate to each other to do request and provide
the results.

As time passed, different versions of the protocol were done, up to
the 11th. Of this 11th version there have been multiple releases, so
you can see references to X11R5; the latest being X11R7. Other names
you can see when referring to the protocol or to the systems that
implements it are the full name, X Window System (singular window, not
windows), or even just the X letter alone.

On other fronts, the global result of X11 and the applications that
run on it is like many other graphics systems for computers: you have
pointers controlled by devices such as mouses or tablets, keyboards to
input text, monitors to show things such as windows, icons, menus. And
you can probably have multiple items of each, even across different
computers. The X11 flexibility obtained by defining the language but
not the rules have allowed it to survive for to decades, and at the
same time evolve to include new concepts.

@item What is a Window Manager?

As we said, X11 provides the means to have graphics, but leaves to
others tasks such as how things have to look or behave. A Window
Manager (WM for short) is a special type of program that runs on X11
and which main tasks are organizing windows of other programs.

If you ever run X11 without a WM, programs will show their windows
without any decoration and placement on the screen would leave a lot
to be desired. You probably will be unable to move windows, for
example.

Window Managers, such as Sawfish, take care of all that, provide
decorations to windows (title bars, side and bottom frame, etc),
decide where to place them, in which order they should overlap, when
they should move or resize, what window will receive your keypresses,
etc.

@item Why Sawfish?

Sawfish is a very fast and extensible Window Manager.

Powerful key bindings: virtually every function can be bound to keys
or mouse buttons or combinations of them. If you want, you can run
without touching the mouse for a long time.

Hooks: many events like moving or changing workspace (more on this
later) can trigger extra functions to make the behavior fit your
needs. So when you change workspace, you can trigger a wallpaper
change by putting the right function call in the hook that is
triggered by change workspace action.

Window matching: for each new window Sawfish can assign different
behaviours as they are created. For example you can set some windows
to always appear like if they were glued to your monitor, above any
other window, like in the case of taskbars.

Flexible theming: Sawfish allows very different themes to be created
and a variety is already available. You can even run different themes
at the same time.
http://sawfish.wikia.com/wiki/Themes

Extensibility: Sawfish can load 3rd party scripts easily and a whole
bunch is just waiting to be discovered by you.
http://sawfish.wikia.com/wiki/Scripts

@item What are those Mouse Button 2?

You probably know about Shift or Control keys, that you can press at
the same time than others to get different results, like Shift and
``a'' to get uppercase A. X11 inherits some extra modifier keys from
past computers that had really special keyboards like the Space Cadet
keyboard. In modern keyboards unused keys can emit these key symbols,
or even multiple symbols from the same key.

The available extra key symbols you will see are Meta (pretty common
to be in Alt key... probably emitting Alt symbol at the same time) and
Hyper & Super (both typically assigned to the keys with logos). Hyper
and Meta can be shortened to H and M, as well as C for Control, A for
Alt and S for Shift.

Mouse buttons in X11 are also named, allowing different hardware to be
used easily as applications only have to support and document things
like Mouse Button number 1, no matter if the mouse is configured for
right hand, left hand... or is a tablet with a pen. Sometimes you will
see the names shortened to MB1, MB2, etc. The typical configuration
for a right handed mouse is MB1 left button, MB2 center button or
press wheel, MB3 rigth button, with wheel rotation creating virtual
presses and releases of MB4 and MB5 with every fraction of turn.

For further reading, please refer to the documentation of your X
system, specially xev and xmodmap programs.

@end enumerate
@c end of Introduction


@item Basic Window Managing Functions

@enumerate
@item Window-Menu

The window-menu is a menu which offers you an easy way to modify the
current window.

You can access it by left-click on the menu button, or middle-click on
the close or iconify button

@item Iconify

To iconify a window means to display a small icon, or task-list entry
representing the window, instead of displaying the whole one, You may
know that feature as "Minimize", which is a different term, having the
same meaning.

You can iconify a window by left-click on the iconify button.

@item Uniconify

To uniconify a window means to restore a previously iconified window,
to it's prior state.

You can uniconify a window by left-click on it's dock-icon or task-list entry.

@item Maximize

To maximize a window means to make it as big as possible, but without
overlapping panel or dock windows, which may be there.

You can maximize a window by left-click on the maximize button.

@item Unmaximize

To unmaximize a window means to restore it to the size it got before
it has been maximized (therefore only maximized windows can be
unmaximized).

You can unmaximize a window by left-click on the maximize button, on a
maximized window.

@item Delete Window

To delete a window simply means to close it, any transient (sub-windows, belonging to that main-window) will be deleted, too.

You can delete a window by left-click on the close button.

@item Shade Window

To shade a window means to only display the titlebar.

You can shade a window by double-left-click on the titlebar or left-click on the shade button

@item Unshade Window

To unshade a window means to restore a previously shaded window.

You can unshade a window by double-left-click on the titlebar or
left-click on the shade button, of a shaded window.

@item Raise Window

To raise a window means to put it above other windows.

To raise a window press ALT + UP (Arrow Up Key).

@item Lower Window

To lower a window means to put it below other windows.

To lower a window press ALT + DOWN (Arrow Down Key).

@item Cycle Windows

To cycle trough windows simply means that you'll look trough all
windows and as you stop the currently cycled window will be the new
active window.

You can cycle trough windows by keeping ALT pressed and press TAB one
time for each window to cycle.

There's also the possibility to cycle backwards, but that is not bound
to any keybinding by default.

@end enumerate
@c end of Basics

@item Organizing Windows

Sawfish offers multiple means to organize windows, most can work at
the same time than others, as you need.

@enumerate
@item Workspaces

Workspaces are virtual surfaces where to place windows. They are also
called (Virtual) Desktops in other WMs. You must have at least one.

Windows can be in one or more workspaces at the same time, with
different positions in each.

@c navigate, add, merge, naming, etc

@item Viewports

Workspaces can be bigger than your monitor, here is where the concept
of Viewport comes into play, it gives you a view into this bigger
space. All Workspaces must share the same size, though, like if they
were cut all at once.

You can move the Viewport around, and you will see how windows that go
out of the right side of the screen will appear from the left, if you
moved your viewport to the right. It is a continuous surface. The
scrolling can be in full monitor increments or partial.

@c navigate, configure, etc

@item Layers

Sometimes you want to keep some windows above all other windows. Or
maybe below them. Sawfish does this by means of Layers. A window in a
layer will always appear in a given depth, above lower valued layers,
but below.

Default level is 0, windows below are in negative levels, and windows
above are in positive levels. Many WMs support just three layers,
Sawfish by default assigns them the numbers -2, 0 and 2.

@c change, configure matchers, etc

@item Tabs

@c to be written once that settles

@end enumerate
@c end of Organization
@end enumerate
@c end of global
