diff --git a/c/mapping/mapper_reshape.c b/c/mapping/mapper_reshape.c
index e643ca48c..3c8a4b3f1 100644
--- a/c/mapping/mapper_reshape.c
+++ b/c/mapping/mapper_reshape.c
@@ -89,9 +89,14 @@ static void mapper_reshape_usage(FILE* o, char* argv0, char* verb) {
 	fprintf(o, "  -r {input field regexes} -o {key-field name,value-field name}\n");
 	fprintf(o, "  These pivot/reshape the input data such that the input fields are removed\n");
 	fprintf(o, "  and separate records are emitted for each key/value pair.\n");
+	fprintf(o, "  Note: this works with tail -f and produces output records for each input\n");
+	fprintf(o, "  record seen.\n");
 	fprintf(o, "Long-to-wide options:\n");
 	fprintf(o, "  -s {key-field name,value-field name}\n");
 	fprintf(o, "  These pivot/reshape the input data to undo the wide-to-long operation.\n");
+	fprintf(o, "  Note: this does not work with tail -f; it produces output records only after\n");
+	fprintf(o, "  all input records have been read.\n");
+	fprintf(o, "\n");
 	fprintf(o, "Examples:\n");
 	fprintf(o, "\n");
 	fprintf(o, "  Input file \"wide.txt\":\n");
@@ -119,6 +124,13 @@ static void mapper_reshape_usage(FILE* o, char* argv0, char* verb) {
 	fprintf(o, "    2009-01-03 Y    1.3179287\n");
 	fprintf(o, "\n");
 	fprintf(o, "  Input file \"long.txt\":\n");
+	fprintf(o, "    time       item value\n");
+	fprintf(o, "    2009-01-01 X    0.65473572\n");
+	fprintf(o, "    2009-01-01 Y    2.4520609\n");
+	fprintf(o, "    2009-01-02 X    -0.89248112\n");
+	fprintf(o, "    2009-01-02 Y    0.2154713\n");
+	fprintf(o, "    2009-01-03 X    0.98012375\n");
+	fprintf(o, "    2009-01-03 Y    1.3179287\n");
 	fprintf(o, "\n");
 	fprintf(o, "  %s --pprint %s -s item,value long.txt\n", argv0, verb);
 	fprintf(o, "    time       X           Y\n");
diff --git a/doc/mlr.1.premade b/doc/mlr.1.premade
index 5860aa823..8701591d2 100644
--- a/doc/mlr.1.premade
+++ b/doc/mlr.1.premade
@@ -781,9 +781,14 @@ Wide-to-long options:
   -r {input field regexes} -o {key-field name,value-field name}
   These pivot/reshape the input data such that the input fields are removed
   and separate records are emitted for each key/value pair.
+  Note: this works with tail -f and produces output records for each input
+  record seen.
 Long-to-wide options:
   -s {key-field name,value-field name}
   These pivot/reshape the input data to undo the wide-to-long operation.
+  Note: this does not work with tail -f; it produces output records only after
+  all input records have been read.
+
 Examples:
 
   Input file "wide.txt":
@@ -811,6 +816,13 @@ Examples:
     2009-01-03 Y    1.3179287
 
   Input file "long.txt":
+    time       item value
+    2009-01-01 X    0.65473572
+    2009-01-01 Y    2.4520609
+    2009-01-02 X    -0.89248112
+    2009-01-02 Y    0.2154713
+    2009-01-03 X    0.98012375
+    2009-01-03 Y    1.3179287
 
   mlr --pprint reshape -s item,value long.txt
     time       X           Y
diff --git a/doc/reference.html b/doc/reference.html
index e049d96a2..09dc36546 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -2474,9 +2474,14 @@ Wide-to-long options:
   -r {input field regexes} -o {key-field name,value-field name}
   These pivot/reshape the input data such that the input fields are removed
   and separate records are emitted for each key/value pair.
+  Note: this works with tail -f and produces output records for each input
+  record seen.
 Long-to-wide options:
   -s {key-field name,value-field name}
   These pivot/reshape the input data to undo the wide-to-long operation.
+  Note: this does not work with tail -f; it produces output records only after
+  all input records have been read.
+
 Examples:
 
   Input file "wide.txt":
@@ -2504,6 +2509,13 @@ Examples:
     2009-01-03 Y    1.3179287
 
   Input file "long.txt":
+    time       item value
+    2009-01-01 X    0.65473572
+    2009-01-01 Y    2.4520609
+    2009-01-02 X    -0.89248112
+    2009-01-02 Y    0.2154713
+    2009-01-03 X    0.98012375
+    2009-01-03 Y    1.3179287
 
   mlr --pprint reshape -s item,value long.txt
     time       X           Y