Imported from archive.
* Release 2.0: Heavy rewrite with too many new features to enumerate here in the ChangeLog file. * NEWS: List of important changes since 1.x releases. * weather, weather.py: Implemented support for Python 3000 as requested by ptchinster on behalf of Arch Linux, conditions/forecast searches by latitude/longitude requested by Brandt Daniels, support for newer NOAA forecasts pointed out by Darryl Mouck and Richard Dooling, custom URIs requested by Michel Pelzer, international weather stations requested by Milton Hubsher, and fixed a metric conversion issue with negative values reported by Jochen Keil, Michiel Appelman and Stefan Metzlaff. Thanks to everyone for your input and assistance!
This commit is contained in:
Jeremy Stanley
258
weather.1
258
weather.1
@@ -1,127 +1,215 @@
|
||||
.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%)
|
||||
.BR \-\-headers =\fIHEADERS\fR
|
||||
list of conditions headers to display (ex:
|
||||
.BR temperature,wind )
|
||||
.TP
|
||||
.B \-\-headers=HEADERS
|
||||
the conditions headers to display
|
||||
.BR \-\-imperial
|
||||
filter/convert conditions for US/UK units
|
||||
.TP
|
||||
.B \-i ID, \-\-id=ID
|
||||
the METAR station ID (ex: KRDU)
|
||||
.BR \-\-info
|
||||
output detailed information for your search
|
||||
.TP
|
||||
.B \-\-imperial
|
||||
filter/convert for US/UK units
|
||||
.BR \-l ", " \-\-list
|
||||
list all configured aliases and cached searches
|
||||
.TP
|
||||
.B \-l, \-\-list
|
||||
print a list of configured aliases
|
||||
.BR \-\-longlist
|
||||
display details of all configured aliases
|
||||
.TP
|
||||
.B \-m, \-\-metric
|
||||
filter/convert for metric units
|
||||
.BR \-m ", " \-\-metric
|
||||
filter/convert conditions for metric units
|
||||
.TP
|
||||
.B \-\-murl=MURL
|
||||
METAR URL (including %id%)
|
||||
.BR \-n ", " \-\-no\-conditions
|
||||
disable output of current conditions
|
||||
.TP
|
||||
.B \-n, \-\-no\-conditions
|
||||
disable output of current conditions (forces \-f)
|
||||
.BR \-\-no\-cache
|
||||
disable all caching (searches and data)
|
||||
.TP
|
||||
.B \-o, \-\-omit\-forecast
|
||||
omit the local forecast (cancels \-f)
|
||||
.BR \-\-no\-cache\-data
|
||||
disable retrieved data caching
|
||||
.TP
|
||||
.B \-\-quiet
|
||||
.BR \-\-no\-cache\-search
|
||||
disable search result caching
|
||||
.TP
|
||||
.BR \-q ", " \-\-quiet
|
||||
skip preambles and don't indent
|
||||
.TP
|
||||
.B \-s ST, \-\-st=ST
|
||||
the state abbreviation (ex: NC)
|
||||
.BR \-\-setpath =\fISETPATH\fR
|
||||
directory search path for correlation sets (ex:
|
||||
.BR .:~/.weather )
|
||||
.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:
|
||||
.TP
|
||||
.B /etc/weatherrc
|
||||
the system\-wide configuration
|
||||
.TP
|
||||
.B ~/.weatherrc
|
||||
the per\-user configuration (can be used to override the above)
|
||||
.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.
|
||||
View output for the default alias, if one has been defined (otherwise
|
||||
display usage/syntax similar to \-\-help)
|
||||
.TP
|
||||
.B weather -i kavl
|
||||
Display current conditions at the KAVL METAR station.
|
||||
.BR weather " " rdu
|
||||
Display weather conditions at the airport with IATA/FAA code \fIRDU\fR.
|
||||
.TP
|
||||
.B weather -n -c asheville -s nc
|
||||
See a forecast for the Asheville, NC area.
|
||||
.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
|
||||
.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.
|
||||
.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
|
||||
.B weather home work
|
||||
Show current conditions for both the home and work aliases in that order.
|
||||
.SH SEE ALSO
|
||||
.BR weatherrc (5)
|
||||
.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
|
||||
.I /etc/weatherrc
|
||||
the system-wide configuration
|
||||
.TP
|
||||
.IR ~/.weather/weatherrc " or " ~/.weatherrc
|
||||
the per-user configuration
|
||||
.TP
|
||||
.I ./weatherrc
|
||||
the local directory configuration
|
||||
.SH AUTHOR
|
||||
Utility and manual written by Jeremy Stanley <fungi@yuggoth.org>.
|
||||
.SH SEE ALSO
|
||||
.IR weatherrc (5)
|
||||
|
||||
Reference in New Issue
Block a user