improve docsHEADmaster

3 files changed, 156 insertions, 14 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a5a8e7
--- /dev/null
+++ b/README.md
@@ -0,0 +1,91 @@
+# `wx` - a command line interface for aviation weather
+
+`wx` fetches weather data from the NOAA Aviation Weather Center's Text Data
+Server (TDS).
+
+## Installation from source
+
+1. Clone the repository
+2. Run `sudo make install`
+
+## Usage
+
+Currently, we support fetching METARs in a variety of methods. When fetching
+METARs, a time constraint must be supplied. A time constraint can either be in
+the form "past x" or "between x and y".
+
+    $ wx metar --past 3h
+    $ wx metar --since 2020-01-01T00:00:00 --until 2020-01-02T00:00:00
+
+The `--past` argument defaults to `1h`, so if none of `--past`, `--since`, or
+`--until` are specified, METARs from the past hour will be fetched.
+
+Note that the TDS only stores METARs from the past three days, so the `wx`
+command cannot effectively be used to pull historical data.
+
+### For a set of stations
+
+You can fetch METARs from a set of stations by their full or partial ICAO IDs:
+
+    $ wx metar kbos
+    $ wx metar kbos ksea
+    $ wx metar kb
+
+### For stations in a region
+
+You can fetch METARs from all stations within a rectangular or radial region.
+Rectangular regions are specified by a `minLat,minLon,maxLat,maxLon` tuple:
+
+    $ wx metar --rect 39,-70,40,-71
+
+Radial regions are specified as a radius in statute miles around a center point
+as a `dist,lat,lon` tuple:
+
+    $ wx metar --radial 5.5,40,-70
+
+### For stations along a flight path
+
+You can fetch weather for all stations with a distance of a specified flight
+path. A flight path is specified by a series of `--waypoint` arguments, where
+each waypoint can be an ICAO identifier or a `lon,lat` tuple. Waypoints must be
+specified in order from origin to destination.
+
+    $ wx metar --path-dist 10 --waypoint ksea --waypoint kbos
+
+### Controlling density
+
+When running a query which will return METARs from many stations, it may be
+helpful to reduce the density of the results. This can be done with the
+`--min-dist` argument which specifies a minimum distance (in degrees of latitude
+or longitude) between stations to display. Providing a higher value for
+`--min-dist` will result in fewer stations being returned.
+
+    $ wx metar \
+      --path-dist 10 --waypoint ksea --waypoint kbos \
+      --min-dist 5 \
+
+### Filtering recency
+
+There are two mechanisms for filtering results by recency. First, you can
+request the single most recent METAR from all the stations being fetched:
+
+    $ wx metar --past 6h kbos ksea --most-recent
+
+Even though we've specified two stations, KBOS and KSEA, we'll only get a single
+METAR back from whichever of the two stations most recently made an observation.
+
+The second filtering mechanism is `--most-recent-by-station`. This argument can
+take several values:
+
+* `constraint` (default): request the most recent for each METAR station in the
+  fastest fashion.
+* `postfilter`: filter results after applying all other constraints.
+* `false`: don't filter results to only the most recent for each station.
+
+## Contributing
+
+Email patches to <mailto:~benburwell/patchall@lists.sr.ht>.
+
+## License
+
+MIT
diff --git a/cmd/metar.go b/cmd/metar.go
index 6355105..ea72f70 100644
--- a/cmd/metar.go
+++ b/cmd/metar.go
@@ -124,7 +124,7 @@ conjunction with --until`)
 		`Ending time for METARs (e.g. "2020-01-01T01:31:00" or "3h"), used in
 conjunction with --since`)
 	metarCmd.Flags().DurationVar(
-		&past, "past", 0,
+		&past, "past", time.Hour,
 		`Duration to retrieve METARs since (e.g. "3h")`)
 
 	// location constraints
@@ -154,8 +154,8 @@ reported. A higher value results in less dense results.`)
 		&mostRecentByStation, "most-recent-by-station", "constraint",
 		`Method for fetching most recent for each station ("constraint",
 "postfilter", "false")`)
-	metarCmd.Flags().BoolVarP(
-		&mostRecent, "one", "1", false,
+	metarCmd.Flags().BoolVar(
+		&mostRecent, "most-recent", false,
 		`Only fetch the single most recently-issued METAR of all the selected
 stations`)
 }
@@ -173,19 +173,14 @@ var metarCmd = &cobra.Command{
 
 		if !since.t.IsZero() || !until.t.IsZero() {
 			reqArgs = append(reqArgs, metar.TimeRange(since.t, until.t))
-		}
-
-		dur, _ := cmd.Flags().GetDuration("past")
-		if dur > 0 {
+		} else if dur, _ := cmd.Flags().GetDuration("past"); dur > 0 {
 			reqArgs = append(reqArgs, metar.HoursBeforeNow(dur.Hours()))
 		}
 
-		if mostRecentByStation != "" {
-			reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation))
-		}
-
 		if mostRecent {
 			reqArgs = append(reqArgs, metar.MostRecent(true))
+		} else if mostRecentByStation != "" {
+			reqArgs = append(reqArgs, metar.MostRecentForEachStation(mostRecentByStation))
 		}
 
 		if !rect.IsZero() {
diff --git a/doc/wx.1.scd b/doc/wx.1.scd
index 1b452d8..a11f65c 100644
--- a/doc/wx.1.scd
+++ b/doc/wx.1.scd
@@ -2,7 +2,7 @@ wx(1)
 
 # NAME
 
-wx - a front-end CLI for NOAA Aviation Weather Center data
+wx - a command line interface for aviation weather
 
 # SYNOPSIS
 
@@ -10,5 +10,61 @@ wx _command_
 
 # COMMANDS
 
-*metar*
-	fetch METAR data
+*metar* [_station_ ...]
+	fetch METAR data for _station_
+
+# METAR
+
+When fetching METARs, a time constraint must be supplied. A time constraint can
+either be in the form "past x" or "between x and y".
+
+Options:
+
+*--past* _duration_
+	fetch METARs from the past _duration_, formatted as a Go duration string
+	(e.g. _3h_).
+
+	*Default:* 1h
+
+*--since* _time_
+	fetch METARs since _time_, formatted as YYYY-MM-DDTHH:MM:SS
+
+*--until* _time_
+	fetch METARs until _time_, formatted as YYYY-MM-DDTHH:MM:SS
+
+*--rect* _minLat_,_minLon_,_maxLat_,_maxLon_
+	fetch METARs within the specified rectangle
+
+*--radial* _dist_,_lat_,_lon_
+	fetch METARs within _dist_ statute miles of the specified point
+
+*--path-dist* _dist_
+	when used with *--waypoint*, specify a maximum distance around the flight
+	path in which to fetch METARs.
+
+*--waypoint* _point_
+	fetch METARs along a flight path specified by multiple *--waypoint* arguments
+	in order from origin to destination. The _point_ may be either an ICAO
+	identifier or a lon,lat pair.
+
+*--min-dist* _dist_
+	when fetching METARs from multiple sources, enforce a minimum distance of
+	_dist_ degrees of latitude or longitude between stations to reduce the
+	density.
+
+*--most-recent*
+	fetch only the single most recent METAR that matches the station filters.
+
+*--most-recent-by-station* _type_
+	fetch the most recent METAR for each station that matches using _type_ as the
+	filter type, which can be one of constraint, postfilter, or false.
+
+	See _https://www.aviationweather.gov/dataserver/example?datatype=metar_ for
+	information about these options.
+
+	*Default:* constraint
+
+# AUTHORS
+
+Ben Burwell <wx@benburwell.com>. For more information, see
+_https://git.sr.ht/~benburwell/wxcli_.