.Dd November 14, 2021
.Dt YWALK 1
.Os
.Sh NAME
.Nm ywalk
.Nd a fast-travel companion for The Elder Scrolls III: Morrowind
.Sh SYNOPSIS
.Nm
.Op Fl T
.Op Fl m Ar modes
.Op Fl M Ar modes
.Op Fl P Ar place
.Op Fl w Ar weighting_mode
.Op Ar place ...
.Nm
.Op Fl h
.Sh DESCRIPTION
.Nm
is a fast-travel companion for The Elder Scrolls III: Morrowind.
It can print out fast-travel information for a given place, or calculate
the quickest fast-travel route between a set of places.
.Pp
Place names are as they appear in the game, for example
.Dq Sadrith Mora
or
.Dq Ald'ruhn .
.Pp
If no
.Ar place
is given,
.Nm
lists all places in its database.
If only one
.Ar place
is given, the program will print out direct connections to and from that
place.
Additionally, a reachability map is printed, showing how easy it is to
travel from the given place to any other on the map.
.Pp
If two or more
.Ar places
are given,
.Nm
will calculate the best route through all of them.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl h
Shows the integrated help page and exits.
.It Fl m Ar modes
Allows only the use of the given modes of transport, separated by
commas.
The modes of transport are as follows:
.Pp
.TS
tab(/);
l |l |l
lb |l |l.
Value/Name/Notes
=
almsivi/Almsivi Intervention/
boat/Boat/
caravan/Caravan/Only in Tamriel Rebuilt
divine/Divine Intervention/
foot/Walking/Used to access Imperial Forts
guide/Guild Guide/
propylon/Propylon Chambers/Includes the Master Index
recall/Recall/
river_strider/River Strider/Only in Tamriel Rebuilt
silt_strider/Silt Strider/
.TE
.It Fl M Ar modes
Avoids the use of the given modes of transport, separated by commas.
.It Fl P Ar place
Avoids traveling through the given place.
This option can be given multiple times.
.It Fl T
Avoids using modes of travel that are based on teleportation.
Specifically this excludes the Guild Guide, any Propylon-based travel,
and the Recall and Intervention spells.
This mode is useful if
.Nm
should find a path that is suitable for escort missions.
.It Fl w Ar weighting_method
Uses the given weighting method when determining the best path.
The weighting methods are as follows:
.Bl -tag -width Ds
.It Sy least-hop
Optimizes for the smallest number of hops between places.
.It Sy least-time
Optimizes for the quickest journey measured by in-game hours.
.El
.Pp
This option overrides any method given in the configuration file.
.El
.Sh CONFIGURATION
Configuration is done using a configuration file.
The file format consists of key-value pairs collected in groups:
.Bd -literal -offset indent
[misc]
data = tr-travels
recall = Tel Uvirith
.Ed
.Pp
The options for the
.Em misc
group are as follows:
.Bl -tag -width Ds
.It Sy data
The base name of the data file to use when building the travel network.
See
.Sx DATA FILES
for more information on the data file format and location.
.Pp
The default installation includes the following data files:
.Bl -tag -width Ds -offset indent
.It Sy goty
Definitions for the vanilla Game of the Year edition of Morrowind.
.It Sy tr-travels
Definitions for the Game of the Year edition of Morrowind including
Tamriel Rebuilt's
.Sy TR_Travels
plugin.
.El
.Pp
The default is
.Sy goty .
.It Sy recall
Specifies which place is accessible through the Recall spell.
This should be one of the places defined in the data file.
.Pp
By default no Recall destination is set.
.It Sy weighting_method
Specifies which weighting method to use.
See the
.Fl w
option for details.
.Pp
The default is
.Sy least-time .
.El
.Sh DATA FILES
.Nm
constructs its travel network by reading connection definitions from a
text file.
A connection definition consists of the origin and destination place,
the mode of transport, and the amount of in-game hours needed to make
the journey.
.Pp
The first line of a data file defines the column names.
Values are separated by the tab character.
.Nm
expects the following column names to be available:
.Bl -tag -width Ds
.It Sy Origin
The origin of a connection.
.It Sy Destination
The destination of a connection.
.It Sy Mode
The mode of transport, given by its full name.
.It Sy Time
The amount of in-game hours needed to complete the journey.
.El
.Pp
The following lines are the connection definitions, with values
separated by the tab character.
.Sh FILES
.Bl -tag -width Ds
.It Pa $XDG_CONFIG_HOME/ywalk/config
The configuration file for
.Nm .
.It Pa $XDG_DATA_HOME/ywalk
The base directory for data files making up the travel network.
.El
.Pp
.Nm
adheres to the XDG Base Directory Specification.
.Pp
If $XDG_CONFIG_HOME is unset or empty, it will default to
.Pa ~/.config .
.Pp
If $XDG_DATA_HOME is unset or empty, it will default to
.Pa ~/.local/share .
.Sh EXAMPLES
To print information about travel options in Vivec:
.Pp
.Dl ywalk Vivec | less
.Pp
To print the shortest path between Vivec and Gnisis:
.Pp
.Dl ywalk Vivec Gnisis
.Pp
To exclude the use of Almsivi and Divine intervention:
.Pp
.Dl ywalk -M almsivi,divine Vivec Gnisis
.Pp
To exclude any teleportation-based transport:
.Pp
.Dl ywalk -T Vivec Gnisis
.Pp
To add an intermediate stop in Vos:
.Pp
.Dl ywalk -T Vivec Vos Gnisis
.Pp
To avoid Ebonheart on the way:
.Pp
.Dl ywalk -T -P Ebonheart Vivec Vos Gnisis
.Pp
To make sure to use the least amount of hops:
.Pp
.Dl ywalk -T -P Ebonheart -w least-hop Vivec Vos Gnisis
.Sh AUTHORS
.An -nosplit
.Nm
was written by
.An Wolfgang Müller Aq Mt wolf@oriole.systems