Stand alone, document, and let the config show anythingv0.1.1

prognosis no longer reads ~/.wegorc. Falling back to another program's
configuration made it useless without wego installed, and hid the fact that
it has no way to know where you are: location= is now required in its own
config, and the error says so and shows how to set it.

Custom columns. Any field the two Open-Meteo APIs expose can be displayed by
declaring it -- column.birch = air:birch_pollen -- and then naming it in
columns=. The source is explicit because forecast and air-quality are separate
services with separate fields; an air column costs one extra request, made only
when one is declared. Air values merge onto forecast hours by timestamp rather
than array index, since nothing guarantees the two endpoints start at the same
hour and merging by position would shift a column by an hour unnoticed. A value
the API withholds renders blank, not zero: for an allergen those are different
claims.

Pollen selection no longer privileges grass. A species named in pollen= is
shown even at zero, because you named it for a reason; pollen=all shows only
what is present, or the line is six zeroes. Grass had been special-cased, which
forced it on someone allergic to birch while hiding theirs.

Temperature colours are compared in Celsius whatever the display units. In
imperial, 85F -- a mild 29C -- was rendering in the red that means IMGW would
issue a heat warning.

A man page, checked by make lint and installed by make install. The Makefile
gains PREFIX/DESTDIR for packaging, a version stamped into the binary, a
release target that refuses to tag a dirty tree or a version with no changelog
entry, cross-compilation for six platforms, and a pre-push hook.

Also: humidity in the default columns, -weather for output meant for someone
else, -ascii so an SMS stays in GSM-7 rather than dropping to 70-character
UCS-2 segments, and -pollen and -version.

1 files changed, 276 insertions, 0 deletions

diff --git a/man/prognosis.1 b/man/prognosis.1
new file mode 100644
index 0000000..8c28b60
--- /dev/null
+++ b/man/prognosis.1
@@ -0,0 +1,276 @@
+.TH PROGNOSIS 1 "2026-08-21" "prognosis" "User Commands"
+.SH NAME
+prognosis \- hour-by-hour terminal forecast with official Polish warnings
+.SH SYNOPSIS
+.B prognosis
+.RI [ options ]
+.RI [ place ]
+.SH DESCRIPTION
+.B prognosis
+prints an hourly weather table, a temperature chart, and \(em for locations in
+Poland \(em the meteorological warnings IMGW has issued for that powiat.
+.PP
+It needs no API key and has no third-party dependencies. Which columns appear,
+in what order, and in which language is set by the configuration file; columns
+the program does not ship with can be declared there too, so any field the
+underlying APIs expose can be displayed. See
+.B CUSTOM COLUMNS .
+.PP
+Output is pipe-safe: colour is switched off when standard output is not a
+terminal, notes and diagnostics go to standard error, and
+.B \-ascii
+restricts output to ASCII for onward transmission by SMS.
+.SH OPTIONS
+.TP
+.BI \-l " PLACE"
+Place to query: a name, or
+.IR lat , lon .
+Overrides
+.B location
+in the configuration file for one run.
+.TP
+.BI \-n " N"
+Show
+.I N
+hours ahead.
+.TP
+.BI \-d " N"
+Show
+.I N
+days ahead, of 24 hours each. Mutually exclusive with
+.BR \-n .
+.TP
+.BI \-pick " N"
+Choose the
+.IR N th
+candidate for an ambiguous place name, and remember it. Re-resolves rather than
+reading the cache, which is how a wrongly cached name is corrected.
+.TP
+.BI \-columns " LIST"
+Comma-separated columns to display, overriding the configuration file.
+.TP
+.BI \-icons " SET"
+Glyph set for the
+.B icon
+column:
+.BR nerd ,
+.BR emoji ,
+or
+.BR none .
+.TP
+.BI \-pollen " LIST"
+Allergens to show for one run: a comma-separated list, or
+.B all
+or
+.BR none .
+.TP
+.BI \-lang " LANG"
+Display language:
+.B en
+or
+.BR pl .
+.TP
+.B \-weather
+Forecast only: omit sun times, the day summary, pollen and the chart.
+.TP
+.B \-no\-warnings
+Omit IMGW warnings.
+.TP
+.B \-no\-graph
+Table only, no chart.
+.TP
+.B \-no\-color
+Plain output, no escape sequences.
+.TP
+.B \-ascii
+Restrict output to ASCII. Intended for SMS, where a single non-ASCII character
+forces the message from GSM\-7 (160 characters per segment) into UCS\-2 (70).
+The degree sign becomes the unit letter and Polish diacritics are transliterated.
+.TP
+.B \-config
+Print the path of the configuration file and exit.
+.TP
+.B \-version
+Print the version and exit.
+.SH CONFIGURATION
+The configuration file is
+.I $XDG_CONFIG_HOME/prognosis/config
+(by default
+.IR ~/.config/prognosis/config ).
+It is written with commented defaults on first run. The format is one
+.I KEY=VALUE
+per line;
+.B #
+begins a comment; values are not quoted.
+.PP
+Command line flags override the file, and the file overrides the built-in
+defaults.
+.TP
+.B location
+Place to query. Required: prognosis has no other way to know where you are and
+will not guess.
+.TP
+.B hours
+Default span in hours.
+.TP
+.B units
+.BR metric ", " imperial " or " si .
+Passed to the provider, so rounding is theirs. Warning thresholds are always
+compared in Celsius, whatever the display units.
+.TP
+.B columns
+Columns to display, in order.
+.TP
+.B icons
+.BR nerd ", " emoji " or " none .
+.TP
+.B graph ", " graph_height
+Whether to draw the temperature chart, and over how many rows.
+.TP
+.B warnings
+Whether to check IMGW for warnings.
+.TP
+.B pollen
+Which allergens to report, or whether to report any:
+.B none
+omits the line entirely,
+.B all
+shows every species that has a reading, and a comma-separated list shows exactly
+those species \(em even at zero, since a species you named is one you react to
+and "none today" is the answer you wanted. With
+.B all
+nobody chose, so absent species are dropped rather than printing a line of
+zeroes. Species:
+.BR grass ", " birch ", " alder ", " mugwort ", " ragweed ", " olive .
+.TP
+.B color
+.BR auto ", " always " or " never .
+.TP
+.B display_lang
+.BR en " or " pl .
+Covers everything prognosis writes itself. IMGW publishes its warning text in
+Polish only, so that text remains Polish in either language.
+.TP
+.B ascii
+Restrict output to ASCII, as
+.BR \-ascii .
+.SH COLUMNS
+Built-in columns:
+.BR hour ", " icon ", " temp ", " feels ", " conditions ", " mm ", " rain ", "
+.BR wind ", " gusts ", " dir ", " humidity ", " dew ", " uv ", " cloud ", "
+.BR pressure ", " visibility .
+.PP
+Only the fields the selected columns need are requested, so a narrow table
+costs a smaller response. An unknown column name is an error at startup naming
+the offender, never a silently blank column.
+.PP
+.B mm
+and
+.B rain
+are hidden automatically when the window is dry and no hour reaches a 20%
+chance of precipitation, and the day summary says
+.I dry
+instead.
+.SH CUSTOM COLUMNS
+Any field the two Open-Meteo APIs expose can be displayed, whether or not
+prognosis knows about it. Declare a short name, then use it in
+.BR columns .
+.PP
+.in +4n
+.EX
+columns=hour,temp,birch,soil,conditions
+
+column.birch = air:birch_pollen
+column.soil  = forecast:soil_temperature_0cm
+
+label.soil     = soil
+suffix.soil    = \(de
+decimals.soil  = 0
+label.birch    = birch
+decimals.birch = 1
+.EE
+.in
+.PP
+.B column.\fINAME\fB = \fISOURCE\fB:\fIFIELD\fR
+is the declaration.
+.I SOURCE
+is
+.B forecast
+(the weather API) or
+.B air
+(the air-quality API, which carries the allergens); they are separate services
+with separate field sets, which is why the source must be given. An
+.B air
+column costs one extra request, made only when such a column is declared.
+.PP
+The remaining keys are optional:
+.B label.\fINAME\fR
+sets the header (default: the name),
+.B width.\fINAME\fR
+the column width (default: derived from the label),
+.B decimals.\fINAME\fR
+the digits after the point (default: 0), and
+.B suffix.\fINAME\fR
+a string appended to each value.
+.PP
+A custom name may not shadow a built-in column. A value the API does not supply
+renders blank rather than as zero: for an allergen, "no data" and "none" are
+different claims.
+.SH WARNINGS
+IMGW publishes every warning in Poland, each tagged with the TERYT codes of the
+powiats it covers. The coordinates are resolved to that code through GUGiK, so
+warnings are filtered to your area rather than the whole country.
+.PP
+Four states are kept deliberately distinct, because silence must never be
+mistaken for an all-clear:
+.TP
+warnings printed
+In force for your powiat.
+.TP
+nothing printed
+Checked; none in force.
+.TP
+.I warnings: could not check IMGW
+The check itself failed.
+.TP
+.I warnings: IMGW covers Poland only
+The location is outside Poland.
+.SH FILES
+.TP
+.I ~/.config/prognosis/config
+Configuration.
+.TP
+.I ~/.cache/prognosis/cache.json
+Cached geocoding and TERYT lookups, one entry per line. Disposable: an entry
+that will not parse is skipped and the rest kept; a file that will not parse at
+all is moved aside to
+.I cache.json.bad
+rather than overwritten.
+.SH EXIT STATUS
+.TP
+.B 0
+Success.
+.TP
+.B 1
+The forecast could not be fetched.
+.TP
+.B 2
+Usage error: bad flags, an invalid configuration, no location set, or an
+ambiguous place name.
+.SH EXAMPLES
+.TP
+.B prognosis
+The next twelve hours where you live.
+.TP
+.B prognosis \-l krakow \-d 3
+Three days for another place.
+.TP
+.B prognosis \-weather \-ascii \-no\-warnings \-n 6
+A short, ASCII-only forecast suitable for sending by SMS.
+.SH SEE ALSO
+.BR wego (1)
+.PP
+Data from Open-Meteo (https://open-meteo.com/), GUGiK
+(https://services.gugik.gov.pl/) and IMGW (https://danepubliczne.imgw.pl/).
+.SH AUTHOR
+Lukasz Kasprzak.