@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

Auto-indent is configured in @samp{Options @result{} Editor}: choose
@samp{Source files} (only files with a known compiler extension),
@samp{All files}, or @samp{Disabled}, and set the indent column.  The setting
is saved with @samp{Options @result{} Save Options}.

@quotation Note
In older xwpe this was bound to @kbd{Alt-Y} / @kbd{Alt-W} / @kbd{Alt-V}.
Those keys are now @samp{Show Buffer} (Edit menu), the @samp{Window} menu, and
@samp{Previous Error} (Run) respectively; auto-indent moved into the dialog
above.
@end quotation

@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

The first file found wins, and xwpe stops looking.  This means a
@strong{personal copy completely shadows the system one}: if
@file{$HOME/.xwpe/syntax_def} exists, the system file is never read.

@quotation Note
A personal @file{$HOME/.xwpe/syntax_def} left over from an older install
will @emph{hide languages added in newer versions} -- those new rules
live only in the updated system file, which the stale personal copy
shadows.  The symptom is that a file of the new language shows no
per-token colouring (it is drawn in a single base colour).  To pick up
new languages, refresh or remove your personal copy, e.g.@:

@example
cp /usr/lib/xwpe/syntax_def ~/.xwpe/syntax_def   # refresh, or
rm ~/.xwpe/syntax_def                             # fall back to system
@end example
@end quotation

@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,
Algol 68 (@code{.a68}/@code{.alg}), and, for the languages debugged over
DAP, Go (@code{.go}), Rust (@code{.rs}) and Scala (@code{.scala}), among
several others.

@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)

Since 1.6.0 the X11 build renders text with @b{Xft} -- anti-aliased,
through Cairo and Pango -- not the old @code{8x13} bitmap core font of the
1.5 era.  The font @emph{family} follows your desktop's monospace setting:
xwpe reads @code{org.gnome.desktop.interface monospace-font-name} via
@command{gsettings} and falls back to fontconfig's @code{monospace} alias
when that is unset.  To change the editor font, set your system monospace
font, e.g.@:

@example
gsettings set org.gnome.desktop.interface monospace-font-name 'JetBrains Mono 11'
@end example

@noindent
or point fontconfig's @code{monospace} alias at the family you want.  The
@emph{size} in that setting is honoured (@samp{@dots{} 13} renders at 13
point).  To override the size -- handy headless, over SSH, or on macOS where
there may be no desktop setting -- set @env{XWPE_FONT_SIZE}:

@example
XWPE_FONT_SIZE=14 xwpe myfile.c
@end example

@quotation Note
The legacy @option{-fn} flag and @code{xwpe*font} X-resource selected a core
@emph{bitmap} font; they have no effect on the default Xft build and apply
only to a build made without Xft.
@end quotation

@subsection The Alt key in X11 (altMask)

@cindex altMask
@cindex Alt key, X11
@cindex Meta key
@cindex XQuartz

The menus and the @kbd{Alt-Q} language-server prefix need an Alt (Meta)
modifier.  The X11 build uses @code{Mod1} (the usual Linux Alt) by
default.  If your X server carries Alt on a different modifier -- notably
@b{XQuartz on macOS}, where the Option key is mapped elsewhere -- point
xwpe at it with the @code{altMask} resource:

@example
xwpe*altMask: mod1
@end example

It accepts @code{mod1} through @code{mod5}.  Run @command{xmodmap} to see
which modifier carries @code{Alt_L}/@code{Alt_R} (or @code{Meta_L}) on
your server, then set @code{altMask} to match.  On XQuartz, also enable
@samp{Option keys send Alt_L and Alt_R} in the XQuartz preferences so the
Option key reaches xwpe as Alt at all.

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