3

I'm writing a command-line program in C, and I'd like to implement a --help option to show the usual stuff like available options and what they do, and usage examples.

Is there a proper method for formatting the text that is displayed in the help? Or do I just do my best to make it look nice?

I looked at some random programs on SourceForge to see how they did it, and most just used a bunch of printf()s to output pre-formatted (as far as spacing and indentation) text.

Is groff or troff appropriate here? I have come across those applications in my Googlings, which seem to be some kind of typesetting programs, but I am unfamiliar with them.

3 Answers 3

5

Generally speaking more people are concerned that the program works as stated than how well the help is displayed. Do your best (effort is always appreciated) with printf and get on with it and your life. You have bigger fish to fry.

2
  • Sounds good to me. Thanks a lot! I just wanted to make sure there's no secret make_nice_looking_help() function tucked away in stdlib or something. ;)
    – Michael
    Jun 27, 2011 at 2:52
  • There's such functionality in libpopt. If you patch some of its bugs, it will even word-wrap the --help text.
    – JdeBP
    Jun 28, 2011 at 8:58
3

Don't sweat the format that much. On the other hand, you yourself will be using it from time to time. Include such pertinent details as the program's purpose, relevant options, and some examples. A blank line to clearly delineate them should be good.

On an unrelated note, if your doing command line options in c, use the gnu getopts c library. It makes it much, much easier. And as a bonus, you don't get mugged by the details of parsing the command line.

2

Using groff or troff is overkill. Decently laid out printf() formatting is sufficient. If you layout your help messages systematically, it is easy enough to manage. The most complex set of options I have in any of my programs has:

static const char optlist[] = "a:cd:e:f:ghi:o:p:st:u:vxyz:A:BCD:E:F:G:HIJL:M:N:O:PQ:RS:TUVX:YZ:";

static const char usestr[] =
"[-cghsvxyY] [-d dbase] [-f file] [-e 'SQL stmt'] ['SQL stmt' ...]\n"
"Other options: [-CJPRU][-BHITV][-D delim][-E escape][-Q quote][-F format]\n"
"               [-A date][-i file][-o file][-L qlimit][-N number][-M FIFO]\n"
"               [-Z debug][-G eor][-t table][-p password][-u username]\n"
"               [-a ibase][-X record=rectag,recset=settag,header=hdrtag]\n"
"               [-O orderby][-S skip][-z number]\n"
"NB: -h gives more help!";

static const char fullhelp[] =
"\nOption summary:\n"
"   -a ibase      - input base (default 0; set to 10 for fields with leading zeroes)\n"
"   -c            - continue after errors\n"
"   -d dbase      - select database\n"
"   -e 'SQL stmt' - execute SQL command\n"
"   -f file       - input file for SQLCMD\n"
"   -g            - debugging mode (single-step commands)\n"
"   -h            - print this message\n"
"   -i file       - input file for SQLRELOAD\n"
"   -o file       - output file for SQLUNLOAD\n"
"   -p password   - password for connection (beware security implications!)\n"
"   -s            - silent mode\n"
"   -t table      - name of table (for SQLRELOAD or SQLUNLOAD)\n"
"   -u username   - username for connection (beware security implications!)\n"
"   -v            - verbose mode\n"
"   -x            - trace mode\n"
"   -y            - enable history\n"
"   -z number     - set debugging level for syntax and lexical analyzers\n"
"   -A date       - set date format (eg dd-mm-yyyy for $DBDATE=dmy4-)\n"
"   -B            - operate in benchmark mode (implies -x and times SQL)\n"
"   -C            - operate as SQLCMD\n"
"   -D delim      - set field delimiter (default $DBDELIMITER or pipe)\n"
"   -E escape     - set escape character (default $DBESCAPE or backslash)\n"
"   -F format     - set output format (default SELECT; alternatives include:\n"
"                   UNLOAD, FIXED, FIXSEP, FIXDEL, CSV, XML, HTML)\n"
"   -G eor        - set EOR (end of record) character string (default $DBNEWLINE or newline)\n"
"   -H            - include column headings in output\n"
"   -I            - interactive mode (after executing command line)\n"
"   -J            - simulate isql/dbaccess; accept [database|-] [script|-]\n"
"   -L qlimit     - limit on number of rows returned by query\n"
"   -M FIFO       - monitor FIFO for input commands\n"
"   -N number     - size of transaction under RELOAD\n"
"                   (default 1024; 0 means no sub-transactions)\n"
"   -O col1,...   - order by these columns (SQLUNLOAD)\n"
"   -P            - operate as SQLUPLOAD (not implemented yet)\n"
"   -Q quote      - set quote character (default $DBQUOTE or double quote)\n"
"   -R            - operate as SQLRELOAD\n"
"   -S skip       - initial rows to skip (SQLRELOAD)\n"
"   -T            - include column types in output\n"
"   -U            - operate as SQLUNLOAD\n"
"   -V            - print version and exit\n"
"   -X xmloptions - configure the XML output\n"
"      recset='recsettag',record='recordtag',header='headertag'\n"
"   -Y            - do not enable history, even in interactive mode\n"
"   -Z debug      - set debugging level (SQLCMD must be compiled with debugging enabled)\n"
;

Yes, it needs to go to long options before long.

1
  • Gotcha. Thanks a lot for the example!
    – Michael
    Jun 27, 2011 at 3:00

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.