-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.
+.
projects / weather.git / blobdiff