Add descriptions for put and filter verbs (#1529)

* Add more info in online help about what put/filter do

* `make dev` artifacts

docs/src/manpage.md

@@ -804,6 +804,7 @@ This is simply a copy of what you should see on running `man mlr` at a command p
  csv "," N/A "\n"
  csvlite "," N/A "\n"
  dkvp "," "=" "\n"
+ gen "," N/A "\n"
  json N/A N/A N/A
  markdown " " N/A "\n"
  nidx " " N/A "\n"
@@ -1072,6 +1073,10 @@ This is simply a copy of what you should see on running `man mlr` at a command p
 
  1mfilter0m
  Usage: mlr filter [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically filter which
+ stream records will be output.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -1525,6 +1530,9 @@ This is simply a copy of what you should see on running `man mlr` at a command p
 
  1mput0m
  Usage: mlr put [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically alter stream records.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -3704,5 +3712,5 @@ This is simply a copy of what you should see on running `man mlr` at a command p
  MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
  https://miller.readthedocs.io
 
- 2024-02-18 4mMILLER24m(1)
+ 2024-03-16 4mMILLER24m(1)
 </pre>

docs/src/manpage.txt

@@ -783,6 +783,7 @@
  csv "," N/A "\n"
  csvlite "," N/A "\n"
  dkvp "," "=" "\n"
+ gen "," N/A "\n"
  json N/A N/A N/A
  markdown " " N/A "\n"
  nidx " " N/A "\n"
@@ -1051,6 +1052,10 @@
 
  1mfilter0m
  Usage: mlr filter [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically filter which
+ stream records will be output.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -1504,6 +1509,9 @@
 
  1mput0m
  Usage: mlr put [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically alter stream records.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -3683,4 +3691,4 @@
  MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
  https://miller.readthedocs.io
 
- 2024-02-18 4mMILLER24m(1)
+ 2024-03-16 4mMILLER24m(1)

docs/src/reference-main-flag-list.md

@@ -477,6 +477,7 @@ Notes about all other separators:
   csv "," N/A "\n"
   csvlite "," N/A "\n"
   dkvp "," "=" "\n"
+  gen "," N/A "\n"
   json N/A N/A N/A
   markdown " " N/A "\n"
   nidx " " N/A "\n"

docs/src/reference-verbs.md

@@ -970,6 +970,10 @@ a,b,c
 </pre>
 <pre class="pre-non-highlight-in-pair">
 Usage: mlr filter [options] {DSL expression}
+Lets you use a domain-specific language to progamatically filter which
+stream records will be output.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -2301,6 +2305,9 @@ Options:
 </pre>
 <pre class="pre-non-highlight-in-pair">
 Usage: mlr put [options] {DSL expression}
+Lets you use a domain-specific language to progamatically alter stream records.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.

man/manpage.txt

@@ -783,6 +783,7 @@
  csv "," N/A "\n"
  csvlite "," N/A "\n"
  dkvp "," "=" "\n"
+ gen "," N/A "\n"
  json N/A N/A N/A
  markdown " " N/A "\n"
  nidx " " N/A "\n"
@@ -1051,6 +1052,10 @@
 
  1mfilter0m
  Usage: mlr filter [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically filter which
+ stream records will be output.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -1504,6 +1509,9 @@
 
  1mput0m
  Usage: mlr put [options] {DSL expression}
+ Lets you use a domain-specific language to progamatically alter stream records.
+ See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
  Options:
  -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -3683,4 +3691,4 @@
  MIME Type for Comma-Separated Values (CSV) Files, the Miller docsite
  https://miller.readthedocs.io
 
- 2024-02-18 4mMILLER24m(1)
+ 2024-03-16 4mMILLER24m(1)

man/mlr.1

@@ -2,12 +2,12 @@
 .\" Title: mlr
 .\" Author: [see the "AUTHOR" section]
 .\" Generator: ./mkman.rb
-.\" Date: 2024-02-18
+.\" Date: 2024-03-16
 .\" Manual: \ \&
 .\" Source: \ \&
 .\" Language: English
 .\"
-.TH "MILLER" "1" "2024-02-18" "\ \&" "\ \&"
+.TH "MILLER" "1" "2024-03-16" "\ \&" "\ \&"
 .\" -----------------------------------------------------------------
 .\" * Portability definitions
 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -936,6 +936,7 @@ Notes about all other separators:
  csv "," N/A "\en"
  csvlite "," N/A "\en"
  dkvp "," "=" "\en"
+ gen "," N/A "\en"
  json N/A N/A N/A
  markdown " " N/A "\en"
  nidx " " N/A "\en"
@@ -1314,6 +1315,10 @@ Options:
 .\}
 .nf
 Usage: mlr filter [options] {DSL expression}
+Lets you use a domain-specific language to progamatically filter which
+stream records will be output.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -1899,6 +1904,9 @@ Options:
 .\}
 .nf
 Usage: mlr put [options] {DSL expression}
+Lets you use a domain-specific language to progamatically alter stream records.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.

pkg/transformers/put_or_filter.go

@@ -52,6 +52,14 @@ func transformerPutOrFilterUsage(
  verb string,
 ) {
  fmt.Fprintf(o, "Usage: %s %s [options] {DSL expression}\n", "mlr", verb)
+ if verb == "put" {
+ fmt.Fprintf(o, "Lets you use a domain-specific language to progamatically alter stream records.\n")
+ } else if verb == "filter" {
+ fmt.Fprintf(o, "Lets you use a domain-specific language to progamatically filter which\n")
+ fmt.Fprintf(o, "stream records will be output.\n")
+ }
+ fmt.Fprintf(o, "See also: https://miller.readthedocs.io/en/latest/reference-verbs\n")
+ fmt.Fprintf(o, "\n")
  fmt.Fprintf(o, "Options:\n")
  fmt.Fprintf(o,
  `-f {file name} File containing a DSL expression (see examples below). If the filename

test/cases/cli-help/0001/expout

@@ -186,6 +186,10 @@ Options:
 ================================================================
 filter
 Usage: mlr filter [options] {DSL expression}
+Lets you use a domain-specific language to progamatically filter which
+stream records will be output.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.
@@ -661,6 +665,9 @@ Options:
 ================================================================
 put
 Usage: mlr put [options] {DSL expression}
+Lets you use a domain-specific language to progamatically alter stream records.
+See also: https://miller.readthedocs.io/en/latest/reference-verbs
+
 Options:
 -f {file name} File containing a DSL expression (see examples below). If the filename
  is a directory, all *.mlr files in that directory are loaded.