eterm/doc/Eterm.1.in

.TH ETERM 1 @DATE@ "X Version 11" "X Tools"
.SH NAME
Eterm - the Enlightened terminal emulator for the X Window System
.SH SYNOPSIS
.B Eterm
.RI [ options ]

.SH DESCRIPTION
.PP
.B Eterm
\(em version
.B @VERSION@
\(em is a color vt102 terminal emulator intended as an
.IR 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.
.B Eterm
uses Imlib for advanced graphic abilities.  See below for details.
.SH OPTIONS
The
.B 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.
.LP
.TP
.BI \-t " theme" ", \-\-theme " theme
Load specified
.I theme\.
Consult the FAQ for more details on what constitutes an Eterm
.I theme\.
.TP
.BI \-X " conffile" ", \-\-config-file " conffile
Use an alternative user config file name.  Otherwise Eterm uses the default,
which is 
.I user.cfg\.
The theme config file is always
.I theme.cfg\.
.TP
.BI \-d " displayname" ", \-\-display " displayname
Attempt to open a window on the named X display
.I displayname.
In the absence of this option, the display specified by the
.B DISPLAY
environment variable is used.
.TP
.BI \-\-debug " level"
Show debugging output.
.I level
is an integer between 0 and 5 which determines how verbose the debugging
output is.
.TP
.B \-\-install
Tells Eterm to install its own colormap rather than using the default one.
.TP
.BR "\-h" , " \-\-help"
Print out a message describing available options.
.TP
.BR \-\-version
Print
.B Eterm
version and compile-time configuration.
.TP
.BR "\-r" , " \-\-reverse-video"
Reverse video, swaps the foreground and background colors.
.TP
.BI \-b " color" ", \-\-background-color " color
Set
.I color
as the background color.
.B NOTE:
this will actually be the foreground color if reverse video is also
selected.
.TP
.BI \-f " color" ", \-\-foreground-color " color
Set
.I color
as the foreground (text) color.
.B NOTE:
this will actually be the background color if reverse video is also
selected.
.TP
.BI \-\-color0 " color"
.TP
.BI ...
.TP
.BI \-\-color15 " color"
Use
.I color
as color X.
.TP
.BI \-\-colorBD " color"
Use
.I color
as the bold color.
.TP
.BI \-\-colorUL " color"
Use
.I color
as the underline color.
.TP
.BI \-\-menu-color " color"
Use
.I color
as the menu color (only makes sense if menu is enabled).
.TP
.BI \-\-menu-text-color " color"
Use
.I color
as the menu text color (only makes sense if menu is enabled).
.TP
.BI \-S " color" ", \-\-scrollbar-color " color
Use
.I color
as the scrollbar color (only makes sense if scrollbar is enabled).
.TP
.BI \-\-unfocused-menu-color " color
Use
.I color
as the menu color when window does not have focus 
(only makes sense if scrollbar is enabled).
.TP
.BI \-\-unfocused-scrollbar-color " color
Use
.I color
as the scrollbar color when window does not have focus 
(only makes sense if scrollbar is enabled).
.TP
.BI \-\-pointer-color " color"
Use
.I color
as the pointer color.
.TP
.BI \-c " color" ", \-\-cursor-color " color
Use
.I color
as the cursor color.
.TP
.BI \-\-cursor-text-color " color"
Use
.I color
as the cursor text color.
.TP
.BI \-g " geom" ", \-\-geometry " geom
Window geometry as Width x Height+X coord+Y coord, i.e 100x200+0+100
.TP
.BR "\-i" , "\-\-iconic"
Start in iconified state (only if the window manager supports
iconification).
.TP
.BI \-n " name" ", \-\-name " name
Sets name of current instance to
.I name.
This will affect the icon title and the window title string unless
they are otherwise explicitly set.
.TP
.BI \-T " title" ", \-\-title " title
Sets window's title text to
.I title.
.TP
.BI \-\-icon-name " text"
Sets the icon title text to
.I text.
.TP
.BI \-B " type" ", \-\-scrollbar-type " type
Specifies the
.I type
scrollbar style should be used.
.I type
can be any of
.BR "motif" ", " "xterm" ", or " "next" "."
.TP
.BI \-\-scrollbar-width " width"
Set the width of the scrollbar, in pixels, to
.IR width "."
Eterm does not impose any restrictions on this value, but it should be reasonable.
.TP
.BI \-D " desktop" ", \-\-desktop " desktop
Starts the Eterm on the specified desktop.
.I desktop
should be an integer between 0 and your highest-numbered desktop.
.BR "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
.B _WIN_WORKSPACE
property and how to support it.
.TP
.BI \-\-line-space " num"
Size of the extra gap, in pixels, to provide between lines in the terminal window.
.TP
.BI \-\-bold-font " font"
Sets the bold text font to
.I font.
.TP
.BI \-F " font" ", \-\-font " font
Sets the normal text font to
.I font.
.TP
.BI \-\-font1 " font"
.TP
.BI ...
.TP
.BI \-\-font4 " font"
Sets font X to
.I font.
.TP
.BI \-P " pic" ", \-\-background-pixmap " pic
Use
.I pic
as the background image.
.I 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
.B @
sign and the geometry string.  Image geometry is specified as
.BI @ w x h + x + y : ops
where
.IR w " and " h
are the horizontal/vertical scaling percentages,
.IR x " and " y
are the horizontal/vertical alignment percentages, and
.I ops
is a colon-delimited list of operations:
.BR tiled " (to tile the image), "
.BR scaled " (for horizontal and vertical scaling), " 
.BR hscaled " (for horizontal scaling), " 
.BR vscaled " (for vertical scaling), and " 
.BR propscaled " (for proportional scaling)."
Note that some of these operations can be combined for various effects.
.TP
.BI \-I " pic" ", \-\-icon " pic
Sets the icon pixmap file to
.IR "pic" "."
Works similarly to the
.B -P
option above.
.TP
.BI \-\-up-arrow-pixmap " pic"
As above, except the scrollbar's up-arrow is set.  
.TP
.BI \-\-down-arrow-pixmap " pic"
As above, except the scrollbar's down-arrow is set.
.TP
.BI \-\-trough-pixmap " pic"
As above, except the scrollbar's background (trough) is set.
.TP
.BI \-\-anchor-pixmap " pic"
As above, except the scrollbar's anchor image is set.
.TP
.BI \-\-menu-pixmap " pic"
As above, except the menu background image is set.
.TP
.BR "\-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
.I Esetroot
program (found in the
.B utils/
directory) to set your root background image.
.TP
.BR \-\-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.
.TP
\fB\-\-cmod\fR \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma \fR] ]
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
.I brightness
value is required for this option.  Keep in mind, though, that you must
specify
.IR brightness " with " contrast ", and both of these with " gamma "."
.TP
\fB\-\-cmod\-red\fR \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma \fR] ]
Same as above, except that the modifier applies to the red values of the
image.
.TP
\fB\-\-cmod\-green\fR \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma \fR] ]
Same as above, except that the modifier applies to the green values of the
image.
.TP
\fB\-\-cmod\-blue\fR \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma \fR] ]
Same as above, except that the modifier applies to the blue values of the
image.
.TP
.BI \-p " newpath" ", \-\-path " newpath
Sets the pic search path.  When the
.B --background-pixmap
or other pixmap options are used, this path will be used to find the image.
.TP
.BI \-N " list" ", \-\-anim " list
Specifies an animation list to be use in cycling the background pixmap.  The
.I 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 have the same syntax as the
.B background
attribute in a configuration file (two integers followed by the image filename),
except that the two integers are optional.  If they are specified, remember to
group them with the filename using quotes.  The following are both valid:
.RS 10
Eterm -N '10 image1.jpg image2.jpg'
.br
Eterm -N '10 "0 0 image1.jpg" "-1 -1 image2.jpg"'
.RE
.TP
.BI \-M " font" ", \-\-mfont " font
Sets the normal multibyte text font to
.I font.
.TP
.BI \-\-mfont1 " font"
.TP
.BI ...
.TP
.BI \-\-mfont4 " font"
Sets multibyte font X to
.I font.
.TP
.BI \-\-mencoding " encoding"
Sets multichar encoding mode (eucj or sjis or euckr)
.TP
.BI \-\-input-method " method"
Sets XIM input method
.TP
.BI \-\-preedit-type " type"
Sets XIM preedit type
.TP
.BR "\-l", " \-\-login-shell"
Makes the new shell a login shell.
.TP
.BR "\-s", " \-\-scrollbar"
Enables the scrollbar. (Default)
.TP
.BR "\-u", " \-\-utmp-logging"
Tries to enable proper utmp logging.  For this to work, Eterm probably needs
to run setuid or setgid, usually setuid root.
.TP
.BR "\-v", " \-\-visual-bell"
Enables the "visual bell".  Means the window will flash or blink rather
than beep.
.TP
.BR "\-H", " \-\-home-on-echo"
Jump to bottom on output.
.TP
.BR "\-\-home-on-input"
Jump to bottom on input.
.TP
.BR "\-E", " \-\-home-on-refresh"
Jump to bottom on refresh (^L)
.TP
.BR "\-\-scrollbar-right"
Display scrollbar on the right hand side.
.TP
.BR "\-\-scrollbar-floating"
Display the scrollbar without a trough.
.TP
.BR "\-\-scrollbar-popup"
Display the scrollbar only when the Eterm window is focused.
.TP
.BR "\-x", " \-\-borderless"
This option forces Eterm to have no borders.
.TP
.BR "\-m", " \-\-map-alert"
Un-iconify on beep.
.TP
.BR "\-8", " \-\-meta8"
Causes the Meta key to set the 8th bit in the char.
.TP
.BR "\-\-backing-store"
If supported by the X server, tries to use backing store for faster
refreshes.
.TP
.BR "\-\-no-cursor"
Disables the text cursor.
.TP
.BR \-\-pause
After the child process terminates, Eterm will wait for a keypress
before exiting.
.TP
.BR \-\-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.
.TP
.BR \-\-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.
.TP
.BR \-\-select-trailing-spaces
Determines whether or not trailing spaces in a selection are maintained (on)
or discarded (off).
.TP
.BR \-\-report-as-keysyms
Reports certain keystrokes as keysyms and modifiers rather than escape sequences.
.B 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.
.TP
.BI \-\-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).
.TP
.BI \-\-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).
.TP
.BI \-\-meta-mod " num"
Specify which X modifier (1-5) to treat as the Meta key.  See
.IR xmodmap (1)
and the output of
.B xmodmap -pm
for more details.
.TP
.BI \-\-alt-mod " num"
Same as
.BR \-\-meta-mod ","
but for the Alt key.
.TP
.BI \-\-numlock-mod " num"
Same as
.BR \-\-meta-mod ","
but for the NumLock key.
.TP
.BI "\-\-greek-keyboard" " mode"
Use Greek keyboard mapping (iso or ibm).
.TP
.BR \-\-app-keypad
Start Eterm in application keypad mode (as opposed to normal keypad mode).
.TP
.BR \-\-app-cursor
Start Eterm in application cursor key mode (as opposed to normal cursor
key mode).
.TP
.BI \-L " num" ", \-\-save-lines " num
Set the number of lines in the scrollback buffer to
.I num.
.TP
.BI \-a " size" ", \-\-min-anchor-size " size
Specifies the minimum size, in pixels high, of the scrollbar anchor.
.B NOTE:
This causes abnormal scrolling behavior when combined with large
scrollback buffers!
.TP
.BI \-w " width" ", \-\-border-width " width
Set the window's border width to
.I 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.
.TP
.BI \-\-print-pipe " pipe"
The pipe for the PrintScreen function.
.TP
.BI \-\-cut-chars " separators"
The seperators for double-click selection.
.TP
.BI \-\-term-name " TERM"
Use
.I TERM
for the value $TERM.
.TP
.BR "\-C", " \-\-console"
Grab console messages.  Depending on your system, Eterm may need to be
setuid root to do this.
.TP
.BI \-e " command" ", \-\-exec " command
Execute
.I command
rather than a shell.

.SH 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 @THEMEDIR@/<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 override.

NOTE:  If you have a user.cfg file in the Eterm theme directory or in ~/.Eterm/, it
will
.B 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 @THEMEDIR@/Eterm/theme.cfg).  The next section contains details
on the format and usage of the configuration file.

.SH CONFIGURATION

Since Eterm @VERSION@ 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
.B 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.
.LP
.TP
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.
.TP
MAIN CONTEXT

There are very few things that are valid within the "main" context.  In
fact, the only non-comment lines allowed in the main context are begin's
and end's for other contexts.  Each context can have any number of
subcontexts, but only a few actually have any.  Valid subcontexts for main
are color, attributes, imageclasses, menu, actions, multichar, xim,
toggles, keyboard, and misc.  They can appear in any order.  The order I
list them here is simply the order in which they appear in the default themes,
which was arbitrarily chosen for continuity.  So that you can follow along
easily, I'll cover them in the same order here.
.TP
COLOR CONTEXT

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

.RS 5
.BI foreground " color"
.RS 5
Use
.I color
for the foreground (text) color.
.RE

.BI background " color"
.RS 5
Use
.I color
for the background color.
.RE

.BI cursor " color"
.RS 5
Use
.I color
for the cursor color.
.RE

.BI cursor_text " color"
.RS 5
Use
.I color
for the cursor text color.
.RE

.BI menu " color"
.RS 5
Use
.I color
for the menu color.
.RE

.BI unfocused_menu " color"
.RS 5
Use
.I color
for the unfocused menu color.
.RE

.BI menu_text " color"
.RS 5
Use
.I color
for the menu text color.
.RE

.BI scrollbar " color"
.RS 5
Use
.I color
for the scrollbar color.
.RE

.BI unfocused_scrollbar " color"
.RS 5
Use
.I color
for the scrollbar color if Eterm is unfocused.
.RE

.BI pointer " color"
.RS 5
Use
.I color
for the mouse pointer color.
.RE

.BR video " { " normal " | " reverse " }"
.RS 5
.B normal
will not reverse the foreground and background colors.
.B reverse
(meaning reverse video) will.
.RE

.BI color " num" " " "color"
.RS 5
Set terminal color
.I num
(0-15) to the color name, string, or set of 3 decimal/hex/octal RGB values
specified by
.IR color .
.RE

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

.TP
ATTRIBUTES CONTEXT

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

.RS 5
.BI geometry " geom"
.RS 5
Use the geometry string
.I geom
to specify the startup geometry.
.I geom
should be in the format 
.BI " " W x H+X+Y
where
.I W
is the width,
.I H
is the height, and
.I +X
and
.I +Y
are the X and Y offsets.  If the signs on
.I X
and
.I 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.
.RE

.BI title " title"
.RS 5
Use
.I title
as the text in the title bar of the Eterm window.
.RE

.BI name " name"
.RS 5
Use
.I name
as the resource name of the Eterm window.
.RE

.BI iconname " name"
.RS 5
Use
.I name
as the icon name of the Eterm window icon.
.RE

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

.BI scrollbar_type " type"
.RS 5
Use a scrollbar with the
.IR type " style.  " type " can"
be any of
.BR motif ", " xterm ", or " next "."
.RE

.BI scrollbar_width " num"
.RS 5
Use a scrollbar that is
.I num
pixels wide.
.RE

.BI font " num" " " "font"
.br
.BI "font bold " font
.RS 5
Set the
.IR num th
font (0-4), or the
.B bold
font, to
.IR font .
.RE
.RE

.TP
IMAGECLASSES CONTEXT

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

.RS 5
.BI icon " filename"
.RS 5
Use
.I filename
as the icon image for the Eterm window.
.I filename
can be an absolute path, relative to the current theme, or relative to one of
the directories in the
.B path
attribute listed above.
.RE

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

.BI anim " interval" "" " images ..."
.RS 5
Specifies an animation list to be use in cycling the background pixmap.
.I 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 remaining words have the same syntax as the
.B background
attribute in a configuration file (two integers followed by the image filename),
except that the two integers are optional.  If they are specified, remember to
group them with the filename using quotes.  The following are both valid:
.RS 5
anim 10 image1.jpg image2.jpg
.br
anim 10 "0 0 image1.jpg" "-1 -1 image2.jpg"
.RE
.RE
.RE

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

.RS 5
.BI type " class"
.RS 5
Specifies the type, or
.IR 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:
.BR background ", " trough ", " anchor ", "
.BR up_arrow ", " down_arrow ", " left_arrow ", "
.BR right_arrow ", " menu ", and " submenu "."
Note that the left and right arrows, while valid, don't do anything just
yet.  All the subsequent attributes up to the next
.B type
definition will be applied to that image class.
.RE
.RE

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

.RS 5
.BR state " { " normal " | " selected " |"
.BR clicked " } "
.RS 5
This sets the state of the image you are about to define.  Up until the next
.B 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
.B normal
state of the image.  It will be used as the default if the attributes for the
.BR selected " and/or " clicked
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-, and 3-state images.
.RE
.PP
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.
.RE

.RS 5
.BI file " filename"
.RS 5
Sets the filename from which to load the image file.  This is used for the
.B 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
.B @
symbol and the geometry string to the end of the filename.  See below for the
syntax of the geometry string.
.I filename
must be an absolute path or a path relative to one of the directories in the
.B path
attribute.  Note that the image is verified and loaded when this attribute is
encountered during parsing.
.RE
.RE

.RS 5
.BI  " "
.RS 5
.RE
.RE

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

.RS 5
\fBcmod\fR { \fBimage\fR | \fBred\fR | \fBgreen\fR | \fBblue\fR } \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma\fR ] ]
.br
\fBcolormod\fR { \fBimage\fR | \fBred\fR | \fBgreen\fR | \fBblue\fR } \fIbrightness\fR [ \fIcontrast\fR [ \fIgamma\fR ] ]
.RS 5
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
.I brightness
value is required for this option.  Keep in mind, though, that you must
specify
.IR brightness " with " contrast ", and both of these with " gamma "."
.RE
.RE

.RS 5
.BI border " left right top bottom"
.RS 5
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.
.RE
.RE

.RS 5
.BI bevel " left right top bottom"
.RS 5
Adds a bevel to an image class.  This can be done to any image class using the
.BR 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.
.RE
.RE

.RS 5
.BI padding " left right top bottom"
.RS 5
This is used only for the
.B 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.
.RE
.RE

.RE

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

.RS 5
.BI title " menu_title"
.RS 5
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.
.RE
.RE

.RS 5
.BI font " font_name"
.RS 5
Tells Eterm to use
.I font_name
as the font for this menu.  If not given, the default terminal font is used.
.RE
.RE

.RS 5
.BR sep " or " -
.RS 5
These symbols can be used as shorthand to insert a separator into the menu.
.RE
.RE

.RE

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

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

.RS 5
.BI rtext " label"
.RS 5
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.
.RE
.RE

.RS 5
\fBaction\fR { \fBstring\fR | \fBecho\fR | \fBsubmenu\fR } \fIparam\fI
.br
.B action separator
.RS 5
Specifies the action to occur when the menuitem is chosen.  If you specify
.BR separator ","
nothing else is needed.  The other action types require a parameter,
.IR param "."
.B string
specifies a string to be sent to Eterm for handling (escape codes, for example).
.B 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,
.I param
will be parsed for escape codes (\\a, C-, and the like) before being sent.
.B submenu
specifies a submenu which should be displayed when this item is selected.
.I param
is the title of the submenu to show.  The submenu must have already been
defined.
.RE
.RE

.RE

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

.RS 5
\fBbind\fR [ \fImodifiers\fR ] { \fIkeysym\fR | \fIbutton\fR } \fBto\fR { \fBstring\fR | \fBecho\fR | \fBmenu\fR } \fIparam\fR
.RS 5
Binds a
.IR keysym " or a mouse " button
to an action.  The action syntax follows the keyword
.B to
and is identical to the syntax used for menus (see above).  There can be any
number of
.I modifiers
but only one
.IR keysym " or " button "."
Valid
.I modifiers
are
.BR ctrl ", " shift ", " lock ", "
.BR mod1 " through " mod5 ", "
.BR alt " and " meta " (which are equivalent to " mod1 "), and"
.BR 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
.B anymod
to allow any arbitrary modifier key to be used.  The
.I keysym
can be given in text (case-sensitive) or as a hex number.
.IR button s
should be specified as
.BR button1 " through " button5 "."
.RE
.RE

.RE

.TP
MULTICHAR CONTEXT

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

.RS 5
\fBencoding\fR { \fBeucj\fR | \fBsjis\fR | \fBeuckr\fR }
.RS 5
Specifies the encoding method.  Patches to support other encoding methods are
encouraged.
.RE
.RE

.RS 5
.BI font " num" " " "font"
.br
.BI "font bold " font
.RS 5
Set the
.IR num th
multichar font (0-4), or the
.B bold
multichar font, to
.IR font .
.RE
.RE

.RE

.TP
XIM CONTEXT

This context controls locale-based behavior.  It, too, does not exist by
default.

.RS 5
.BI input_method " input_method"
.RS 5
Specify your input method program of choice.
.RE
.RE

.RS 5
.BR preedit_type " { " OverTheSpot " | " OffTheSpot " | "
.BR Root " }"
.RS 5
Specify your preedit type of choice.
.RE
.RE

.RE

.TP
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
.IR boolean .
They all default to false unless otherwise noted.

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

.BI visual_bell " boolean"
.RS 5
If true, Eterm will flash rather than sending a beep.
.RE

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

.BI scrollbar " boolean"
.RS 5
This turns on and off the display of the scrollbar.  Default is on.
.RE

.BI utmp_logging " boolean"
.RS 5
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.
.RE

.BI meta8 " boolean"
.RS 5
Toggles the interpretation of the Meta key setting the 8th bit in a
character.
.RE

.BI iconic " boolean"
.RS 5
If true, Eterm will launch as an icon.
.RE

.BI home_on_echo " boolean"
.RS 5
Zoom to the bottom of the scrollback buffer on output.
.RE

.BI home_on_input " boolean"
.RS 5
Zoom to the bottom of the scrollback buffer on input.
.RE

.BI home_on_refresh " boolean"
.RS 5
Zoom to the bottom of the scrollback buffer on refresh (Ctrl-L).
.RE

.BI scrollbar_floating " boolean"
.RS 5
If true, the scrollbar will have no trough.
.RE

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

.BI scrollbar_popup " boolean"
.RS 5
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.
.RE

.BI borderless " boolean"
.RS 5
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
.B geometry
with this attribute.
.RE

.BI backing_store " boolean"
.RS 5
If true, Eterm will use a backing store.
.RE

.BI no_cursor " boolean"
.RS 5
If true, Eterm will not display a text cursor.
.RE

.BI pause " boolean"
.RS 5
After the child process terminates, Eterm will wait for a keypress
before exiting.
.RE

.BI xterm_select " boolean"
.RS 5
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.
.RE

.BI select_line " boolean"
.RS 5
If true, this attribute causes a triple-click to select from the current
word to the end of the line.  If off, a triple click selects the entire
line from beginning to end.
.RE

.BI select_trailing_spaces " boolean"
.RS 5
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.
.RE

.BI report_as_keysyms " boolean"
.RS 5
Reports certain keystrokes as keysyms and modifiers rather than escape sequences.
.B 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.
.RE

.RE

.TP
KEYBOARD CONTEXT

This context contains keyboard-related configuration options.

.RS 5
.BI smallfont_key " keysym"
.RS 5
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).
.RE

.BI bigfont_key " keysym"
.RS 5
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).
.RE

.BI keysym " keysym" " " "string"
.RS 5
Define keysym
.I keysym
to send
.I string
instead of its default.
.I keysym
must be between 0xff00 and 0xffff or Eterm will complain.
.RE

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

.BI alt_mod " num"
.RS 5
Same as
.BR meta_mod ","
but for the Alt key.
.RE

.BI numlock_mod " num"
.RS 5
Same as
.BR meta_mod ","
but for the NumLock key.
.RE

.BI greek " boolean"
.BR " " "{ " "iso" " | " "ibm" " }"
.RS 5
Turn on/off greek keyboard support, and set which greek mode to use.
.RE

.BI app_keypad " boolean"
.RS 5
Turn on/off application keypad mode on startup.
.RE

.BI app_cursor " boolean"
.RS 5
Turn on/off application cursor key mode on startup.
.RE
.RE

.TP
MISC CONTEXT

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

.RS 5
.BI print_pipe " command"
.RS 5
Set the command to which to pipe print requests (printscreen) to
.IR command .
.RE

.BI save_lines " num"
.RS 5
Set the number of lines in the scrollback buffer to
.IR num .
.RE

.BI cut_chars " string"
.RS 5
Define the characters used as word delimiters to the characters contained in
.IR string .
.RE

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

.BI border_width " num"
.RS 5
Sets the width of the border between the text window and the X window to
.IR num .
.RE

.BI term_name " name"
.RS 5
Use
.I name
as the
.B $TERM
environment variable, which controls which termcap/terminfo entry gets used.
The default is
.BR xterm .
.RE

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

.TP
BUILT-IN FUNCTIONS

Eterm has a set of built-in functions which are available in config files.
They can be used anywhere their output would be valid.  Built-in functions
are prefixed with the
.B %
character.

.RS 5
.BI %random( params )
.RS 5
This function randomly chooses one of the words which compose
.I params
and returns that.  "Words" are defined in shell terms, meaning that single or
double quotes can be used to separate individual words of
.I params
which contain spaces.  And you can even get creative and use a
backquote-executed command to generate the list of words to pass to
.BR %random() .
The default themes that come with Eterm demonstrate this technique, in fact.
But keep in mind that random pixmaps aren't the only thing you can do with this
function.  You can randomize anything...colors, toggles, fonts, tinting...you
name it!
.RE

.BI %exec( command )
.RS 5
Executes
.I command
and returns the result.  Basically it's exactly like using backquotes.
.RE

.BI %appname()
.RS 5
Returns the application name, a hyphen, and the version number.  Currently this
is the string 
.BR Eterm-@VERSION@ .
.RE

.BI %version()
.RS 5
Returns the version number.  Currently this
is the string 
.BR @VERSION@ .
.RE
.RE

.TP
INCLUDES

Eterm supports the
.BI %include " file"
directive to allow for separation of the configuration information into
multiple files.

.SH AUTHORS
Michael Jennings (mej@eterm.org)
Man page re-written for version 0.8 by Shaleh (shaleh@debian.org).

.SH URL(s)
Eterm Home Page -- http://www.eterm.org/
.br
Eterm FAQ -- http://www.eterm.org/FAQ.html
.br
Eterm I-Docs -- http://eterm.i-docs.org/