.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "IRCMARKERS 1"
.TH IRCMARKERS 1 "2023-10-24" "ircmarkers" "User Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
ircmarkers \- place markers on maps at given coordinates
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBircmarkers\fR [\-q] [\-o command] [\-y \fIsouth/north\fR \-x \fIwest/east\fR] \fIconfig\fR [\fIinputmap\fR \fIoutputmap\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
IrcMarkers takes a map in .png or .jpg format and a list of coordinates
and labels in xplanet format and places markers on the map.
It was written to generate user maps of \s-1IRC\s0 channels.
.PP
GnuPG/PGP key ids can be associated with each marker, to create \*(L"maps of trust\*(R".
.PP
IrcMarkers reads its configuration and the list of markers from a config file.
The most important options (map to read/write, map dimensions) can be specified
on the command line. Settings on the command line override settings in the
config file.
.SH "OPTIONS"
.IX Header "OPTIONS"
.IP "\fIconfig\fR" 4
.IX Item "config"
Config file to read markers and options from. This parameter is mandatory.
.IP "\fIinputmap\fR" 4
.IX Item "inputmap"
Read input map from \fIinputmap\fR. Supported formats are .gif, .jpg/jpeg, .png,
\&.xbm, .xpm, and the libgd-Formats .gd/gd1 and .gd2.
.IP "\fIoutputmap\fR" 4
.IX Item "outputmap"
Write output map to \fIoutputmap\fR. Supported formats are .gif, .jpg/jpeg, .png,
\&.gd/gd1, .gd2, and .wbmp.
.IP "\-q" 4
.IX Item "-q"
Be quiet. Per default, IrcMarkers prints which labels and links are placed on
the map.
.IP "\-y \fIsouth/north\fR" 4
.IX Item "-y south/north"
.PD 0
.IP "\-x \fIwest/east\fR" 4
.IX Item "-x west/east"
.PD
Declare input map dimensions. Unless specified otherwise in the config file,
the map is assumed to be in equirectangular projection. \-y specifies the lower/upper
latitude coordinates, \-x the left/right edge longitude. Per default, the map is
assumed to be a world map (\-y \-90/90 \-x \-180/180).
.IP "\-o \fIcommand\fR" 4
.IX Item "-o command"
Evaluate a configuration command. It will be executed before any commands in
the config file (i.e. it will not override commands there).
.SH "CONFIG FILE SYNTAX"
.IX Header "CONFIG FILE SYNTAX"
The following directives can be used in the config file:
.SS "Marker and Label Definitions"
.IX Subsection "Marker and Label Definitions"
.ie n .IP "\fIlat\fR \fIlon\fR ""\fImarker\fR""" 4
.el .IP "\fIlat\fR \fIlon\fR ``\fImarker\fR''" 4
.IX Item "lat lon ""marker"""
.PD 0
.ie n .IP "\fIlat\fR \fIlon\fR ""\fImarker\fR"" \fIoptions\fR" 4
.el .IP "\fIlat\fR \fIlon\fR ``\fImarker\fR'' \fIoptions\fR" 4
.IX Item "lat lon ""marker"" options"
.ie n .IP "\fIaa11aa\fR ""\fImarker\fR"" \fIoptions\fR" 4
.el .IP "\fIaa11aa\fR ``\fImarker\fR'' \fIoptions\fR" 4
.IX Item "aa11aa ""marker"" options"
.ie n .IP """\fImarker\fR"" \fIoptions\fR" 4
.el .IP "``\fImarker\fR'' \fIoptions\fR" 4
.IX Item """marker"" options"
.PD
Place marker with label \fImarker\fR on map at given coordinates.
Use negative values for south/east, positive for north/west.
This (decimal) format is compatible with the xplanet syntax.
.Sp
.Vb 1
\& 49.2532 7.0425 "Myon"
.Ve
.Sp
Alternative formats recognized are:
.Sp
.Vb 3
\& N51X11.123 E006X25.846
\& N 51 11.123 E 006 25.846
\& N 51X 11\*(Aq 7.38" E 006X 25\*(Aq 50.76"
.Ve
.Sp
The noise characters X'" are optional.
.Sp
Also recognized are Maidenhead (\s-1QTH\s0) locators.
.Sp
.Vb 1
\& JN39PF "Myon"
.Ve
.ie n .IP "label \fIy\fR \fIx\fR ""\fItext\fR""" 4
.el .IP "label \fIy\fR \fIx\fR ``\fItext\fR''" 4
.IX Item "label y x ""text"""
.PD 0
.ie n .IP "label \fIy\fR \fIx\fR ""\fItext\fR"" \fIoptions\fR" 4
.el .IP "label \fIy\fR \fIx\fR ``\fItext\fR'' \fIoptions\fR" 4
.IX Item "label y x ""text"" options"
.PD
Place a label at position \fIy\fR/\fIx\fR (in pixels). Useful for headlines etc.
Using negative values will count from the bottom/right border in X11's
\&\-geometry style.
.SS "Marker and Label Options"
.IX Subsection "Marker and Label Options"
The following options can be specified per marker or globally (except gpg).
Global options set defaults for all following marker definitions.
.IP "gpg \fIkeyid\fR" 4
.IX Item "gpg keyid"
Associate GnuPG/PGP \fIkeyid\fR with the marker. If two keys have signed each
other, and both markers are visible on the map, a link will be drawn between
the markers. Multiple keyids can be given. Example:
.Sp
\&\fB\*(L"Myon\*(R" gpg B46B923B6D8ABE71 gpg C5AF774A58510B5A\fR
.Sp
\&\fBNote:\fR This is the long, 16 character keyid. To retrieve it, use \f(CW\*(C`gpg
\&\-\-list\-key \-\-with\-colon\*(C'\fR.
.IP "label_color \fIR G B\fR" 4
.IX Item "label_color R G B"
.PD 0
.IP "label_border \fIR G B\fR|none" 4
.IX Item "label_border R G B|none"
.PD
Color of the labels placed on the map. Default is label_color 255 255 0,
label_border 0 0 0. The border can be removed by specifying the \*(L"none\*(R" color.
.IP "font \fIfontfile\fR" 4
.IX Item "font fontfile"
Full pathname to the .ttf font used for the labels. Default is
font \fI/usr/share/ircmarkers/fixed_01.ttf\fR.
.IP "fontsize|ptsize \fIsize\fR" 4
.IX Item "fontsize|ptsize size"
Size in points of the labels. Default is fontsize 6.
.IP "dot_color \fIR G B\fR" 4
.IX Item "dot_color R G B"
.PD 0
.IP "dot_border \fIR G B\fR|none" 4
.IX Item "dot_border R G B|none"
.PD
Color of the dots placed on the map. Default is dot_color 255 255 255,
dot_border 0 0 0.
.IP "dot_size \fIsize\fR" 4
.IX Item "dot_size size"
Size of the dots. Default is 2.
.IP "dot_shape dot|circle" 4
.IX Item "dot_shape dot|circle"
Dots are filled (dot) or hollow (circle). Default is dot.
.IP "href \fIlink\fR" 4
.IX Item "href link"
Link target to use in an imagemap.
.IP "alias|pic|bigpic|sex \fIstring\fR" 4
.IX Item "alias|pic|bigpic|sex string"
Options for export to \fBpisg\fR\|(1), see the \fBpisg\fR option below.
.SS "Link Definition and Options"
.IX Subsection "Link Definition and Options"
.ie n .IP """\fImarker1\fR"" <\-> ""\fImarker2\fR""" 4
.el .IP "``\fImarker1\fR'' <\-> ``\fImarker2\fR''" 4
.IX Item """marker1 <-> marker2"""
.PD 0
.ie n .IP """\fImarker1\fR"" <\-> ""\fImarker2\fR"" \fIoptions\fR" 4
.el .IP "``\fImarker1\fR'' <\-> ``\fImarker2\fR'' \fIoptions\fR" 4
.IX Item """marker1 <-> marker2"" options"
.PD
Draw a link between \fImarker1\fR and \fImarker2\fR.
.IP "link_color|sign2_color \fIR G B\fR|none" 4
.IX Item "link_color|sign2_color R G B|none"
Color of the lines drawn between the markers. Default is link_color 255 128 0.
.SS "Global Options"
.IX Subsection "Global Options"
.IP "read \fIinputmap\fR" 4
.IX Item "read inputmap"
Read input map from \fIinputmap\fR. Supported formats are .jpg and .png.
.IP "write \fIoutputmap\fR" 4
.IX Item "write outputmap"
Write output map to \fIoutputmap\fR. Supported formats are .jpg, .png, .gd1, .gd2,
and .wbmp.
.IP "lat|south_north \fIsouth/north\fR" 4
.IX Item "lat|south_north south/north"
.PD 0
.IP "lon|west_east \fIwest/east\fR" 4
.IX Item "lon|west_east west/east"
.PD
Declare input map dimensions. Default is lat \-90/90, lon \-180/180.
.Sp
\&\fBNote:\fR It is possible to use \*(L"unusual\*(R" values like lon 0/360 if you adjust
the coordinates as well. (\-20 becomes 340 etc.)
.IP "view_lat|view_south_north \fIsouth/north\fR" 4
.IX Item "view_lat|view_south_north south/north"
.PD 0
.IP "view_lon|view_west_east \fIwest/east\fR" 4
.IX Item "view_lon|view_west_east west/east"
.PD
Only show part of the map in the output. Default is to show the whole map.
.IP "view_width \fIpixels\fR" 4
.IX Item "view_width pixels"
.PD 0
.IP "view_height \fIpixels\fR" 4
.IX Item "view_height pixels"
.PD
Size of output map. Default is input map, or size of part selected.
.IP "projection square|mercator|sinusoidal" 4
.IX Item "projection square|mercator|sinusoidal"
.PD 0
.IP "center_lon \fIcenter\fR" 4
.IX Item "center_lon center"
.PD
Map projection. Default is square, which selects equirectangular projection.
center_lon is only used for sinusoidal projection.
There is no default for center_lon.
.IP "link_outside on|off" 4
.IX Item "link_outside on|off"
Whether to draw lines to markers that are not visible on the map. Default is
link_outside off.
.IP "sign1_color \fIR G B\fR|none" 4
.IX Item "sign1_color R G B|none"
Color of the lines drawn for uni-directional GnuPG/PGP signatures. Default is
link_color none.
.IP "imagemap \fIfile\fR" 4
.IX Item "imagemap file"
Write \s-1HTML\s0 image map to \fIfile\fR. The map contains areas for all markers and
labels with a href option. The name of the imagemap is the basename of the
output map with the extension stripped.
.IP "overlap \fIoverlapcorrector\fR" 4
.IX Item "overlap overlapcorrector"
Full pathname to the binary that moves the labels around to reduce overlap.
Default is overlapcorrector \fI/usr/lib/ircmarkers/overlap\fR.
Chances are that you only need to change that parameter if you are debugging
the overlap corrector.
.IP "overlap_correction on|off" 4
.IX Item "overlap_correction on|off"
Whether to use the overlap corrector or not. Default is overlap_correction on.
Turn it off if you have really many labels.
.IP "pisg" 4
.IX Item "pisg"
Instead of writing a map, print a config file suitable for \fBpisg\fR\|(1), most useful
with \fBircmarkers \-o pisg\fR \fIfile\fR. The exported marker options are \fBalias\fR,
\&\fBpic\fR, \fBbigpic\fR, \fBsex\fR, and \fBhref\fR (the latter as \fBlink\fR).
.IP "recv-keys" 4
.IX Item "recv-keys"
Call gpg \-\-recv\-keys (most useful with \fBircmarkers \-o recv-keys\fR).
.IP "quiet on|off" 4
.IX Item "quiet on|off"
Be quiet. Default is quiet off.
.ie n .IP "#include ""\fIconfigfile\fR""" 4
.el .IP "#include ``\fIconfigfile\fR''" 4
.IX Item "#include ""configfile"""
Read auxillary config file.
.IP "# comment" 4
.IX Item "# comment"
Anything else starting with a # character is a comment.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
\&\fBircmarkers \-x \-10.4/29.4 \-y 32/72 coordinates.txt europe.jpg mutt\-eu.jpg\fR
.PP
.Vb 10
\&        read dl.jpg
\&        write debian.de.jpg
\&        lat 44/56
\&        lon 4/20
\&        label_color 0 255 0
\&        49.2532 7.0425 "Myon"
\&        50.8574 6.4585 "formorer" label_color 255 255 0
\&        N 51X 11.123 E 006X 25.846 "GC1ACE3"
\&        #include "debian.de.txt"
\&        #include "debian.de.keys"
.Ve
.SH "BUGS"
.IX Header "BUGS"
The \s-1GD\s0 library keeps a raw bitmap of the map in memory. Big maps will use lots
of memory. Precompute the map you are going to use, i.e. downsample it to the
target size using Imagemagick's \fIconvert\fR or IrcMarkers view_* functions.
.PP
Please report bugs in IrcMarkers using the Debian bug tracking system. The
IrcMarkers bug page is at \fBhttp://bugs.debian.org/ircmarkers\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
.SS "Library used"
.IX Subsection "Library used"
.IP "\(bu" 4
\&\s-1\fBGD\s0\fR\|(3) \- \s-1GD\s0 version 2
.SS "Programs related to IrcMarkers"
.IX Subsection "Programs related to IrcMarkers"
.IP "\(bu" 4
MapMarkers: http://www.nul\-en.info/mapmarkers/ \- IrcMarkers' predecessor
.IP "\(bu" 4
\&\fBxplanet\fR\|(1): http://xplanet.sourceforge.net/
.IP "\(bu" 4
Image::WorldMap: http://www.astray.com/WorldMap/
.IP "\(bu" 4
\&\fBpisg\fR\|(1): http://pisg.sourceforge.net/
.SS "Locating coordinates"
.IX Subsection "Locating coordinates"
.IP "\(bu" 4
http://www.multimap.com/ \- online maps to everywhere
.IP "\(bu" 4
http://www.calle.com/world/ \- directory of cities and towns in world
.IP "\(bu" 4
http://tiger.census.gov/cgi\-bin/mapbrowse\-tbl \- United States
.IP "\(bu" 4
http://www.ckdhr.com/dns\-loc/finding.html \- more pointers
.SS "Maps"
.IX Subsection "Maps"
.IP "\(bu" 4
http://visibleearth.nasa.gov/cgi\-bin/viewrecord?11656 \- nice copyright-free world map
.IP "\(bu" 4
http://www.elho.net/misc/xplanet/ \- compilation of suitable maps from \s-1NASA\s0
.SH "AUTHOR"
.IX Header "AUTHOR"
IrcMarkers was written by Christoph Berg <cb@df7cb.de>.
You can find me (Myon) on ircnet/freenode/oftc.
.PP
Thanks go to Uli Martens for the \*(L"map of trust\*(R" idea.
.PP
Alexander Wirt suggested the capability to draw selected parts of the map.
.PP
Elmar Hoffmann suggested several error checks and config options.
.PP
Rico Gloeckner suggested to support Maidenhead locators.
.PP
The IrcMarkers homepage is at \fBhttp://www.df7cb.de/projects/ircmarkers/\fR.
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright (C) 2003\-2014 Christoph Berg <cb@df7cb.de>
.PP
This program is free software; you can redistribute it and/or modify it under
the terms of the \s-1GNU\s0 General Public License as published by the Free Software
Foundation; either version 2 of the License, or (at your option) any later
version.
.PP
This program is distributed in the hope that it will be useful, but \s-1WITHOUT ANY
WARRANTY\s0; without even the implied warranty of \s-1MERCHANTABILITY\s0 or \s-1FITNESS FOR A
PARTICULAR PURPOSE.\s0  See the \s-1GNU\s0 General Public License for more details.
.PP
You should have received a copy of the \s-1GNU\s0 General Public License with the
Debian GNU/Linux distribution in file \fI/usr/share/common\-licenses/GPL\fR; if not,
write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor,
Boston, \s-1MA\s0  02110\-1301 \s-1USA\s0
.PP
IrcMarkers is an improved version of MapMarkers.
.PP
Copyright (C) 2002, 2003 Guillaume Leclanche (Mo-Ize) <mo\-ize@nul\-en.info>
.PP
The font provided with this package, fixed_01.ttf, has been created by the
Orgdot team, http://www.orgdot.com/aliasfonts/.
.PP
(C) 2001 http://www.orgdot.com