Standard command-line options

This page describes just some usual conventions used when interpreting command-line options by my programs (actually, these conventions are widely known and used by most good programs in the world) :

• Long options start with -- (two dashes), like --long-option. Short options start with - (one dash) and consist of one letter, like -p. The advantage of the long form is that you can easily remember it, the advantage of the short form is that you have less typing. Many options have both forms : long and short and you can use whichever you want.

• All my programs should accept option --help (short form -h). Using this option instructs the program to print some short usage instructions and a short description of available options.

• All my programs should accept option --version (short form -v). Using this option instructs the program to print version number. Sometimes (for help2man and consistency with other Unix utilities) it's preceded by the program name. Here's a description of versioning scheme used in all my programs. Version number is always printed on standard output, never in a message box or something that; this allows to use calls like program_name --version in batch scripts, makefiles etc.

  Note for Windows users of our GUI programs: when Windows program does not explicitly create a console, it usually has no standard output available. You must explicitly redirect it's stdout when using option --version.

• If option requires one argument, you can give it as
  --long-option=argument (with '=') or
  --long-option argument (passing argument as separate parameter) or
  -p=argument (same as the first one, but using short form) or
  -p argument (same as the second one, but using short form).

  E.g. following methods of running castle-model-viewer are equivalent:

    castle-model-viewer --navigation=Examine scene.wrl
    castle-model-viewer --navigation Examine scene.wrl
  

  If option allows but not requires an argument, you have to use --long-option=argument or -p=argument if you want to give an argument.

• Short options can be combined. This means that you can put more than one short option in a one parameter, e.g.

    program -abc
  

  means the same as

    program -a -b -c
  

  Note that only the last option in such "combined parameter" may take an argument, e.g.

    program -de=50
  

  means the same as

    program -d -e=50
  

  but if you want to give an argument for -d and -e, you can't combine them : you must use something like

    program -d=40 -e=50
  

• Special option -- means "do not interpret following parameters". You can use it if you have files with names beginning with a '-'.

  E.g. suppose you have a file named --file.png and you want to view it using Castle Image Viewer. If you call

    castle-image-viewer --file.png

  then castle-image-viewer will exit with an error 'invalid long option "--file.png"'. Even worse, if you have a file named --geometry (--geometry not only begins with a dash but it even IS a valid option for castle-image-viewer) and you call

    castle-image-viewer --geometry

  then castle-image-viewer will try to interpret the --geometry option and will give an error 'missing argument for "--geometry"'. So you can force castle-image-viewer to treat --file.png or --geometry as file names using :

    castle-image-viewer -- --file.png
    castle-image-viewer -- --geometry