@node Configuration
@chapter Configuration

@cindex configuration
@cindex xwperc
@cindex syntax_def
@cindex X resources

xwpe is configured through three mechanisms: the @file{xwperc} options
file, the @file{syntax_def} syntax highlighting definitions, and X11
resources (for the X11 binaries).

@section The xwperc options file

@cindex xwperc
@cindex initialization file

On startup, xwpe reads its options from a personal configuration file.
The search order is:

@enumerate
@item
Personal file: @file{$HOME/.xwpe/xwperc} (or @file{$HOME/.wpe/wperc}
for @command{wpe}).
@item
System-wide file: @file{/usr/local/lib/xwpe/xwperc} (or the path set
by @code{LIBRARY_DIR} at compile time; on Debian this is
@file{/usr/lib/xwpe/xwperc}).
@item
Built-in defaults (if neither file exists).
@end enumerate

The options file is a text file with @code{name = value} entries.
It is normally written by xwpe itself when you choose
@samp{Options @result{} Save Options} (@kbd{Alt-O S}).

@strong{Warning}: if you hand-edit @file{xwperc}, any comments you add
will be erased the next time xwpe saves the options.

@subsection Command-line overrides

@table @option
@item -sf @var{file}
Use @var{file} instead of the default @file{xwperc}.
@item -so
Ignore the options file entirely; use built-in defaults.
@end table

@subsection Options available in the Options menu

The @samp{Options} menu (@kbd{Alt-O}) provides dialogs for:

@table @samp
@item Editor
Tab size, auto-indent, line wrapping, maximum column width.
See @ref{Editor options dialog} for the full list of fields.
@item File-Manager
Sort order, hidden files, wastebasket behaviour, link defaults.
See @ref{File manager options dialog} for the full list of fields.
@item Programming
Compiler path, default flags, message-string format.
@item Compiler
Compiler command, flags, and switches for the current project.
See @ref{Compiler options dialog} for the full list of fields.
@item Debugger
Select debugger backend: gdb, sdb, or dbx.  Choose between
full-screen and normal terminal mode.
@item Adjust Colors
Modify the 16-colour scheme used by the interface.
@end table

@anchor{Editor options dialog}
@subsection Editor options dialog

@cindex editor options

The editor options dialog (@samp{Options @result{} Editor}, @kbd{Alt-O E})
contains the following fields.  (Documented since v1.4.)

@subsubheading Data

@table @kbd
@item Alt-A
The next file loaded will be treated as an ASCII (text) file.
@item Alt-B
The next file loaded will be a binary file.
@end table

@subsubheading Display

@table @kbd
@item Alt-S
Toggle end-of-line display: @samp{$} for newlines, blank for NULL
(continuation lines).
@end table

@subsubheading Auto-save

@table @kbd
@item Alt-P
Save all options automatically when quitting.
@item Alt-H
Enable periodic auto-save.  After N changes (configurable in the
Max.@: Changes field), the file is saved with an @file{.ASV} extension.
The original file is not modified.  The @file{.ASV} file is deleted on
normal exit.
@end table

@subsubheading Keys (function key bindings)

@table @kbd
@item Alt-L
Use the default keybindings (Turbo C style, xwpe < 1.2.0 compatible).
@item Alt-C
Use Common User Access (CUA) keybindings (MS-Windows / OSF Motif style).
@end table

@subsubheading Auto-indent

@table @kbd
@item Alt-Y
Auto-indent only for files that can be compiled (matching a defined
file extension in @samp{Options @result{} Compiler}).
@item Alt-W
Auto-indent for all files.
@item Alt-V
Disable auto-indent.
@end table

@subsubheading Numeric fields

@table @kbd
@item Alt-M
Maximum number of columns per row (word-wrap column).
@item Alt-T
Number of characters per tab stop.
@item Alt-X
Number of changes before an auto-save (if enabled).
@item Alt-N
Number of undo steps saved.
@item Alt-I
Number of columns for auto-indent step.
@end table

@anchor{File manager options dialog}
@subsection File manager options dialog

@cindex file manager options

The file manager options dialog (@samp{Options @result{} File-Manager},
@kbd{Alt-O F}) contains the following fields.
(Documented since v1.4.)

@subsubheading Directories

@table @kbd
@item Alt-F
Show hidden files.
@item Alt-D
Show hidden directories.
@item Alt-K
Make all actions (Move, Link, Copy, Remove) recursive (include
sub-directories).
@end table

@subsubheading Sort files by

@table @kbd
@item Alt-N
Sort by name.
@item Alt-I
Sort by time (creation/modification time).
@item Alt-B
Sort by size (bytes).
@item Alt-R
Reverse order.
@end table

@subsubheading Move/Copy behaviour

@table @kbd
@item Alt-Q
Ask for confirmation before overwriting an existing file.
@item Alt-V
Overwrite existing files without confirmation.
@item Alt-T
Never overwrite existing files.
@end table

@subsubheading Remove behaviour

@table @kbd
@item Alt-W
Deleted files are moved to the wastebasket.
@item Alt-A
Files are permanently deleted (with confirmation).
@item Alt-M
Files are permanently deleted (no confirmation).
@end table

@subsubheading Link defaults

@table @kbd
@item Alt-H
Try a hard link first; fall back to a symbolic link if the hard link
fails (e.g.@: cross-filesystem or directory link).
@item Alt-S
Always use symbolic links.
@end table

@subsubheading Wastebasket on exit

@table @kbd
@item Alt-P
Prompt to delete the wastebasket contents on exit.
@item Alt-E
Automatically empty the wastebasket on exit.
@item Alt-L
Keep the wastebasket contents on exit.
@end table

@anchor{Compiler options dialog}
@subsection Compiler options dialog

@cindex compiler options

The compiler options dialog (@samp{Options @result{} Compiler},
@kbd{Alt-O C}) allows adding, removing, and configuring compilers.
When opened, it shows @samp{Add Compiler}, @samp{Remove Compiler},
and a list of all defined compilers.  Selecting @samp{Add Compiler}
or an existing compiler opens the following fields.
(Documented since v1.4.)

@table @strong
@item Language
The name of the programming language.
@item Compiler
The path to the compiler executable.
@item Compiler-Options
Flags passed to the compiler (e.g.@: @code{-Wall -g}).
@item Loader-Options
Flags passed to the linker (e.g.@: @code{-lm}).
@item Executable-Name
The name of the resulting executable (default: @file{@var{name}.e}).
@item File-Postfix
The file extension that triggers this compiler (e.g.@: @code{.c}).
@item Compiler-Style
Select whether error messages use the GNU format
(@code{file:line:column:}) or a custom format defined in the
Message-String field.
@item OK
Accept changes.
@item CANCEL
Reject changes.
@end table

@section Syntax highlighting (syntax_def)

@cindex syntax highlighting
@cindex syntax_def

Syntax highlighting rules are defined in the @file{syntax_def} file.
xwpe looks for this file in:

@enumerate
@item @file{$HOME/.xwpe/syntax_def} (personal).
@item @file{/usr/local/lib/xwpe/syntax_def} (system; on Debian:
@file{/usr/lib/xwpe/syntax_def}).
@end enumerate

@subsection File format

Each language definition consists of the following fields, one per line:

@enumerate
@item
@strong{File extension} (string): the suffix that triggers this language
(e.g.@: @code{.c}).

@item
@strong{Number of keywords} (integer).

@item
@strong{Keywords} (strings): the reserved words, one per line or
space-separated.

@item
@strong{Number of multi-character operators} (integer).

@item
@strong{Multi-character operators} (strings): operators longer than one
character (e.g.@: @code{==}, @code{!=}, @code{<<}).

@item
@strong{Single-character operators} (string): all single-character
operators concatenated (e.g.@: @samp{+-/*%=|&!.?:,}).

@item
@strong{Comment start} (string): the opening comment delimiter
(e.g.@: @code{/*}).

@item
@strong{Comment end} (string): the closing comment delimiter
(e.g.@: @code{*/}).

@item
@strong{Line comment} (string): the single-line comment marker
(e.g.@: @code{//}).

@item
@strong{Column-dependent comment characters} (string): for languages
where comment status depends on column position (e.g.@: Fortran).

@item
@strong{Special single characters} (string of 6 characters):
@enumerate a
@item Character for string constants (typically @code{"}).
@item Character for character constants (typically @code{'}).
@item Preprocessor command character (typically @code{#}).
@item Quote/escape character (typically @code{\}).
@item Line-continuation character (typically @code{\}).
@item Case-insensitivity flag (non-empty = case insensitive).
@end enumerate

@item
@strong{Comment column} (integer): column for comments (-1 for none).

@item
@strong{Continuation column} (integer): column for line continuation
(-1 for none).

@item
@strong{End-of-line comment column} (integer): column for end-of-line
comments (1000 for none).
@end enumerate

The default @file{syntax_def} shipped with xwpe includes definitions
for C, C++, Fortran, Pascal, Java, Perl, Python, shell, Makefile, and
several other languages.

@section X11 resources

@cindex X resources
@cindex Xwpe class

The X11 binaries (@command{xwpe}, @command{xwe}) accept standard X
resources.  The application name is @code{xwpe} or @code{xwe}; both
belong to the @code{Xwpe} class.

@table @code
@item font (class Font)
The font to use for text display.  Must be a fixed-width font.
Default: @code{8x13}.

@item geometry (class Geometry)
Preferred window size and position.  Sizes smaller than 80x25 are
ignored.

@item iconic (class Iconic)
Start as an icon if set to @code{yes}.  Equivalent to the @option{-iconic}
command-line option.  (Documented since v1.4.)

@item color1 through color16 (class Color1 through Color16)
The 16 colours used by the interface.  The default set resembles the
standard PC colour palette.

Suggested font sizes for X11: @code{8x13}, @code{9x15}, @code{10x20},
@code{8x13bold}, @code{9x15bold}, @code{10x20bold}.  (Documented since v1.4.)
@end table

Example @file{~/.Xresources} entries:

@example
xwpe*font: 9x15
xwpe*geometry: 120x40
xwpe*color1: #000000
@end example

Apply with @command{xrdb -merge ~/.Xresources} before starting xwpe.

@section Font recommendations

@cindex fonts
@cindex Terminus
@cindex JetBrains Mono

xwpe requires a fixed-width (monospace) font.  The font is not chosen
by xwpe itself in terminal mode --- it comes from your terminal emulator
or console configuration.

@subsection Terminal emulators (wpe in xterm, gnome-terminal, kitty, etc.)

Set the font in your terminal emulator's preferences.  Recommended:

@table @strong
@item JetBrains Mono
Modern monospace font with excellent hinting and readability at all
sizes.  Good for daily use.
@code{sudo apt install fonts-jetbrains-mono}

@item Terminus
Bitmap font that reproduces the crisp, pixel-perfect look of 1990s
terminals.  Best for the classic xwpe experience.
@code{sudo apt install xfonts-terminus}

@item Your terminal's default
Most terminal emulators ship with a good monospace font (e.g.@:
Noto Mono, DejaVu Sans Mono).  These work fine with xwpe.
@end table

@subsection Linux console (wpe on a tty without X11)

The console uses a framebuffer font, changed with @command{setfont}:

@example
# Install Terminus for the console
sudo apt install console-terminus

# Change font in the current tty (takes effect immediately)
setfont Lat15-Terminus16

# Now run xwpe
wpe myfile.c
@end example

To make the font permanent, edit @file{/etc/default/console-setup}:

@example
CODESET="Lat15"
FONTFACE="Terminus"
FONTSIZE="16"
@end example

Then run @command{sudo setupcon} or reboot.

@subsection X11 mode (xwpe/xwe)

The X11 binaries use the @code{8x13} bitmap font by default.  Change it
with the @option{-fn} flag or an X resource:

@example
xwpe -fn 9x15 myfile.c
@end example

Or in @file{~/.Xresources}:

@example
xwpe*font: 9x15
@end example

Available bitmap fonts: @code{8x13}, @code{9x15}, @code{10x20}, and
their bold variants (@code{8x13bold}, @code{9x15bold}, @code{10x20bold}).
These are crisp bitmap fonts that do not suffer from antialiasing blur.

@section Recovery mode

@cindex recovery
@cindex crash recovery
@cindex .ESV files

If xwpe receives a signal (except @code{SIGKILL}), it saves all internal
buffers to files with the @file{.ESV} extension in the current directory.

To recover a crashed session:

@example
wpe -r
@end example

This restores all files that were open when the crash occurred.
