diff --git a/c/draft-release-notes.md b/c/draft-release-notes.md
index 4d83f965b..047bda161 100644
--- a/c/draft-release-notes.md
+++ b/c/draft-release-notes.md
@@ -1,9 +1,6 @@
 ## Features:
 
-* **Comment strings in data files:** `mlr --skip-comments` allows you to
-filter out input lines starting with `#`, for all file formats.  Likewise, `mlr
---skip-comments-with X` lets you specify the comment-string `X`.  Comments are
-only supported at start of data line.
+* [**Comment strings in data files:**](http://johnkerl.org/miller-releases/miller-5.3.0/doc/file-formats.html#Comments_in_data) `mlr --skip-comments` allows you to filter out input lines starting with `#`, for all file formats.  Likewise, `mlr --skip-comments-with X` lets you specify the comment-string `X`.  Comments are only supported at start of data line.  `mlr --pass-comments` and `mlr --pass-comments-with X` allow you to forward comments to program output as they are read.  
 
 * The [**count-similar**](http://johnkerl.org/miller-releases/miller-5.3.0/doc/reference-verbs.html#count-similar)
 verb lets you compute cluster sizes by cluster labels.
diff --git a/c/todo.txt b/c/todo.txt
index 234eff55a..2d95f751f 100644
--- a/c/todo.txt
+++ b/c/todo.txt
@@ -16,10 +16,10 @@ BUGFIXES
 
 * comment-handling:
   o UT for CRLFs
-  o mlh
-  o mld
+  o UT for non-#
+
+! double-check line-number handling for csv/csvlite/other errors
 
-* xxx note for trailing whitespace in json fixed
 * sql-setup doc somewhere .......
 
 * bare ./configure ?
diff --git a/doc/content-for-file-formats.html b/doc/content-for-file-formats.html
index e8f488686..6d94563d5 100644
--- a/doc/content-for-file-formats.html
+++ b/doc/content-for-file-formats.html
@@ -10,7 +10,8 @@ POKI_PUT_TOC_HERE
 
 <p/>Miller handles name-indexed data using several formats: some you probably
 know by name, such as CSV, TSV, and JSON &mdash; and other formats you&rsquo;re
-likely already seeing and using in your structured data.
+likely already seeing and using in your structured data. Additionally, Miller gives
+you the option of including comments within your data.
 
 </div>
 <h1>Examples</h1>
@@ -361,3 +362,19 @@ POKI_PUT_LINK_FOR_PAGE(reference.html#Record/field/pair_separators)HERE for
 more information about record/field/pair separators.
 
 </div>
+<h1>Comments in data</h1>
+<button style="font-weight:bold;color:maroon;border:0" padding=0 onclick="toggle_by_name('section_toggle_comments_in_data');" href="javascript:;">Toggle section visibility</button>
+<div id="section_toggle_comments_in_data" style="display: block">
+
+<p/>You can include comments within your data files, and either have them ignored, or passed directly
+through to the standard output as soon as they are encountered:
+
+POKI_RUN_COMMAND{{mlr --usage-comments-in-data}}HERE
+
+<p/>Examples:
+
+POKI_RUN_COMMAND{{cat data/budget.csv}}HERE
+POKI_RUN_COMMAND{{mlr --skip-comments --icsv --opprint sort -nr quantity data/budget.csv}}HERE
+POKI_RUN_COMMAND{{mlr --pass-comments --icsv --opprint sort -nr quantity data/budget.csv}}HERE
+
+</div>
diff --git a/doc/data/budget.csv b/doc/data/budget.csv
new file mode 100644
index 000000000..db8efc622
--- /dev/null
+++ b/doc/data/budget.csv
@@ -0,0 +1,5 @@
+# Asana -- here are the budget figure you asked for!
+type,quantity
+purple,456.78
+green,678.12
+orange,123.45
diff --git a/doc/file-formats.html b/doc/file-formats.html
index ad5440572..4373f2b41 100644
--- a/doc/file-formats.html
+++ b/doc/file-formats.html
@@ -204,6 +204,7 @@ Miller commands were run with pretty-print-tabular output format.
 &bull;&nbsp;<a href="#Markdown_tabular">Markdown tabular</a><br/>
 &bull;&nbsp;<a href="#Data-conversion_keystroke-savers">Data-conversion keystroke-savers</a><br/>
 &bull;&nbsp;<a href="#Autodetect_of_line_endings">Autodetect of line endings</a><br/>
+&bull;&nbsp;<a href="#Comments_in_data">Comments in data</a><br/>
 </div>
 <p/>
 
@@ -217,7 +218,8 @@ Miller commands were run with pretty-print-tabular output format.
 
 <p/>Miller handles name-indexed data using several formats: some you probably
 know by name, such as CSV, TSV, and JSON &mdash; and other formats you&rsquo;re
-likely already seeing and using in your structured data.
+likely already seeing and using in your structured data. Additionally, Miller gives
+you the option of including comments within your data.
 
 </div>
 <a id="Examples"/><h1>Examples</h1>
@@ -1004,6 +1006,76 @@ Unix/Linux/BSD/MacOSX, and CRLF on Windows.
 <a href="reference.html#Record/field/pair_separators">Reference</a> for
 more information about record/field/pair separators.
 
+</div>
+<a id="Comments_in_data"/><h1>Comments in data</h1>
+<button style="font-weight:bold;color:maroon;border:0" padding=0 onclick="toggle_by_name('section_toggle_comments_in_data');" href="javascript:;">Toggle section visibility</button>
+<div id="section_toggle_comments_in_data" style="display: block">
+
+<p/>You can include comments within your data files, and either have them ignored, or passed directly
+through to the standard output as soon as they are encountered:
+
+<p/>
+<div class="pokipanel">
+<pre>
+$ mlr --usage-comments-in-data
+  --skip-comments                 Ignore commented lines (prefixed by "#")
+                                  within the input.
+  --skip-comments-with {string}   Ignore commented lines within input, with
+                                  specified prefix.
+  --pass-comments                 Immediately print commented lines (prefixed by "#")
+                                  within the input.
+  --pass-comments-with {string}   Immediately print commented lines within input, with
+                                  specified prefix.
+Notes:
+* Comments are only honored at the start of a line.
+* In the absence of any of the above four options, comments are data like
+  any other text.
+* When pass-comments is used, comment lines are written to standard output
+  immediately upon being read; they are not part of the record stream.
+  Results may be counterintuitive. A suggestion is to place comments at the
+  start of data files.
+</pre>
+</div>
+<p/>
+
+<p/>Examples:
+
+<p/>
+<div class="pokipanel">
+<pre>
+$ cat data/budget.csv
+# Asana -- here are the budget figure you asked for!
+type,quantity
+purple,456.78
+green,678.12
+orange,123.45
+</pre>
+</div>
+<p/>
+<p/>
+<div class="pokipanel">
+<pre>
+$ mlr --skip-comments --icsv --opprint sort -nr quantity data/budget.csv
+type   quantity
+green  678.12
+purple 456.78
+orange 123.45
+</pre>
+</div>
+<p/>
+<p/>
+<div class="pokipanel">
+<pre>
+$ mlr --pass-comments --icsv --opprint sort -nr quantity data/budget.csv
+# Asana -- here are the budget figure you asked for!
+type   quantity
+green  678.12
+purple 456.78
+orange 123.45
+</pre>
+</div>
+<p/>
+
 </div>
     </div>
   </td>