upstream/current/llsearch.1n

.TH LLSEARCH 1 "Jul 24, 2001" \" -*- nroff -*-
.SH NAME
llsearch \- Search a GNIS file for place names within a given block of latitude/longitude
.SH SYNOPSIS
.B llsearch
[-L] | [latitude_low longitude_low latitude_high longitude_high]

.SH DESCRIPTION
The U.S. Geological Survey supports sites on the Internet with
Geographic Names Information System (GNIS) files.
These files contain lists of place names, complete with their latitude/longitude and other information.
There are separate files for each of the U.S. states, and each file contains many, many, many place names.
If you want to use this data with
.I drawmap,
it is useful to reduce the data to only the items that you need.
.I Llsearch
lets you filter a GNIS file and winnow out only those place names that fall within
the latitude/longitude boundaries that you specify.
(You may want to specify boundaries that are a tiny bit larger than what you are
interested in, so that numerical quantization doesn't eliminate locales that fall
exactly on your boundaries.)
.PP
Latitudes and longitudes are positive for north latitude and east longitude, and negative
for south latitude and west longitude.
.I Llsearch
expects you to enter them in decimal degrees.
(The latitudes and longitudes in the GNIS file are in degrees-minutes-seconds format, followed
by 'N', 'S', 'E', or 'W'.  However, there are two available file formats, and one of the formats
also contains the latitudes/longitudes in decimal degrees.)
Typical usage is as follows:
.TP
gunzip -c california.gz | llsearch 33 -118 34 -117 > gnis_santa_ana_west
.PP
If you enter the "-L" option, the program will print some license information and exit.
.PP
Once you have reduced the data to some subset of interest, you can search for
particular items via the
.I grep
or
.I perl
commands, or other search commands,
or you can simply edit the results with your favorite text editor.
Search commands are useful in reducing the sheer volume of data to
a more manageable size (by extracting, say, all mountain summits or all
streams), but you will probably ultimately end up looking through the remaining
data manually.  The individual records contain codes, such as "ppl" for
populated places, and "summit" for mountain tops, that can help you pick
and choose.
.PP
There is considerable
redundancy in place names, and human intelligence is useful in sorting
things out.  While I was writing
.I drawmap
and
.I llsearch,
I frequently gazed out my office window, where I could spot at least
two, and possibly three Baldy Mountains.  There are also quite a
few Beaver Creeks, Bear Canyons, Saddle Buttes, and Springfields out there.
By taking a close look at the information associated with each place name,
you can find the particular locations that interest you.
.SH SEE ALSO
.I drawmap(1)
\" =========================================================================
\" llsearch.1 - The manual page for the llsearch program.
\" Copyright (c) 1997,1998,1999,2000,2001  Fred M. Erickson
\"
\" This program is free software; you can redistribute it and/or modify
\" it under the terms of the GNU General Public License as published by
\" the Free Software Foundation; either version 2, or (at your option)
\" any later version.
\"
\" This program is distributed in the hope that it will be useful,
\" but WITHOUT ANY WARRANTY; without even the implied warranty of
\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
\" GNU General Public License for more details.
\"
\" You should have received a copy of the GNU General Public License
\" along with this program; if not, write to the Free Software
\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
\" =========================================================================
1	.TH LLSEARCH 1 "Jul 24, 2001" \" -- nroff --
2	.SH NAME
3	llsearch \- Search a GNIS file for place names within a given block of latitude/longitude
4	.SH SYNOPSIS
5	.B llsearch
6	[-L] \| [latitude_low longitude_low latitude_high longitude_high]
7
8	.SH DESCRIPTION
9	The U.S. Geological Survey supports sites on the Internet with
10	Geographic Names Information System (GNIS) files.
11	These files contain lists of place names, complete with their latitude/longitude and other information.
12	There are separate files for each of the U.S. states, and each file contains many, many, many place names.
13	If you want to use this data with
14	.I drawmap,
15	it is useful to reduce the data to only the items that you need.
16	.I Llsearch
17	lets you filter a GNIS file and winnow out only those place names that fall within
18	the latitude/longitude boundaries that you specify.
19	(You may want to specify boundaries that are a tiny bit larger than what you are
20	interested in, so that numerical quantization doesn't eliminate locales that fall
21	exactly on your boundaries.)
22	.PP
23	Latitudes and longitudes are positive for north latitude and east longitude, and negative
24	for south latitude and west longitude.
25	.I Llsearch
26	expects you to enter them in decimal degrees.
27	(The latitudes and longitudes in the GNIS file are in degrees-minutes-seconds format, followed
28	by 'N', 'S', 'E', or 'W'. However, there are two available file formats, and one of the formats
29	also contains the latitudes/longitudes in decimal degrees.)
30	Typical usage is as follows:
31	.TP
32	gunzip -c california.gz \| llsearch 33 -118 34 -117 > gnis_santa_ana_west
33	.PP
34	If you enter the "-L" option, the program will print some license information and exit.
35	.PP
36	Once you have reduced the data to some subset of interest, you can search for
37	particular items via the
38	.I grep
39	or
40	.I perl
41	commands, or other search commands,
42	or you can simply edit the results with your favorite text editor.
43	Search commands are useful in reducing the sheer volume of data to
44	a more manageable size (by extracting, say, all mountain summits or all
45	streams), but you will probably ultimately end up looking through the remaining
46	data manually. The individual records contain codes, such as "ppl" for
47	populated places, and "summit" for mountain tops, that can help you pick
48	and choose.
49	.PP
50	There is considerable
51	redundancy in place names, and human intelligence is useful in sorting
52	things out. While I was writing
53	.I drawmap
54	and
55	.I llsearch,
56	I frequently gazed out my office window, where I could spot at least
57	two, and possibly three Baldy Mountains. There are also quite a
58	few Beaver Creeks, Bear Canyons, Saddle Buttes, and Springfields out there.
59	By taking a close look at the information associated with each place name,
60	you can find the particular locations that interest you.
61	.SH SEE ALSO
62	.I drawmap(1)
63	\" =========================================================================
64	\" llsearch.1 - The manual page for the llsearch program.
65	\" Copyright (c) 1997,1998,1999,2000,2001 Fred M. Erickson
66	\"
67	\" This program is free software; you can redistribute it and/or modify
68	\" it under the terms of the GNU General Public License as published by
69	\" the Free Software Foundation; either version 2, or (at your option)
70	\" any later version.
71	\"
72	\" This program is distributed in the hope that it will be useful,
73	\" but WITHOUT ANY WARRANTY; without even the implied warranty of
74	\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
75	\" GNU General Public License for more details.
76	\"
77	\" You should have received a copy of the GNU General Public License
78	\" along with this program; if not, write to the Free Software
79	\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
80	\" =========================================================================