From 819de818577e2d3a0b4aa1e596233fc78c2bd4f8 Mon Sep 17 00:00:00 2001
From: John Kerl <kerl.john.r@gmail.com>
Date: Fri, 8 May 2015 21:33:01 -0700
Subject: [PATCH] sortv2 impl checkpoint incl. UTs & doc

---
 c/cli/mlrcli.c                            |   1 -
 c/mapping/mapper_sort.c                   | 168 +++++++++++----
 c/mapping/mapper_sortv2.c                 | 250 ----------------------
 c/mapping/mappers.h                       |   1 -
 c/t1.rb                                   |  16 +-
 c/test/expected/out                       | 184 ++++++++++++++++
 c/test/output/out                         | 184 ++++++++++++++++
 c/test/run                                |  21 ++
 c/todo.txt                                |   2 +
 doc/content-for-data-examples.html        |   8 +-
 doc/content-for-record-heterogeneity.html |   2 +-
 doc/content-for-reference.html            |  16 +-
 doc/data-examples.html                    |  26 +--
 doc/performance.html                      |   4 +-
 doc/perftbl.txt                           |   4 +-
 doc/record-heterogeneity.html             |   2 +-
 doc/reference.html                        |  70 +++---
 doc/subcommand-example.txt                |   2 +-
 18 files changed, 584 insertions(+), 377 deletions(-)
 delete mode 100644 c/mapping/mapper_sortv2.c

diff --git a/c/cli/mlrcli.c b/c/cli/mlrcli.c
index 9d8ed7cf1..9b9b694c6 100644
--- a/c/cli/mlrcli.c
+++ b/c/cli/mlrcli.c
@@ -28,7 +28,6 @@ static mapper_setup_t* mapper_lookup_table[] = {
 	&mapper_rename_setup,
 	&mapper_reorder_setup,
 	&mapper_sort_setup,
-	&mapper_sortv2_setup,
 	&mapper_stats1_setup,
 	&mapper_stats2_setup,
 	&mapper_step_setup,
diff --git a/c/mapping/mapper_sort.c b/c/mapping/mapper_sort.c
index 710f2c3ec..85f764d80 100644
--- a/c/mapping/mapper_sort.c
+++ b/c/mapping/mapper_sort.c
@@ -8,18 +8,73 @@
 #include "containers/mixutil.h"
 #include "mapping/mappers.h"
 
-// * sort  a,b,c
-// * group-by a,b,c
-// * group-like (same schema, for het-csv-out)
+#define SORT_NUMERIC    0x40
+#define SORT_DESCENDING 0x80
 
 typedef struct _mapper_sort_state_t {
 	slls_t* pkey_field_names;
+	int*    psort_params;
 	// map from list of string to list of record
 	lhmslv_t* precords_by_key_field_names;
 	int do_sort;
 } mapper_sort_state_t;
 
-static int string_list_compare(const void* pva, const void* pvb);
+static int cmp_for_qsort(const void* pva, const void* pvb);
+
+// state for bucket choices:
+// o slls of key-field values
+// n slls/array of key_field_names
+// config for the sort:
+// * compare two arrays of u.string/double by array of num/lex asc/dec
+
+// need num/lex & +/- flags for the sort -- static context for the non-reentrant qsort
+// 'v' payload should be a pair of:
+// * union of double & char*: here do the sscanf of the double if doing numeric sort on that field || abend
+// * record-list as now
+// at the end make an array of the pairs and qsort them on the union part
+// then emit the record-lists as now
+//
+// before doing that, do the num/lex & the +/- at the CLI interface & handle (inefficiently)
+// via repeated sscanf in the comparator:
+// -rn a,b -fn c,d,e -r f,g -f h,i,j,k -- OR--
+// -nr a,b -nf c,d,e -r f,g -f h,i,j,k
+//
+// data structure down there: sllv of sort info which is triple of char* field_name, char do_num, char do_rev.
+
+// xxx cmt about re-entrancy
+static int* pcmp_sort_params = NULL;
+static int cmp_for_qsort(const void* pva, const void* pvb) {
+	const lhmslve_t* pea = pva;
+	const lhmslve_t* peb = pvb;
+	slls_t* pa = pea->key;
+	slls_t* pb = peb->key;
+	if (pa->length != pb->length)
+		return pa->length - pb->length;
+	sllse_t* pe = pa->phead;
+	sllse_t* pf = pb->phead;
+	for (int i = 0; pe != NULL && pf != NULL; pe = pe->pnext, pf = pf->pnext, i++) {
+		if (pcmp_sort_params[i] & SORT_NUMERIC) {
+			double e, f;
+			if (sscanf(pe->value, "%lf", &e) != 1) {
+				fprintf(stderr, "xxx b04k!\n");
+				exit(1);
+			}
+			if (sscanf(pf->value, "%lf", &f) != 1) {
+				fprintf(stderr, "xxx b04k!\n");
+				exit(1);
+			}
+			double d = e - f;
+			int s = (d < 0) ? -1 : 1;
+			if (s != 0)
+				return (pcmp_sort_params[i] & SORT_DESCENDING) ? -s : s;
+		} else {
+			int s = strcmp(pe->value, pf->value);
+			if (s != 0)
+				return (pcmp_sort_params[i] & SORT_DESCENDING) ? -s : s;
+		}
+	}
+	return 0;
+}
 
 // ----------------------------------------------------------------
 sllv_t* mapper_sort_func(lrec_t* pinrec, context_t* pctx, void* pvstate) {
@@ -31,19 +86,6 @@ sllv_t* mapper_sort_func(lrec_t* pinrec, context_t* pctx, void* pvstate) {
 			plist = sllv_alloc();
 			sllv_add(plist, pinrec);
 			lhmslv_put(pstate->precords_by_key_field_names, slls_copy(pkey_field_values), plist);
-			// need num/lex & +/- flags for the sort -- static context for the non-reentrant qsort
-			// 'v' payload should be a pair of:
-			// * union of double & char*: here do the sscanf of the double if doing numeric sort on that field || abend
-			// * record-list as now
-			// at the end make an array of the pairs and qsort them on the union part
-			// then emit the record-lists as now
-			//
-			// before doing that, do the num/lex & the +/- at the CLI interface & handle (inefficiently)
-			// via repeated sscanf in the comparator:
-			// -rn a,b -fn c,d,e -r f,g -f h,i,j,k -- OR--
-			// -nr a,b -nf c,d,e -r f,g -f h,i,j,k
-			//
-			// data structure down there: sllv of sort info which is triple of char* field_name, char do_num, char do_rev.
 		} else {
 			sllv_add(plist, pinrec);
 		}
@@ -69,7 +111,9 @@ sllv_t* mapper_sort_func(lrec_t* pinrec, context_t* pctx, void* pvstate) {
 			pairs[i].value = pe->value;
 		}
 
-		qsort(pairs, num_lists, sizeof(pairs[0]), string_list_compare);
+		pcmp_sort_params = pstate->psort_params;
+		qsort(pairs, num_lists, sizeof(pairs[0]), cmp_for_qsort);
+		pcmp_sort_params = NULL;
 
 		sllv_t* poutput = sllv_alloc();
 		for (i = 0; i < num_lists; i++) {
@@ -84,23 +128,6 @@ sllv_t* mapper_sort_func(lrec_t* pinrec, context_t* pctx, void* pvstate) {
 	}
 }
 
-static int string_list_compare(const void* pva, const void* pvb) {
-	const lhmslve_t* pea = pva;
-	const lhmslve_t* peb = pvb;
-	slls_t* pa = pea->key;
-	slls_t* pb = peb->key;
-	if (pa->length != pb->length)
-		return pa->length - pb->length;
-	sllse_t* pe = pa->phead;
-	sllse_t* pf = pb->phead;
-	for (; pe != NULL && pf != NULL; pe = pe->pnext, pf = pf->pnext) {
-		int s = strcmp(pe->value, pf->value);
-		if (s != 0)
-			return s;
-	}
-	return 0;
-}
-
 // ----------------------------------------------------------------
 static void mapper_sort_free(void* pvstate) {
 	mapper_sort_state_t* pstate = pvstate;
@@ -109,17 +136,22 @@ static void mapper_sort_free(void* pvstate) {
 	if (pstate->precords_by_key_field_names != NULL)
 		// xxx free void-star payloads 1st
 		lhmslv_free(pstate->precords_by_key_field_names);
+	if (pstate->psort_params != NULL)
+		free(pstate->psort_params);
 }
 
-mapper_t* mapper_sort_alloc(slls_t* pkey_field_names, int do_sort) {
+mapper_t* mapper_sort_alloc(slls_t* pkey_field_names, int* psort_params, int do_sort) {
 	mapper_t* pmapper = mlr_malloc_or_die(sizeof(mapper_t));
 
 	mapper_sort_state_t* pstate = mlr_malloc_or_die(sizeof(mapper_sort_state_t));
-	pstate->pkey_field_names = pkey_field_names;
-	pstate->precords_by_key_field_names = lhmslv_alloc();
-	pstate->do_sort = do_sort;
-	pmapper->pvstate = pstate;
 
+	pstate->pkey_field_names            = pkey_field_names;
+	pstate->psort_params                = psort_params;
+	pstate->precords_by_key_field_names = lhmslv_alloc();
+	pstate->do_sort                     = do_sort;
+
+	// xxx put this line by the next x all mapper_*_allocs
+	pmapper->pvstate = pstate;
 	pmapper->pmapper_process_func = mapper_sort_func;
 	pmapper->pmapper_free_func    = mapper_sort_free;
 
@@ -139,7 +171,7 @@ mapper_t* mapper_group_by_parse_cli(int* pargi, int argc, char** argv) {
 	slls_t* pnames = slls_from_line(argv[*pargi+1], ',', FALSE);
 
 	*pargi += 2;
-	return mapper_sort_alloc(pnames, FALSE);
+	return mapper_sort_alloc(pnames, NULL, FALSE);
 }
 
 // ----------------------------------------------------------------
@@ -151,17 +183,61 @@ mapper_setup_t mapper_group_by_setup = {
 
 // ----------------------------------------------------------------
 void mapper_sort_usage(char* argv0, char* verb) {
-	fprintf(stdout, "Usage: %s %s {comma-separated field names}\n", argv0, verb);
+	fprintf(stdout, "Usage: %s %s {xxx}\n", argv0, verb);
+	fprintf(stdout, "       xxx info goes here\n");
 }
 mapper_t* mapper_sort_parse_cli(int* pargi, int argc, char** argv) {
-	if ((argc - *pargi) < 2) {
+	if ((argc - *pargi) < 3) {
 		mapper_sort_usage(argv[0], argv[*pargi]);
 		return NULL;
 	}
+	char* verb = argv[*pargi];
+	*pargi += 1;
+	slls_t* pnames = slls_alloc();
+	slls_t* pflags = slls_alloc();
 
-	slls_t* pnames = slls_from_line(argv[*pargi+1], ',', FALSE);
-	*pargi += 2;
-	return mapper_sort_alloc(pnames, TRUE);
+	while ((argc - *pargi) >= 1 && argv[*pargi][0] == '-') {
+		if ((argc - *pargi) < 2)
+			mapper_sort_usage(argv[0], verb);
+		char* flag  = argv[*pargi];
+		char* value = argv[*pargi+1];
+		*pargi += 2;
+
+		if (streq(flag, "-f")) {
+		} else if (streq(flag, "-n")) {
+		} else if (streq(flag, "-nf")) {
+		} else if (streq(flag, "-r")) {
+		} else if (streq(flag, "-nr")) {
+		} else {
+			mapper_sort_usage(argv[0], verb);
+		}
+		slls_t* pnames_for_flag = slls_from_line(value, ',', FALSE);
+		for (sllse_t* pe = pnames_for_flag->phead; pe != NULL; pe = pe->pnext) {
+			slls_add_no_free(pnames, pe->value);
+			slls_add_no_free(pflags, flag);
+		}
+		slls_free(pnames_for_flag);
+	}
+
+	if (pnames->length < 1)
+		mapper_sort_usage(argv[0], verb);
+
+	int* opt_array  = mlr_malloc_or_die(pnames->length * sizeof(int));
+	sllse_t* pe;
+	int di;
+	for (pe = pflags->phead, di = 0; pe != NULL; pe = pe->pnext, di++) {
+		char* flag = pe->value;
+		int opt =
+			streq(flag, "-nf") ? SORT_NUMERIC :
+			streq(flag, "-n")  ? SORT_NUMERIC :
+			streq(flag, "-r")  ? SORT_DESCENDING :
+			streq(flag, "-nr") ? SORT_NUMERIC|SORT_DESCENDING :
+			0;
+		opt_array[di] =opt;
+	}
+	slls_free(pflags);
+
+	return mapper_sort_alloc(pnames, opt_array, TRUE);
 }
 
 // ----------------------------------------------------------------
diff --git a/c/mapping/mapper_sortv2.c b/c/mapping/mapper_sortv2.c
deleted file mode 100644
index 01952f7bd..000000000
--- a/c/mapping/mapper_sortv2.c
+++ /dev/null
@@ -1,250 +0,0 @@
-#include <stdio.h>
-#include <stdlib.h>
-#include <string.h>
-#include "lib/mlrutil.h"
-#include "containers/sllv.h"
-#include "containers/slls.h"
-#include "containers/lhmslv.h"
-#include "containers/mixutil.h"
-#include "mapping/mappers.h"
-
-#define SORT_NUMERIC    0x40
-#define SORT_DESCENDING 0x80
-
-// * sortv2  a,b,c
-// * group-by a,b,c
-// * group-like (same schema, for het-csv-out)
-
-typedef struct _mapper_sortv2_state_t {
-	slls_t* pkey_field_names;
-	int*    psort_params;
-	// map from list of string to list of record
-	lhmslv_t* precords_by_key_field_names;
-	int do_sort;
-} mapper_sortv2_state_t;
-
-static int cmp_for_qsort(const void* pva, const void* pvb);
-
-// state for bucket choices:
-// o slls of key-field values
-// n slls/array of key_field_names
-// config for the sort:
-// * compare two arrays of u.string/double by array of num/lex asc/dec
-
-// need num/lex & +/- flags for the sortv2 -- static context for the non-reentrant qsort
-// 'v' payload should be a pair of:
-// * union of double & char*: here do the sscanf of the double if doing numeric sortv2 on that field || abend
-// * record-list as now
-// at the end make an array of the pairs and qsort them on the union part
-// then emit the record-lists as now
-//
-// before doing that, do the num/lex & the +/- at the CLI interface & handle (inefficiently)
-// via repeated sscanf in the comparator:
-// -rn a,b -fn c,d,e -r f,g -f h,i,j,k -- OR--
-// -nr a,b -nf c,d,e -r f,g -f h,i,j,k
-//
-// data structure down there: sllv of sortv2 info which is triple of char* field_name, char do_num, char do_rev.
-
-// xxx cmt about re-entrancy
-static int* pcmp_sort_params = NULL;
-static int cmp_for_qsort(const void* pva, const void* pvb) {
-	const lhmslve_t* pea = pva;
-	const lhmslve_t* peb = pvb;
-	slls_t* pa = pea->key;
-	slls_t* pb = peb->key;
-	if (pa->length != pb->length)
-		return pa->length - pb->length;
-	sllse_t* pe = pa->phead;
-	sllse_t* pf = pb->phead;
-	for (int i = 0; pe != NULL && pf != NULL; pe = pe->pnext, pf = pf->pnext, i++) {
-		if (pcmp_sort_params[i] & SORT_NUMERIC) {
-			double e, f;
-			if (sscanf(pe->value, "%lf", &e) != 1) {
-				fprintf(stderr, "xxx b04k!\n");
-				exit(1);
-			}
-			if (sscanf(pf->value, "%lf", &f) != 1) {
-				fprintf(stderr, "xxx b04k!\n");
-				exit(1);
-			}
-			double d = e - f;
-			int s = (d < 0) ? -1 : 1;
-			if (s != 0)
-				return (pcmp_sort_params[i] & SORT_DESCENDING) ? -s : s;
-		} else {
-			int s = strcmp(pe->value, pf->value);
-			if (s != 0)
-				return (pcmp_sort_params[i] & SORT_DESCENDING) ? -s : s;
-		}
-	}
-	return 0;
-}
-
-// ----------------------------------------------------------------
-sllv_t* mapper_sortv2_func(lrec_t* pinrec, context_t* pctx, void* pvstate) {
-	mapper_sortv2_state_t* pstate = pvstate;
-	if (pinrec != NULL) {
-		slls_t* pkey_field_values = mlr_selected_values_from_record(pinrec, pstate->pkey_field_names);
-		sllv_t* plist = lhmslv_get(pstate->precords_by_key_field_names, pkey_field_values);
-		if (plist == NULL) {
-			plist = sllv_alloc();
-			sllv_add(plist, pinrec);
-			lhmslv_put(pstate->precords_by_key_field_names, slls_copy(pkey_field_values), plist);
-		} else {
-			sllv_add(plist, pinrec);
-		}
-		return NULL;
-	}
-	else if (!pstate->do_sort) {
-		sllv_t* poutput = sllv_alloc();
-		for (lhmslve_t* pe = pstate->precords_by_key_field_names->phead; pe != NULL; pe = pe->pnext) {
-			sllv_t* plist = pe->value;
-			for (sllve_t* pf = plist->phead; pf != NULL; pf = pf->pnext) {
-				sllv_add(poutput, pf->pvdata);
-			}
-		}
-		sllv_add(poutput, NULL);
-		return poutput;
-	} else {
-		int num_lists = pstate->precords_by_key_field_names->num_occupied;
-		lhmslve_t* pairs = mlr_malloc_or_die(num_lists * sizeof(lhmslve_t));
-
-		int i = 0;
-		for (lhmslve_t* pe = pstate->precords_by_key_field_names->phead; pe != NULL; pe = pe->pnext, i++) {
-			pairs[i].key   = pe->key;
-			pairs[i].value = pe->value;
-		}
-
-		pcmp_sort_params = pstate->psort_params;
-		qsort(pairs, num_lists, sizeof(pairs[0]), cmp_for_qsort);
-		pcmp_sort_params = NULL;
-
-		sllv_t* poutput = sllv_alloc();
-		for (i = 0; i < num_lists; i++) {
-			sllv_t* plist = pairs[i].value;
-			for (sllve_t* pf = plist->phead; pf != NULL; pf = pf->pnext) {
-				sllv_add(poutput, pf->pvdata);
-			}
-		}
-		free(pairs);
-		sllv_add(poutput, NULL);
-		return poutput;
-	}
-}
-
-// ----------------------------------------------------------------
-static void mapper_sortv2_free(void* pvstate) {
-	mapper_sortv2_state_t* pstate = pvstate;
-	if (pstate->pkey_field_names != NULL)
-		slls_free(pstate->pkey_field_names);
-	if (pstate->precords_by_key_field_names != NULL)
-		// xxx free void-star payloads 1st
-		lhmslv_free(pstate->precords_by_key_field_names);
-	if (pstate->psort_params != NULL)
-		free(pstate->psort_params);
-}
-
-mapper_t* mapper_sortv2_alloc(slls_t* pkey_field_names, int* psort_params, int do_sort) {
-	mapper_t* pmapper = mlr_malloc_or_die(sizeof(mapper_t));
-
-	mapper_sortv2_state_t* pstate = mlr_malloc_or_die(sizeof(mapper_sortv2_state_t));
-
-	pstate->pkey_field_names            = pkey_field_names;
-	pstate->psort_params                = psort_params;
-	pstate->precords_by_key_field_names = lhmslv_alloc();
-	pstate->do_sort                     = do_sort;
-
-	// xxx put this line by the next x all mapper_*_allocs
-	pmapper->pvstate = pstate;
-	pmapper->pmapper_process_func = mapper_sortv2_func;
-	pmapper->pmapper_free_func    = mapper_sortv2_free;
-
-	return pmapper;
-}
-
-// ----------------------------------------------------------------
-void mapper_group_by_v2_usage(char* argv0, char* verb) {
-	fprintf(stdout, "Usage: %s %s {comma-separated field names}\n", argv0, verb);
-}
-mapper_t* mapper_group_by_v2_parse_cli(int* pargi, int argc, char** argv) {
-	if ((argc - *pargi) < 2) {
-		mapper_group_by_v2_usage(argv[0], argv[*pargi]);
-		return NULL;
-	}
-
-	slls_t* pnames = slls_from_line(argv[*pargi+1], ',', FALSE);
-
-	*pargi += 2;
-	return mapper_sortv2_alloc(pnames, NULL, FALSE);
-}
-
-// ----------------------------------------------------------------
-mapper_setup_t mapper_group_v2_by_setup = {
-	.verb = "group-by-v2",
-	.pusage_func = mapper_group_by_v2_usage,
-	.pparse_func = mapper_group_by_v2_parse_cli
-};
-
-// ----------------------------------------------------------------
-void mapper_sortv2_usage(char* argv0, char* verb) {
-	fprintf(stdout, "Usage: %s %s {xxx}\n", argv0, verb);
-	fprintf(stdout, "       xxx info goes here\n");
-}
-mapper_t* mapper_sortv2_parse_cli(int* pargi, int argc, char** argv) {
-	if ((argc - *pargi) < 3) {
-		mapper_sortv2_usage(argv[0], argv[*pargi]);
-		return NULL;
-	}
-	char* verb = argv[*pargi];
-	*pargi += 1;
-	slls_t* pnames = slls_alloc();
-	slls_t* pflags = slls_alloc();
-
-	while ((argc - *pargi) >= 1 && argv[*pargi][0] == '-') {
-		if ((argc - *pargi) < 2)
-			mapper_sortv2_usage(argv[0], verb);
-		char* flag  = argv[*pargi];
-		char* value = argv[*pargi+1];
-		*pargi += 2;
-
-		if (streq(flag, "-f")) {
-		} else if (streq(flag, "-nf")) {
-		} else if (streq(flag, "-r")) {
-		} else if (streq(flag, "-nr")) {
-		} else {
-			mapper_sortv2_usage(argv[0], verb);
-		}
-		slls_t* pnames_for_flag = slls_from_line(value, ',', FALSE);
-		for (sllse_t* pe = pnames_for_flag->phead; pe != NULL; pe = pe->pnext) {
-			slls_add_no_free(pnames, pe->value);
-			slls_add_no_free(pflags, flag);
-		}
-		slls_free(pnames_for_flag);
-	}
-
-	if (pnames->length < 1)
-		mapper_sortv2_usage(argv[0], verb);
-
-	int* opt_array  = mlr_malloc_or_die(pnames->length * sizeof(int));
-	sllse_t* pe;
-	int di;
-	for (pe = pflags->phead, di = 0; pe != NULL; pe = pe->pnext, di++) {
-		char* flag = pe->value;
-		int opt =
-			streq(flag, "-nf") ? SORT_NUMERIC :
-			streq(flag, "-r")  ? SORT_DESCENDING :
-			streq(flag, "-nr") ? SORT_NUMERIC|SORT_DESCENDING :
-			0;
-		opt_array[di] =opt;
-	}
-	slls_free(pflags);
-
-	return mapper_sortv2_alloc(pnames, opt_array, TRUE);
-}
-
-// ----------------------------------------------------------------
-mapper_setup_t mapper_sortv2_setup = {
-	.verb = "sortv2",
-	.pusage_func = mapper_sortv2_usage,
-	.pparse_func = mapper_sortv2_parse_cli
-};
diff --git a/c/mapping/mappers.h b/c/mapping/mappers.h
index 4424ff01b..ea9ab0405 100644
--- a/c/mapping/mappers.h
+++ b/c/mapping/mappers.h
@@ -25,7 +25,6 @@ extern mapper_setup_t mapper_put_setup;
 extern mapper_setup_t mapper_rename_setup;
 extern mapper_setup_t mapper_reorder_setup;
 extern mapper_setup_t mapper_sort_setup;
-extern mapper_setup_t mapper_sortv2_setup;
 extern mapper_setup_t mapper_stats1_setup;
 extern mapper_setup_t mapper_stats2_setup;
 extern mapper_setup_t mapper_step_setup;
diff --git a/c/t1.rb b/c/t1.rb
index a5cd65a94..facf1ff1f 100755
--- a/c/t1.rb
+++ b/c/t1.rb
@@ -37,7 +37,6 @@ run("CATMLRV",   "mlr --csv cat       < data/big.csv > /dev/null")
 puts
 puts
 
-
 run("cutcut",    "cut -d , -f 1,4          < data/big > /dev/null")
 run("cutawk",    "awk -F, '{print $1,$4}'  < data/big > /dev/null")
 run("CUTMLR",    "mlr cut -f a,x           < data/big > /dev/null")
@@ -51,7 +50,6 @@ run("CUTMLRXV",  "mlr --csv cut -x -f a,x       < data/big.csv > /dev/null")
 puts
 puts
 
-
 run("rensed",    "sed -e 's/x=/EKS=/' -e 's/b=/BEE=/' < data/big > /dev/null")
 run("RENMLR",    "mlr rename x,EKS,b,BEE              < data/big > /dev/null")
 puts
@@ -61,7 +59,6 @@ run("RENMLRV",   "mlr --csv rename x,EKS,b,BEE        < data/big.csv > /dev/null
 puts
 puts
 
-
 run("addawk",    "awk -F, '{gsub(\"x=\",\"\",$4);gsub(\"y=\",\"\",$5);print $4+$5}' < data/big > /dev/null")
 run("ADDMLR",    "mlr put '$z=$x+$y'                  < data/big > /dev/null")
 puts
@@ -71,7 +68,6 @@ run("ADDMLRV",   "mlr --csv put '$z=$x+$y'            < data/big.csv > /dev/null
 puts
 puts
 
-
 run("MEANMLR",   "mlr       stats1 -a avg  -f x,y -g a,b < data/big > /dev/null")
 run('CORRMLR',   "mlr       stats2 -a corr -f x,y -g a,b < data/big > /dev/null")
 puts
@@ -81,20 +77,18 @@ run('CORRMLRV',  "mlr      --csv  stats2 -a corr -f x,y -g a,b < data/big.csv >
 puts
 puts
 
-
 run("sortsort1", "sort -t, -k 1,2      < data/big > /dev/null")
-run("SORTMLR1",  "mlr sort a,b         < data/big > /dev/null")
+run("SORTMLR1",  "mlr sort -f a,b      < data/big > /dev/null")
 puts
 
-run("sortsort2", "sort -t, -k 4,5      < data/big > /dev/null")
-run("SORTMLR2",  "mlr sort x,y         < data/big > /dev/null")
+run("sortsort2", "sort -t, -n -k 4,5   < data/big > /dev/null")
+run("SORTMLR2",  "mlr sort -n x,y      < data/big > /dev/null")
 puts
 puts
 
-
 run("sortsort1v",  "sort -t, -k 1,4            < data/big.csv > /dev/null")
-run("SORTMLR1V",   "mlr      --csv sort a,x    < data/big.csv > /dev/null")
+run("SORTMLR1V",   "mlr      --csv sort -f a,x < data/big.csv > /dev/null")
 puts
 
 run("sortsort2v",  "sort -t, -k 4,5            < data/big.csv > /dev/null")
-run("SORTMLR2V",   "mlr      --csv sort x,y    < data/big.csv > /dev/null")
+run("SORTMLR2V",   "mlr      --csv sort -n x,y < data/big.csv > /dev/null")
diff --git a/c/test/expected/out b/c/test/expected/out
index 74b3157d6..bd0b721f4 100644
--- a/c/test/expected/out
+++ b/c/test/expected/out
@@ -203,6 +203,190 @@ a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
 ./test/../mlr tac /dev/null
 
 
+================================================================
+SORT
+
+./test/../mlr sort -f a ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+
+./test/../mlr sort -r a ./test/input/abixy
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+
+./test/../mlr sort -f x ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -r x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -nf x ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -nr x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -f a,b ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+
+./test/../mlr sort -r a,b ./test/input/abixy
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -f x,y ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -r x,y ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -nf x,y ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -nr x,y ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -f a -nr x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+
+./test/../mlr sort -nr y -f a ./test/input/abixy
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+
+./test/../mlr sort -f a -r b -nf x -nr y ./test/input/abixy
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+
+
 ================================================================
 STATS
 
diff --git a/c/test/output/out b/c/test/output/out
index 74b3157d6..bd0b721f4 100644
--- a/c/test/output/out
+++ b/c/test/output/out
@@ -203,6 +203,190 @@ a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
 ./test/../mlr tac /dev/null
 
 
+================================================================
+SORT
+
+./test/../mlr sort -f a ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+
+./test/../mlr sort -r a ./test/input/abixy
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+
+./test/../mlr sort -f x ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -r x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -nf x ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -nr x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -f a,b ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+
+./test/../mlr sort -r a,b ./test/input/abixy
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -f x,y ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -r x,y ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -nf x,y ./test/input/abixy
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+
+./test/../mlr sort -nr x,y ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+
+./test/../mlr sort -f a -nr x ./test/input/abixy
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+
+./test/../mlr sort -nr y -f a ./test/input/abixy
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+
+./test/../mlr sort -f a -r b -nf x -nr y ./test/input/abixy
+a=eks,b=zee,i=7,x=0.6117840605678454,y=0.1878849191181694
+a=eks,b=wye,i=4,x=0.38139939387114097,y=0.13418874328430463
+a=eks,b=pan,i=2,x=0.7586799647899636,y=0.5221511083334797
+a=hat,b=wye,i=9,x=0.03144187646093577,y=0.7495507603507059
+a=pan,b=wye,i=10,x=0.5026260055412137,y=0.9526183602969864
+a=pan,b=pan,i=1,x=0.3467901443380824,y=0.7268028627434533
+a=wye,b=wye,i=3,x=0.20460330576630303,y=0.33831852551664776
+a=wye,b=pan,i=5,x=0.5732889198020006,y=0.8636244699032729
+a=zee,b=wye,i=8,x=0.5985540091064224,y=0.976181385699006
+a=zee,b=pan,i=6,x=0.5271261600918548,y=0.49322128674835697
+
+
 ================================================================
 STATS
 
diff --git a/c/test/run b/c/test/run
index 1ac42e8ec..29a4b9ad8 100755
--- a/c/test/run
+++ b/c/test/run
@@ -77,6 +77,27 @@ run_command $mlr group-like $indir/het.dkvp
 run_command $mlr tac $indir/abixy
 run_command $mlr tac /dev/null
 
+# ----------------------------------------------------------------
+announce SORT
+
+run_command $mlr sort -f a   $indir/abixy
+run_command $mlr sort -r a   $indir/abixy
+run_command $mlr sort -f x   $indir/abixy
+run_command $mlr sort -r x   $indir/abixy
+run_command $mlr sort -nf x  $indir/abixy
+run_command $mlr sort -nr x  $indir/abixy
+
+run_command $mlr sort -f a,b   $indir/abixy
+run_command $mlr sort -r a,b   $indir/abixy
+run_command $mlr sort -f x,y   $indir/abixy
+run_command $mlr sort -r x,y   $indir/abixy
+run_command $mlr sort -nf x,y  $indir/abixy
+run_command $mlr sort -nr x,y  $indir/abixy
+
+run_command $mlr sort -f a -nr x $indir/abixy
+run_command $mlr sort -nr y -f a $indir/abixy
+run_command $mlr sort -f a -r b -nf x -nr y $indir/abixy
+
 # ----------------------------------------------------------------
 announce STATS
 run_command $mlr count-distinct -f a,b $indir/small $indir/abixy
diff --git a/c/todo.txt b/c/todo.txt
index fcb82bf8e..6fbf59021 100644
--- a/c/todo.txt
+++ b/c/todo.txt
@@ -33,6 +33,8 @@ NEATEN
 * rip through filenames @ start & abend unless -f each.
 * play with python sketch.py (& rename -- mlr.py??) & make sure it's at least usable for something
 
+! re-do mlr sort -n stats in t1.rb -> mlrwik
+
 ================================================================
 ONLINE HELP
 * then-chaining note into mlr online help
diff --git a/doc/content-for-data-examples.html b/doc/content-for-data-examples.html
index 7537d249b..194f7c380 100644
--- a/doc/content-for-data-examples.html
+++ b/doc/content-for-data-examples.html
@@ -56,12 +56,12 @@ POKI_RUN_COMMAND{{mlr --opprint histogram -f flag,u,v --lo -0.1 --hi 1.1 --nbins
 color-dependent flag probabilities pop out, aligning with their original
 Bernoulli probablities from the data-generator script:
 
-POKI_RUN_COMMAND{{mlr --opprint stats1 -a min,avg,max -f flag,u,v -g color then sort color data/colored-shapes.dkvp}}HERE
-POKI_RUN_COMMAND{{mlr --opprint stats1 -a min,avg,max -f flag,u,v -g shape then sort shape data/colored-shapes.dkvp}}HERE
+POKI_RUN_COMMAND{{mlr --opprint stats1 -a min,avg,max -f flag,u,v -g color then sort -f color data/colored-shapes.dkvp}}HERE
+POKI_RUN_COMMAND{{mlr --opprint stats1 -a min,avg,max -f flag,u,v -g shape then sort -f shape data/colored-shapes.dkvp}}HERE
 
-<p/> Look at bivariate stats by color and shape. In particular, <tt>u,v</tt> pairwise correlation for red circles pops out (xxx sort -n oppo):
+<p/> Look at bivariate stats by color and shape. In particular, <tt>u,v</tt> pairwise correlation for red circles pops out:
 POKI_RUN_COMMAND{{mlr --opprint --right stats2 -a corr -f u,v,w,x data/colored-shapes.dkvp}}HERE
-POKI_RUN_COMMAND{{mlr --opprint --right stats2 -a corr -f u,v,w,x -g color,shape then sort u_v_corr data/colored-shapes.dkvp}}HERE
+POKI_RUN_COMMAND{{mlr --opprint --right stats2 -a corr -f u,v,w,x -g color,shape then sort -nr u_v_corr data/colored-shapes.dkvp}}HERE
 
 <h1>Program timing</h1>
 
diff --git a/doc/content-for-record-heterogeneity.html b/doc/content-for-record-heterogeneity.html
index 5343ada94..990d06f71 100644
--- a/doc/content-for-record-heterogeneity.html
+++ b/doc/content-for-record-heterogeneity.html
@@ -50,5 +50,5 @@ vary, and moreover the sorted-on field name(s) don&rsquo;t need to be in the sam
 <table><tr><td>
 POKI_RUN_COMMAND{{cat data/sort-het.dkvp}}HERE
 </td><td>
-POKI_RUN_COMMAND{{mlr sort count data/sort-het.dkvp}}HERE
+POKI_RUN_COMMAND{{mlr sort -n count data/sort-het.dkvp}}HERE
 </td></tr></table>
diff --git a/doc/content-for-reference.html b/doc/content-for-reference.html
index 2d4d24115..9102a52ec 100644
--- a/doc/content-for-reference.html
+++ b/doc/content-for-reference.html
@@ -87,14 +87,14 @@ In accord with the
 <a href="http://en.wikipedia.org/wiki/Unix_philosophy">Unix philosophy</a>, you can pipe data into or out of
 Miller. For example:
 
-POKI_CARDIFY(mlr cut --complement -f os_version *.dat | mlr sort hostname,uptime)HERE
+POKI_CARDIFY(mlr cut --complement -f os_version *.dat | mlr sort -f hostname,uptime)HERE
 
 <p/>
 For better performance (avoiding redundant string-parsing and string-formatting
 when you pipe Miller commands together) you can, if you like, instead simply
 chain commands together using the <tt>then</tt> keyword:
 
-POKI_CARDIFY(mlr cut --complement -f os_version then sort hostname,uptime *.dat)HERE
+POKI_CARDIFY(mlr cut --complement -f os_version then sort -f hostname,uptime *.dat)HERE
 
 <!-- ================================================================ -->
 <h1>I/O options</h1>
@@ -219,9 +219,7 @@ POKI_RUN_COMMAND{{mlr --icsv --oxtab cat a.csv b.csv}}HERE
 
 POKI_RUN_COMMAND{{mlr count-distinct --help}}HERE
 
-<p/>xxx great oppo for sort -nr
-
-POKI_RUN_COMMAND{{mlr count-distinct -f a,b then sort count data/medium}}HERE
+POKI_RUN_COMMAND{{mlr count-distinct -f a,b then sort -nr count data/medium}}HERE
 
 <!-- ================================================================ -->
 <h2>cut</h2>
@@ -278,7 +276,7 @@ clear.
 <table><tr> <td>
 POKI_RUN_COMMAND{{mlr --opprint group-by a data/small}}HERE
 </td> <td>
-POKI_RUN_COMMAND{{mlr --opprint sort a data/small}}HERE
+POKI_RUN_COMMAND{{mlr --opprint sort -f a data/small}}HERE
 </td> </tr></table>
 
 <p/>In this example, since the sort is on field <tt>a</tt>, the first step is
@@ -428,7 +426,7 @@ optionally categorized by one or more fields.
 <table><tr><td>
 POKI_RUN_COMMAND{{mlr --oxtab stats1 -a count,sum,avg -f x,y data/medium}}HERE
 </td></tr><tr><td>
-POKI_RUN_COMMAND{{mlr --opprint stats1 -a avg -f x,y -g b then sort b data/medium}}HERE
+POKI_RUN_COMMAND{{mlr --opprint stats1 -a avg -f x,y -g b then sort -f b data/medium}}HERE
 </td></tr></table>
 
 <!-- ================================================================ -->
@@ -521,7 +519,7 @@ Note that <tt>top</tt> is distinct from <a href="#head"><tt>head</tt></a>
 <table><tr><td>
 POKI_RUN_COMMAND{{mlr --opprint top -n 4 -f x data/medium}}HERE
 </td><td>
-POKI_RUN_COMMAND{{mlr --opprint top -n 2 -f x -g a then sort a data/medium}}HERE
+POKI_RUN_COMMAND{{mlr --opprint top -n 2 -f x -g a then sort -f a data/medium}}HERE
 </td></tr></table>
 
 <!-- ================================================================ -->
@@ -534,7 +532,7 @@ POKI_RUN_COMMAND{{wc -l data/colored-shapes.dkvp}}HERE
 </td></tr><tr><td>
 POKI_RUN_COMMAND{{mlr uniq -g color,shape data/colored-shapes.dkvp}}HERE
 </td></tr><tr><td>
-POKI_RUN_COMMAND{{mlr --opprint uniq -g color,shape -c then sort color,shape data/colored-shapes.dkvp}}HERE
+POKI_RUN_COMMAND{{mlr --opprint uniq -g color,shape -c then sort -f color,shape data/colored-shapes.dkvp}}HERE
 </td></tr></table>
 
 <!-- ================================================================ -->
diff --git a/doc/data-examples.html b/doc/data-examples.html
index bee883813..dae6df243 100644
--- a/doc/data-examples.html
+++ b/doc/data-examples.html
@@ -283,7 +283,7 @@ Bernoulli probablities from the data-generator script:
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint stats1 -a min,avg,max -f flag,u,v -g color then sort color data/colored-shapes.dkvp
+$ mlr --opprint stats1 -a min,avg,max -f flag,u,v -g color then sort -f color data/colored-shapes.dkvp
 color  flag_min flag_avg flag_max u_min    u_avg    u_max    v_min     v_avg    v_max
 blue   0.000000 0.599086 1.000000 0.000044 0.503581 0.999976 0.000057  0.496972 0.999870
 green  0.000000 0.207102 1.000000 0.000010 0.504358 0.999983 0.000079  0.498956 0.999889
@@ -297,7 +297,7 @@ yellow 0.000000 0.898270 1.000000 0.000327 0.502877 0.999923 0.000138  0.501022
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint stats1 -a min,avg,max -f flag,u,v -g shape then sort shape data/colored-shapes.dkvp
+$ mlr --opprint stats1 -a min,avg,max -f flag,u,v -g shape then sort -f shape data/colored-shapes.dkvp
 shape    flag_min flag_avg flag_max u_min    u_avg    u_max    v_min     v_avg    v_max
 circle   0.000000 0.398115 1.000000 0.000037 0.502212 0.999976 -0.096195 0.496996 1.095540
 square   0.000000 0.397398 1.000000 0.000037 0.499935 0.999970 0.000088  0.500389 0.999975
@@ -306,7 +306,7 @@ triangle 0.000000 0.398542 1.000000 0.000010 0.501676 0.999983 0.000010  0.50180
 </div>
 <p/>
 
-<p/> Look at bivariate stats by color and shape. In particular, <tt>u,v</tt> pairwise correlation for red circles pops out (xxx sort -n oppo):
+<p/> Look at bivariate stats by color and shape. In particular, <tt>u,v</tt> pairwise correlation for red circles pops out:
 <p/>
 <div class="pokipanel">
 <pre>
@@ -319,8 +319,17 @@ u_v_corr w_x_corr
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint --right stats2 -a corr -f u,v,w,x -g color,shape then sort u_v_corr data/colored-shapes.dkvp
+$ mlr --opprint --right stats2 -a corr -f u,v,w,x -g color,shape then sort -nr u_v_corr data/colored-shapes.dkvp
  color    shape  u_v_corr  w_x_corr
+   red   circle  0.980343  0.004277
+  blue triangle  0.029301  0.017138
+orange   circle  0.021871 -0.040626
+purple   circle  0.021701  0.037687
+ green triangle  0.010633 -0.025945
+   red   square  0.006553 -0.007587
+orange   square  0.005342  0.042003
+yellow   square  0.001905 -0.002849
+orange triangle  0.000620 -0.013529
    red triangle -0.000349  0.003179
 yellow triangle -0.001735  0.032633
 yellow   circle -0.002083 -0.012606
@@ -330,15 +339,6 @@ purple   square -0.011754 -0.003372
   blue   circle -0.017771  0.014975
   blue   square -0.019537 -0.006952
  green   circle -0.034313 -0.049415
-orange triangle  0.000620 -0.013529
-yellow   square  0.001905 -0.002849
-orange   square  0.005342  0.042003
-   red   square  0.006553 -0.007587
- green triangle  0.010633 -0.025945
-purple   circle  0.021701  0.037687
-orange   circle  0.021871 -0.040626
-  blue triangle  0.029301  0.017138
-   red   circle  0.980343  0.004277
 </pre>
 </div>
 <p/>
diff --git a/doc/performance.html b/doc/performance.html
index 5b9cb3648..129545c83 100644
--- a/doc/performance.html
+++ b/doc/performance.html
@@ -181,10 +181,10 @@ Note that for CSV data, the command is <tt>mlr --csv ...</tt> rather than <tt>ml
    2.587   2.389       mlr stats2 -a corr -f x,y -g a,b
 
   23.247  14.466       sort -t, -k 1,2
-   3.023   5.658       mlr sort a,b
+   3.023   5.658       mlr sort -f a,b
 
   17.224  15.523       sort -t, -k 4,5
-   5.807   5.194       mlr sort x,y
+   5.807   5.194       mlr sort -n x,y
 </pre>
 </div>
 <p/>
diff --git a/doc/perftbl.txt b/doc/perftbl.txt
index bcc8376fc..201dacdff 100644
--- a/doc/perftbl.txt
+++ b/doc/perftbl.txt
@@ -23,7 +23,7 @@
    2.587   2.389       mlr stats2 -a corr -f x,y -g a,b
 
   23.247  14.466       sort -t, -k 1,2
-   3.023   5.658       mlr sort a,b
+   3.023   5.658       mlr sort -f a,b
 
   17.224  15.523       sort -t, -k 4,5
-   5.807   5.194       mlr sort x,y
+   5.807   5.194       mlr sort -n x,y
diff --git a/doc/record-heterogeneity.html b/doc/record-heterogeneity.html
index 347b5eec8..20084c10e 100644
--- a/doc/record-heterogeneity.html
+++ b/doc/record-heterogeneity.html
@@ -309,7 +309,7 @@ count=450
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr sort count data/sort-het.dkvp
+$ mlr sort -n count data/sort-het.dkvp
 count=100,color=green
 status=ok,count=200,hours=3.4
 status=ok,count=250,hours=0.22
diff --git a/doc/reference.html b/doc/reference.html
index 32777f60f..aa2bfbda6 100644
--- a/doc/reference.html
+++ b/doc/reference.html
@@ -133,7 +133,7 @@ Whereas the Unix toolkit is made of the separate executables <tt>cat</tt>, <tt>t
 <pre>
 mlr tac *.dat
 mlr cut --complement -f os_version *.dat
-mlr sort hostname,uptime *.dat
+mlr sort -f hostname,uptime *.dat
 </pre>
 </div>
 <p/>
@@ -234,7 +234,8 @@ I/O options:
 <div class="pokipanel">
 <pre>
 $ mlr sort --help
-Usage: mlr sort {comma-separated field names}
+Usage: mlr sort {xxx}
+       xxx info goes here
 </pre>
 </div>
 <p/>
@@ -249,7 +250,7 @@ Miller. For example:
 <p/>
 <div class="pokipanel">
 <pre>
-mlr cut --complement -f os_version *.dat | mlr sort hostname,uptime
+mlr cut --complement -f os_version *.dat | mlr sort -f hostname,uptime
 </pre>
 </div>
 <p/>
@@ -262,7 +263,7 @@ chain commands together using the <tt>then</tt> keyword:
 <p/>
 <div class="pokipanel">
 <pre>
-mlr cut --complement -f os_version then sort hostname,uptime *.dat
+mlr cut --complement -f os_version then sort -f hostname,uptime *.dat
 </pre>
 </div>
 <p/>
@@ -472,37 +473,35 @@ Usage: mlr count-distinct [options]
 </div>
 <p/>
 
-<p/>xxx great oppo for sort -nr
-
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr count-distinct -f a,b then sort count data/medium
-a=eks,b=zee,count=357
-a=hat,b=pan,count=363
-a=eks,b=pan,count=371
-a=wye,b=wye,count=377
-a=hat,b=hat,count=381
-a=hat,b=zee,count=385
-a=wye,b=zee,count=385
-a=wye,b=eks,count=386
-a=zee,b=pan,count=389
-a=hat,b=eks,count=389
-a=zee,b=eks,count=391
-a=wye,b=pan,count=392
-a=pan,b=wye,count=395
-a=zee,b=zee,count=403
-a=eks,b=wye,count=407
-a=zee,b=hat,count=409
-a=eks,b=eks,count=413
-a=pan,b=zee,count=413
+$ mlr count-distinct -f a,b then sort -nr count data/medium
+a=zee,b=wye,count=455
+a=pan,b=eks,count=429
+a=pan,b=pan,count=427
+a=wye,b=hat,count=426
+a=hat,b=wye,count=423
 a=pan,b=hat,count=417
 a=eks,b=hat,count=417
-a=hat,b=wye,count=423
-a=wye,b=hat,count=426
-a=pan,b=pan,count=427
-a=pan,b=eks,count=429
-a=zee,b=wye,count=455
+a=eks,b=eks,count=413
+a=pan,b=zee,count=413
+a=zee,b=hat,count=409
+a=eks,b=wye,count=407
+a=zee,b=zee,count=403
+a=pan,b=wye,count=395
+a=wye,b=pan,count=392
+a=zee,b=eks,count=391
+a=zee,b=pan,count=389
+a=hat,b=eks,count=389
+a=wye,b=eks,count=386
+a=hat,b=zee,count=385
+a=wye,b=zee,count=385
+a=hat,b=hat,count=381
+a=wye,b=wye,count=377
+a=eks,b=pan,count=371
+a=hat,b=pan,count=363
+a=eks,b=zee,count=357
 </pre>
 </div>
 <p/>
@@ -677,7 +676,7 @@ wye pan 5 0.5732889198020006  0.8636244699032729
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint sort a data/small
+$ mlr --opprint sort -f a data/small
 a   b   i x                   y
 eks pan 2 0.7586799647899636  0.5221511083334797
 eks wye 4 0.38139939387114097 0.13418874328430463
@@ -1100,7 +1099,8 @@ wye 0.5732889198020006  0.8636244699032729  5 pan
 <div class="pokipanel">
 <pre>
 $ mlr sort --help
-Usage: mlr sort {comma-separated field names}
+Usage: mlr sort {xxx}
+       xxx info goes here
 </pre>
 </div>
 <p/>
@@ -1144,7 +1144,7 @@ y_avg   0.506206
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint stats1 -a avg -f x,y -g b then sort b data/medium
+$ mlr --opprint stats1 -a avg -f x,y -g b then sort -f b data/medium
 b   x_avg    y_avg
 eks 0.506361 0.510293
 hat 0.487899 0.513118
@@ -1458,7 +1458,7 @@ top_idx x_top
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint top -n 2 -f x -g a then sort a data/medium
+$ mlr --opprint top -n 2 -f x -g a then sort -f a data/medium
 a   top_idx x_top
 eks 1       0.998811
 eks 2       0.998534
@@ -1528,7 +1528,7 @@ color=orange,shape=circle
 <p/>
 <div class="pokipanel">
 <pre>
-$ mlr --opprint uniq -g color,shape -c then sort color,shape data/colored-shapes.dkvp
+$ mlr --opprint uniq -g color,shape -c then sort -f color,shape data/colored-shapes.dkvp
 color  shape    count
 blue   circle   3578
 blue   square   6016
diff --git a/doc/subcommand-example.txt b/doc/subcommand-example.txt
index db8bbbc26..ace8950d8 100644
--- a/doc/subcommand-example.txt
+++ b/doc/subcommand-example.txt
@@ -1,3 +1,3 @@
 mlr tac *.dat
 mlr cut --complement -f os_version *.dat
-mlr sort hostname,uptime *.dat
+mlr sort -f hostname,uptime *.dat