commit bf5177b65a99d5e54854d1582bed66cd26a1b191
from: mtmn <miro@haravara.org>
date: Sun Aug 23 20:43:43 2026 UTC

add demo files

commit - 6a82e8ad5c44b3d93d46ddf1435abf7d80c5fd21
commit + bf5177b65a99d5e54854d1582bed66cd26a1b191
blob - 8283d22422e606634ca60f721913a870e1bac089
blob + 73d03f6f42c37dd0d01d033814130591f837d5a8
--- README.md
+++ README.md
@@ -2,14 +2,25 @@
 
 Terminal browser for an MPD release archive, written in Chez Scheme.
 
-Paths are read as:
+The input directory must contain `all.txt`. Its non-empty lines are
+slash-separated release paths, read as:
 
 - `artist/album`
-- `label/artist/release`
+- `label/artist/release` (or a longer label/artist/release path)
 
-Parent paths are not counted as releases. All recognized files are scanned; no
-date cutoff is applied.
+Parent paths are not counted as releases. mcol scans the catalog and recognized
+dated lists without a date cutoff:
 
+- `YEAR/MONTH/dailies/YYYY-MM-DD.txt`, or historical `DD_MM_YYYY.txt`
+- `YEAR/dailies/YYYY-MM-DD.txt` as a fallback when a month-local daily is absent
+- `YEAR/dailies/stdin_playlist_YYYYMMDD*.txt` as a fallback when no daily exists
+- `YEAR/MONTH/1_..._....txt` through `YEAR/MONTH/4_..._....txt` for weekly lists
+
+`MONTH` is a full English month name. Multiple session playlists for a date are
+merged. Weekly and daily totals are compared in the Weeks view, never combined.
+Files below `mixes/` or `labels/` are ignored. `--strict` rejects malformed
+filenames in recognized daily and weekly locations.
+
 ## Run
 
 Requires Chez Scheme 10.4 or newer. Playback requires `mpc`.
@@ -25,6 +36,12 @@ export MCOL_INPUT=~/src/mtmn.name/releases
 make tui
 ```
 
+A small runnable demo is included in [`demo/`](demo/README.md):
+
+```sh
+make tui INPUT=demo
+```
+
 ## Keys
 
 ```text
@@ -39,8 +56,9 @@ Enter a row number to open it. Commands such as `:mont
 `:day 2026-08-11`, `:label Warp`, `:artist Autechre`, and `:search Autechre`
 are also accepted.
 
-Use `p 4 5 2` to append visible releases 4, 5, and 2 and start the first one.
-Use `q 4 5 2` to append them without changing playback.
+`r` prompts for a random-release count (default: 5). Use `p 4 5 2` to append
+visible releases 4, 5, and 2 and start the first one. Use `q 4 5 2` to append
+them without changing playback.
 
 ## Build and install
 
blob - d3f6be58e4c132b824df642eafd4f3215950b56b
blob + 95e2464c6878a517eb2e5fe7da0f74b22d682ad1
--- doc/mcol.1
+++ doc/mcol.1
@@ -1,4 +1,4 @@
-.TH MCOL 1 "2026-08-12" "mcol" "User Commands"
+.TH MCOL 1 "2026-08-23" "mcol" "User Commands"
 .SH NAME
 mcol \- browse an MPD release archive
 .SH SYNOPSIS
@@ -8,16 +8,50 @@ mcol \- browse an MPD release archive
 .SH DESCRIPTION
 .B mcol
 is a terminal browser for a directory of release lists.
-It reads two-part paths as artist/album and longer paths as
-label/artist/release.
+The directory must contain an
+.I all.txt
+catalog.  Each non-empty line is a slash-separated release path.  Two-part
+paths are interpreted as artist/album; paths with three or more parts are
+interpreted as label/artist/release, with any remaining parts retained in the
+release name.  Parent paths are not counted as releases.
 .PP
 The input directory comes from
 .BR \-\-input ,
 .BR MCOL_INPUT ,
 or the current directory, in that order.
-All recognized files are scanned.
+The catalog and recognized dated lists are scanned without a date cutoff.
 Playback uses
 .BR mpc (1).
+.SH ARCHIVE LAYOUT
+In addition to
+.IR all.txt ,
+mcol recognizes these text-list locations beneath the input directory:
+.TP
+.I YEAR/MONTH/dailies/YYYY-MM-DD.txt
+Daily additions, where MONTH is a full English month name.  The historical
+.I DD_MM_YYYY.txt
+form is also accepted.
+.TP
+.I YEAR/dailies/YYYY-MM-DD.txt
+A legacy daily list.  It is used only when no month-local daily list exists
+for that date.
+.TP
+.I YEAR/dailies/stdin_playlist_YYYYMMDD*.txt
+Session playlists.  Multiple playlists for a date are merged and are used
+only when no daily list exists for that date.
+.TP
+.I YEAR/MONTH/1_..._....txt through YEAR/MONTH/4_..._....txt
+Weekly lists.  Weekly and daily totals are shown side by side and are not
+combined.
+.PP
+Other text files, including files below directories named
+.IR mixes
+or
+.IR labels ,
+are ignored.  With
+.BR \-\-strict ,
+malformed filenames in otherwise recognized daily or weekly locations cause
+the scan to fail.
 .SH OPTIONS
 .TP
 .BI \-\-input " PATH"
@@ -39,22 +73,26 @@ Show months, weeks, labels, or artists.
 .B s
 Search artists, labels, releases, and paths.
 .TP
+.B r
+Play randomly selected releases.  It prompts for a count and defaults to 5.
+.TP
 .B p
 Append the selected release to the MPD queue and play its first track.
 .B p N ...
-does the same for numbered release rows in the given order.
+does the same for numbered release rows visible on the current page, in the
+given order.
 .TP
 .B q
 Append the selected release to the end of the MPD queue.
 .B q N ...
-queues numbered release rows in the given order.
+queues numbered release rows visible on the current page, in the given order.
 .TP
 .B NUMBER
 Open a row.
 .TP
-.BR [ ,
-.B ]
-Move between pages.
+.BR nn ,
+.B pp
+Move to the next or previous page.
 .TP
 .B b
 Go back.
@@ -81,7 +119,7 @@ and
 Default input directory.
 .TP
 .B NO_COLOR
-Disable colour.
+Disable ANSI colour when set to any value.
 .TP
 .B MPD_HOST
 MPD server or socket, read by
@@ -92,4 +130,5 @@ Override terminal dimensions.
 .SH EXIT STATUS
 Zero on normal exit, non-zero on error.
 .SH SEE ALSO
+.BR mpc (1),
 .BR mpd (1)
blob - /dev/null
blob + f1b71aebc64cd176e8e40db41867a315c6bc3444 (mode 644)
--- /dev/null
+++ demo/2024/december/dailies/2024-12-05.txt
@@ -0,0 +1,2 @@
+Distant Signs/Loam/Seasonal Shift
+Field Notes/Iris/Slow Map
blob - /dev/null
blob + 45a35329552163bd1942010c73f1ea141920aab5 (mode 644)
--- /dev/null
+++ demo/2025/august/1_08_2025.txt
@@ -0,0 +1,3 @@
+Coral Circuit/Zero Fold/Date Line
+Analog Sea/Nocturne/Resonant
+Coastline/Rune/Blue Current
blob - /dev/null
blob + 9cd12db105eed5ef3f82fcab73f10de57cc87be9 (mode 644)
--- /dev/null
+++ demo/2025/dailies/2025-08-12.txt
@@ -0,0 +1,4 @@
+Coral Circuit/Zero Fold/Date Line
+Lumen Records/Mara Venn/Between Stations
+Heat Index/Sable/Light Leak
+Kaito/Glass Gardens
blob - /dev/null
blob + 39b49ef0a0eac834655130b34833b3a5a12d4638 (mode 644)
--- /dev/null
+++ demo/2026/august/1_08_2026.txt
@@ -0,0 +1,5 @@
+Northern Electronics/Elin Piel/Soft Static
+Lumen Records/Mara Venn/Between Stations
+Kaito/Glass Gardens
+Aria/Signals at Dawn
+Analog Sea/Nocturne/Resonant
blob - /dev/null
blob + 5262217dbea8bf8e9b04178c5d64fc8b54250294 (mode 644)
--- /dev/null
+++ demo/2026/august/dailies/2026-08-20.txt
@@ -0,0 +1,7 @@
+Northern Electronics/Elin Piel/Soft Static
+Kaito/Glass Gardens
+Aria/Signals at Dawn
+Distant Signs/Loam/Seasonal Shift
+Coastline/Rune/Blue Current
+Heat Index/Sable/Light Leak
+Field Notes/Iris/Slow Map
blob - /dev/null
blob + 6b73089ed3ffa5a9ee4c3f318cbeb960f053313e (mode 644)
--- /dev/null
+++ demo/2026/august/dailies/21_08_2026.txt
@@ -0,0 +1,2 @@
+Lumen Records/Mara Venn/Between Stations
+Analog Sea/Nocturne/Resonant
blob - /dev/null
blob + 9d42347726a1704cc598d961331516e8adc7913c (mode 644)
--- /dev/null
+++ demo/2026/august/labels/august_labels.txt
@@ -0,0 +1,2 @@
+Distant Signs
+Lumen Records
blob - /dev/null
blob + 3245a971988aa00cf7394461d80b921cf6191b9a (mode 644)
--- /dev/null
+++ demo/2026/dailies/2026-08-18.txt
@@ -0,0 +1,3 @@
+Aria/Signals at Dawn
+Coral Circuit/Zero Fold/Date Line
+Heat Index/Sable/Light Leak
blob - /dev/null
blob + b85fcf2c43b4d1ea69dba4765a27172ea671a319 (mode 644)
--- /dev/null
+++ demo/2026/dailies/2026-08-20.txt
@@ -0,0 +1,5 @@
+Aria/Signals at Dawn
+Kaito/Glass Gardens
+Distant Signs/Loam/Seasonal Shift
+Field Notes/Iris/Slow Map
+Coastline/Rune/Blue Current
blob - /dev/null
blob + b3d079eae2c5e1cae583136393d056211608b378 (mode 644)
--- /dev/null
+++ demo/2026/dailies/stdin_playlist_20260819_120000.txt
@@ -0,0 +1,4 @@
+Northern Electronics/Elin Piel/Soft Static
+Lumen Records/Mara Venn/Between Stations
+Distant Signs/Loam/Seasonal Shift
+Heat Index/Sable/Light Leak
blob - /dev/null
blob + a0b6533a13f32c4d86d0e1fd66e77b08fd381e59 (mode 644)
--- /dev/null
+++ demo/2026/dailies/stdin_playlist_20260819_180000.txt
@@ -0,0 +1,2 @@
+Lumen Records/Mara Venn/Between Stations
+Coastline/Rune/Blue Current
blob - /dev/null
blob + a26e5133697c62ba42413cd19c29659bddee9cea (mode 644)
--- /dev/null
+++ demo/README.md
@@ -0,0 +1,10 @@
+# Demo
+
+Run this small set of release lists from the repository root:
+
+```sh
+make tui INPUT=demo
+```
+
+The dated lists demonstrate daily, legacy, session, and weekly activity
+sources. mcol derives its browsable release library from these files.