.\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.pso gpxsplit-config --format=man
.TH GPXSPLIT\-CHUNK 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
gpxsplit\-chunk \- split GPX route into small chunks
.br
.ne 5
.SH SYNOPSIS
.B gpxsplit\-chunk
\*[ade_standard_synopsis_component]
[
.B \-\-suffixes=\fIsuffix1\fB,...
]
[
.B \-\-renumber
]
{
.B \-\-count=\fIcount
|
.B \-\-regex=\fIregex
}
.I gpx\-file
.br
.ne 5
.SH DESCRIPTION
.B Gpxsplit\-chunk
converts one GPX file containing one large route into many GPX files each containing one small section of that route,
either limiting the maximum number of routepoints in each output file or specifying a regular expression for the
routepoints to be at the chunk boundaries.
.br
.ne 5
.SH CONFIGURATION
GPS displays may not be wide enough to display the whole of route's name. 
For this reason, if you name your routes according to the following format:
.IP
\fInumber\-or\-word\fB\-\fIdescription\fR
.PP
for example:
.IP
.B 123\ \-\ Ammersee\ round\-trip (128km)
.PP
then
.B gpxsplit\-chunk
will set the route name to 
.I number\-or\-word
in the GPX file, for example:
.IP 
.B 123
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP
.B \-\-suffixes=\fIsuffix1\fB,...
Normally chunks are named after the route's name with suffixes
.B .00\fR, .01\fR, ... appended.
Sometimes it can be desirable to use other suffixes, for example
.B .outward\fR and \fB.return\fR. This option facilitates this. It is typically
only useful for splitting a loop into an outward and return chunk, and then in conjunction with the
.B \-\-regex=\fIregex
option.
.TP
.B \-\-renumber
Routepoints will be renumbered 
.B RPT001\fR, \fBRPT002\fR, ...
with the number of digits being just enough to ensure all routepoints' names are the same length.
.TP
.B \-\-count=\fIcount
Chunks will contain at most the specified number of routepoints.
This option is intended to help Garmin Etrex owners with self-drawn routes exceeding 250 routepoints.
.TP
.B \-\-regex=\fIregex
Chunks will be delimited by routepoints matching the specified regular expression.
.br
.ne 5
.SH EXIT STATUS
On success
.B gpxsplit\-chunk
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
None.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
Here is the output from chopping a large GPX file called 01.gpx (and containing a route called 01)
into chunks of 250 routepoints:
.B 01.gpx\fR:
.IP
.nf
.fam C
user$ \fBls -1rt\fR
01.gpx
user$ \fBgpxsplit-chunk -v --count=250 01.gpx\fR
gpxsplit-chunk: INFO: 01.gpx: processing file ...
gpxsplit-chunk: INFO: 01: processing route ...
user$ \fBls -1rt\fR
01.gpx
01.00.gpx
01.01.gpx
01.02.gpx
01.03.gpx
01.04.gpx
user$
.fam T
.fi
.br
.ne 5
.SH CAVEATS
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B gpxsplit\-chunk\fR.
.br
.ne 5
.SH SEE ALSO
gpxsplit\-chunk-config(1), gpxsplit\-unbundle(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 2017-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]