add manpage and README

3 files changed, 118 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index 93ef656..35eee5c 100644
--- a/Makefile
+++ b/Makefile
@@ -1,9 +1,12 @@
-CFLAGS=-O2 -Wall -Wno-unused-parameter -Wextra -Wwrite-strings
-
 ALL=mlog
 
+CFLAGS=-g -O2 -Wall -Wno-unused-parameter -Wextra -Wwrite-strings
+
 all: $(ALL)
 
+README: mlog.1
+	mandoc -Tutf8 $< | col -bx >$@
+
 clean: FRC
 	rm -f $(ALL)
 
diff --git a/README b/README
new file mode 100644
index 0000000..6b6e439
--- /dev/null
+++ b/README
@@ -0,0 +1,49 @@
+MLOG(1)                     General Commands Manual                    MLOG(1)
+
+NAME
+     mlog – merge log files by timestamp
+
+SYNOPSIS
+     mlog [-f] [-s] [-u] [files ...]
+
+DESCRIPTION
+     mlog reads lines from multiple log files and prints them in chronological
+     order.  The files need to start with comparable timestamps.  mlog prints
+     the oldest line first, thus preserving relative order.
+
+     mlog behaves like a combination of ‘sort -m’ and ‘tail -f’.
+
+     The options are as follows:
+
+     -f      Follow the output files, output appended lines as file grows.
+             When the file is truncated or recreated, start from beginning.
+             With two -f flags, seek to the end of files on start and only
+             print fresh lines.
+
+     -s      Strip a prefix generated by socklog(8) from each line, which have
+             a format like ‘facility.priority: timestamp’.
+
+     -u      Only print unique lines.  If other files contain the same line at
+             the current position, skip them.
+
+EXIT STATUS
+     The mlog utility exits 0 on success, and >0 if an error occurs.
+
+INTERNALS
+     On Linux, inotify(7) is used to detect file changes.
+
+SEE ALSO
+     tail(1), sort(1), svlogd(8)
+
+AUTHORS
+     Leah Neukirchen <leah@vuxu.org>
+
+LICENSE
+     mlog is in the public domain.
+
+     To the extent possible under law, the creator of this work has waived all
+     copyright and related or neighboring rights to this work.
+
+     http://creativecommons.org/publicdomain/zero/1.0/
+
+Void Linux                     January 12, 2024                     Void Linux
diff --git a/mlog.1 b/mlog.1
new file mode 100644
index 0000000..edbd3a9
--- /dev/null
+++ b/mlog.1
@@ -0,0 +1,64 @@
+.Dd January 12, 2024
+.Dt MLOG 1
+.Os
+.Sh NAME
+.Nm mlog
+.Nd merge log files by timestamp
+.Sh SYNOPSIS
+.Nm
+.Op Fl f
+.Op Fl s
+.Op Fl u
+.Op Ar files\ ...
+.Sh DESCRIPTION
+.Nm
+reads lines from multiple log files and prints them in chronological order.
+The files need to start with comparable timestamps.
+.Nm
+prints the oldest line first, thus preserving relative order.
+.Pp
+.Nm
+behaves like a combination of
+.Ql sort -m
+and
+.Ql tail -f .
+.Pp
+The options are as follows:
+.Bl -tag -width Ds
+.It Fl f
+Follow the output files, output appended lines as file grows.
+When the file is truncated or recreated, start from beginning.
+With two
+.Fl f
+flags, seek to the end of files on start and only print fresh lines.
+.It Fl s
+Strip a prefix generated by
+.Xr socklog 8
+from each line, which have a format like
+.Ql Ar facility Ns \&. Ns Ar priority Ns \&: Ar timestamp .
+.It Fl u
+Only print unique lines.
+If other files contain the same line at the current position, skip them.
+.El
+.Sh EXIT STATUS
+.Ex -std
+.Sh INTERNALS
+On Linux,
+.Xr inotify 7
+is used to detect file changes.
+.Sh SEE ALSO
+.Xr tail 1 ,
+.Xr sort 1 ,
+.Xr svlogd 8
+.Sh AUTHORS
+.An Leah Neukirchen Aq Mt leah@vuxu.org
+.Sh LICENSE
+.Nm
+is in the public domain.
+.Pp
+To the extent possible under law,
+the creator of this work
+has waived all copyright and related or
+neighboring rights to this work.
+.Pp
+.Lk http://creativecommons.org/publicdomain/zero/1.0/