\input texinfo.tex   @c -*-texinfo-*-
@c %**start of header
@setfilename trip-user-guide.info
@documentencoding UTF-8
@c Automake automatically updates version.texi to @set VERSION and
@c @set UPDATED to appropriate values.
@include version-ug.texi
@settitle Trip Server User Guide for version @value{VERSION}
@c @paragraphindent none
@c %**end of header

@direntry
* trip-user-guide: (trip-user-guide).   User guide for TRIP
@end direntry

@copying
This User Guide is for using Trip, version @value{VERSION},
@value{UPDATED} in a browser.  Trip is an application supporting trip
recording and itinerary planning.

Copyright @copyright{} 2021-2026 Frank Dean
@end copying

@titlepage
@title Trip Server User Guide
@author Frank Dean
@page
@vskip 0pt plus 1filll
@insertcopying

@end titlepage

@contents

@ifnottex
@node Top, Introduction
@top Trip Server User Guide
@insertcopying
@end ifnottex

@menu
* Introduction::                Introduction to Trip Server
* Overview::                    Overview of Trip Server
* Remote Logging::              Logging current location to a Trip server
* Tracking::                    Location tracking
* Tracker Info::                Information about tracking configuration
* Track Sharing::               Controlling sharing of tracking information
* Itineraries::                 Itinerary management
* Itinerary Search::            Searching itineraries
* My Account::                  Account management
* Shortcut Keys::
* Concept Index::               Index

@detailmenu
 --- The Detailed Node Listing ---

Tracking

* List Tracks::
* Show Map::
* Download Tracks::
* Copy Tracks::

Tracker Info

* Download TripLogger Settings::

Track Sharing

* Amend Share Details::
* Activating and Deactivating Shares::
* Deleting Shares::

Itineraries

* Itinerary Notes::
* Map::
* Live Map::
* Sharing::
* GPX Upload::
* GPX and KML Downloads::
* Download Full Itinerary::
* Add Waypoint::
* Creating a New Route::
* Creating Waypoints using the Map::
* Amending Routes::
* Copying and Renaming Routes and Tracks::
* Copying and Pasting between Itineraries::
* Moving Waypoints::
* Joining Routes and Tracks::
* Editing Tracks::
* Split Track::
* Editing Route Points::
* Duplicating the Itinerary::
* Assigning Colours to Routes and Tracks::
* Convert Tracks to Routes::
* Simplify Track::

My Account

* Change Password::
* Upload TripLogger Settings::

Shortcut Keys

* Tracking Page Shortcut Keys::
* Tracker Info Shortcut Keys::
* Track Sharing Shortcut Keys::
* Itinerary List Shortcut Keys::
* My Account Shortcut Keys::

Track Sharing Shortcut Keys

* Location Sharing Form Shortcut Keys::

Itinerary List Shortcut Keys

* Itinerary Edit Shortcut Keys::
* Itinerary Shortcut Keys::

Itinerary Shortcut Keys

* Itinerary Sharing Shortcut Keys::
* Itinerary Import Shortcut Keys::
* Itinerary Track Edit Shortcut Keys::
* Itinerary Track Segement Edit Shortcut Keys::
* Itinerary Route Edit Shortcut Keys::
* Itinerary Join Path Shortcut Keys::

@end detailmenu
@end menu

@node Introduction, Overview, Top, Top
@chapter Introduction
@cindex Introduction to Trip Server

TRIP - Trip Recording and Itinerary Planner, is a web-based application
supporting trip recording and itinerary planning.

The intended use is for a hiker, mountain-biker or other adventurer, to be
able to publish and share their planned itinerary, then subsequently log their
positions at intervals, allowing someone else to be able to monitor their
progress.

In the event of contact being lost, the plans and tracking information can be
passed to rescue services etc., to assist with locating the missing
adventurer.

@set tripserverurl https://www.fdsd.co.uk/trip-server-2/

The application is
@url{https://en.wikipedia.org/wiki/Open-source_software, open-source}
and can be obtained from
@url{@value{tripserverurl}}.

@c [TripLogger]: https://www.fdsd.co.uk/triplogger/ "TripLogger Remote for iOS"
@set triploggerurl https://www.fdsd.co.uk/triplogger/
@c [GPSLogger]: https://gpslogger.app "A battery efficient GPS logging application"
@set gpsloggerurl https://gpslogger.app
@c [OpenStreetMap]: https://www.openstreetmap.org/
@set osmurl https://www.openstreetmap.org/
@c [gpx]: https://www.topografix.com/gpx.asp "The GPX Exchange Format"
@set gpxurl https://www.topografix.com/gpx.asp
@c [Markdown]: https://daringfireball.net/projects/markdown/ "Markdown is a text-to-HTML conversion tool for web writers."
@set markdownurl https://daringfireball.net/projects/markdown/

The following features are provided:

@itemize @bullet
@item
Remote tracking client applications such as
@url{@value{triploggerurl},TripLogger Remote for iOS} or
@url{@value{gpsloggerurl},GPSLogger for Android} can be used to submit
locations to the server.

@item
Sharing tracks with others.

@item
Viewing tracks on a map provided by a tile server,
e.g. @url{@value{osmurl},OpenStreetMap tiles.}

@cindex Markdown
@item
Creating and sharing itineraries using the
@url{@value{markdownurl},Markdown markup language.}

@item
Using the map, interactively creating routes and waypoints for an itinerary.

@item
Uploading and downloading routes, tracks and waypoints for an itinerary as a
@url{@value{gpxurl},GPX} file.

@item
Viewing routes, tracks and waypoints of an itinerary on the map.

@item
Splitting, simplifying and joining routes and tracks.

@item
Deleting individual points from routes and tracks.

@item
Account maintenance -- uploading @url{@value{triploggerurl},,TripLogger} settings.

@item
Account maintenance -- password change.

@item
Itinerary shares report -- list shared itineraries including nicknames.

@item
Itinerary search by coordinate and radius.

@item
Administration -- user management.

@item
Administration -- tile usage report.
@end itemize

@node Overview, Remote Logging, Introduction, Top
@chapter Overview
@cindex Overview of Trip Server

To access the system, you will need to request the administrator of the TRIP
installation to create an account for you, using your e-mail address and
providing you with an initial password.  You should @ref{Change Password,
change the password} after your first login.

Thereafter you will be able to login to the system using the provided e-mail
address and associated password.  The application uses nicknames to identify
users as a way of avoiding disclosure of e-mail addresses between users.  In
order to share your information with other users, you will need to know their
nickname.

@strong{Note:} nicknames are
@url{https://en.wikipedia.org/wiki/Case_sensitivity,case-sensitive.}

@c [trip-web-client]: https://www.fdsd.co.uk/trip-web-client-docs/

@node Remote Logging, Tracking, Overview, Top
@chapter Remote Logging
@cindex Remote Logging
@cindex Logging

Currently, there are three remote logging applications known to work
with @url{@value{tripserverurl}, TRIP}.

@c [Traccar Client]: https://www.traccar.org/client/
@set traccarurl https://www.traccar.org/client/

@enumerate
@item
@url{@value{gpsloggerurl},GPSLogger} for Android phones

@item
@url{@value{triploggerurl},TripLogger Remote for iOS} for Apple Watch,
iPhones and iPads

@item
@url{@value{traccarurl},Traccar Client} also for Apple iPhones and iPads
@end enumerate

@url{@value{triploggerurl},,TripLogger Remote} is an iOS application
providing various options to minimise battery use of the iPhone or iPad.
It also supports the Apple Watch Series 3 onwards.  If you would like to
help test future versions of this app, please contact
@email{support@@fdsd.co.uk}.

Instructions for configuring these application are displayed on the
@code{Tracker Info} page of the web application, @xref{Tracker Info}.
There are also @url{@value{triploggerurl},,instructions} for using the
@url{@value{triploggerurl},,TripLogger Remote app.}

@node Tracking, Tracker Info, Remote Logging, Top
@chapter Tracking
@cindex Tracking

Select @code{Tracking} from the menu to display your track log or the
track log of another user who has chosen to share theirs with you.

If another user has shared their track log with you, a selection list
titled @code{Display shared user's tracks} will be displayed.  Select
the user whose tracks you wish to see.

Specify a time and date range for the track points you wish to see.

@set hdopurl https://en.wikipedia.org/wiki/Dilution_of_precision_%28navigation%29

You can also specify a maximum Horizontal Dilution of Precision
@url{@value{hdopurl}, HDOP} value to exclude less accurate positions.

@quotation
@strong{Note:} Entering a @code{Max hdop} value will also exclude all
positions that have no HDOP value.  Whether an HDOP value is available
will depend on the features of the GPS logging application and hardware
used.
@end quotation

You can further filter the results to show only those that include a note by
selecting the @code{Show notes only} option.

@menu
* List Tracks::
* Show Map::
* Download Tracks::
* Copy Tracks::
@end menu

@node List Tracks, Show Map, Tracking, Tracking
@section List Tracks
@cindex List Tracks

Click the @code{List tracks} button to see any new locations.  The page
is not automatically refreshed when a new location is received.

@quotation
@strong{Restricted Sharing:} When a user shares their tracks with you,
they can restrict how far back you can view their track points.  In that
event, the date range shown at the top of the page may be reduced to
show the actual time period being viewed.
@end quotation

The following data is shown for each location.  The values are those sent from
the device.  The units for those values are assumed to be as follows:

@itemize
@item
Time--localised to the web browser's time zone.

@item
Latitude/Longitude--location using the WGS84 geodetic reference system.

@item
HDOP--Horizontal Dilution of Precision--estimated horizontal accuracy in metres.

@item
Altitude--metres.

@item
Speed--metres-per-second.

@item
Bearing-- degrees.

@item
Note--optional text entered by the user for the location.

@item
Provider--optional data provider, e.g. GPS, Network.

@item
Satellites--Optional value indicating how many satellites the fix was using.

@item
Battery--most recently recorded battery percentage for the GPS device, where
available.
@end itemize

To convert the speed to kilometres-per-hour, multiply by 3.6.  To convert the
speed in metres-per-second to approximate miles-per-hour, multiply by 2.24.
For an exact conversion to miles-per-hour, multiply by 3,600 then divide by
1,609.344.

@node Show Map, Download Tracks, List Tracks, Tracking
@section Show Map
@cindex Show Map

Clicking the @code{Show map} button displays all the points matching the
selection criteria on a map.

Dragging within the map area moves the map.  The map can be zoomed in and out
using the @code{plus} and @code{minus} icons at the top left-hand side of the
map.

If the installation supports more than one map layer, there will also be
a @code{stacked layer} icon beneath the zoom icons at the top left of
the map.

While you are viewing the map, if any new track points are recorded for the
user be monitored, the map should be updated within 60 seconds, showing their
latest position within the criteria previously selected.

@quotation
@strong{Live Map Date Ranges:} When new track points are recorded the
map respects the date range and other criteria you have specified.  If
the time of the new track points is outside the date range or does not
meet the other criteria, it will not be included on the map.
@end quotation

@node Download Tracks, Copy Tracks, Show Map, Tracking
@section Download Tracks
@cindex Download Tracks

@c [GIS]: https://en.wikipedia.org/wiki/Geographic_information_system "Geographic information system"
@set gisurl https://en.wikipedia.org/wiki/Geographic_information_system

Clicking the @code{Download Tracks} button initiates a browser file
download of the track points meeting the specified date range and other
selected criteria.  The downloaded file is in the common
@url{@value{gpxurl},,GPX} file format which can be imported into many
Geographic information system @url{@value{gisurl},GIS} based
applications.

@node Copy Tracks,  , Download Tracks, Tracking
@section Copy Tracks
@cindex Copy tracks

The set of track points can be copied to an itinerary as a track log.  Click
the @code{Copy} button, then navigate to the intended destination itinerary.
When the itinerary page is displayed, select the @code{Features > Edit > Paste}
menu option.

@quotation
@strong{Note:} The copy and paste operations must be performed in the
same browser session.

The copy operation does not copy the entire detail of the items being copied,
instead just copying a reference to them together with any criteria used to
select them.  Should the results change in between the copy and paste
operation, different values may be pasted from those displayed at the time the
copy was initiated.
@end quotation

@c [KML]: https://en.wikipedia.org/wiki/Keyhole_Markup_Language
@set kmlurl https://en.wikipedia.org/wiki/Keyhole_Markup_Language

@ignore
@quotation
@cindex KML
@strong{Tip:} To download the track as a @url{@value{kmlurl},,Keyhole
Markup Language (KML)} file, click the @code{Copy} button, then
temporarily create a new itinerary.  When the new itinerary page is
displayed, click the @code{Paste} button.  After a delay, the new track
will have been copied to the itinerary.  You can then select the track
and click the @code{KML download} button to download it in the KML
format.
@end quotation

@node Further Information, Tracker Info, Tracking, Top
  @section Further Information
@cindex Further Information

@itemize
@item
@url{@value{kmlurl},KML - Keyhole Markup Language}
@end itemize
@end ignore

@node Tracker Info, Track Sharing, Tracking, Top
@chapter Tracker Info
@cindex Tracker Info

Select @code{Tracker Info} from the menu to display information on
setting up a tracker client application.

@c [UUID]: https://en.wikipedia.org/wiki/Universally_unique_identifier "Wikipedia article&mdash;Universally unique identifier"
@set uuidurl https://en.wikipedia.org/wiki/Universally_unique_identifier

@cindex UUID
If you are using the @url{@value {triploggerurl},,TripLogger Remote for
iOS} app, you only need this page to ascertain the @code{Device
identifier} which is a @url{@value{uuidurl},Universally Unique
Identifier} (UUID).  All the other information is for customising
another client app.  The UUID consists of a string of 32 characters
separated by four dashes.  This value needs to be copied, ideally by
cut-and-paste, into the @code{User identifier} field in the app's
settings page.

If you think there is the slightest possibility that your UUID may have been
exposed to an unauthorised person, simply click the @code{Generate new tracking ID}
to immediately revoke the previous UUID and generate a new one.  There is
absolutely no harm in creating new ones as frequently as you like.  Just make
sure to update the client application you are using with the new UUID and test
that it successfully reports your location to the remote server.

@menu
* Download TripLogger Settings::
@end menu

@node Download TripLogger Settings,  , Tracker Info, Tracker Info
@section Download TripLogger Settings
@cindex Download TripLogger Settings

You can upload the settings from the
@url{@value{triploggerurl},,TripLogger Remote for iOS} app to the
website as described in @ref{Upload TripLogger Settings}.

@cindex UUID
Clicking on the @code{Download Updated TripLogger Settings} button will
download those settings, updating them with the latest user
@url{@value{uuidurl},,UUID} that you may have generated.  The settings
can then be imported into the @url{@value{triploggerurl},,TripLogger}
app.  This can be easier than trying to copy and paste the UUID from a
browser window etc.

If you have never uploaded any settings, this option creates and
downloads some default values that you can import into
@url{@value{triploggerurl},,TripLogger}.  The values used for the
default settings are configured by the administrator of your
@url{@value{tripserverurl},,TripServer} website.  This procedure is
intended for use when you are performing the app's initial
configuration.

The downloaded file contains your current UUID, so, if you intend to
share the file with someone else, you should generate a new tracking
UUID and import that into @url{@value{triploggerurl},,TripLogger} before
passing the previous file containing the old UUID to anyone else.

@node Track Sharing, Itineraries, Tracker Info, Top
@chapter Track Sharing
@cindex Track Sharing

The track points you record can be shared with another user, by nickname.

@quotation
@strong{Nicknames:} Note that nicknames are
@url{https://en.wikipedia.org/wiki/Case_sensitivity,case-sensitive.}
@end quotation

You can limit the exposure of your track points to a point in time that
is the lesser of the following:

@itemize
@item
the most recently logged point
@item
a maximum time period in any event
@end itemize

The latter period effectively overrides the former, so there is little
advantage in setting a most recently logged period of time that is
longer than the overall maximum time period.

Click on the @code{Track Sharing} menu option to display the @code{Track
Sharing} page.  The page lists any tracks you are already sharing with another
user.

Click the @code{New} button to share your tracks with another user.  Enter the
user's nickname and set any date range constraints you wish to apply.  Check
the @code{Active} checkbox when you're ready to start sharing.

@menu
* Amend Share Details::
* Activating and Deactivating Shares::
* Deleting Shares::
@end menu

@node Amend Share Details, Activating and Deactivating Shares, Track Sharing, Track Sharing
@section Amend Share Details
@cindex Amend Share Details

To amend the details of a share, select the checkbox next to the appropriate
user in the list and click @code{Edit selected}.  The details are then
displayed in the form below the list.  Amend the periods and click the
@code{Save} button to update the list of shares.

@node Activating and Deactivating Shares, Deleting Shares, Amend Share Details, Track Sharing
@section Activating and Deactivating Shares
@cindex Activating and Deactivating Shares

You can activate or deactivate location sharing by selecting one or more
nicknames from the list and clicking the @code{Activate} or @code{Deactivate} buttons.

@node Deleting Shares,  , Activating and Deactivating Shares, Track Sharing
@section Deleting Shares
@cindex Deleting Shares

Although deactivating a shared location stops the relevant user from seeing
your location history, you can delete the location sharing altogether.  The
effect is the same, other than the nickname is no longer shown in the list.
Select one or more users and click the @code{Delete selected} button.

@node Itineraries, Itinerary Search, Track Sharing, Top
@chapter Itineraries
@cindex Itineraries

Itineraries provide the ability to record information about a specific
trip, together with useful waypoints and routes.  You may also wish to
show and share previous track logs that relate to the trip or add track
logs after the trip for future reference.

Additionally you can create and modify routes and waypoints.  You can
also modify track logs.

Although routes and tracks are quite similar in that they both can
denote a path, they are treated a little differently by the system.

@itemize
@item
Routes are intended to be something that is planned.  Therefore new ones
can be created and points can be added to existing ones.  Two or more
routes can also be joined.
@item
Tracks are intended to relate to points that have been visited.  Each
point must have a time related to it.  Additionally, tracks can be split
into multiple segments.  Each segment represents a logical break in a
track, which might be due to stopping and restarting a track or losing
the GPS signal for a while.  New points cannot be added to a track.
However, points can be removed, tracks and their segments can be split
and joined.
@end itemize

Itineraries are listed in descending start date order.  Itineraries with
no dates are listed in alphabetical order prior to those with dates.

You can only edit itineraries that you created yourself.  You cannot
edit itineraries shared with you by others.

@menu
* Itinerary Notes::
* Map::
* Live Map::
* Sharing::
* GPX Upload::
* GPX and KML Downloads::
* Download Full Itinerary::
* Add Waypoint::
* Creating a New Route::
* Creating Waypoints using the Map::
* Amending Routes::
* Copying and Renaming Routes and Tracks::
* Copying and Pasting between Itineraries::
* Moving Waypoints::
* Joining Routes and Tracks::
* Editing Tracks::
* Split Track::
* Editing Route Points::
* Duplicating the Itinerary::
* Assigning Colours to Routes and Tracks::
* Convert Tracks to Routes::
* Simplify Track::
@end menu

@node Itinerary Notes, Map, Itineraries, Itineraries
@section Itinerary Notes
@cindex Itinerary Notes

To create a new itinerary, select @code{Itineraries} from the main menu
and click the @code{New} button.

When you first create an itinerary, you must give it a title and can
optionally enter start and end dates together with some descriptive
text.

@cindex Markdown
The text is interpreted following the syntax of
@url{@value{markdownurl},Markdown} as created by John Gruber.  Markdown
is a wonderful way of being able to write markup in a format that is
very presentable in its original text form and also efficiently
displayed as formatted HTML on the web.

There are various flavours of the Markdown syntax and whilst the current
implementation uses the @url{https://github.com/commonmark/cmark, cmark}
library which follows the @url{https://commonmark.org, CommonMark}
standard, it is advised that you don't use the extended features beyond
that of the original @url{@value{markdownurl}, Markdown} specification,
in case this application needs to employ a different implementation in
the future.

@node Map, Live Map, Itinerary Notes, Itineraries
@section Map
@cindex Map

The map can be rotated on touch devices by touching and twisting with
two fingers.  On a system with a keyboard, the map can be rotated by
holding down the @code{shift} and @code{alt} keys simultaneously while
dragging with the mouse.  When the map as been rotated, an arrow icon is
displayed in the top right corner of the map, pointing north.

Click on the @code{north arrow} icon to reset the map orientation.

@node Live Map, Sharing, Map, Itineraries
@section Live Map
@cindex Live Map

One or more live tracks can be viewed on an itinerary map.  From the
itinerary page, optionally select any routes, waypoints and tracks and
click the @code{Show map} button.

To see live track logs on the map, click the @code{settings (gear)} control
displayed near the top right of the map.  A list of users who are sharing
their tracks with you are displayed, including yourself.  You can modify
the start range date and time for displaying locations and also filter
the reported locations to only include those less than a maximum HDOP
value.  You can also modify how frequently the map checks for updates by
altering the value for @code{Refresh interval (seconds)}.

If your browser supports providing your position, you can use it to track your
own position.  Generally, it is likely to be better to log your locations
using one of the client applications, but this facility is provided as a
fallback, should it be more convenient to use the browser.  Bear in mind some
browsers have an option to reduce the accuracy of your position for privacy
reasons.

When the @code{Track & record yourself} checkbox is enabled, the browser will
occasionally report your position.  The positions will be added to your track
log with the @code{provider} attribute set to @code{web-browser} and shared
with any other users that you have given permission to.  You can minimise the
frequency of these updates by changing the value for @code{Tracking interval
(seconds)}.  The actual frequency of updates is ultimately dictated by the
browser.

Click the @code{Start or Apply button} to put your choices into effect.

Clicking the @code{Stop} button stops both the live updates of tracked
locations as well as stopping logging your own locations.

@node Sharing, GPX Upload, Live Map, Itineraries
@section Sharing
@cindex Sharing

Sharing of itineraries is treated quite separately to that of sharing
tracks, although when viewing an itinerary map you can choose to see the
track points shared by others even if you haven't shared the itinerary
with them.  In fact this is the only place where you can view and
monitor the progress of multiple users.

To access itinerary sharing, select the @code{Sharing} menu option from the
@code{Itinerary} tab of the the itinerary page.

The list of any existing itinerary shares is displayed.  You can choose one or
more of the shares and click @code{Activate} or @code{Deactivate} buttons to
change their activation status.  You can also choose to delete the share,
although this has the same effect as simply deactivating the share, but
additionally removes the nickname from the list.

Click the @code{New} button to start sharing the itinerary with someone else.
Enable the @code{Active} checkbox to actually enable sharing.

@node GPX Upload, GPX and KML Downloads, Sharing, Itineraries
@section GPX Upload
@cindex GPX Upload

You can import waypoints, tracks and routes from a standard GPX file.  Not all
the possible attributes within the GPX file are supported, so keep the
original if the contents might be important.

@quotation
@strong{Importing GPX Files:} Some sources of GPX files create waypoints
for every point on a route which can make a mess of an existing
itinerary resulting in a laborious cleanup operation.  If you do not
fully know the contents of a GPX file you wish to import, create a new
itinerary for temporary purposes and import the file into the temporary
itinerary.  Check the contents and delete any elements from the
itinerary that are not required.  You can then use the copy-and-paste
functionality to copy the desired contents to the ultimately intended
itinerary.
@end quotation

@node GPX and KML Downloads, Download Full Itinerary, GPX Upload, Itineraries
@section GPX and KML Downloads
@cindex GPX Downloads
@cindex KML Downloads
@cindex GPX
@cindex KML
@cindex GIS

Select one or more routes, tracks and waypoints, then select the
@code{Features > Transfer > Download GPX} menu option from the itinerary page,
to download the chosen items in the @url{@value{gpxurl},,GPX} format.

The GPX file format can be imported into many Geographic Information
System (@url{@value{gisurl},,GIS}) based applications.

The KML file
format is recognised by some GIS based applications, in particular
@url{https://earth.google.com/,Google Earth.}

@node Download Full Itinerary, Add Waypoint, GPX and KML Downloads, Itineraries
@section Download Full Itinerary
@cindex Download Full Itinerary
@cindex YAML

@c [YAML]: https://yaml.org "YAML Ain't Markup Language"
@set yamlurl https://yaml.org "YAML Ain't Markup Language"

The full details of the itinerary, including the dates, text, sharing, routes,
waypoints and tracks can be downloaded by selecting the
@code{Features > Transfer > Download Full Itinerary} menu option on the
Itinerary page.  The downloaded file is in the @url{@value{yamlurl},YAML}
format, a text file format that can be readily understood by humans.

The YAML file can either be saved and used as a long-term backup or be
imported into another instance of a
@url{@value{tripserverurl},,TripServer} application.  The itinerary can
be imported by clicking on the @code{Import} button on the itineraries
page.

If you are creating a backup, it is a good idea to also select all the GIS
attributes (routes, waypoints and tracks) and export them in the GPX format,
as this is a common format that can be imported into many other applications.

@node Add Waypoint, Creating a New Route, Download Full Itinerary, Itineraries
@section Add Waypoint
@cindex Add Waypoint

Select the @code{Features > Add waypoint} menu option of the itinerary page to
add a new waypoint to the route.

Optionally give the waypoint a name.  A valid position/location is required.

A variety of common formats are recognised when entering a position.

@quotation
@strong{Position Recognition:} To be sure that the intended format has
been recognised correctly, it is recommended you select the appropriate
source position from the @code{Display position format} selection list
and check the output matches the expected values.

@strong{Tip:} If you are having difficulty persuading the system to
recognise a particular format, enter a simple comma separated latitude
and longitude value appropriate for the region, then select the
@code{Display position format} you wish to use.  The formatting output
below the select list will indicate a format you can enter values in.
Values are case-significant.
@end quotation

@node Creating a New Route, Creating Waypoints using the Map, Add Waypoint, Itineraries
@section Creating a New Route
@cindex Creating a New Route

Optionally select one or more waypoints, routes or tracks in the
itinerary that will help to zoom the map into the intended area.

Select the @code{Features > View > Show map} menu option to display the
selected features on the map.  Pan and zoom to the desired area.

To start creating a new route, click on the @code{new route icon} at the
top right of the page.  The icon depicts a slight left turn sign.

Click on each position you want the route to follow.  When you have
finished entering all the points for the route, either click the
@code{Finish} button adjacent to the @code{new route icon} or click on
the last point of the route.

On a system with a keyboard and mouse, holding down the shift key allows a
freehand route to be created.

When you view the itinerary page all the new routes are at at the end of
the list of routes and are unnamed having only an ID.  To edit the
route's attributes, select the route in the itinerary page and select the
@code{Features > Edit > Attributes} menu option.

Click the @code{edit icon} to modifying an existing route.  Click and
drag on existing nodes, or click and drag on other parts of the route to
create a new node.  Nodes can be deleted by holding down the @code{alt}
key and clicking on the node to be deleted.  On touch screen devices
double-click the node to delete it.

@node Creating Waypoints using the Map, Amending Routes, Creating a New Route, Itineraries
@section Creating Waypoints using the Map
@cindex Creating Waypoints using the Map

In addition to being able to create routes on the itinerary map, you can add
waypoints by clicking the @code{new waypoint icon} (flag symbol) at the top
right of the page.  Click on the map at the location you wish to create a
waypoint.  A new anonymous waypoint is created.

When you view the itinerary page all the new waypoints are at at the end
of the list of waypoints and are unnamed having only an ID.  To edit the
waypoint's attributes, select the waypoint in the itinerary page and
click the @code{Edit attributes} button.

@node Amending Routes, Copying and Renaming Routes and Tracks, Creating Waypoints using the Map, Itineraries
@section Amending Routes
@cindex Amending Routes

To amend a route, select it in the itinerary page then select the
@code{Features > View > Show map} menu option of the itinerary page.  To
commence editing the routes on the itinerary map, click the @code{edit icon}
at the top right hand side of the map.  The icon represents a pencil inside a
square.

Existing points can be dragged to a new location.  To create a new point in
between the existing points, start dragging the line in between two points.  A
new point is created when you finishing dragging.

Click the @code{Save} button adjacent to the @code{edit icon} at the top
right hand side of the map to finish make changes.  Click the @code{Cancel}
button to abandon the changes.

Nodes can be deleted by holding down the @code{alt} key and clicking on
the node to be deleted.  On touch screen devices double-click the node
to delete it.

@node Copying and Renaming Routes and Tracks, Copying and Pasting between Itineraries, Amending Routes, Itineraries
@section Copying and Renaming Routes and Tracks
@cindex Copying and Renaming Routes and Tracks

Route and track names and colours can be amended by selecting the route or
track in the itinerary page and selected the @code{Features > Edit > Path}
menu option of the itinerary page.

@quotation
@strong{Copying Routes and Tracks:} To make copies of waypoints, tracks and
routes, select them in the itinerary list, click the @code{Copy} button, then
click the @code{Paste} button.
@end quotation

@node Copying and Pasting between Itineraries, Moving Waypoints, Copying and Renaming Routes and Tracks, Itineraries
@section Copying and Pasting between Itineraries
@cindex Copying and Pasting between Itineraries

Select the waypoint, routes and tracks in the itinerary list to be
copied, click the @code{Copy} button at the bottom of the itinerary
page.  Navigate to the target itinerary, then click the @code{Paste}
button.

@quotation
@strong{Copy and Paste:} The copy and paste operations must be performed
in the same browser session.

The copy operation does not copy the entire detail of the items being
copied, instead just copying a reference to them together with any
criteria used to select them.  Should the results change in between the
copy and paste operation, different values may be pasted from those
displayed at the time the copy was initiated.
@end quotation

@node Moving Waypoints, Joining Routes and Tracks, Copying and Pasting between Itineraries, Itineraries
@section Moving Waypoints
@cindex Moving Waypoints
@cindex Waypoints

To move a waypoint to a different position, select it in the itinerary
page, then select the @code{Features > View > Show map} menu option.  To
commence editing the routes on the itinerary map, click the @code{edit
icon} at the top right hand side of the map.  The icon represents a
pencil inside a square.

Drag the waypoint to the new location and click the @code{Save}
button adjacent to the @code{edit icon} at the top right hand side of
the map.

@quotation
@strong{Tip:} Multiple routes and waypoints can be selected for editing
on the map in a single session.

You can also select tracks to be displayed on the map whilst editing
routes and waypoints, but you cannot modify the tracks interactively on
the map.
@end quotation

@node Joining Routes and Tracks, Editing Tracks, Moving Waypoints, Itineraries
@section Joining Routes and Tracks
@cindex Joining Routes and Tracks
@cindex Routes
@cindex Tracks

Two different itinerary routes or itinerary tracks can be joined together to
create a single route or track.  Tracks cannot be joined to routes and vice
versa.  To simplify these instructions, both routes and tracks are referred to
as paths in these instructions.

Select all the paths to be joined and click the @code{Join paths} button
at the bottom of the itinerary page.

@quotation
@strong{Tip:} To make it easier to visualise the different paths, give
them each a different colour before attempting to join them.
@end quotation

A map is displayed showing each of the paths in their individual
colours.

Use the @code{Up} and @code{Down} buttons to reorder the paths into the
desired order.

Once satisfied with your choices, optionally edit the new path name and
select a colour.  Then click the @code{Join} button to make a copy of
the combined paths.

@node Editing Tracks, Split Track, Joining Routes and Tracks, Itineraries
@section Editing Tracks
@cindex Editing Tracks
@cindex Tracks

Tracks can be edited by;

@itemize
@item
splitting track segments

@item
splitting the track between segments to form two tracks

@item
deleting individual points
@end itemize

Select the track to be edited by clicking the @code{Edit path} button at
the bottom of the itinerary page.

@node Split Track, Editing Route Points, Editing Tracks, Itineraries
@section Split Track
@cindex Split Track

If a track has multiple segments, selecting a segment and clicking the
@code{Split track} button splits the existing track into two.  The
selected and following segments are moved from the current track to a
new one.

@subsection Split Segment
@cindex Split Segment
@cindex Segment
@cindex Track segment

Click on the segment ID to display the track segment points.

Clicking on the checkbox in the table header above the list of segments,
selects all segments and displays them on the map below.

If there are more than 10 track segment points, you can page forwards
and backwards through them.

@quotation
@strong{Tip:} Whether the checkbox in the table header was selected when
you navigate to a new page is remembered.  Therefore, selecting the
checkbox and navigating through the pages allows you to quickly review a
track segment.
@end quotation

To split a segment into two, select a single track segment checkbox and
click the @code{Split segment} button.  The selected track segment point
and all subsequent ones in the same segment are moved from the current
segment into a new segment.

@quotation
@strong{Tip:} To split a track at a particular track segment point,
split the track in two operations.  Firstly split the track segment at
that track segment point, then secondly split the track at the new track
segment.
@end quotation

@node Editing Route Points, Duplicating the Itinerary, Split Track, Itineraries
@section Editing Route Points
@cindex Editing Route Points

In addition to being able to edit routes on the itinerary map, you can perform
some operations using the @code{Features > Edit > Path} menu option of the
itinerary page which cannot be easily accomplished on the map.  E.g. Splitting
the route.  Sometimes it can also be difficult to select and delete points on
the map when they are very close together, so navigating through the points in
the @code{Edit path} mode provides another method to identify and delete them.

Editing routes is very similar to editing tracks as described above.

@node Duplicating the Itinerary, Assigning Colours to Routes and Tracks, Editing Route Points, Itineraries
@section Duplicating the Itinerary
@cindex Duplicating the Itinerary
@cindex Itinerary, duplicating

The @code{Features > Edit > Create duplicate itinerary} menu option of the
itinerary page creates a duplicate of the current itinerary.  The new
itinerary is displayed once it has been created.

@node Assigning Colours to Routes and Tracks, Convert Tracks to Routes, Duplicating the Itinerary, Itineraries
@section Assigning Colours to Routes and Tracks
@cindex Assigning Colours to Routes and Tracks
@cindex Colours, assigning colours to routes and tracks
@cindex Routes, assigning colours
@cindex Tracks, assigning colours

This option is intended to make it easy to quickly give routes and
tracks different colours, to more easily identify them on the map.

Select select the routes and tracks you wish to change and choose the
@code{Assign colours to routes and tracks} from the @code{Edit} menu of the
@code{Features} tab.  After confirmation each colour defined on the system is
assigned to each route and then each track in sequence.  If there are more
tracks and routes selected than there are colours, the colours are repeated
from the beginning again.

@node Convert Tracks to Routes, Simplify Track, Assigning Colours to Routes and Tracks, Itineraries
@section Convert Tracks to Routes
@cindex  Convert Tracks to Routes
@cindex Routes, converting to tracks
@cindex Tracks, converting to routes

To create routes from tracks or vice versa, select the routes and tracks you
wish to convert and choose the @code{Features > Edit > Convert tracks and
routes} menu option.  After confirmation, a copy of each route and track is
created.

@quotation
@strong{Note:} When converting a route to a track, each track point is given a
time stamp from the early 20th century, with one second intervals, to make it
clear they are artificial.  (Some systems reject tracks that have no
timestamps.)  Conversely converting tracks to routes loses the time
information.
@end quotation

@node Simplify Track,  , Convert Tracks to Routes, Itineraries
@section Simplify Track
@cindex Simplify Track
@cindex Track, simplifying

Sometimes, a track log has a high frequency of points.  You might wish
to reduce the number of points, (simplifying the path), perhaps before
converting it to a route, or just to make it smaller to fit the maximum
point constraint of some software or GPS systems.

@set openlayersurl https://openlayers.org/

Trip uses the
@url{https://en.wikipedia.org/wiki/Ramer%E2%80%93Douglas%E2%80%93Peucker_algorithm,
Ramer---Douglas---Peucker} simplification algorithm implemented by the
@url{https://openlayers.org/,OpenLayers mapping project}.

Select a single track, then choose the @code{Features > Edit > Simplify track}
menu option.

The selected track is displayed on a map.  A slider control is used to
change the @code{tolerance} value.  The higher the tolerance value is,
the more likely points are reduced.

The display shows the total number of points originally in the track together
with an estimated total number of points that remain after simplification.  A
preview of the estimated final track is displayed on the map, together with
the original track shown translucent, so that you can judge the impact of the
simplification.

The first and last point of each track segment are always retained.  If that
behaviour is undesired, consider joining the segments before-hand, as
described in @ref{Joining Routes and Tracks}.

Selecting the @code{Save} button saves a copy of the track, appending
@code{(simplified)} to the track name.

@quotation
@strong{Note:} Due to some technical implementation limitations, the number of
points in the final track may differ from the preview by a small amount, so
checking the new track after simplification is advised.
@end quotation

@quotation
@strong{Tip:} To simplify a route, convert it to a track, simplify the track
and convert the new track to a route.  However, if the route contains
individual point attributes (name, comment, description or symbol) these are
lost when converting to a track.
@end quotation

@node Itinerary Search, My Account, Itineraries, Top
@chapter Itinerary Search
@cindex Itinerary Search
@cindex Search, itinerary

Itineraries can be searched using either a full text based search or by
location and a radius.  Click the @code{Search} button at the bottom of
the @code{Itineraries} list page to show the search form.

Full text searches search the title and description of the itinerary
using keywords.  Enter all the required keywords separated with spaces.
All the keywords must exist within the combined itinerary title and
description for a successful match.  A dictionary for the default
language is used such that words like ``track'' will match variants like
``tracking'', ``tracked'', ``tracks'', ``run'' will match ``running'',
``ran'' etc.  @strong{Note:} that using
@url{https://en.wikipedia.org/wiki/Stop_word, stop words} such as
``the'', ``a'', ``in'' in the search terms are ignored.  Searching using
only stop words will not find any itineraries.

For a location search, enter the position of the centre of the area to
search, in any of the formats supported when adding a waypoint.
@ref{Add Waypoint} Enter the radius in kilometres in the @code{Distance}
input field.  (E.g. 0.125 for 125 metres.)  Click @code{Search} to
perform the search.

@quotation
@strong{Note:} If a waypoint been copied using the
@code{Features > Edit > Copy} menu option of the Itinerary page, it is used to
pre-populate the search position for convenience.  E.g. if you want to search
an area, drop a waypoint on the itinerary map, copy it using the menu option,
then initiate the search.
@end quotation

The itinerary search results shows a list of itineraries that have either
waypoints, tracks or routes with a point lying within the search radius.  Use
your browser's options to open itineraries of interest in a separate tab or
window to examine their contents without losing your search results.

@quotation
@strong{Note:} A path that intersects with the search radius but doesn't
actually have a point within it, is excluded from the results.
@end quotation

@node My Account, Shortcut Keys, Itinerary Search, Top
@chapter My Account
@cindex My Account
@cindex Account

@menu
* Change Password::
* Upload TripLogger Settings::
@end menu

@node Change Password, Upload TripLogger Settings, My Account, My Account
@section Change Password
@cindex  Change Password
@cindex Password, change

Click on the @code{Change password} option of the Account page to change your
current password.  You need to enter your current password before any changes
can be made.  Then enter your new password.

As you type the password, the system evaluates it's apparent strength.
The @code{Save} button remains disabled until the password is apparently
sufficiently strong.  Repeat the password in the next field, then click
the @code{Save} button.  Hints and warnings are displayed to assist in choosing
a strong password.

@node Upload TripLogger Settings,  , Change Password, My Account
@section Upload TripLogger Settings
@cindex Upload TripLogger Settings
@cindex Settings, TripLogger uploading

If you are using the @url{@value{triploggerurl},,TripLogger Remote for iOS
app}, you can export your settings from TripLogger, save them to a file, then
upload them by clicking the @code{Choose File} option, selecting the saved
settings file and then clicking the @code{Upload} button to store the settings
in the database.  This can act as a quick backup of your settings, but can
also make it easier to update your unique user @url{@value{uuidurl},,UUID.}
@xref{Download TripLogger Settings}

@node Shortcut Keys, Concept Index, My Account, Top
@chapter Shortcut Keys
@cindex Shortcut keys
@cindex Access keys
@cindex Keys, access keys, shortcut keys

The application implments shortcut keys (also known as access keys) for most
options.  Unfortunately, whilst the HTML specification allows such keys to be
defined, it does not specify a method for indicating where they exist.

See
@url{https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/accesskey,accesskey}
in the MDN developer documentation for a list of the key combinations to use
to activate a shortcut key.

The implemented shortcuts keys are listed in the following sub-sections.

@menu
* Tracking Page Shortcut Keys::
* Tracker Info Shortcut Keys::
* Track Sharing Shortcut Keys::
* Itinerary List Shortcut Keys::
* My Account Shortcut Keys::
@end menu

@node Tracking Page Shortcut Keys, Tracker Info Shortcut Keys, Shortcut Keys, Shortcut Keys
@section Tracking Page Shortcut Keys
@cindex Tracking Page Shortcut Keys

@table @code

@item l

List tracks

@item m

Show map

@item d

Download tracks

@item y

Copy

@item r

Reset

@end table

@node Tracker Info Shortcut Keys, Track Sharing Shortcut Keys, Tracking Page Shortcut Keys, Shortcut Keys
@section Tracker Info Shortcut Keys
@cindex Tracker Info Shortcut Keys

@table @code

@item g

Generate new tracking ID

@item d

Download TripLogger Settings

@end table

@node Track Sharing Shortcut Keys, Itinerary List Shortcut Keys, Tracker Info Shortcut Keys, Shortcut Keys
@section Track Sharing Shortcut Keys

@table @code

@item a

Toggles checkboxes in list of shares

@item v

Activate

@item x

Deactivate

@item d

Delete selected

@item e

Edit selected

@item w

New

@end table

@menu
* Location Sharing Form Shortcut Keys::
@end menu

@node Location Sharing Form Shortcut Keys,  , Track Sharing Shortcut Keys, Track Sharing Shortcut Keys
@subsection Location Sharing Form Shortcut Keys
@cindex Location Sharing Form Shortcut Keys

@table @code

@item a

Activate

@item s

Save

@item c

Cancel

@item r

Reset

@end table

@node Itinerary List Shortcut Keys, My Account Shortcut Keys, Track Sharing Shortcut Keys, Shortcut Keys
@section Itinerary List Shortcut Keys
@cindex Itinerary List Shortcut Keys

@table @code

@item n

next page

@item p

previous page

@item g

goto page

@item w

New itinerary

@item i

Import itinerary

@item s

Search

@item r

Itinerary shares report

@end table

@menu
* Itinerary Edit Shortcut Keys::
* Itinerary Shortcut Keys::
@end menu

@node Itinerary Edit Shortcut Keys, Itinerary Shortcut Keys, Itinerary List Shortcut Keys, Itinerary List Shortcut Keys
@subsection Itinerary Edit Shortcut Keys
@cindex Itinerary Edit Shortcut Keys

@table @code

@item s

Save

@item c

Cancel

@item r

Reset

@end table

@node Itinerary Shortcut Keys,  , Itinerary Edit Shortcut Keys, Itinerary List Shortcut Keys
@subsection Itinerary Shortcut Keys
@cindex Itinerary Shortcut Keys

@table @code

@item i

select itinerary tab

@item f

select features tab

@item e

Edit

@item c

Close

@item m

Show map

@item a

toggle selecting all checkboxes

@item r

toggle selecting all routes

@item w

toggle selecting all waypoints

@item t

toggle selecting all tracks

@item y

Copy

@item b

Edit Attributes

@item l

Assign colours to routes and tracks

@item z

Edit Path

@item p

Paste

@item q

Add waypoint

@item v

Convert tracks and routes

@item s

Simplify track

@item d

Delete selected items

@item j

Join paths

@item u

Upload GPX

@item g

Download GPX

@item k

Download KML

@item n

Download full itinerary

@item o (read-only mode)

Show Markdown

@item h (read-only mode)

Hide Markdown

@item x

Create duplicate itinerary

@end table

@menu
* Itinerary Sharing Shortcut Keys::
* Itinerary Import Shortcut Keys::
* Itinerary Track Edit Shortcut Keys::
* Itinerary Track Segement Edit Shortcut Keys::
* Itinerary Route Edit Shortcut Keys::
* Itinerary Join Path Shortcut Keys::
@end menu

@node Itinerary Sharing Shortcut Keys, Itinerary Import Shortcut Keys, Itinerary Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Sharing Shortcut Keys
@cindex Itinerary Sharing Shortcut Keys

@table @code

@item v

Activate

@item x

Deactivate

@item d

Delete selected

@item w

New

@item c

Close

@end table

@node Itinerary Import Shortcut Keys, Itinerary Track Edit Shortcut Keys, Itinerary Sharing Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Import Shortcut Keys
@cindex Itinerary Import Shortcut Keys

@table @code

@item f

Choose file

@item u

Upload

@item c

Cancel

@end table

@node Itinerary Track Edit Shortcut Keys, Itinerary Track Segement Edit Shortcut Keys, Itinerary Import Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Track Edit Shortcut Keys
@cindex Itinerary Track Edit Shortcut Keys

@table @code

@item a

toggle selecting all checkboxes

@item g

Go

@item n

next page

@item p

previous page

@item d

Delete segments

@item s

Split track

@item m

Merge segments

@item c

Close

@end table

@node Itinerary Track Segement Edit Shortcut Keys, Itinerary Route Edit Shortcut Keys, Itinerary Track Edit Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Track Segment Edit Shortcut Keys
@cindex Itinerary Track Segment Edit Shortcut Keys

@table @code

@item a

toggle selecting all checkboxes

@item g

Go

@item n

next page

@item p

previous page

@item d

Delete points

@item s

Split segment

@item c

Close

@end table

@node Itinerary Route Edit Shortcut Keys, Itinerary Join Path Shortcut Keys, Itinerary Track Segement Edit Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Route Edit Shortcut Keys
@cindex Itinerary Route Edit Shortcut Keys

@table @code

@item a

toggle selecting all checkboxes

@item g

Go

@item n

next page

@item p

previous page

@item d

Delete points

@item s

Split route

@item r

Reverse

@item c

Close

@item u

Up (first path)

@item d

Down (first path)

@end table

@node Itinerary Join Path Shortcut Keys,  , Itinerary Route Edit Shortcut Keys, Itinerary Shortcut Keys
@subsubsection Itinerary Join Path Shortcut Keys
@cindex Itinerary Join Path Shortcut Keys

@table @code

@item n

Name

@item l

Colour

@item j

Join

@item c

Cancel

@end table

@node My Account Shortcut Keys,  , Itinerary List Shortcut Keys, Shortcut Keys
@section My Account Shortcut Keys
@cindex My Account Shortcut Keys

@table @code

@item f

Choose File

@item u

Upload

@end table

@node Concept Index,  , Shortcut Keys, Top
@unnumbered Index

@printindex cp

@bye
