X-Git-Url: https://www.yuggoth.org/gitweb?p=weather.git;a=blobdiff_plain;f=weather.1;h=7321ff50f3375ee8a11bbb65d6e05eed56c59311;hp=bbffa8c51b0e3d703258dcba06d2ae1fc08ccc2b;hb=93f58b4538974d6c1d0161cf1d273fe7576c74dd;hpb=4d25a49d5a5ec5415f8e83ba26fea5adf4e5512a diff --git a/weather.1 b/weather.1 index bbffa8c..7321ff5 100644 --- a/weather.1 +++ b/weather.1 @@ -1,127 +1,215 @@ -.TH WEATHER 1 "March 15, 2010" "" \" -*- nroff -*- -\" Copyright (c) 2006-2010 Jeremy Stanley . +.TH weather 1 "2012\-06\-24" "2.0" \" -*- nroff -*- +\" Copyright (c) 2006-2012 Jeremy Stanley . \" 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 . +.SH SEE ALSO +.IR weatherrc (5)