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.