From ee30c7fd182f0f17d3da957cecc34e38b4331f85 Mon Sep 17 00:00:00 2001 From: John Kerl Date: Mon, 12 Dec 2016 18:58:23 -0500 Subject: [PATCH] doc neaten --- c/cli/mlrcli.c | 3 +- c/todo.txt | 2 + doc/content-for-file-formats.html | 10 ++- doc/cookbook.html | 106 +++++++++++++++--------------- doc/file-formats.html | 72 +++++++++++++++++++- doc/manpage.html | 5 +- doc/manpage.txt | 5 +- doc/mlr.1 | 7 +- doc/reference.html | 3 +- 9 files changed, 149 insertions(+), 64 deletions(-) diff --git a/c/cli/mlrcli.c b/c/cli/mlrcli.c index c430a3f7a..bb7ef4c4b 100644 --- a/c/cli/mlrcli.c +++ b/c/cli/mlrcli.c @@ -696,7 +696,8 @@ static void main_usage_data_format_options(FILE* o, char* argv0) { fprintf(o, " --ipprint --opprint --pprint Pretty-printed tabular (produces no\n"); fprintf(o, " output until all input is in).\n"); fprintf(o, " --right Right-justifies all fields for PPRINT output.\n"); - fprintf(o, " --barred Prints a border around PPRINT output.\n"); + fprintf(o, " --barred Prints a border around PPRINT output\n"); + fprintf(o, " (only available for output).\n"); fprintf(o, "\n"); fprintf(o, " --omd Markdown-tabular (only available for output).\n"); fprintf(o, "\n"); diff --git a/c/todo.txt b/c/todo.txt index 3198708c9..51ead41ce 100644 --- a/c/todo.txt +++ b/c/todo.txt @@ -29,6 +29,8 @@ OTHER: * poki-run no '$ ' for comment lines +! --c2x et al. on file-formats page + ---------------------------------------------------------------- MAPVAR CHECKLIST: diff --git a/doc/content-for-file-formats.html b/doc/content-for-file-formats.html index 47a860cee..267a679e7 100644 --- a/doc/content-for-file-formats.html +++ b/doc/content-for-file-formats.html @@ -4,7 +4,7 @@ POKI_PUT_TOC_HERE

Miller handles name-indexed data using several formats: some you probably know by name, such as CSV, TSV, and JSON — and other formats you’re -likely already seeing in structured data. +likely already seeing and using in your structured data.

Examples

@@ -265,3 +265,11 @@ which renders like this when dropped into various web tools (e.g. github comment

As of Miller 4.3.0, markdown format is supported only for output, not input. + +

Data-conversion keystroke-savers

+ +

While you can do format conversion using mlr --icsv --ojson cat myfile.csv, +there are also keystroke-savers for this purpose, such as mlr --c2j cat myfile.csv. +For a complete list: + +POKI_RUN_COMMAND{{mlr --usage-data-format-options}}HERE diff --git a/doc/cookbook.html b/doc/cookbook.html index 20ebdeea2..8edb5038c 100644 --- a/doc/cookbook.html +++ b/doc/cookbook.html @@ -607,33 +607,33 @@ $ mlr --ofmt '%.9lf' --opprint seqgen --start 1 --stop 28 then put ' ' then put '$seconds=systime()' then step -a delta -f seconds then cut -x -f seconds i o fcount seconds_delta 1 1 1 0 -2 2 3 0.000025988 -3 3 5 0.000013113 +2 2 3 0.000028133 +3 3 5 0.000012875 4 5 9 0.000015974 -5 8 15 0.000020981 -6 13 25 0.000033140 -7 21 41 0.000044823 -8 34 67 0.000070095 -9 55 109 0.000111103 -10 89 177 0.000175953 -11 144 287 0.000279903 -12 233 465 0.000450134 -13 377 753 0.000735998 -14 610 1219 0.001163006 -15 987 1973 0.001877785 -16 1597 3193 0.003018141 -17 2584 5167 0.004863977 -18 4181 8361 0.007838011 -19 6765 13529 0.012058020 -20 10946 21891 0.019617081 -21 17711 35421 0.032136917 -22 28657 57313 0.056536913 -23 46368 92735 0.087702990 -24 75025 150049 0.140336037 -25 121393 242785 0.217164993 -26 196418 392835 0.361617088 -27 317811 635621 0.591296911 -28 514229 1028457 0.958522081 +5 8 15 0.000022173 +6 13 25 0.000032902 +7 21 41 0.000046015 +8 34 67 0.000071049 +9 55 109 0.000110865 +10 89 177 0.000179052 +11 144 287 0.000281096 +12 233 465 0.000451803 +13 377 753 0.000724077 +14 610 1219 0.001167059 +15 987 1973 0.002076864 +16 1597 3193 0.003108025 +17 2584 5167 0.004957199 +18 4181 8361 0.008294821 +19 6765 13529 0.017652035 +20 10946 21891 0.022655964 +21 17711 35421 0.039558172 +22 28657 57313 0.054703951 +23 46368 92735 0.088239908 +24 75025 150049 0.155187130 +25 121393 242785 0.232927799 +26 196418 392835 0.364882231 +27 317811 635621 0.610341787 +28 514229 1028457 0.956062078

@@ -665,33 +665,33 @@ $ mlr --ofmt '%.9lf' --opprint seqgen --start 1 --stop 28 then put ' ' then put '$seconds=systime()' then step -a delta -f seconds then cut -x -f seconds i o fcount seconds_delta 1 1 1 0 -2 2 3 0.000030994 -3 3 3 0.000015020 -4 5 3 0.000013113 -5 8 3 0.000012875 -6 13 3 0.000013113 -7 21 3 0.000011921 -8 34 3 0.000011921 -9 55 3 0.000012159 -10 89 3 0.000011921 -11 144 3 0.000011921 -12 233 3 0.000015974 -13 377 3 0.000012159 -14 610 3 0.000012875 -15 987 3 0.000012159 -16 1597 3 0.000010967 -17 2584 3 0.000011921 -18 4181 3 0.000011921 -19 6765 3 0.000012159 -20 10946 3 0.000010967 -21 17711 3 0.000011921 -22 28657 3 0.000013113 -23 46368 3 0.000015020 -24 75025 3 0.000011921 -25 121393 3 0.000011921 -26 196418 3 0.000012159 -27 317811 3 0.000011921 -28 514229 3 0.000011921 +2 2 3 0.000033855 +3 3 3 0.000015974 +4 5 3 0.000012159 +5 8 3 0.000018835 +6 13 3 0.000019073 +7 21 3 0.000019073 +8 34 3 0.000116825 +9 55 3 0.000044107 +10 89 3 0.000020981 +11 144 3 0.000023127 +12 233 3 0.000044823 +13 377 3 0.000033140 +14 610 3 0.000022888 +15 987 3 0.000019073 +16 1597 3 0.000017881 +17 2584 3 0.000019073 +18 4181 3 0.000026941 +19 6765 3 0.000025034 +20 10946 3 0.000028133 +21 17711 3 0.000017881 +22 28657 3 0.000020981 +23 46368 3 0.000038147 +24 75025 3 0.000018835 +25 121393 3 0.000038147 +26 196418 3 0.000064850 +27 317811 3 0.000015974 +28 514229 3 0.000013113

diff --git a/doc/file-formats.html b/doc/file-formats.html index 3caad3d50..525c39df4 100644 --- a/doc/file-formats.html +++ b/doc/file-formats.html @@ -156,6 +156,7 @@ Miller commands were run with pretty-print-tabular output format. • PPRINT: Pretty-printed tabular
• XTAB: Vertical tabular
• Markdown tabular
+• Data-conversion keystroke-savers

@@ -163,7 +164,7 @@ Miller commands were run with pretty-print-tabular output format.

Miller handles name-indexed data using several formats: some you probably know by name, such as CSV, TSV, and JSON — and other formats you’re -likely already seeing in structured data. +likely already seeing and using in your structured data.

Examples

@@ -780,6 +781,75 @@ which renders like this when dropped into various web tools (e.g. github comment

As of Miller 4.3.0, markdown format is supported only for output, not input. + +

Data-conversion keystroke-savers

+ +

While you can do format conversion using mlr --icsv --ojson cat myfile.csv, +there are also keystroke-savers for this purpose, such as mlr --c2j cat myfile.csv. +For a complete list: + +

+

+
+$ mlr --usage-data-format-options
+  --idkvp   --odkvp   --dkvp      Delimited key-value pairs, e.g "a=1,b=2"
+                                  (this is Miller's default format).
+
+  --inidx   --onidx   --nidx      Implicitly-integer-indexed fields
+                                  (Unix-toolkit style).
+
+  --icsv    --ocsv    --csv       Comma-separated value (or tab-separated
+                                  with --fs tab, etc.)
+
+  --itsv    --otsv    --tsv       Keystroke-savers for "--icsv --ifs tab",
+                                  "--ocsv --ofs tab", "--csv --fs tab".
+
+  --ipprint --opprint --pprint    Pretty-printed tabular (produces no
+                                  output until all input is in).
+                      --right     Right-justifies all fields for PPRINT output.
+                      --barred    Prints a border around PPRINT output
+                                  (only available for output).
+
+            --omd                 Markdown-tabular (only available for output).
+
+  --ixtab   --oxtab   --xtab      Pretty-printed vertical-tabular.
+                      --xvright   Right-justifies values for XTAB format.
+
+  --ijson   --ojson   --json      JSON tabular: sequence or list of one-level
+                                  maps: {...}{...} or [{...},{...}].
+                      --jvstack   Put one key-value pair per line for JSON
+                                  output.
+                      --jlistwrap Wrap JSON output in outermost [ ].
+                      --jquoteall Quote map keys in JSON output, even if they're
+                                  numeric.
+              --jflatsep {string} Separator for flattening multi-level JSON keys,
+                                  e.g. '{"a":{"b":3}}' becomes a:b => 3 for
+                                  non-JSON formats. Defaults to :.
+
+  -p is a keystroke-saver for --nidx --fs space --repifs
+
+  Examples: --csv for CSV-formatted input and output; --idkvp --opprint for
+  DKVP-formatted input and pretty-printed output.
+
+  PLEASE USE "mlr --csv --rs lf" FOR NATIVE UN*X (LINEFEED-TERMINATED) CSV FILES.
+  You can also have MLR_CSV_DEFAULT_RS=lf in your shell environment, e.g.
+  "export MLR_CSV_DEFAULT_RS=lf" or "setenv MLR_CSV_DEFAULT_RS lf" depending on
+  which shell you use.
+
+As keystroke-savers for format-conversion you may use the following:
+  --c2t --c2d --c2n --c2j --c2x --c2p --c2m
+  --t2c       --t2d --t2n --t2j --t2x --t2p --t2m
+  --d2c --d2t       --d2n --d2j --d2x --d2p --d2m
+  --n2c --n2t --n2d       --n2j --n2x --n2p --n2m
+  --j2c --j2t --j2d --j2n       --j2x --j2p --j2m
+  --x2c --x2t --x2d --x2n --x2j       --x2p --x2m
+  --p2c --p2t --p2d --p2n --p2j --p2x       --p2m
+The letters c t d n j x p m refer to formats CSV with LF, TSV with LF, DKVP,
+NIDX, JSON, XTAB, PPRINT, and markdown, respectively. Note that markdown format
+is available for output only.
+
+
+

diff --git a/doc/manpage.html b/doc/manpage.html index a46cb81bb..3d0ac3673 100644 --- a/doc/manpage.html +++ b/doc/manpage.html @@ -308,7 +308,8 @@ OPTIONS --ipprint --opprint --pprint Pretty-printed tabular (produces no output until all input is in). --right Right-justifies all fields for PPRINT output. - --barred Prints a border around PPRINT output. + --barred Prints a border around PPRINT output + (only available for output). --omd Markdown-tabular (only available for output). @@ -1964,7 +1965,7 @@ SEE ALSO - 2016-12-11 MILLER(1) + 2016-12-12 MILLER(1)

diff --git a/doc/manpage.txt b/doc/manpage.txt index c7e5dac89..07b6bb0a7 100644 --- a/doc/manpage.txt +++ b/doc/manpage.txt @@ -159,7 +159,8 @@ OPTIONS --ipprint --opprint --pprint Pretty-printed tabular (produces no output until all input is in). --right Right-justifies all fields for PPRINT output. - --barred Prints a border around PPRINT output. + --barred Prints a border around PPRINT output + (only available for output). --omd Markdown-tabular (only available for output). @@ -1815,4 +1816,4 @@ SEE ALSO - 2016-12-11 MILLER(1) + 2016-12-12 MILLER(1) diff --git a/doc/mlr.1 b/doc/mlr.1 index 984fb749a..0310dc595 100644 --- a/doc/mlr.1 +++ b/doc/mlr.1 @@ -2,12 +2,12 @@ .\" Title: mlr .\" Author: [see the "AUTHOR" section] .\" Generator: ./mkman.rb -.\" Date: 2016-12-11 +.\" Date: 2016-12-12 .\" Manual: \ \& .\" Source: \ \& .\" Language: English .\" -.TH "MILLER" "1" "2016-12-11" "\ \&" "\ \&" +.TH "MILLER" "1" "2016-12-12" "\ \&" "\ \&" .\" ----------------------------------------------------------------- .\" * Portability definitions .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -214,7 +214,8 @@ Please use "mlr --help-all-keywords" or "mlr -k" for help on all keywords. --ipprint --opprint --pprint Pretty-printed tabular (produces no output until all input is in). --right Right-justifies all fields for PPRINT output. - --barred Prints a border around PPRINT output. + --barred Prints a border around PPRINT output + (only available for output). --omd Markdown-tabular (only available for output). diff --git a/doc/reference.html b/doc/reference.html index 475bc522f..105491710 100644 --- a/doc/reference.html +++ b/doc/reference.html @@ -391,7 +391,8 @@ Data-format options, for input, output, or both: --ipprint --opprint --pprint Pretty-printed tabular (produces no output until all input is in). --right Right-justifies all fields for PPRINT output. - --barred Prints a border around PPRINT output. + --barred Prints a border around PPRINT output + (only available for output). --omd Markdown-tabular (only available for output).