Proper help for all commands and arguments

diff --git a/TODO b/TODO
index 3228957da0591ecb1ae32673822a97d5f5a3eb85..d5a20d31026f44511146a34889181cfb77994575 100644 (file)
--- 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 e446c8392b889481b7d6c53f39d8d2d79c20f44e..11c46482aa960a116209d2e67a31f6ccd1a011e3 100644 (file)
--- 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 9081c558c861bfd2551b0a941887f7b32680b7a6..5ee7620d050cd28163062943431bc127b3bda4ad 100644 (file)
--- 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 f49fd7cc1e96745b94b695ac0510596b19063fab..6419a7ef40e59bbc6859920530e177e592e89142 100644 (file)
--- 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 aa840ba2af6cdda39bdb7382d84727c7aa8fe384..a7b38f6c34be4e31b3159327df7a11be427f1479 100644 (file)
--- 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");
     }
 }