From: Martin Mares <mj@ucw.cz>
Date: Sat, 7 Apr 2018 09:09:57 +0000 (+0200)
Subject: Proper help for all commands and arguments
X-Git-Tag: v0.1~2
X-Git-Url: http://mj.ucw.cz/gitweb/?a=commitdiff_plain;h=fb5c6a3936ad37051d3dd1f1d8612bfdae2ec9b0;p=paperjam.git

Proper help for all commands and arguments
---

diff --git a/TODO b/TODO
index 3228957..d5a20d3 100644
--- a/TODO
+++ b/TODO
@@ -1,7 +1,6 @@
 - Integrate pdf-tools.cc with the rest of the code
 - What if an input page specifies /Rotate?
 - "-f" switch
-- Help
 
 | # Position bbox on a new paper
 | paper("a4")
diff --git a/cmds.cc b/cmds.cc
index e446c83..11c4648 100644
--- a/cmds.cc
+++ b/cmds.cc
@@ -20,7 +20,7 @@ public:
 };
 
 static const arg_def no_args[] = {
-  { NULL,	0 }
+  { NULL,	0,	NULL }
 };
 
 /*** Generic routines ***/
@@ -105,9 +105,9 @@ public:
 };
 
 #define PAPER_ARGS \
-  { "paper",	AT_STRING | AT_POSITIONAL },	\
-  { "w",	AT_DIMEN },			\
-  { "h",	AT_DIMEN }
+  { "paper",	AT_STRING | AT_POSITIONAL,		"Paper format name (e.g., a4)" },	\
+  { "w",	AT_DIMEN,				"Paper width" },			\
+  { "h",	AT_DIMEN,				"Paper height" }
 
 // Position specification
 
@@ -173,7 +173,7 @@ public:
 };
 
 #define POS_ARGS \
-  { "pos",	AT_STRING }
+  { "pos",	AT_STRING,			"Position on the page: (t|c|b)(l|c|r)" }
 
 // Margins
 
@@ -213,19 +213,19 @@ public:
     }
 };
 
-#define MARGIN_ARGS1_NAMED(name)	\
-  { name,	AT_DIMEN }
+#define MARGIN_ARGS1_NAMED(name)							\
+  { name,	AT_DIMEN,			"Size of all margins (default: 0)" }
 
-#define MARGIN_ARGS1_POSNL(name)	\
-  { name,	AT_DIMEN | AT_POSITIONAL }
+#define MARGIN_ARGS1_POSNL(name)							\
+  { name,	AT_DIMEN | AT_POSITIONAL,	"Size of all margins (default: 0)" }
 
-#define MARGIN_ARGS2(sx)		\
-  { "h" sx,	AT_DIMEN },		\
-  { "v" sx,	AT_DIMEN },		\
-  { "l" sx,	AT_DIMEN },		\
-  { "r" sx,	AT_DIMEN },		\
-  { "t" sx,	AT_DIMEN },		\
-  { "b" sx,	AT_DIMEN }
+#define MARGIN_ARGS2(sx)								\
+  { "h" sx,	AT_DIMEN,			"Size of horizontal margins" },		\
+  { "v" sx,	AT_DIMEN,			"Size of vertical margins" },		\
+  { "l" sx,	AT_DIMEN,			"Size of left margin" },		\
+  { "r" sx,	AT_DIMEN,			"Size of right margin" },		\
+  { "t" sx,	AT_DIMEN,			"Size of top margin" },			\
+  { "b" sx,	AT_DIMEN,			"Size of bottom margin" }
 
 // Colors
 
@@ -396,12 +396,12 @@ string cropmark_spec::pdf_stream(out_context *out, BBox &box, pdf_matrix &xform)
   return s;
 }
 
-#define CROPMARK_ARGS(px)		\
-  { px "mark",	AT_STRING },		\
-  { px "pen",	AT_DIMEN },		\
-  { px "len",	AT_DIMEN },		\
-  { px "offset",AT_DIMEN },		\
-  { px "color",	AT_STRING }
+#define CROPMARK_ARGS(px)									\
+  { px "mark",	AT_STRING,		"Cropmark style: box/cross/in/out/bg" },		\
+  { px "pen",	AT_DIMEN,		"Cropmark pen width (default: 0.2pt)" },		\
+  { px "len",	AT_DIMEN,		"Cropmark arm length (default: 5mm)" },			\
+  { px "offset",AT_DIMEN,		"Cropmark offset outside the box (default: 0)" },	\
+  { px "color",	AT_STRING,		"Cropmark color (RRGGBB, default: 000000)" }
 
 // Scaling preserving aspect ratio
 
@@ -434,9 +434,9 @@ public:
 };
 
 static const arg_def move_args[] = {
-  { "x",	AT_DIMEN | AT_MANDATORY | AT_POSITIONAL },
-  { "y",	AT_DIMEN | AT_MANDATORY | AT_POSITIONAL },
-  { NULL,	0 }
+  { "x",	AT_DIMEN | AT_MANDATORY | AT_POSITIONAL,	"Move right by this distance" },
+  { "y",	AT_DIMEN | AT_MANDATORY | AT_POSITIONAL,	"Move up by this distance" },
+  { NULL,	0,				NULL }
 };
 
 /*** scale ***/
@@ -458,9 +458,9 @@ public:
 };
 
 static const arg_def scale_args[] = {
-  { "x",	AT_DOUBLE | AT_MANDATORY | AT_POSITIONAL },
-  { "y",	AT_DOUBLE | AT_POSITIONAL },
-  { NULL,	0 }
+  { "x",	AT_DOUBLE | AT_MANDATORY | AT_POSITIONAL,	"Scale horizontally by this fraction" },
+  { "y",	AT_DOUBLE | AT_POSITIONAL,			"Scale vertically by this fraction (default: x)" },
+  { NULL,	0,						NULL }
 };
 
 /*** rotate ***/
@@ -503,8 +503,8 @@ public:
 };
 
 static const arg_def rotate_args[] = {
-  { "angle",	AT_INT | AT_MANDATORY | AT_POSITIONAL },
-  { NULL,	0 }
+  { "angle",	AT_INT | AT_MANDATORY | AT_POSITIONAL,	"Rotate clockwise by this angle" },
+  { NULL,	0,					NULL }
 };
 
 /*** flip ***/
@@ -538,9 +538,9 @@ public:
 };
 
 static const arg_def flip_args[] = {
-  { "h",	AT_SWITCH },
-  { "v",	AT_SWITCH },
-  { NULL,	0 }
+  { "h",	AT_SWITCH,				"Flip horizontally" },
+  { "v",	AT_SWITCH,				"Flip vertically" },
+  { NULL,	0,					NULL }
 };
 
 /*** select ***/
@@ -699,9 +699,9 @@ vector<page *> modulo_cmd::process(vector<page *> &pages)
 }
 
 static const arg_def modulo_args[] = {
-  { "n",	AT_INT | AT_MANDATORY | AT_POSITIONAL },
-  { "half",	AT_SWITCH },
-  { NULL,	0 }
+  { "n",	AT_INT | AT_MANDATORY | AT_POSITIONAL,		"Number of pages in a single tuple" },
+  { "half",	AT_SWITCH,					"Process only the first half of n-tuples" },
+  { NULL,	0,						NULL }
 };
 
 /*** debug ***/
@@ -809,7 +809,7 @@ public:
 static const arg_def paper_args[] = {
   PAPER_ARGS,
   POS_ARGS,
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** scaleto ***/
@@ -837,7 +837,7 @@ public:
 static const arg_def scaleto_args[] = {
   PAPER_ARGS,
   POS_ARGS,
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** fit ***/
@@ -884,7 +884,7 @@ static const arg_def fit_args[] = {
   POS_ARGS,
   MARGIN_ARGS1_NAMED("margin"),
   MARGIN_ARGS2("margin"),
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** expand ***/
@@ -909,7 +909,7 @@ public:
 static const arg_def expand_args[] = {
   MARGIN_ARGS1_POSNL("by"),
   MARGIN_ARGS2(""),
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** margins ***/
@@ -935,7 +935,7 @@ public:
 static const arg_def margins_args[] = {
   MARGIN_ARGS1_POSNL("size"),
   MARGIN_ARGS2(""),
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** add-blank ***/
@@ -971,9 +971,9 @@ vector<page *> add_blank_cmd::process(vector<page *> &pages)
 }
 
 static const arg_def add_blank_args[] = {
-  { "n",	AT_INT | AT_POSITIONAL },
+  { "n",	AT_INT | AT_POSITIONAL,		"Number of blank pages to add (default: 1)" },
   PAPER_ARGS,
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** book ***/
@@ -1018,8 +1018,8 @@ vector<page *> book_cmd::process(vector<page *> &pages)
 }
 
 static const arg_def book_args[] = {
-  { "n",	AT_INT | AT_POSITIONAL },
-  { NULL,	0 }
+  { "n",	AT_INT | AT_POSITIONAL,		"Number of pages in a single booklet" },
+  { NULL,	0,				NULL }
 };
 
 /*** nup ***/
@@ -1334,23 +1334,23 @@ page *nup_cmd::process_single(vector<page *> &in)
 }
 
 static const arg_def nup_args[] = {
-  { "n",	AT_INT | AT_POSITIONAL | AT_MANDATORY },
-  { "m",	AT_INT | AT_POSITIONAL },
-  { "by",	AT_STRING },
-  { "crop",	AT_SWITCH },
-  { "mixed",	AT_SWITCH },
-  { "rotate",	AT_SWITCH },
-  { "scale",	AT_DOUBLE },
+  { "n",	AT_INT | AT_POSITIONAL | AT_MANDATORY,	"Number of tiles on a page" },
+  { "m",	AT_INT | AT_POSITIONAL,			"If both n and m are given, produce n x m tiles on a page" },
+  { "by",	AT_STRING,				"Tile filling order: rows/cols/tile (default: rows)" },
+  { "crop",	AT_SWITCH,				"Crop input pages to their image box" },
+  { "mixed",	AT_SWITCH,				"Allow input pages of mixed sizes" },
+  { "rotate",	AT_SWITCH,				"Force (non-)rotation" },
+  { "scale",	AT_DOUBLE,				"Force specific scaling factor" },
   PAPER_ARGS,
   MARGIN_ARGS1_NAMED("margin"),
   MARGIN_ARGS2("margin"),
   POS_ARGS,
   CROPMARK_ARGS("c"),
-  { "tpos",	AT_STRING },
-  { "space",	AT_DIMEN },
-  { "hspace",	AT_DIMEN },
-  { "vspace",	AT_DIMEN },
-  { NULL,	0 }
+  { "tpos",	AT_STRING,				"Position of images inside tiles (default: tl)" },
+  { "space",	AT_DIMEN,				"Space between tiles (default: 0)" },
+  { "hspace",	AT_DIMEN,				"Horizontal space between tiles (default: space)" },
+  { "vspace",	AT_DIMEN,				"Vertical space between tiles (default: space)" },
+  { NULL,	0,					NULL }
 };
 
 /*** cropmarks ***/
@@ -1379,7 +1379,7 @@ public:
 
 static const arg_def cropmarks_args[] = {
   CROPMARK_ARGS(""),
-  { NULL,	0 }
+  { NULL,	0,				NULL }
 };
 
 /*** clip ***/
@@ -1412,8 +1412,8 @@ public:
 };
 
 static const arg_def clip_args[] = {
-  { "bleed",	AT_DIMEN },
-  { NULL,	0 }
+  { "bleed",	AT_DIMEN,			"Allow bleeding of image outside its box" },
+  { NULL,	0,				NULL }
 };
 
 /*** Command table ***/
@@ -1421,25 +1421,46 @@ static const arg_def clip_args[] = {
 template<typename T> cmd_exec *ctor(cmd *c) { return new T(c); }
 
 const cmd_def cmd_table[] = {
-  { "add-blank",add_blank_args,	0,	&ctor<add_blank_cmd>	},
-  { "apply",	no_args,	1,	&ctor<apply_cmd>	},
-  { "book",	book_args,	0,	&ctor<book_cmd>		},
-  { "clip",	clip_args,	0,	&ctor<clip_cmd>		},
-  { "cropmarks",cropmarks_args,	0,	&ctor<cropmarks_cmd>	},
-  { "debug",	no_args,	0,	&ctor<debug_cmd>	},
-  { "expand",	expand_args,	0,	&ctor<expand_cmd>	},
-  { "fit",	fit_args,	0,	&ctor<fit_cmd>		},
-  { "flip",	flip_args,	0,	&ctor<flip_cmd>		},
-  { "margins",	margins_args,	0,	&ctor<margins_cmd>	},
-  { "merge",	no_args,	0,	&ctor<merge_cmd>	},
-  { "modulo",	modulo_args,	1,	&ctor<modulo_cmd>	},
-  { "move",	move_args,	0,	&ctor<move_cmd>		},
-  { "null",	no_args,	0,	&ctor<null_cmd>		},
-  { "nup",	nup_args,	0,	&ctor<nup_cmd>		},
-  { "paper",	paper_args,	0,	&ctor<paper_cmd>	},
-  { "rotate",	rotate_args,	0,	&ctor<rotate_cmd>	},
-  { "scale",	scale_args,	0,	&ctor<scale_cmd>	},
-  { "scaleto",	scaleto_args,	0,	&ctor<scaleto_cmd>	},
-  { "select",	no_args,	1,	&ctor<select_cmd>	},
-  { NULL,	NULL,		0,	NULL	}
+  { "add-blank",add_blank_args,	0,	&ctor<add_blank_cmd>,
+		"Add blank page(s) after each page" },
+  { "apply",	no_args,	1,	&ctor<apply_cmd>,
+		"Apply commands to selected pages" },
+  { "book",	book_args,	0,	&ctor<book_cmd>,
+		"Prepare booklets for book binding" },
+  { "clip",	clip_args,	0,	&ctor<clip_cmd>,
+		"Suppress page contents drawn outside the image box" },
+  { "cropmarks",cropmarks_args,	0,	&ctor<cropmarks_cmd>,
+		"Draw cropping marks around the image box" },
+  { "debug",	no_args,	0,	&ctor<debug_cmd>,
+		"Draw debugging information on the page)" },
+  { "expand",	expand_args,	0,	&ctor<expand_cmd>,
+		"Expand paper around the image" },
+  { "fit",	fit_args,	0,	&ctor<fit_cmd>,
+		"Fit image to a given paper" },
+  { "flip",	flip_args,	0,	&ctor<flip_cmd>,
+		"Flip page horizontally and/or vertically" },
+  { "margins",	margins_args,	0,	&ctor<margins_cmd>,
+		"Define image box by dimensions of margins around it" },
+  { "merge",	no_args,	0,	&ctor<merge_cmd>,
+		"Merge all pages to one by placing them one over another" },
+  { "modulo",	modulo_args,	1,	&ctor<modulo_cmd>,
+		"Act on n-tuples of pages" },
+  { "move",	move_args,	0,	&ctor<move_cmd>,
+		"Shift contents on the page" },
+  { "null",	no_args,	0,	&ctor<null_cmd>,
+		"Do nothing" },
+  { "nup",	nup_args,	0,	&ctor<nup_cmd>,
+		"Combine multiple pages to one (n-up printing)" },
+  { "paper",	paper_args,	0,	&ctor<paper_cmd>,
+		"Place image on a given paper" },
+  { "rotate",	rotate_args,	0,	&ctor<rotate_cmd>,
+		"Rotate the page by multiples of 90 degrees" },
+  { "scale",	scale_args,	0,	&ctor<scale_cmd>,
+		"Scale the page by a given factor" },
+  { "scaleto",	scaleto_args,	0,	&ctor<scaleto_cmd>,
+		"Scale the page to a given size" },
+  { "select",	no_args,	1,	&ctor<select_cmd>,
+		"Select a subset of pages" },
+  { NULL,	NULL,		0,	NULL,
+		NULL, }
 };
diff --git a/jam.h b/jam.h
index 9081c55..5ee7620 100644
--- a/jam.h
+++ b/jam.h
@@ -48,6 +48,7 @@ enum arg_type {
 struct arg_def {
   const char *name;
   uint type;
+  const char *help;
 };
 
 class arg_val {
@@ -102,6 +103,7 @@ struct cmd_def {
   const arg_def *arg_defs;
   bool has_pipeline;
   cmd_exec *(*constructor)(cmd *cmd);
+  const char *help;
 };
 
 struct cmd {
diff --git a/paperjam.cc b/paperjam.cc
index f49fd7c..6419a7e 100644
--- a/paperjam.cc
+++ b/paperjam.cc
@@ -89,6 +89,10 @@ Options:\n\
 -b, --bbox		Recalculate bounding boxes\n\
 -d, --debug		Show debugging messages\n\
 \n\
+<command> = <name>(<args>, <named-arg>[=<value>], ...) [<pipeline>]\n\
+<pipeline> = { <stage>, <stage>, ... }\n\
+<stage> = <page> <page> ... [: <commands>]\n\
+\n\
 Commands:\n\
 ");
   parser_help();
diff --git a/parse.cc b/parse.cc
index aa840ba..a7b38f6 100644
--- a/parse.cc
+++ b/parse.cc
@@ -505,23 +505,25 @@ void parser_help()
   for (int i=0; cmd_table[i].name; i++)
     {
       const cmd_def *def = &cmd_table[i];
-      printf("%s\n", def->name);
+      printf("%s - %s\n", def->name, def->help);
 
       const arg_def *arg = def->arg_defs;
       static const char * const type_names[] = {
-	"string", "int", "double", "dimen", "switch"
+	"string", "int", "real", "dimen", "switch"
       };
       while (arg->name)
 	{
-	  printf("\t%s (%s)%s%s\n",
+	  char a[32];
+	  snprintf(a, sizeof(a), "%s%s=%s<%s>",
+	    (arg->type & AT_POSITIONAL) ? "[" : "",
 	    arg->name,
-	    type_names[arg->type & AT_TYPE_MASK],
-	    (arg->type & AT_MANDATORY) ? " [mandatory]" : "",
-	    (arg->type & AT_POSITIONAL) ? " [positional]" : "");
+	    (arg->type & AT_POSITIONAL) ? "]" : "",
+	    type_names[arg->type & AT_TYPE_MASK]);
+	  printf("   %-20s %s\n", a, arg->help);
 	  arg++;
 	}
 
 	if (def->has_pipeline)
-	  printf("\t{ pipeline }\n");
+	  printf("   { pipeline }\n");
     }
 }