-.TH WEATHER 1 "March 15, 2010" "" \" -*- nroff -*-
-\" Copyright (c) 2006-2010 Jeremy Stanley <fungi@yuggoth.org>.
+.TH weather 1 "2012\-06\-24" "2.0" \" -*- nroff -*-
+\" Copyright (c) 2006-2012 Jeremy Stanley <fungi@yuggoth.org>.
\" Permission to use, copy, modify, and distribute this software is
\" granted under terms provided in the LICENSE file distributed with
\" this software.
.SH NAME
-weather \- command\-line tool to obtain weather conditions and forecasts
+weather \- command-line tool to obtain weather conditions and forecasts
.SH SYNOPSIS
-.B weather [ options ] [ alias [ alias [...] ] ]
+.B weather
+[
+.I options
+] [
+.I alias1
+|
+.I search1
+[
+.I alias2
+|
+.I search2
+[...]]]
.SH DESCRIPTION
-This utility is intended to provide quick access to current weather
-conditions and forecasts. Presently, it is capable of providing data for
-localities throughout the United States of America by retrieving and
-processing METAR data from the National Oceanic and Atmospheric
-Administration and forecasts from the National Weather Service. Behavior
-can be determined by command\-line options and specification of zero or
-more aliases. Aliases are defined in weatherrc files, as a convenient
-means of grouping option combinations together using a short name.
-Specifying multiple aliases on the command line causes the utility to
-output data for each, as if it had been invoked multiple times. If no
-alias is specified, then an alias of "default" is used (assuming it has
-been defined) or the built\-in default values are chosen (if it has not).
+.
+This command-line utility is intended to provide quick access to current
+weather conditions and forecasts.
+.
+Presently, it is capable of returning data for localities throughout the
+USA and some select locations globally by retrieving and formatting
+decoded METARs (Meteorological Aerodrome Reports) from NOAA (the USA
+National Oceanic and Atmospheric Administration) and forecasts/alerts
+from NWS (the USA National Weather Service).
+.
+The tool is written to function in the same spirit as other command-line
+informational utilities like \fIcal\fR(1), \fIcalendar\fR(1) and
+\fIdict\fR(1).
+.
+It retrieves arbitrary weather data via precompiled correlations or
+custom-tailored aliases (system-wide or on a per-user basis).
+
+Behavior can be determined by command-line options and specification of
+zero or more location aliases and search terms.
+
+Aliases are defined in \fIweatherrc\fR(5) files, as a convenient means
+of grouping URIs together using a short name.
+.
+Specifying multiple aliases or location search terms on the command line
+causes the utility to output data for each, as if it had been invoked
+multiple times.
+.
+If none are specified, then an alias of \fIdefault\fR is checked for a
+\fIdefargs\fR option and any alias names listed within it
+(comma-separated) are applied instead.
+
+Searches utilize location correlation sets in INI-style text files named
+\fIairports\fR, \fIplaces\fR, \fIstations\fR, \fIzctas\fR and
+\fIzones\fR.
+.
+A precomputed copy is distributed with the source, but can be rebuilt
+from updated data sources as needed by placing them in the current
+working directory and running with the \fI\-\-build\-sets\fR option (see
+the comments at the top of any location correlation set file for
+instructions on where to find updated data sources).
+.
+Positive search results are cached and sourced as aliases on subsequent
+runs for as long as the correlation sets remain unchanged, and are
+cleared automatically once the correlation sets are updated.
+
+Retrieved data is also cached automatically for a short period of time,
+adjustable with the \fIcacheage\fR configuration option or
+\fI\-\-cacheage\fR command-line option.
+.
+This helps throttle load against NOAA/NWS servers in case the utility is
+repeatedly re-run requesting the same data, but can be overridden with
+the \fIcache_data\fR configuration option or \fI\-\-no\-cache\-data\fR
+command-line option.
+.
.SH OPTIONS
A summary of options is included below.
.TP
-.B \-\-version
+.BR \-\-version
show program's version number and exit
.TP
-.B \-h, \-\-help
+.BR \-h ", " \-\-help
show a help message and exit
.TP
-.B \-a, \-\-alert
+.BR \-a ", " \-\-alert
include local alert notices
.TP
-.B \-\-atypes=ATYPES
-alert notification types to display
+.BR \-\-atypes =\fIATYPES\fR
+list of alert notification types to display (ex:
+.BR tornado_warning,urgent_weather_message )
.TP
-.B \-\-aurl=AURL
-alert URL (including %atype% and %zone%)
+.BR \-\-build\-sets
+(re)build location correlation sets
.TP
-.B \-c CITY, \-\-city=CITY
-the city name (ex: "Raleigh Durham")
+.BR \-\-cacheage =\fICACHEAGE\fR
+duration in seconds to refresh cached data (ex:
+.BR 900 )
.TP
-.B \-\-flines=FLINES
-maximum number of forecast lines to show
+.BR \-\-cachedir =\fICACHEDIR\fR
+directory for storing cached searches and data (ex:
+.BR ~/.weather )
.TP
-.B \-f, \-\-forecast
+.BR \-f ", " \-\-forecast
include a local forecast
.TP
-.B \-\-furl=FURL
-forecast URL (including %city% and %st%)
-.TP
-.B \-\-headers=HEADERS
-the conditions headers to display
+.BR \-\-headers =\fIHEADERS\fR
+list of conditions headers to display (ex:
+.BR temperature,wind )
.TP
-.B \-i ID, \-\-id=ID
-the METAR station ID (ex: KRDU)
+.BR \-\-imperial
+filter/convert conditions for US/UK units
.TP
-.B \-\-imperial
-filter/convert for US/UK units
+.BR \-\-info
+output detailed information for your search
.TP
-.B \-l, \-\-list
-print a list of configured aliases
+.BR \-l ", " \-\-list
+list all configured aliases and cached searches
.TP
-.B \-m, \-\-metric
-filter/convert for metric units
+.BR \-\-longlist
+display details of all configured aliases
.TP
-.B \-\-murl=MURL
-METAR URL (including %id%)
+.BR \-m ", " \-\-metric
+filter/convert conditions for metric units
.TP
-.B \-n, \-\-no\-conditions
-disable output of current conditions (forces \-f)
+.BR \-n ", " \-\-no\-conditions
+disable output of current conditions
.TP
-.B \-o, \-\-omit\-forecast
-omit the local forecast (cancels \-f)
-.TP
-.B \-\-quiet
-skip preambles and don't indent
+.BR \-\-no\-cache
+disable all caching (searches and data)
.TP
-.B \-s ST, \-\-st=ST
-the state abbreviation (ex: NC)
+.BR \-\-no\-cache\-data
+disable retrieved data caching
.TP
-.B \-v, \-\-verbose
-show full decoded feeds (cancels \-q)
-.TP
-.B \-z ZONES, \-\-zones=ZONES
-alert zones (ex: nc/ncc183,nc/ncz041)
-.SH FILES
-.B weather
-may additionally obtain configuration data from a system\-wide
-configuration file, a per\-user configuration file, and a local
-directory configuration file. The file format and configuration options
-are described in
-.BR weatherrc (5) .
-They are aggregated in the following order:
+.BR \-\-no\-cache\-search
+disable search result caching
.TP
-.B /etc/weatherrc
-the system\-wide configuration
+.BR \-q ", " \-\-quiet
+skip preambles and don't indent
.TP
-.B ~/.weatherrc
-the per\-user configuration (can be used to override the above)
+.BR \-\-setpath =\fISETPATH\fR
+directory search path for correlation sets (ex:
+.BR .:~/.weather )
.TP
-.B ./weatherrc
-the local directory configuration (can be used to override the above)
+.BR \-v ", " \-\-verbose
+show full decoded feeds
.SH EXAMPLES
.TP
.B weather
-View output for the defined default alias, or the built-in default values
-if there is no default alias defined in the configuration files.
-.TP
-.B weather -i kavl
-Display current conditions at the KAVL METAR station.
+View output for the default alias, if one has been defined (otherwise
+display usage/syntax similar to \-\-help)
+.TP
+.BR weather " " rdu
+Display weather conditions at the airport with IATA/FAA code \fIRDU\fR.
+.TP
+.BR weather " " \-\-info " " raleigh
+Show a list of FIPS codes for United States Census Bureau places
+containing the word \fIraleigh\fR (or the proximity information if only
+one match was found).
+.TP
+.BR weather " " \(dq ^ral[ie]{2}gh " " city.*nc$ \(dq
+Get the current weather conditions from the nearest station to the
+Census place name matching the regular expression provided.
+.TP
+.BR weather " " \-fv " " fips3755000
+Get the full decoded METAR from the nearest station, and the forecast
+data for the nearest zone to the Census place with FIPS code
+\fI3755000\fR with no special filtering or formatting.
+.TP
+.BR weather " " \-\-forecast " " \-\-no\-cache\-data " " 27613
+Ignore any recent cached METAR or forecast data and display fresh output
+for the nearest station and zone to the Census ZCTA (essentially USPS
+ZIP code) \fI27613\fR.
+.TP
+.BR weather " " home " " work
+Show current conditions for both the \fIhome\fR and \fIwork\fR aliases
+in that order.
+.TP
+.BR weather " " 35.878573,\-78.727813
+.TP
+.BR weather " " 35\-52\-43n,78\-43\-40w
+.TP
+.BR weather " " \(dq 35\-52n, " " 78\-43w \(dq
+Display weather conditions for the nearest station to an arbitrary set
+of global coordinates in latitude,longitude order either in decimal
+format or degree, degree\-minute or degree\-minute\-second formats,
+optionally using signed or cardinal hemisphere designations with or
+without spacing.
+.
+Note that the cut-off for maximum acceptable distance is hard-coded at
+0.1 radians (roughly 637km or 396mi).
+.
+.SH INPUT FILES
+.
+.B weather
+may additionally obtain configuration data from a system-wide
+configuration file, a per-user configuration file, and a local
+directory configuration file.
+.
+The file format and configuration options are described in
+.IR weatherrc (5).
+.
+They are aggregated in the following order:
.TP
-.B weather -n -c asheville -s nc
-See a forecast for the Asheville, NC area.
+.I /etc/weatherrc
+the system-wide configuration
.TP
-.B weather -fv gso
-Get the full decoded METAR for the station associated with the gso alias,
-and the forecast data for the city/state associated with the gso alias,
-without filtering or fancy formatting.
+.IR ~/.weather/weatherrc " or " ~/.weatherrc
+the per-user configuration
.TP
-.B weather home work
-Show current conditions for both the home and work aliases in that order.
-.SH SEE ALSO
-.BR weatherrc (5)
+.I ./weatherrc
+the local directory configuration
.SH AUTHOR
Utility and manual written by Jeremy Stanley <fungi@yuggoth.org>.
+.SH SEE ALSO
+.IR weatherrc (5)
projects / weather.git / blobdiff