Major Mode Option
All command line options for swim always start with a major mode option, except for ``swim <enter>`` which will show the whole listing of options. A major mode option is surrounded in braces { major mode option }. In the case of {--search} there are the alternative major mode options {--refinesearch} and {--research}, but because --search needs to be used first before either of these two options, --refinesearch and --research are surrounded in parentheses ().
Note: Through the other chapters of this manual {} is assumed for the major modes in the usage: section shown at the beginning of every chapter.
Let's take a closer look at this situation:
{--search ? (--research || --refinesearch)<pattern(s)>}
`||' or `|' are used to indicate
`or', `?' indicates
`optional', <diamond> indicates an
argument (a required argument - see Arguments below),
(parenthesis) means `if used, must be used after the
previous required option was used'. Note: for readability
--research and --refinesearch are not surrounded in
{}.
Normal Options
Options to the major mode options are enclosed in brackets [
option to major mode ]. swim [-n]
<enter> (assume enter from here on out), for instance,
will show all the command line options without using the pager. The pager
which swim uses can be set in swimrc (see swimrc(8)).
``swim {--help} [-n]'' will provide brief explanations of all of
swim's options without using the pager. In this case the major mode option
{--help}, and the option [-n] were used.
Dashes
Options which have a single dash can be combined with other single dashed options (-qaint). Double dashed options need to be entered by themselves (--help --nopager), many double dashed options have an alternative single dash option (-n for --nopager). The meaning of options is related to the major mode they are being used with. [-n] means no pager when called with {--help}, but it's a reference to the not-installed databases when used with {-q --query}, fortunately most options do not have double meanings.
Arguments
Many options require an argument. Arguments are enclose in diamonds < argument >. An argument to an option may also be optional in which case a question mark ``?'' will be placed between the option and the argument. [-l ? <[--df]>] illustrates such a situation. [-l] shows a file listings, and optionally the option [--df] can be use with [-l] to show an expanded listing.
[--dbpath <dir>] requires an argument, this time the argument would not be another option, but rather it is a directory.
Rule: When an option is an argument to another option it can be written anywhere, but when a non-option is an argument <dir> (notice no brackets) it has to be placed directly after the option. Sometimes, there may be alternative arguments divided with ``|''. <argument1|argument2> means use argument1 or argument2, but not both.
Based on what we now know, let's compare this situation to the {--search} situation shown above:
[--ftp ? --source | --source_only ? <[--diff]>]
In this case --source or alternatively --source_only can be optionally used along with --ftp because they aren't in parentheses () (also notice: | was used instead of ||, but means the same thing ``or''). --diff can optionally be provided as an argument to either --source or --source_only. For readability --source and --source_only weren't enclosed in brackets.
Global Arguments
A global argument can be typed anywhere on the command line, and can be an option or text. If global arguments exist they are placed last after the list of normal options that can be used with a major mode option.
[targets | -S] and [targets|APT|DF] are examples. {-q}, {--initndb}, and {--rebuildndb} all use global arguments.
Minor Mode Options
{-q --query} will generally use zero or more minor mode options [-afpgn --dir], with one exception (see QUERYING THE INSTALLED AND NOT-INSTALLED DATABASES , chapter 9).