IceWM for Debian
================

Introduction
------------

This is the Debian version of the Ice Window Manager. In particular, this is
the "fork edition" maintained by a group of volunteers started after the
original development has apparently ceased to exist.

To report obvious program bugs and feature requests, please visit
https://github.com/bbidulock/icewm/issues . To report Debian specific problems,
please use the reportbug utility.

Adding missing functionality:
----------------------------

 * Screensaver and display locking function:
   Install xscreensaver package!

 * Enabling Shutdown, Reboot and Suspend actions:
   I) Install systemd-sysv and policykit-1 and start using systemd
   or
   II)
   a) Install sudo
   b) Create a special user group:
      addgroup shutdown
   c) Add your user account to this group:
      adduser username shutdown
   d) Edit /etc/sudoers, add:

    Cmnd_Alias POWEROFF = /sbin/shutdown, /sbin/halt, /sbin/reboot, /sbin/poweroff, /usr/sbin/pm-suspend
    %shutdown   ALL = (root) NOPASSWD: POWEROFF

   e) Logout and login again


Configuration
-------------

IceWM is configured using several text files (mainly: preferences, keys,
toolbar, menu and winoptions).
These files can be placed under ~/.icewm/ (personal configuration) or
/etc/X11/icewm/ (system-wide configuration). A file under ~/.icewm/ will
override the corresponding file under /etc/X11/icewm/. 

Sample configuration files with comments are provided under
/usr/share/icewm/. Just copy the files there to ~/.icewm/ or
/etc/X11/icewm/ and edit as required. Note that many settings are
commented out in the sample files (using a leading #).

Autostart of commands and extensions
------------------------------------

icewm-session (not icewm alone!) can run applications on startup in a safe
manner, i.e. when all X11 services are configured and icewmtray is ready to
accept/catch tray icons.

To use this functionality, add a shell script called "startup" to one of the
configuration folders (see above). It needs to be readable and executable the
by the user.

The Debian package provides an example in /usr/share/doc/icewm-common/examples/
that can be copied a config directory (see above). It also contains an example
of execution of all autorun files installed by XDG aware packages.

There is also a "shutdown" script which is processed in a similar way when
icewm-session terminates icewm.

General startup hints:
---------------------

With version 1.2.13 and higher, the handling of startup and restart
scripts has moved to the icewm-session (...-lite, ...-experimental)
program. Use this command in your .xsession resp. .xinitrc file to 
restore the normal behavior. This program also cares about automatic
restart of IceWM on crashes.

IceWM use without icewm-session is still possible but requires to run
icewm, icewmbg, icewmtray and other tools in the correct order to get
the optional features (see IceWM manual for details).

Solving font selection and size problems
----------------------------------------

There are at least three factors that modify the size of the fonts:

 - the X resources settings that you can check with "xrdb -query". If
   set, it is called Xft.dpi and can have a float value, something
   between 50 and 200 dpi, depending on your monitor. See also check
   ~/.Xresources file and use "xrdb -merge < .Xresources" to apply changes.

 - the DPI settings that the X server suggests to the applications. You
   can check it with xdpyinfo. There are different ways to set this value, it
   be made through xorg.conf file or the command line options of the X server,
   which can be set on different places where X server is started from (for
   example /etc/X11/xinit/xserverrc for startx resp. xinit,
   /etc/X11/xdm/Xservers, other places for other display managers)

 - the DPI setting (again, see above) with runtime manipulation via XRANDR
   extension. You can use xrandr command with --dpi or -fbmm options to tune
   that (see manpage). However, xrandr command call can be hardly used in the
   startup script because it's not guaranteed that it will be applied before
   icewm starts.

 - The fontconfig braindamage factor, producing all kinds of font
   problems for different people, including missing chars or huge fonts.
   Unfortunately an inpredictable value.

PS: and the easiest way to set font sizes is using the fontconfig
specification, as shown in the file
/usr/share/doc/icewm-common/examples/preferences.fonts .

Another issue is dealing with fonts that don't provide the required range of
Unicode characters. This repeatedly hits users of Asian encodings trying to
display special European characters in window titles. Often this can be solved
by using Xft fonts with a list of alternative fonts, comma-separated. E.g.:

  QuickSwitchFontNameXft="sans-serif,Bitstream Vera Sans"
  NormalTaskBarFontNameXft="sans-serif,Bitstream Vera Sans"
  ActiveTaskBarFontNameXft="sans-serif,Bitstream Vera Sans"
  TitleFontNameXft="sans-serif,Bitstream Vera Sans"

Localization hints:
------------------

Please make sure that IceWM (or icewm-session) is started with the
correct locale if you wish the non-ascii character to be displayed
correctly. If the system-wide locale setting does not match the
preference of the user or simply does not exist, you must set at least
LC_CTYPE to the proper character set description in the environment that
actually starts IceWM. Setting LANG or LC_CTYPE somewhere in .bashrc is
usually NOT SUFFICIENT because .bashrc file is only executed for interactive
shells. If icewm is started via .xsession (or .xinitrc) file then this
needs to be configured there (see example of an .xsession file below).
To check the locale actually used by IceWM open the About dialog from
taskbar's context menu (right-click in empty taskbar).

To enable translated menus, follow these instructions:

 - edit /etc/menu-methods/menu.h
 - locate the line with LOCALE and uncomment it
 - run the update-menus program under the needed locale setting

If you wish to do this for a user with different locale settings, you
will need to run update-menus as user with appropriate locale setting.
And don't forget that the file ~/.icewm/programs will be created and
used by IceWM in the following sessions, but on package updates, the
general update-menus command (from root) won't update your personal
~/.icewm/programs. So make sure that you run update-menus when needed.

Example .xsession file:
---------------------

The icewm session can be started from graphical login manager which allow
selection of available session handlers. If selection is not available (xdm) or
for console start (startx), local ~/.xsession file can be created, with the
following contents:

#!/bin/sh

# locale setting needed for Germany, for example
LANG=de_DE.UTF-8
export LANG
exec /usr/bin/icewm-session

 -- Eduard Bloch <blade@debian.org>, Wed, 23 Sep 2015 20:59:07 +0200
