Ubuntu Manpage: Eterm - the Enlightened terminal emulator for the X Window System

NAME

       Eterm - the Enlightened terminal emulator for the X Window System

SYNOPSIS

       Eterm [options]

DESCRIPTION

       Eterm  —  version  0.9.6  —  is  a  color  vt102 terminal emulator intended as an xterm(1)
       replacement. It is designed with a Freedom of Choice philosophy, leaving  as  much  power,
       flexibility,  and  freedom  as  possible in the hands of the user.  It is designed to look
       good and work well, but takes a feature-rich  approach  rather  than  one  of  minimalism.
       Eterm uses Imlib for advanced graphic abilities.  See below for details.

OPTIONS

The Eterm options are listed below. In keeping with the freedom-of-choice philosophy,
options may be eliminated or default values chosen at compile-time, so options and
defaults listed may not accurately reflect the version installed on your system.

Options that do not take a parameter (besides -h and --help) are boolean. If you use the
POSIX (short) option, you are forcing the parameter to "true". If you use the long
option, you can use any of the accepted boolean values, which are "yes", "on", "1", and
"true" to turn the option on, or "no", "off", "0", or "false" to turn the option off. The
same is true for boolean values in the configuration file.

-t theme, --theme theme
Load specified theme. Consult the FAQ for more details on what constitutes an
Eterm theme.

-X conffile, --config-file conffile
Use an alternative user config file name. Otherwise Eterm uses the default, which
is user.cfg. The theme config file is always theme.cfg.

-d displayname, --display displayname
Attempt to open a window on the named X display displayname. In the absence of
this option, the display specified by the DISPLAY environment variable is used.

--debug level
Show debugging output. level is an integer between 0 and 5 which determines how
verbose the debugging output is.

--install
Tells Eterm to install its own colormap rather than using the default one.

-h, --help
Print out a message describing available options.

--version
Print Eterm version and compile-time configuration.

-r, --reverse-video
Reverse video, swaps the foreground and background colors.

-b color, --background-color color
Set color as the background color. NOTE: this will actually be the foreground
color if reverse video is also selected.

-f color, --foreground-color color
Set color as the foreground (text) color. NOTE: this will actually be the
background color if reverse video is also selected.

--color0 color

...

--color15 color
Use color as color X.

--colorBD color
Use color as the bold color.

--colorUL color
Use color as the underline color.

--pointer-color color
Use color as the pointer color.

-c color, --cursor-color color
Use color as the cursor color.

--cursor-text-color color
Use color as the cursor text color.

-g geom, --geometry geom
Window geometry as Width x Height+X coord+Y coord, i.e 100x200+0+100

-i,--iconic
Start in iconified state (only if the window manager supports iconification).

-n name, --name name
Sets name of current instance to name. This will affect the icon title and the
window title string unless they are otherwise explicitly set.

-T title, --title title
Sets window's title text to title.

--icon-name text
Sets the icon title text to text.

-B type, --scrollbar-type type
Specifies the type scrollbar style should be used. type can be any of motif,
xterm, or next.

--scrollbar-width width
Set the width of the scrollbar, in pixels, to width. Eterm does not impose any
restrictions on this value, but it should be reasonable.

-D desktop, --desktop desktop
Starts the Eterm on the specified desktop. desktop should be an integer between 0
and your highest-numbered desktop. NOTE: You must have a GNOME-compliant window
manager for this feature to work. Please see http://www.gnome.org/devel/gnomewm/
for more information on the _WIN_WORKSPACE property and how to support it.

--line-space num
Size of the extra gap, in pixels, to provide between lines in the terminal window.

--bold-font font
Sets the bold text font to font.

-F font, --font font
Sets the normal text font to font.

--default-font-index num
Specifies the index of the default (normal) text font.

--font1 font

...

--font4 font
Sets the font at the specified index (1-4) to font.

--proportional
Specifies that the font in use is proportional and requests standard deviation-
based character cell spacing. Terminals must use fixed-width character cells to
maintain proper columnal alignment, even when proportionally-spaced fonts are in
use. Some proportionally-spaced fonts vary greatly between the minimum and maximum
character widths. This option chooses a character cell size which is up to two
standard deviations above the average character width but will not exceed the
maximum width of the largest glyph. Note that characters larger than the chosen
cell width will overwrite (or be overwritten by) other characters and may tend to
leave pixel droppings. This behavior is an expected side-effect of an imperfect
scenario. If you object to this behavior, do not use this option.

--font-fx effects
Specifies the effects to apply to the terminal window font. The value of effects
is a single string containing a series of corner/color pairs. These pairs define
toward which corner a drop shadow of each character should be made, and what color
that shadow will be. The corner is specified first using the following keywords:
top_left or tl, top_right or tr, bottom_left or bl, and bottom_right or br. Each
corner specifier is then followed by a color.

There are also several shortcuts for doing common effects. You can get a single-
color outline by using the keyword outline followed by a color. A single-color
drop shadow is also available using the keyword shadow followed by an optional
corner specifier (bottom_right being the default) and a color. For a 3-D embossed
look, use emboss dark_color light_color. The opposite effect, a carved-out look,
can be obtained with carved dark_color light_color. (Of course, with those last
two, the 3-D look will only work if you choose the light and dark colors wisely.)

Finally, for no font effects at all, simply specify the keyword none.

The default value is bottom_right black which yields a black drop shadow, greatly
improving the visibility of lightly-colored fonts on top of light spots in a
background image. Note that font effects are not active in solid color mode.

-P pic, --background-pixmap pic
Use pic as the background image. pic can be in any format that Imlib understands.
Currently this means just about anything, including JPG, PNG, GIF, TIFF, PPM, etc.
The image is tiled by default. To specify alternate geometry, follow the filename
with an @ sign and the geometry string. Image geometry is specified as
@wxh+x+y:ops where w and h are the horizontal/vertical scaling percentages, x and y
are the horizontal/vertical alignment percentages, and ops is a colon-delimited
list of operations: tiled (to tile the image), propscaled (for proportional
scaling). Note that these operations can be combined for various effects.

-I pic, --icon pic
Sets the icon pixmap file to pic. Works similarly to the -P option above.

--up-arrow-pixmap pic
As above, except the scrollbar's up-arrow is set.

--down-arrow-pixmap pic
As above, except the scrollbar's down-arrow is set.

--trough-pixmap pic
As above, except the scrollbar's background (trough) is set.

--anchor-pixmap pic
As above, except the scrollbar's anchor image is set.

--menu-pixmap pic
As above, except the menu background image is set.

-O, --trans
This gives a pseudo-transparent Eterm. The image is taken directly from the root
window, so any requests for changing the pixmap are ignored. If you do not use
Enlightenment (http://www.enlightenment.org/) as your window manager (or another
compliant window manager...I have been told that WindowMaker works also), you will
need to use the Esetroot program (found in the utils/ directory) to set your root
background image.

-0, --itrans
Activate the immotile transparency optimization for transparent Eterm windows.
Note that this does NOT activate transparency; you must still include the -O or
--trans option. This option should be used on transparent windows which are shaded
or tinted and which do not move around on the desktop much. See the Mon Mar 6
21:11:13 PST 2000 ChangeLog entry for a more detailed explanation.

--viewport-mode
This activates a special Eterm mode which is hard to describe in words. Basically,
imagine the effect you get with pseudo-transparency, where the desktop background
moves through the Eterm window as you move the window, so that it always aligns
with the desktop image. Now, imagine the same effect, but the image used isn't the
desktop image but any pixmap you choose. The image is scaled or tiled up to the
size of the desktop, and dragging the Eterm around the screen reveals different
portions of the image as you move, much like a small viewport window in a ship or
submarine does. The effect is especially keen if you open several Eterms in this
mode with the same image.

--shade percentage
Shade the background image/transparency by a specified percentage.

--tint mask

--tint color
Tints the background pixmap (either an image file or the transparent portion can be
shaded). The mask is an integer, usually specified in hexadecimal in the form
0xRRGGBB, where RR, GG, and BB are hexadecimal numbers between 00 and ff (0 and 255
decimal) which represent the brightness of the image's red, green, and blue values,
respectively. A value of 00 will mask that color out entirely, while a value of ff
will not change that color at all.

You may also specify an X color such as grey75 or MidnightBlue or #babb7f instead
of a mask.

--cmod brightness [ contrast [ gamma ] ]
Specifies a color modifier to apply to the image overall. Each of the three values
is a number greater than or equal to 0. The numbers can be specified as decimal,
octal (if preceded by "0"), or hexadecimal (if preceded by "0x"). A value of 256
(0x100) represents 100%, or "leave that value unchanged." 0 represents 0%, 512
(0x200) is 200%, etc. However, be aware that overflow can occur with excessively
high values. Only the brightness value is required for this option. Keep in mind,
though, that you must specify brightness with contrast, and both of these with
gamma.

--cmod-red brightness [ contrast [ gamma ] ]
Same as above, except that the modifier applies to the red values of the image.

--cmod-green brightness [ contrast [ gamma ] ]
Same as above, except that the modifier applies to the green values of the image.

--cmod-blue brightness [ contrast [ gamma ] ]
Same as above, except that the modifier applies to the blue values of the image.

-p newpath, --path newpath
Sets the pic search path. When the --background-pixmap or other pixmap options are
used, this path will be used to find the image.

--cache size
Specify the size in bytes for the Imlib2 cache.

-N list, --anim list
Specifies an animation list to be use in cycling the background pixmap. The list
consists of two or more words. The first word defines the delay, in seconds,
between updates of the background. This should be set to a reasonable value to
insure that Eterm doesn't spend all its time rendering backgrounds. All remaining
words specify background images and have the same syntax as the -P option above,
including the optional geometry string.

-M font, --mfont font
Sets the normal multibyte text font to font.

--mfont1 font

...

--mfont4 font
Sets multibyte font X to font.

--mencoding encoding
Sets multichar encoding mode (eucj or sjis or euckr)

--input-method method
Sets XIM input method

--preedit-type type
Sets XIM preedit type

-l, --login-shell
Makes the new shell a login shell.

-s, --scrollbar
Enables the scrollbar. (Default)

-u, --utmp-logging
Tries to enable proper utmp logging. For this to work, Eterm probably needs to run
setuid or setgid, usually setuid root.

-v, --visual-bell
Enables the "visual bell". Means the window will flash or blink rather than beep.

-H, --home-on-output
Jump to bottom on output.

--home-on-input
Jump to bottom on input.

-q, --no-input
Keeps Eterm from accepting keyboard input, and keeps the window manager from
focusing it. Useful for log tailers and such.

--scrollbar-right
Display scrollbar on the right hand side.

--scrollbar-floating
Display the scrollbar without a trough.

--scrollbar-popup
Display the scrollbar only when the Eterm window is focused.

-x, --borderless
This option forces Eterm to have no borders.

-S, --sticky
Start Eterm as a sticky window (shows on all desktops)

-m, --map-alert
Un-iconify on beep.

-8, --meta8
Causes the Meta key to set the 8th bit in the char.

--double-buffer
Rather than drawing text directly onto the window, this option causes Eterm to
allocate an additional pixmap the size of the terminal window into which the
background *and* the text are rendered. This pixmap is then set as the window
background. Double-buffering uses additional memory in the X server, but it allows
Eterm to ignore expose events so redraws are faster.

--no-cursor
Disables the text cursor.

--pause
After the child process terminates, Eterm will wait for a keypress before exiting.

--xterm-select
Duplicate's xterm's treatment of cutchars. The only real difference is what
happens when you double click on a single cutchar between two words. If this
option is on, only that single character gets selected. If it is off, that
character is selected along with the two words. The latter behavior is useful for
double-clicking on the space between someone's first and last names, or the @ sign
in an e-mail address, etc.

--select-line
If activated, this option causes a triple click to select the entire line from
beginning to end. If off, a triple-click selects just from the current word to the
end of the line.

--select-trailing-spaces
Determines whether or not trailing spaces in a selection are maintained (on) or
discarded (off).

--report-as-keysyms
Reports certain keystrokes as keysyms and modifiers rather than escape sequences.
NOTE: This option is intended for use only with programs that support this special
Eterm mode. Do not enable it unless you are executing a program which uses this
mode.

--buttonbar
Toggle the display of all buttonbars.

--resize-gravity
If true, Eterm will automatically detect the nearest corner, and font-change
resizes will cause the Eterm window to gravitate toward that corner.

--overstrike-bold
If true (default), Eterm will simulate a bold font by printing each character
twice, offsetting the second pass by one pixel. This makes the characters seem
thicker without the need for a special font. You may wish to disable this if you
use a specific color for bold.

--bold-brightens-foreground
If true (default), Eterm will use the "bold" ANSI color attribute to brighten the
foreground color by using the high-intensity colors (8 through 15) rather than the
low-intensity colors (0 through 7). Note that having a specific color selected for
bold will override this.

--blink-brightens-background
If true (default), Eterm will use the "blink" ANSI color attribute to brighten the
background color by using the high-intensity colors (8 through 15) rather than the
low-intensity colors (0 through 7).

--colors-suppress-bold
If true (default), any colored text (that is, any text not rendered using the
default foreground color) will not be given any other special treatment for bolding
(e.g., bold font or bold overstrike).

--big-font-key keysym
Specify a keysym to increase the font size. Default is Shift and the + key on the
keypad. Ctrl-> or Meta-> may also work (if you #define one of the hotkeys in
src/feature.h).

--small-font-key keysym
Specify a keysym to decrease the font size. Default is Shift and the - key on the
keypad. Ctrl-< or Meta-< may also work (if you #define one of the hotkeys in
src/feature.h).

--meta-mod num
Specify which X modifier (1-5) to treat as the Meta key. See xmodmap(1) and the
output of xmodmap -pm for more details.

--alt-mod num
Same as --meta-mod, but for the Alt key.

--numlock-mod num
Same as --meta-mod, but for the NumLock key.

--greek-keyboard mode
Use Greek keyboard mapping (iso or ibm).

--app-keypad
Start Eterm in application keypad mode (as opposed to normal keypad mode).

--app-cursor
Start Eterm in application cursor key mode (as opposed to normal cursor key mode).

-L num, --save-lines num
Set the number of lines in the scrollback buffer to num.

-a size, --min-anchor-size size
Specifies the minimum size, in pixels high, of the scrollbar anchor. NOTE: This
causes abnormal scrolling behavior when combined with large scrollback buffers!

-w width, --border-width width
Set the window's border width to width. The border this controls is the gap
between the edge of the X window and the edge of the terminal window; this has
nothing to do with the window border's your window manager supplies.

--print-pipe pipe
The pipe for the PrintScreen function.

--cut-chars separators
The seperators for double-click selection.

--finished-title title
Specifies the string Eterm should add to its title bar if --pause is specified and
the child process completes.

--finished-text text
Same as above, but displays text in the terminal window.

--term-name TERM
Use TERM for the value $TERM.

--pipe-name pipe
Specifies a named pipe from which to display output. This is useful for systems
where syslog output goes to a named pipe, like /dev/xconsole on Debian.

-a line, --attribute line
This option is used to pass config file attributes on the command line. line
should be a single string, so you will almost certainly have to quote it. The
first word of line must be the context (see config file section below) which should
parse the rest of the line. So, for example, you could specify the foreground
color like so: -a 'color foreground blue'. Or you could add a binding: -a 'actions
bind anymod button1 to script exit'. Note that this option may only be used with
config file attributes that are not context-sensitive; i.e., menus and imageclasses
cannot be specified using this option.

-C, --console
Grab console messages. Depending on your system, Eterm may need to be setuid root
to do this.

-e command, --exec command
Execute command rather than a shell. Forces Eterm mode.

-U URL, --url URL
Pick up a "screen" session at URL rather than a local (-U "") one. URLs look like
so (screen://user@host.dom:port/screen_options), with all parts optional,
defaulting to "screen://current_user@localhost:22/-RDD". Forces Escreen mode,
overrides --exec. Note that only screen-options (see "man screen") are allowed; do
not pass a command (with or without arguments) here: to pass a command to the
screen-session, use screen [<options>] <command> [<args>] instead.

-Z lclport:fw:fwport,delay, --fw lclport:fw:fwport,delay
The URL given to -U is in an intranet behind firewall fw so we'll build an SSH-
tunnel to that firewall (to port 22/SSH, or fwport if given) from our local machine
(using any available port-number, or lclport if given). Then, after delay seconds
(or a sensible default if not given), we will try to open a screen session on the
host behind the firewall using ssh -p localport ... localhost screen cf. ssh -L

THEMES

Eterm is built on the philosophy of Freedom of Choice. Each user should be able to choose
the environment in which he or she wishes to exist, and the tools used should support
that. In accordance with that philosophy, Eterm is extremely configurable. Eterm
supports a concept called "themes," which should be familiar to users of Enlightenment,
icewm, or Microsoft Windows 95/98/NT. The general concept of a theme is a collection of
resources that change as many aspects of a programs look and feel as possible. For
example, an Enlightenment theme allows you to customize menus, window borders, desktops,
icons, iconbars, and everything else about how E looks and feels.

An Eterm theme consists of a primary configuration file, always called "theme.cfg",
residing in a directory bearing the same name as the theme. This directory must be a child
of one of the directories specified by CONFIG_SEARCH_PATH in src/feature.h. The theme may
also contain additional configuration files referenced by the primary theme.cfg file, as
well as pixmaps, menu files, documentation, etc., which are allowable as extensions to the
minimum requirement of an Eterm theme.

By convention and default, Eterm themes should be stored under
~/.Eterm/themes/<theme_name>/ or /usr/share/Eterm/themes/<theme_name>.

Eterm now supports the existence of a user configuration file as a suppliment to the theme
configuration file. The default name for this file is user.cfg, and it follows the exact
same syntax as any other configuration file. It is searched for using the same algorithm
used for the theme.cfg file, and any settings in the user.cfg will override any previous
values for those settings defined by the theme. Thus, it is recommended that any user.cfg
files not be complete config files, but rather only contain those values which the user
wishes to explicitly override.

NOTE: If you have a user.cfg file in the Eterm theme directory or in ~/.Eterm/, it will
override any previous settings, even if you are running a different theme. For example,
if you run the trans theme, but ~/.Eterm/themes/Eterm/user.cfg has a mode line which sets
the image mode to "image" rather than "trans," you will not get transparency. This is why
user.cfg files should be kept small and only override settings that you know you want to
enforce. If, on the other hand, you were running the trans theme and had a user.cfg file
in the trans theme (or in ~/.Eterm/themes/trans/), that user.cfg would be found before the
one in the Eterm theme.

Almost all command line options can be enabled/disabled in the theme's configuration file
(the default is /usr/share/Eterm/themes/Eterm/theme.cfg). The next section contains
details on the format and usage of the configuration file.

CONFIGURATION

Since Eterm 0.9.6 is based on the concept of themes, it is vital that you have a thorough
understanding of the previous section before taking on this one. The previous section and
this one were written by the same person who wrote the Eterm code which handles options,
config files, and themes, so it's probably the most authoritative documentation on the
subject you're going to find.

From here on out, I will assume you've read the above text and know how to change the
default value for the theme. It is highly recommended that you have a copy of the Eterm
theme config file that comes with Eterm handy while you read this documentation.

Okay, first the general idea. The theme.cfg file is composed of comments and non-
comments. Comments begin with a pound sign and continue to the end of the line. Lines of
whitespace are also ignored. The rest of the file is the config stuff, which is divided
into sections (called "contexts") and variables (called "attributes"). There are several
contexts which are listed below in sections. Each attribute must be inside a certain
context to be valid. For instance, while the "foreground" attribute is perfectly
acceptable in the color context, it would be rejected if found in, say, the toggles
context. This allows for better organization of the config file as well as for multiple
contexts to have attributes of the same name (like the scrollbar attributes in the color
and toggles section).

Each context must be enclosed in a begin...end pair that specifies the type of section.
The statement "begin toggles" starts the toggles context, and the next "end" statement
would terminate it. (You'll notice that some "end" statements have the context name after
them. This is for readability only; any text after the word "end" is ignored.)

The rest of this section will contain a step-by-step analysis of the config file,
including what can go in each section. Note that some attributes (and even entire
contexts) may not be available depending on what support was compiled into Eterm by the
person who built it.

MAGIC NUMBER

The first line of the config file must contain a "magic number" type line that lets
Eterm verify that it's reading an Eterm config file and not something else (like an
Enlightenment 0.13 and earlier config file). The line should look like this:

<Eterm-VERSION>

where VERSION is the Eterm version for which the config file is intended. For
example, config files written for Eterm 0.9 should have "<Eterm-0.9>" as their
first line, followed immediately by a newline.

COLOR CONTEXT

This context contains color specifications. With the exception of the terminal
colors 0-15, all colors should be either a valid color name or an RGB string as
outlined in the X11(7) man page.

foreground color
Use color for the foreground (text) color.

background color
Use color for the background color.

cursor color
Use color for the cursor color.

cursor_text color
Use color for the cursor text color.

pointer color
Use color for the mouse pointer color.

video { normal | reverse }
normal will not reverse the foreground and background colors. reverse (meaning
reverse video) will.

color num color
Set terminal color num (0-15) to the color name, string, or set of 3
decimal/hex/octal RGB values specified by color.

color { bd | ul } color
Set terminal bold (bd) or underline (ul) color to the color name, string, or
set of 3 decimal/hex/octal RGB values specified by color.

ATTRIBUTES CONTEXT

This context contains X11 attributes. Most of these are dependent upon the
cooperation of the window manager.

geometry geom
Use the geometry string geom to specify the startup geometry. geom should be in
the format WxH+X+Y where W is the width, H is the height, and +X and +Y are the
X and Y offsets. If the signs on X and Y are positive, the coordinates are
offsets (in pixels) from the left and top, respectively, of the screen. If the
signs are negative, the offsets are relative to the right and bottom of the
screen, respectively.

title title
Use title as the text in the title bar of the Eterm window.

name name
Use name as the resource name of the Eterm window.

iconname name
Use name as the icon name of the Eterm window icon.

desktop num
Start Eterm on desktop num. NOTE: This requires a GNOME-compliant Window
Manager. Please see http://www.gnome.org/devel/gnomewm/ for more information on
the _WIN_WORKSPACE property and how to support it.

scrollbar_type type
Use a scrollbar with the type style. type can be any of motif, xterm, or next.

scrollbar_width num
Use a scrollbar that is num pixels wide.

font num font
font bold font
Set the numth font, or the bold font, to font.

font default num
Specifies that the numth font should be considered the "default" font.

font proportional boolean
Specifies that the font in use is proportional and requests standard deviation-
based character cell spacing. Terminals must use fixed-width character cells to
maintain proper columnal alignment, even when proportionally-spaced fonts are in
use. Some proportionally-spaced fonts vary greatly between the minimum and
maximum character widths. This option chooses a character cell size which is up
to two standard deviations above the average character width but will not exceed
the maximum width of the largest glyph. Note that characters larger than the
chosen cell width will overwrite (or be overwritten by) other characters and may
tend to leave pixel droppings. This behavior is an expected side-effect of an
imperfect scenario. If you object to this behavior, do not use this option.

font fx effects
Specifies the effects to apply to the terminal window font. The value of
effects is a single string containing a series of corner/color pairs. These
pairs define toward which corner a drop shadow of each character should be made,
and what color that shadow will be. The corner is specified first using the
following keywords: top_left or tl, top_right or tr, bottom_left or bl, and
bottom_right or br. Each corner specifier is then followed by a color.

There are also several shortcuts for doing common effects. You can get a
single-color outline by using the keyword outline followed by a color. A
single-color drop shadow is also available using the keyword shadow followed by
an optional corner specifier (bottom_right being the default) and a color. For
a 3-D embossed look, use emboss dark_color light_color. The opposite effect, a
carved-out look, can be obtained with carved dark_color light_color. (Of
course, with those last two, the 3-D look will only work if you choose the light
and dark colors wisely.)

Finally, for no font effects at all, simply specify the keyword none.

The default value is bottom_right black which yields a black drop shadow,
greatly improving the visibility of lightly-colored fonts on top of light spots
in a background image. Note that font effects are not active in solid color
mode.

IMAGECLASSES CONTEXT

This context contains global image attributes. It also provides the parent context
for defining images via the "image" context.

icon filename
Use filename as the icon image for the Eterm window. filename can be an
absolute path, relative to the current theme, or relative to one of the
directories in the path attribute listed below.

cache num
Sets the Imlib2 cache size to num bytes. The default is 0.

path directory_list
Specifies a colon-delimited list of directories relative to which Eterm should
search for image and menu files. The syntax for directory_list is precisely the
same as that of the $PATH environment variable in UNIX shells.

anim interval images ...
Specifies an animation list to be use in cycling the background pixmap. The
interval defines the delay, in seconds, between updates of the background. This
should be set to a reasonable value to insure that Eterm doesn't spend all its
time rendering backgrounds. All the images specify background images and have
the same syntax as the -P option above, including the optional geometry string.

IMAGE CONTEXT

This context defines all the attributes of a particular image. There can be (and
usually are) several image contexts per theme, one for each class of image.

type class
Specifies the type, or class, of the image that is going to be defined in that
context. This MUST be the first attribute defined in the image context. Valid
classes are: background, trough, anchor, up_arrow, down_arrow, left_arrow,
right_arrow, menu, menuitem, submenu, button, and buttonbar. Note that the left
and right arrows, while valid, don't do anything just yet. All the subsequent
attributes up to the next type definition will be applied to that image class.

mode initial_mode [ allow allowed_modes ]
Specifies the initial mode for this image class as well as the modes which the
image class is allowed to use. initial_mode is the mode that the image will
have on startup (unless overridden by command-line options. allowed_modes is a
list of one or more modes. The image will be prevented from switching to any
mode not listed in the allow section. If the allow section is omitted entirely,
the image will never be permitted to change from the initial_mode. If no mode
line is specified for an image class, the default is equivalent to mode solid
allow solid. Valid mode names are image (to use an image), trans (for
transparency), viewport (for viewport mode), auto (for auto mode, which requires
Enlightenment 0.16 or better), and solid (which is a solid color only).

state { normal | selected | clicked | disabled }
This sets the state of the image you are about to define. Up until the next
state attribute that is encountered (or until you change types), all attributes
will apply to that particular state of the image. You should at minimum define
the normal state of the image. It will be used as the default if the attributes
for the other states are not specified. However, each image state has self-
contained options. Therefore, if you define multiple states for an image class,
you must define ALL attributes needed by that state. The sample themes supplied
with Eterm demonstrate how to define 1-, 2-, 3-, and 4-state images.

The above attributes affect the image class as a whole. All remaining attributes in
this context affect only the current state of the image class.

color fg bg
Sets the foreground and background colors for this imageclass. The foreground
color is used for text, and the background color is used for the object itself.
If an invalid color is specified, the default value for fg is white, and the
default for bg is black.

file filename
Sets the filename from which to load the image file. This is used for the image
mode. If you allow the image mode for your image, don't forget to supply an
image file! Note that you can also supply an image geometry string here by
adding an @ symbol and the geometry string to the end of the filename. See
below for the syntax of the geometry string. filename must be an absolute path
or a path relative to one of the directories in the path attribute. Note that
the image is verified and loaded when this attribute is encountered during
parsing.

geom image_geometry
Specifies the geometry and geometry-related operations which are to be applied
to the image. This attribute only applies to image classes using the image
mode. Image geometry is specified as wxh+x+y:ops where w and h are the
horizontal/vertical scaling percentages, x and y are the horizontal/vertical
alignment percentages, and ops is a colon-delimited list of operations: tiled
(to tile the image), propscaled (for proportional scaling). Note that these
operations can be combined for various effects.

cmod { image | red | green | blue } brightness [ contrast [ gamma ] ]
colormod { image | red | green | blue } brightness [ contrast [ gamma ] ]
Specifies a color modifier to apply to the image. The second keyword determines
whether the modifier will be applied to the image overall, the red values, the
green values, or the blue values. Each of the three parameters is a number
greater than or equal to 0. The numbers can be specified as decimal, octal (if
preceded by "0"), or hexadecimal (if preceded by "0x"). A value of 256 (0x100)
represents 100%, or "leave that value unchanged." 0 represents 0%, 512 (0x200)
is 200%, etc. However, be aware that overflow can occur with excessively high
values. Only the brightness value is required for this option. Keep in mind,
though, that you must specify brightness with contrast, and both of these with
gamma.

border left right top bottom
Specifies that the image has borders which should not be scaled with the rest of
the image. This is primarily used for images that have a beveled look, so that
the bevel will not end up getting scaled and lose the bevel effect. All four
parameter values are in pixels, just like the equivalent options for E themes
and Gtk+ pixmap themes.

bevel { up | down } left right top bottom
Adds a bevel to an image class. This can be done to any image class using the
image or trans modes. The parameters are pixel values which represent the width
of each edge of the bevel. This is especially useful if you want to use tiled
images or transparency for the arrow or anchor scrollbar widgets, or for menus.

padding left right top bottom
This is used only for the submenu image class. It defines the amount of pixels
on each side to reserve so that the text will not overwrite part of the image.
Works just like the same option in Enlightenment themes.

MENU CONTEXT

This context is used to create a menu. There is one instance of this context per
menu, and the menus should be defined in submenu-menu order; i.e., any menu that
refers to another menu (as its submenu) should be defined after the submenu is
defined. Within the menu context, there should be a menuitem subcontext for each
menu item (with the exception of the shorthand for separators).

title menu_title
This specifies the title for the menu to be defined. This MUST be the first
attribute given after the "begin menu". The title must be unique amongst all
the menus. It may contain spaces, but don't forget to enclose it in single or
double quotes if it does. Any future references to the menu will use the title.

font font_name
Tells Eterm to use font_name as the font for this menu. If not given, the
default terminal font is used.

sep or -
These symbols can be used as shorthand to insert a separator into the menu.

MENUITEM CONTEXT

This is a subcontext of the menu context which creates a single item for a menu.
There can be (and usually are) several menuitem contexts per menu.

text label
This is the text that is displayed for this menuitem. It is left-justified in
the menu window. It can have spaces, but enclose label in quotes if it does.

rtext label
This is text which is right-justified next to the menuitem text. This is
generally used to show what keystrokes correspond to a particular menu item,
like "C-x C-c" for the "Exit" menuitem in an Emacs menu.

action { string | echo | submenu | script } param
action separator
Specifies the action to occur when the menuitem is chosen. If you specify
separator, nothing else is needed. The other action types require a parameter,
param. string specifies a string to be sent to Eterm for handling (escape
codes, for example). echo specifies a string to be sent to the client program
(for sending commands to a shell, or keystrokes to an application like emacs or
mutt). If you use either of these action types, param will be parsed for escape
codes (\a, C-, and the like) before being sent. submenu specifies a submenu
which should be displayed when this item is selected, and param is the title of
the submenu to show. The submenu must have already been defined. The script
action type executes the Eterm-builtin script contained in param. See the
section below for more details on the builtin Eterm functions allowed for this
action type.

ACTION CONTEXT

Actions are key or mouse button bindings which activate certain behaviors. Any
action that can be triggered through an escape code can be bound to a key or mouse
button, with or without modifiers. You can also bind menus to keystrokes or mouse
buttons.

bind [ modifiers ] { keysym | button } to { string | echo | menu | script } param
Binds a keysym or a mouse button to an action. The action syntax follows the
keyword to and is identical to the syntax used for menus (see above). There can
be any number of modifiers (so long as the combination is reasonable) but only
one keysym or button. Valid modifiers are ctrl, shift, lock, mod1 through mod5,
alt, meta, and anymod (which allows any modifier). If none are given, the
keypress must not have modifier keys in use or the action will not be triggered.
Use anymod to allow any arbitrary modifier key to be used. The keysym can be
given in text (case-sensitive) or as a hex number. buttons should be specified
as button1 through button5. Also note that alt and meta will be equivalent to
one or more of mod1 through mod5, as well as perhaps each other, based on your
modifier settings. You can view these settings using xmodmap -pm. See also the
alt_mod and meta_mod options below.

BUTTON_BAR CONTEXT

The buttonbar is an addition to Eterm 0.9.1 which allows users to have a fully-
customizeable buttonbar at the top or bottom of each terminal window. Buttons on
the buttonbar can be used just like menuitems; they can popup menus (like a
menubar), or they can activate any other action a menuitem can.

font font
Specifies the font in which button labels will be displayed.

dock { top | bottom | no }
Specify whether or not to dock the buttonbar, and if so, whether to dock it at
the top or the bottom of the Eterm window. Note that only top and bottom are
currently enabled.

visible boolean
Toggle whether or not this particular buttonbar will be visible on startup.

button [ text ] [ icon filename ] action { string | echo | menu | script } param
Binds an action to a button. The usage of param and the action types work the
same here as they do for menuitems. Also note that you may specify some text or
an icon or both, but you cannot omit both.

MULTICHAR CONTEXT

Behavior for multi-byte fonts and encodings are defined here. This context does
not exist by default.

encoding { eucj | sjis | euckr | big5 | gb | iso-10646 }
Specifies the encoding method. Patches to support other encoding methods are
encouraged.

font num font
Set the numth multichar font to font.

XIM CONTEXT

This context controls locale-based behavior.

input_method input_method
Specify your input method program of choice.

preedit_type { OverTheSpot | OffTheSpot | Root }
Specify your preedit type of choice.

ESCREEN CONTEXT

This context allows for customizations specific to Escreen mode. See the Escreen
section below for more details.

url protocol://user@host:port/params
Connect to (or create) a particular screen session via a URL-type construct.
Standard URL rules apply. The protocol should be either screen (the default) or
twin. If user, host, and/or port are specified, an ssh connection is made to
the remote server using the given login information. The default is to
create/attach to a local session.

Any params that are given are passed directly to the underlying protocol and are
separated from each other by a plus sign (+).

firewall localport:firewall:remoteport
Bounce the connection through a firewall via ssh.

delay secs
Specify the amount of time to wait before sending the screen/twin initialization
sequence. This is required to insure that the remote session has been
established prior to sending the init sequence.

bbar_font font
Font to use for the Escreen buttonbar. The default is -*-helvetica-medium-r-
normal--10-*-*-*-p-*-iso8859-1.

bbar_dock { top | bottom | no }
Dock the Escreen buttonbar as specified. Note that only top and bottom are
currently enabled.

TOGGLES CONTEXT

This context contains boolean variables which can be toggled on or off. Valid
values for the attributes in this section are "yes", "on", "1", and "true" to turn
the option on, or "no", "off", "0", or "false" to turn the option off. These
values are denoted by boolean. They all default to false unless otherwise noted.

map_alert boolean
If true, Eterm will un-iconify itself when it receives a beep (ASCII 0x07).

visual_bell boolean
If true, Eterm will flash rather than sending a beep.

login_shell boolean
If true, Eterm will prepend '-' to the shell name when calling it. Depending on
your shell, this may modify its startup behavior.

scrollbar boolean
This turns on and off the display of the scrollbar. Default is on.

utmp_logging boolean
If true, Eterm will attempt to make an entry in the utmp file to record the
login information. Eterm may need to run privileged to do this.

meta8 boolean
Toggles the interpretation of the Meta key setting the 8th bit in a character.

iconic boolean
If true, Eterm will launch as an icon.

home_on_output boolean
Zoom to the bottom of the scrollback buffer on output.

home_on_input boolean
Zoom to the bottom of the scrollback buffer on input.

no_input boolean
If true, Eterm will not accept any keyboard input and will ask the window
manager to not allow it to be focused.

scrollbar_floating boolean
If true, the scrollbar will have no trough.

scrollbar_right boolean
If true, Eterm will put the scrollbar on the right of the window (default is
left).

scrollbar_popup boolean
If true, Eterm will hide the scrollbar when the Eterm window loses focus and
restore it when focus is regained. Default is to not change the scrollbar state
based on focus.

borderless boolean
If true, Eterm will run with no window borders. This also means that the window
can not be moved or resized. You will want to specify a geometry with this
attribute.

double_buffer boolean
Rather than drawing text directly onto the window, this causes Eterm to allocate
an additional pixmap the size of the terminal window into which the background
*and* the text are rendered. This pixmap is then set as the window background.
Double-buffering uses additional memory in the X server, but it allows Eterm to
ignore expose events so redraws are faster.

no_cursor boolean
If true, Eterm will not display a text cursor.

pause boolean
After the child process terminates, Eterm will wait for a keypress before
exiting.

xterm_select boolean
Duplicate's xterm's treatment of cutchars. The only real difference is what
happens when you double click on a single cutchar between two words. If this
option is on, only that single character gets selected. If it is off, that
character is selected along with the two words. The latter behavior is useful
for double-clicking on the space between someone's first and last names, or the
@ sign in an e-mail address, etc.

select_line boolean
If true, this attribute causes a triple click to select the entire line from
beginning to end. If false (default), a triple-click selects from the current
word to the end of the line.

select_trailing_spaces boolean
If true, this attribute causes spaces at the end of a line to be included as
part of the selection text when selecting. The default is to strip these
trailing spaces.

report_as_keysyms boolean
Reports certain keystrokes as keysyms and modifiers rather than escape
sequences. NOTE: This option is intended for use only with programs that
support this special Eterm mode. Do not enable it unless you are executing a
program which uses this mode.

itrans boolean
immotile_trans boolean
Toggles the immotile transparency optimization for transparent Eterm windows.
Note that this does NOT activate transparency; you must still activate "trans"
mode for the background image. This option should be used on transparent
windows which are shaded or tinted and which do not move around on the desktop
much. See the Mon Mar 6 21:11:13 PST 2000 ChangeLog entry for a more detailed
explanation.

buttonbar boolean
Toggle the display of all buttonbars.

resize_gravity boolean
If true, Eterm will automatically detect the nearest corner, and font-change
resizes will cause the Eterm window to gravitate toward that corner.

overstrike_bold boolean
If true (default), Eterm will simulate a bold font by printing each character
twice, offsetting the second pass by one pixel. This makes the characters seem
thicker without the need for a special font. You may wish to disable this if
you use a specific color for bold.

bold_brightens_foreground boolean
If true (default), Eterm will use the "bold" ANSI color attribute to brighten
the foreground color by using the high-intensity colors (8 through 15) rather
than the low-intensity colors (0 through 7). Note that having a specific color
selected for bold will override this.

blink_brightens_background boolean
If true (default), Eterm will use the "blink" ANSI color attribute to brighten
the background color by using the high-intensity colors (8 through 15) rather
than the low-intensity colors (0 through 7).

colors_suppress_bold boolean
If true (default), any colored text (that is, any text not rendered using the
default foreground color) will not be given any other special treatment for
bolding (e.g., bold font or bold overstrike).

sticky boolean
If true, Eterm will make its window sticky (shows on all desktops).

KEYBOARD CONTEXT

This context contains keyboard-related configuration options.

smallfont_key keysym
Specify a keysym to decrease the font size. Default is Shift and the - key on
the keypad. Ctrl-< or Meta-< may also work (if you #define one of the hotkeys
in src/feature.h).

bigfont_key keysym
Specify a keysym to increase the font size. Default is Shift and the + key on
the keypad. Ctrl-> or Meta-> may also work (if you #define one of the hotkeys
in src/feature.h).

keysym keysym string
Define keysym keysym to send string instead of its default. keysym must be
between 0xff00 and 0xffff or Eterm will complain.

meta_mod num
Specify which X modifier (1-5) to treat as the Meta key. See xmodmap(1) and the
output of xmodmap -pm for more details.

alt_mod num
Same as meta_mod, but for the Alt key.

numlock_mod num
Same as meta_mod, but for the NumLock key.

greek boolean { iso | ibm }
Turn on/off greek keyboard support, and set which greek mode to use.

app_keypad boolean
Turn on/off application keypad mode on startup.

app_cursor boolean
Turn on/off application cursor key mode on startup.

MISC CONTEXT

This context contains miscellaneous attributes that really didn't belong anywhere
else.

print_pipe command
Set the command to which to pipe print requests (printscreen) to command.

save_lines num
Set the number of lines in the scrollback buffer to num.

cut_chars string
Define the characters used as word delimiters to the characters contained in
string.

min_anchor_size num
Sets the minimum size, in pixels, of the scrollbar anchor (the part your mouse
grabs onto and moves around) to num.

border_width num
Sets the width of the border between the text window and the X window to num.

line_space num
Put num pixels' worth of space between each row of the terminal window.

finished_title title
Specifies that title should be displayed in the title bar of a paused Eterm when
the child process has completed.

finished_text text
Specifies that text should be displayed in the terminal window of a paused Eterm
when the child process has completed.

term_name name
Use name as the $TERM environment variable, which controls which
termcap/terminfo entry gets used. The default is Eterm.

exec command
Rather than executing a shell, this will cause Eterm to spawn command as its
child process. You can only have one of these!

BUILT-IN FUNCTIONS

Eterm has a set of built-in functions which are available in config files. Each
one accepts zero or more parameters and outputs a series of zero or more words.
"Words" are defined in shell terms; i.e., words are separated by whitespace, and
single or double quotes can be used to encapsulate words which contain whitespace
themselves. You also employ backquotes to execute a command whose output can
become part of the config file itself or can be passed to a built-in function as
its parameter list. Built-in functions and backquotes may be used anywhere their
output would be valid. Built-in functions are prefixed with the % character.

%appname()
Returns the application name, a hyphen, and the version number. Currently this
is the string Eterm-0.9.6.

%exec(command)
Executes command and returns the result. Basically it's exactly like using
backquotes.

%get(variable)
Retrieve the value of a config file variable. Refer to the %put() function
below.

%put(variable value)
Create a config variable named variable and assign it the value of value. The
value can then subsequently be retrieved using %get(variable)

%random(params)
This function randomly chooses one of the words which compose params and returns
that. The default themes that come with Eterm use this function to choose
random backgrounds, but backgrounds aren't the only things that can be
randomized with this function. You can randomize anything...colors, toggles,
fonts, tinting, etc.

%version()
Returns the version number. Currently this is the string 0.9.6.

PREPROCESSING

Eterm supports the %include file directive to allow for separation of the
configuration information into multiple files. Eterm will load and parse file just
like any other config file, but will treat its contents as if they replaced the
directive itself.

You may also request that the config file be run through an external preprocessor
(such as m4 or cpp) before Eterm reads it. This is done via the %preproc command
directive. You may specify anything you like for command so long as it accepts
input on STDIN and sends output to STDOUT. See the menus.cfg file in the default
chooser theme for an example.

SCRIPT FUNCTIONS

One of the action types which can be bound to keypresses, mouse buttons, menuitems,
or buttonbar buttons is a script. The script must be a single word (i.e.,
containing no spaces or enclosed in quotes) and consists of one or more calls to
the script functions below. Each call is separated from the next by a semicolon
(;). Function parameters are enclosed in parentheses; the parentheses are optional
if no parameters are to be passed. Commas and/or whitespace separate parameters
from each other.

copy(buffer)
Copies the current selection to the specified clipboard or cut buffer. buffer
is either a number 0-7, in which case the selection is copied to the cut buffer
specified, or one of the words clipboard, primary, or secondary (or any initial
substring thereof), in which case the selection is copied to the specified
clipboard. You may omit buffer, in which case the default buffer is primary
(XA_PRIMARY in Xlib-speak).

echo(string)
Send the specified string to the subcommand. Exactly equivalent to the echo
action.

es_display(cmd, params)
Aliases: es_disp
This is a master function which permits manipulation of Escreen displays through
the use of a series of subcommands. The specified cmd determines what, if any,
params are permitted. Available subcommands are:
goto - Switch to the specified display (0-9)
prev - Switch to the previous display
next - Switch to the next display
toggle - Toggle display
new - Create a new display. A name for the new display may be passed as a
parameter, or ask to prompt the user for the name.
rename - Change the name of the current display. A name for the new
display may be passed as a parameter, or ask to prompt the user for the
name.
kill - Terminate the current (or specified) display.
watch - Toggle monitoring of the current/specified display for activity.
scrollback - View the scrollback for the current/specified display.

es_region(cmd, params)
Aliases: es_reg es_win es_window
This is a master function which permits manipulation of Escreen display regions
through the use of a series of subcommands. The specified cmd determines what,
if any, params are permitted. Available subcommands are:
goto - Switch to the specified region (0-9)
prev - Switch to the previous region
next - Switch to the next region
toggle - Toggle region
new - Create a new region. A name for the new region may be passed as a
parameter, or ask to prompt the user for the name.
rename - Change the name of the current region. A name for the new region
may be passed as a parameter, or ask to prompt the user for the name.
kill - Terminate the current (or specified) region.
only - Maximize the current/specified region to the full display.
watch - Toggle monitoring of the current/specified region for activity.
scrollback - View the scrollback for the current/specified region.

es_statement(statement)
Execute an Escreen (screen/twin) command directly.

es_reset()
Aliases: es_rst
Reset the Escreen session

exec_dialog(command)
The same as exec/spawn, but this function presents the user with a dialog box in
which she can edit/confirm the command to be run and specify additional
parameters if needed.

exit(message)
exit(code)
Aliases: die quit
Exit Eterm with an optional message or an integer return code. Either parameter
may be specified, but not both. If neither is specified, a code of 0 (zero) is
the default.

kill(signal)
Sends the specified signal to Eterm's primary child process (either your shell,
or whatever you specify for Eterm to execute). For the time being, signal must
be numeric. SIGTERM is the default if signal is omitted.

msgbox(message)
Displays a small dialog box containing message and waits for a keypress before
continuing.

nop()
Does absolutely nothing except waste time. :-)

paste(buffer)
Pastes the contents of the specified clipboard or cut buffer into the terminal
window. buffer is either a number 0-7, in which case the selection is pasted
from the cut buffer specified, or one of the words clipboard, primary, or
secondary (or any initial substring thereof), in which case the contents of the
specified clipboard are pasted. You may omit buffer, in which case the default
buffer is primary (XA_PRIMARY in Xlib-speak).

save(type, filename)
Save the current theme/user configuration. type can be either user or theme;
the default is user. filename is the file to which the settings should be
saved. It may contain a path which is either absolute or relative to the theme
directory. The default filename for user is user.cfg, and the default filename
for theme is theme.cfg.

save_buff(filename)
Dumps the contents of the scrollback buffer to the specified file.

scroll(n)
Scrolls backward or forward in the scrollback buffer. n is a floating point
number followed by an optional unit specifier. The unit specifier is one of:
lines or l; pages or p; or buffers or b. The floating point number may be
separated from the unit specifier by whitespace or a comma, but it is not
required. The floating point number should be positive to scroll down (forward)
and negative to scroll up (backward). For example, the key sequence Shift-PgUp
is equivalent to scroll(-1p). You may also specify fractional quantities, such
as scroll(0.5p) to scroll down half a page. The default unit if not specified
is lines.

search(str)
Presents a dialog box into which the user may enter a search term. The default
value is set to str. All occurances of the specified search string are
highlighted in the scrollback buffer, and Eterm jumps back to the most recent
one. Searching again with the same keyword will clear the previous
highlighting.

spawn(command)
Aliases: exec
Spawns a secondary child process to execute command, or Eterm if no value is
passed.

string(string)
The specified string is parsed via Eterm. This is exactly identical to the
string action.

ESCREEN

Escreen is a screen/twin interface layer which allows Eterm to interoperate with GNU
screen and with Massimiliano Ghilardi's twin software. This allows Eterm to support
multiple subshell sessions within a single window. On the surface, this feature works
similarly to the "tabbed" sessions offered by programs like konsole and multi-gnome-
terminal. However, Escreen has the advantage of being an interface to existing software,
thus providing additional capabilities like multiple regions per display, detach/reattach
capability, seamless remote session support, firewall support, and more.

Escreen support is still somewhat experimental and is thus not compiled into Eterm by
default. To enable it, you must compile with --enable-escreen and/or --enable-etwin
(depending on whether you have screen, twin, or both). If you installed from a package,
you can use Eterm --version and check for either +ESCREEN (enabled) or -ESCREEN
(disabled).

For best results, if you wish to use Escreen mode, do so by invoking Eterm with the
Escreen theme (Eterm -t Escreen). This theme supplies default key bindings, the basic
Escreen menu, color definitions, etc. for use by the Escreen engine. Most importantly, it
supplies the required url parameter in order to invoke Escreen mode.

Consult the README.Escreen file for more in-depth discussion of Escreen mode.

AUTHORS

       Michael Jennings (mej@eterm.org)

URL(s)

       Eterm Home Page -- http://www.eterm.org/
       Author's Home Page -- http://www.kainx.org/