weather.1

   1 .TH weather 1 "2012\-06\-24" "2.0" \" -*- nroff -*-
   2 \" Copyright (c) 2006-2012 Jeremy Stanley <fungi@yuggoth.org>.
   3 \" Permission to use, copy, modify, and distribute this software is
   4 \" granted under terms provided in the LICENSE file distributed with
   5 \" this software.
   6 .SH NAME
   7 weather \- command-line tool to obtain weather conditions and forecasts
   8 .SH SYNOPSIS
   9 .B weather
  10 [
  11 .I options
  12 ] [
  13 .I alias1
  14 |
  15 .I search1
  16 [
  17 .I alias2
  18 |
  19 .I search2
  20 [...]]]
  21 .SH DESCRIPTION
  22 .
  23 This command-line utility is intended to provide quick access to current
  24 weather conditions and forecasts.
  25 .
  26 Presently, it is capable of returning data for localities throughout the
  27 USA and some select locations globally by retrieving and formatting
  28 decoded METARs (Meteorological Aerodrome Reports) from NOAA (the USA
  29 National Oceanic and Atmospheric Administration) and forecasts/alerts
  30 from NWS (the USA National Weather Service).
  31 .
  32 The tool is written to function in the same spirit as other command-line
  33 informational utilities like \fIcal\fR(1), \fIcalendar\fR(1) and
  34 \fIdict\fR(1).
  35 .
  36 It retrieves arbitrary weather data via precompiled correlations or
  37 custom-tailored aliases (system-wide or on a per-user basis).
  38
  39 Behavior can be determined by command-line options and specification of
  40 zero or more location aliases and search terms.
  41
  42 Aliases are defined in \fIweatherrc\fR(5) files, as a convenient means
  43 of grouping URIs together using a short name.
  44 .
  45 Specifying multiple aliases or location search terms on the command line
  46 causes the utility to output data for each, as if it had been invoked
  47 multiple times.
  48 .
  49 If none are specified, then an alias of \fIdefault\fR is checked for a
  50 \fIdefargs\fR option and any alias names listed within it
  51 (comma-separated) are applied instead.
  52
  53 Searches utilize location correlation sets in INI-style text files named
  54 \fIairports\fR, \fIplaces\fR, \fIstations\fR, \fIzctas\fR and
  55 \fIzones\fR.
  56 .
  57 A precomputed copy is distributed with the source, but can be rebuilt
  58 from updated data sources as needed by placing them in the current
  59 working directory and running with the \fI\-\-build\-sets\fR option (see
  60 the comments at the top of any location correlation set file for
  61 instructions on where to find updated data sources).
  62 .
  63 Positive search results are cached and sourced as aliases on subsequent
  64 runs for as long as the correlation sets remain unchanged, and are
  65 cleared automatically once the correlation sets are updated.
  66
  67 Retrieved data is also cached automatically for a short period of time,
  68 adjustable with the \fIcacheage\fR configuration option or
  69 \fI\-\-cacheage\fR command-line option.
  70 .
  71 This helps throttle load against NOAA/NWS servers in case the utility is
  72 repeatedly re-run requesting the same data, but can be overridden with
  73 the \fIcache_data\fR configuration option or \fI\-\-no\-cache\-data\fR
  74 command-line option.
  75 .
  76 .SH OPTIONS
  77 A summary of options is included below.
  78 .TP
  79 .BR \-\-version
  80 show program's version number and exit
  81 .TP
  82 .BR \-h ", " \-\-help
  83 show a help message and exit
  84 .TP
  85 .BR \-a ", " \-\-alert
  86 include local alert notices
  87 .TP
  88 .BR \-\-atypes =\fIATYPES\fR
  89 list of alert notification types to display (ex:
  90 .BR tornado_warning,urgent_weather_message )
  91 .TP
  92 .BR \-\-build\-sets
  93 (re)build location correlation sets
  94 .TP
  95 .BR \-\-cacheage =\fICACHEAGE\fR
  96 duration in seconds to refresh cached data (ex:
  97 .BR 900 )
  98 .TP
  99 .BR \-\-cachedir =\fICACHEDIR\fR
 100 directory for storing cached searches and data (ex:
 101 .BR ~/.weather )
 102 .TP
 103 .BR \-f ", " \-\-forecast
 104 include a local forecast
 105 .TP
 106 .BR \-\-headers =\fIHEADERS\fR
 107 list of conditions headers to display (ex:
 108 .BR temperature,wind )
 109 .TP
 110 .BR \-\-imperial
 111 filter/convert conditions for US/UK units
 112 .TP
 113 .BR \-\-info
 114 output detailed information for your search
 115 .TP
 116 .BR \-l ", " \-\-list
 117 list all configured aliases and cached searches
 118 .TP
 119 .BR \-\-longlist
 120 display details of all configured aliases
 121 .TP
 122 .BR \-m ", " \-\-metric
 123 filter/convert conditions for metric units
 124 .TP
 125 .BR \-n ", " \-\-no\-conditions
 126 disable output of current conditions
 127 .TP
 128 .BR \-\-no\-cache
 129 disable all caching (searches and data)
 130 .TP
 131 .BR \-\-no\-cache\-data
 132 disable retrieved data caching
 133 .TP
 134 .BR \-\-no\-cache\-search
 135 disable search result caching
 136 .TP
 137 .BR \-q ", " \-\-quiet
 138 skip preambles and don't indent
 139 .TP
 140 .BR \-\-setpath =\fISETPATH\fR
 141 directory search path for correlation sets (ex:
 142 .BR .:~/.weather )
 143 .TP
 144 .BR \-v ", " \-\-verbose
 145 show full decoded feeds
 146 .SH EXAMPLES
 147 .TP
 148 .B weather
 149 View output for the default alias, if one has been defined (otherwise
 150 display usage/syntax similar to \-\-help)
 151 .TP
 152 .BR weather " " rdu
 153 Display weather conditions at the airport with IATA/FAA code \fIRDU\fR.
 154 .TP
 155 .BR weather " " \-\-info " " raleigh
 156 Show a list of FIPS codes for United States Census Bureau places
 157 containing the word \fIraleigh\fR (or the proximity information if only
 158 one match was found).
 159 .TP
 160 .BR weather " " \(dq ^ral[ie]{2}gh " " city.*nc$ \(dq
 161 Get the current weather conditions from the nearest station to the
 162 Census place name matching the regular expression provided.
 163 .TP
 164 .BR weather " " \-fv " " fips3755000
 165 Get the full decoded METAR from the nearest station, and the forecast
 166 data for the nearest zone to the Census place with FIPS code
 167 \fI3755000\fR with no special filtering or formatting.
 168 .TP
 169 .BR weather " " \-\-forecast " " \-\-no\-cache\-data " " 27613
 170 Ignore any recent cached METAR or forecast data and display fresh output
 171 for the nearest station and zone to the Census ZCTA (essentially USPS
 172 ZIP code) \fI27613\fR.
 173 .TP
 174 .BR weather " " home " " work
 175 Show current conditions for both the \fIhome\fR and \fIwork\fR aliases
 176 in that order.
 177 .TP
 178 .BR weather " " 35.878573,\-78.727813
 179 .TP
 180 .BR weather " " 35\-52\-43n,78\-43\-40w
 181 .TP
 182 .BR weather " " \(dq 35\-52n, " " 78\-43w \(dq
 183 Display weather conditions for the nearest station to an arbitrary set
 184 of global coordinates in latitude,longitude order either in decimal
 185 format or degree, degree\-minute or degree\-minute\-second formats,
 186 optionally using signed or cardinal hemisphere designations with or
 187 without spacing.
 188 .
 189 Note that the cut-off for maximum acceptable distance is hard-coded at
 190 0.1 radians (roughly 637km or 396mi).
 191 .
 192 .SH INPUT FILES
 193 .
 194 .B weather
 195 may additionally obtain configuration data from a system-wide
 196 configuration file, a per-user configuration file, and a local
 197 directory configuration file.
 198 .
 199 The file format and configuration options are described in
 200 .IR weatherrc (5).
 201 .
 202 They are aggregated in the following order:
 203 .TP
 204 .I /etc/weatherrc " or " /etc/weather/weatherrc
 205 the system-wide configuration
 206 .TP
 207 .IR ~/.weather/weatherrc " or " ~/.weatherrc
 208 the per-user configuration
 209 .TP
 210 .I ./weatherrc
 211 the local directory configuration
 212 .SH AUTHOR
 213 Utility and manual written by Jeremy Stanley <fungi@yuggoth.org>.
 214 .SH SEE ALSO
 215 .IR weatherrc (5)