1 files changed, 59 insertions, 0 deletions
diff --git a/scripts/annotate-output.1 b/scripts/annotate-output.1
new file mode 100644
index 0000000..f2fec00
--- /dev/null
+++ b/scripts/annotate-output.1
@@ -0,0 +1,59 @@
+.TH ANNOTATE-OUTPUT 1 "Debian Utilities" "DEBIAN" \" -*- nroff -*-
+.SH NAME
+annotate-output \- annotate program output with time and stream
+.SH SYNOPSIS
+\fBannotate\-output\fR [\fIoptions\fR] \fIprogram\fR [\fIargs\fR ...]
+.SH DESCRIPTION
+\fBannotate\-output\fR will execute the specified program, while
+prepending every line with the current time and O for stdout and E for
+stderr.
+
+.SH OPTIONS
+.TP
+\fB+FORMAT\fR
+Controls the timestamp format, as per \fBdate\fR(1).  Defaults to
+"%H:%M:%S".
+.TP
+\fB\-h\fR, \fB\-\-help\fR
+Display a help message and exit successfully.
+
+.SH EXAMPLE
+
+.nf
+$ annotate-output make
+21:41:21 I: Started make
+21:41:21 O: gcc \-Wall program.c
+21:43:18 E: program.c: Couldn't compile, and took me ages to find out
+21:43:19 E: collect2: ld returned 1 exit status
+21:43:19 E: make: *** [all] Error 1
+21:43:19 I: Finished with exitcode 2
+.fi
+
+.SH BUGS
+Since stdout and stderr are processed in parallel, it can happen that
+some lines received on stdout will show up before later-printed stderr
+lines (and vice-versa).
+
+This is unfortunately very hard to fix with the current annotation
+strategy.  A fix would involve switching to PTRACE'ing the process.
+Giving nice a (much) higher priority over the executed program could
+however cause this behaviour to show up less frequently.
+
+The program does not work as well when the output is not linewise.  In
+particular, when an interactive program asks for input, the question
+might not be shown until after you have answered it.  This will give
+the impression that the annotated program has hung, while it has not.
+
+.SH "SEE ALSO"
+\fBdate\fR(1)
+
+.SH SUPPORT
+This program is community-supported (meaning: you'll need to fix it
+yourself).  Patches are however appreciated, as is any feedback
+(positive or negative).
+
+.SH AUTHOR
+\fBannotate-output\fR was written by Jeroen van Wolffelaar
+<jeroen@wolffelaar.nl>. This manpage comes under the same copyright as
+annotate-output itself, read /usr/bin/annotate-output (or wherever
+you install it) for the details.