I'm maintaining an old KornShell shell script and its man page.
The shell script's command line options include both -wwidth (no intervening space) and -w width (with intervening white space), which have the same effect. In the man page this is documented in the SYNOPSIS section as [-w<>width], apparently using <> to mean optional white space.
I haven't been able to find on the Web other UNIX or Linux man pages that use <> for this purpose, so I presume that this doesn't follow a convention that UNIX or Linux users expect, and thus users may be confused by <> in the man page.
Which of the following representations in a man page makes it most clear that white space between the -w and width is optional:
[-w<>width],
[-w[ ]width], or
[-wwidth|-w width]?
Is it better to just have one of either [-wwidth] or [-w width] in the man page, on the basis that they do the same thing so there is little or no value added to the user to document that both of these alternatives are available?
I would just document -w width because it's a universal convention that options with arguments can take the argument either in the same command-line argument (-w80) or the following command-line argument (-w 80).
Any tool/option that does not follow the convention should document it, but your case looks pretty standard.
Related
Question: using the less command in any linux shell (i'm using bash as probably most people do), is there a way to search a file only for it's commands or options?
So, to be more precise:
if i want to quickly find the description for one special option in a man-page,
is there a special search syntax to quickly jump to the corresponding line explaining that specific command?
example:
if i type:
man less
and i want to quickly find the description for the "-q" command,
is there a search syntax to directly jump to that line?
If I type /-q, it finds all occurences of "-q" everywhere in the file, so I get around 10-20 hits, of which only one is the one i was looking for..
So I'm just hoping there is a better/quicker way to do this..
(not to important though :D)
In man, options are generally described with the option name in bold at the start of the line.
So, if you are looking for the option -q, then the search command would be /^\s*-q\>
The regex ^\s*-q\> reads as follow:
^ start of a line
\s* any number of spaces (including none)
-q the option name you are looking for
\> the end of the word
In Linux command line, one can use either of two ways to pass options to commands. Either we can use the short option format which uses a single dash followed by a single letter, for example: -o or the long option format which uses two consecutive dashes followed by a word, for example: --option. But recently I came across some commands which in my thinking uses a 'hybrid' of both the formats, which uses a single dash followed by a word, for example: -option. Now I'm not talking about a commands where you can stick multiple short options together like ls -lisa. I'm talking about options where the word after the single dash is just one option and not multiple short options strung together.
I don't seem to understand why there's a third option. Because what I know about the Linux command line is you can have only a short form format or a long form format. Where did the third format came from?
It's actually confusing because sometimes you cannot be sure if the third format is really a dash followed by one option or a dash followed by multiple short options.
This is not a bash issue. All programs have their on way of handling the options/flags. There are many different styles:
the singe letter style with a single hyphen, for example:
ls -l
the mnemonic-style with double dashes, which seems a preference for GNU-stuff, for example, ls --size
the variable=value-style, for example dd if=file of=otherfile
options without dashes, as in tar cvzf arghive.tgz
You could even use a + instead of a - (as in date +%m).
etcetera.
It is important to understand that bash just passes these options to the programs/commands. So, in the programs you will generally see:
int main(int argc, char *argv[]){
(c-code example). In that case, argv[0] will point to the program-name (to simplify things a bit) and argv[1] will point to the first argument. Depending on the program, that may be different.
A quick scan through the built-in commands reveals that the built-ins always seem to use the minus-single letter (-a) for specifying options.
I think you are confusing which component does which part of the parsing.
The command line you type into bash gets parsed twice. First it gets parsed by bash. At this stage, spaces are used to separate the different parameters. Quotes and escapes are being taken into consideration. Wildcards are expanded, and $ variables are substituted.
At the end of this phase, we are left with a command line that has a list of strings, the first of which describes the command to be executed. At this point, bash calls execve, and passes it that list of strings.
The next phase of parsing is optional, and is up to each program to carry out. Most programs call getopt_long, a library function that parses options. The one and two dash convention you mention is applied by it (as well as it's older sibling, getopt).
It is, however, up to each program to parse its own parameters. Many programs use getopt_long, which is why you feel, correctly, that it is a standard. Some, however, do not. Those who do not follow their own way.
That's just how things are.
For your programs, you should try to use either getopt_long or some compatible solution, as that causes the least amount of confusion for users.
I have a file whose name is -q (It looks like this is made by accident)
I want to see it’s content, so I tried these
$ cat '-q'
$ cat "-q"
$ cat $'-q'
But nothing worked.(All gives same error cat: invalid option -- 'q')
Is there any way to see it’s content?
sjsam's helpful answer offers viable solutions, but it's worth digging deeper:
Arguments passed to Unix utilities (such as cat) can be divided into two groups (using POSIX terminology):
options (e.g., -l; depending on the option's definition, possibly followed by an option-argument) - switches that modify the utility's basic behavior.
operands (e.g., a filename) - the data that the utility operates on.
POSIX requires all options, if any, to come before any operands, but GNU utilities relax this requirement to allow intermingling options and operands for convenience.
Either way, a - followed by a letter or digit generally implies an option.
So as to allow passing operands that happen to start with -, special option -- can be used to tell any utility: treat any subsequent arguments as operands, even if they look like options.
Since operand -q in this case looks like an option, preceding it with -- to mark it as an operand is a must.
As for how to pass string -q itself as an argument:
-q contains no shell metacharacters, so the shell passes it as-is to cat - no quoting needed.
Quoting ('-q', "-q", $'-q', \-q) does no harm in this case, but has absolutely no effect here, because the shell - after having applied any expansions - simply removes any quoting characters (a process called quote removal) before passing the word to cat (as Charles Duffy notes in comments on the question).
to create a file named -q do
touch -- "-q"
and to view its contents
cat -- '-q' # Used single quotes to treat anything inside as literal characters
should do it. -- means what follows should be treated as a positional parameter.
Pls take time to look at #rici's [ answer ] which reminds some substle aspects regarding single vs double quotes.
Until recently, I was under the impression that by convention, all Linux command options were required to be prefixed by a hyphen (-). So for example, the instruction ls –l executes the ls command with the l option (here we can see that the l option is prefixed by a hyphen).
Life was good until I got to the chapter of my Linux for beginners book that explained the ps command. There I learned that I could write something like ps u U xyz where as far as I can tell, theu and U are options that are not required to be prefixed by a hyphen. Normally, I would have expected to have to write that same command as something like ps –uU xyz to force the usage of a hyphen.
I realize that this is probably a stupid question but I was wondering if there is a particular reason as to why the ps command does not follow what I thought was the standard way of specifying command options (prefixing them with hyphens). Why the variation? Is there a particular meaning to specifying hyphen-less options like that?
There are a handful of old programs on Unix that were written when the conventions were not as widely adopted, and ps is one of them. Another example is tar, although it has since been updated to allow options both with and without the - prefix.
IMO the best practice concerning hyphenation is to use them as the default go-to. More times than not, they have accepted hyphen prefixes to most or all flags/options available for commands. Happy to be corrected if I am wrong in this instance. I am still new to this myself! :)
Is there a function on one of the linux shells like the emacs dabbrev-expand?
First to give a definition:
M-xdescribe-functionEnterdabbrev-expandEnter
...
Expands to the most recent, preceding word for which this is a prefix.
Given that bash seems to be most heavily influenced by Emacs, looking there first reveals a few possibilities:
man bash(1), readline section
dynamic-complete-history (M-TAB)
Attempt completion on the text before point, comparing the text
against lines from the history list for possible completion matches.
dabbrev-expand
Attempt menu completion on the text before point, comparing the text
against lines from the history list for possible completion matches.
By default (or my system at least), M-/ is already bound to complete-filename:
$ bind -l | grep /
"\e/": complete-filename
You could re-bind it by putting
"\e/": dabbrev-expand
in your ~/.inputrc or /etc/inputrc.
Note that it only seems to complete the first word (the command), and only from history, not from the current command line as far as I can tell.
In zsh, I can't see anything in the man page that does this, but it should be possible to make it happen by figuring out the appropriate compctl command (Google mirror).