From 83a2eaef9853194093a457b0ab65fc231acce23f Mon Sep 17 00:00:00 2001
From: Lukasz Kasprzak <lukas@labunix.xyz>
Date: Thu, 27 Aug 2026 08:49:38 +0200
Subject: Draw a meteogram, and let the output go somewhere

-svg renders the forecast as a standalone SVG: temperature with the apparent
temperature dashed, precipitation as bars with the probability on its own
right-hand axis, and humidity, over shaded night bands with a rule at each
midnight. The rain panel carries two units, so the probability gets a second
axis; read against millimetres a 60% chance looks like 0.6 mm.

Written as markup rather than through gnuplot or a plotting library, so it
needs nothing installed and works wherever the binary does -- the phone
included. Axis ticks are snapped to round values and the number of gridlines
follows the step, since snapping only the ends still yields 12.5 and 27.5.
An hour label that would land under a bold date is dropped, or "23" and
"28.08" render on top of each other.

-o and -out choose the destination, for the table as much as the meteogram. A
directory gets a filename made from the place and the date, so a daily run does
not overwrite yesterday; a bare name gains the extension, so nothing lands as a
file no viewer will open. Colour is omitted when writing to a file. The place
is transliterated rather than stripped, so Zbylitowska Gora keeps its vowels.

Documented which viewers accept a pipe: feh - and chafa do, nsxiv does not and
answers with its usage, which hides the cause. The earlier claim that
ImageMagick renders these files wrong was too broad -- that is convert falling
back to its own renderer; display delegates to rsvg-convert and is fine.
---
 man/prognosis.1 | 83 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

(limited to 'man')

diff --git a/man/prognosis.1 b/man/prognosis.1
index 8c28b60..75c276a 100644
--- a/man/prognosis.1
+++ b/man/prognosis.1
@@ -87,6 +87,36 @@ 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 \-svg
+Produce an SVG meteogram instead of the hourly table. See
+.BR METEOGRAM .
+.TP
+.BI \-o " PATH" ", " \-out " PATH"
+Write to
+.I PATH
+instead of standard output.
+.PP
+.RS
+If
+.I PATH
+is an existing directory, or ends in a separator (in which case it is created),
+a filename is generated from the place and the date, so repeated runs on
+different days do not overwrite each other:
+.IR krakow-pl-2026-08-27.svg .
+Otherwise
+.I PATH
+is a filename, gaining
+.B .svg
+or
+.B .txt
+if it has none. A single
+.B -
+means standard output.
+.PP
+Colour is omitted when writing to a file, whatever the terminal would have
+shown.
+.RE
+.TP
 .B \-config
 Print the path of the configuration file and exit.
 .TP
@@ -216,6 +246,59 @@ a string appended to each value.
 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 METEOGRAM
+.B \-svg
+writes a standalone SVG: three panels sharing one time axis \(em temperature
+with the apparent temperature dashed, precipitation as bars with the
+probability as a dashed line against its own right-hand axis, and relative
+humidity \(em over shaded night bands, with dates marked at midnight.
+.PP
+No plotting library or external program is involved: SVG is markup, so this
+works on a machine with no graphics tooling at all.
+.PP
+.in +4n
+.EX
+prognosis \-l Krakow \-d 2 \-svg meteogram.svg
+firefox meteogram.svg
+rsvg\-convert \-o meteogram.png meteogram.svg
+.EE
+.in
+.PP
+The meteogram requests the fields it needs regardless of
+.BR columns ,
+so it is complete even when the table shows none of them.
+.PP
+Not every viewer reads from a pipe.
+.BR feh (1)
+does, given
+.BR - ,
+and so does
+.BR chafa (1);
+.BR nsxiv (1)
+has no standard-input mode at all and prints its usage, which does not make the
+cause obvious. Write the file first with
+.B \-o
+for those:
+.PP
+.in +4n
+.EX
+prognosis \-l Krakow \-svg | feh -
+prognosis \-l Krakow \-svg | chafa
+prognosis \-l Krakow \-svg \-o ~/tmp && nsxiv ~/tmp/krakow-pl-*.svg
+.EE
+.in
+.PP
+Most viewers handle the file itself, including
+.BR nsxiv (1),
+.BR feh (1),
+.BR display (1)
+and any browser, or
+.BR chafa (1)
+to draw it inside the terminal.
+.BR convert (1)
+may fall back to ImageMagick's own SVG renderer, which drops the curves;
+.BR rsvg-convert (1)
+does not.
 .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
-- 
cgit v1.3