Take the 2-minute tour ×
Unix & Linux Stack Exchange is a question and answer site for users of Linux, FreeBSD and other Un*x-like operating systems.. It's 100% free, no registration required.

This might come across a completely noob question, but on the other hand this has puzzled me more than a few times or probably I haven't seen enough of linux to draw a pattern. When linux commands list their usage, this usually is how they do it (for eg wget):

wget [option]... [URL]...

From what I understand of this pattern of specifying command usage, this is not the usual regex way of specifying patterns and for the wget command says that it is not mandatory to specify any options and by that logic it is not mandatory to specify any URL as well. I mean I can directly do

wget www.google.com

and this will work. So the options are not mandatory. If the options are not mandatory because they are in square brackets, then following through with that logic specifying a URL should not be mandatory as well and just

wget

as a command should work as well. My question is- Is there some document where this pattern of specifying command usage is elaborated on?

share|improve this question
    
there isn't any. normally programs use getargs –  Lelouch Lamperouge Mar 16 '12 at 2:40
    
@LelouchLamperouge-Do you mean getopt() by any chance? As far as I understand, isn't getopt() for parsing the command line arguments. Does it have anything to do with how command usage is specified at the top a man page. –  sandman Mar 16 '12 at 14:12

5 Answers 5

up vote 4 down vote accepted

Typically a syntax where [...] is used to indicate optional args and '|' is used to indicate a logical OR is used in most man pages. It depends who writes the man page as there is no authority that dictates what a man page must read like. More specific to your question however, the man page reads true in this case. Either you can specify a url through the -i switch or you can supply a URL itself. So you can think of the options as "conditionally optional". Really it should probably read something like

      ([option (excluding -i)] (-i file | URL)) 

but you can see how this would get complicated very quickly. So you need to take the quick descriptions with a grain of salt. In my experience the command syntax is usually the least of your worries.

Also, I'm nit picking here but what you are seeing isn't a regex ;)

share|improve this answer
    
@fthinker- Thanks! That cleared up a lot of things in my head and should make my command exploring a lot less confusing. My bad for using regex. When I said regex, I meant something like a command pattern or something. I used regex rather loosely to mean something like that. –  sandman Mar 16 '12 at 14:19
    
Yep, I know. :) –  fthinker Mar 16 '12 at 15:01

I don't think there's a formal definition for that (I might be wrong), but it seems that there isn't much of a standard for this logic, judging from a random sampling of some manpages.

share|improve this answer
    
If there isn't, I think it is high time they standardized it. Judging from my own experience it will help navigating the plethora of commands and their specific idiosyncrasies a lot more easier. –  sandman Mar 16 '12 at 2:11
    
@sandman. Once you get past the initial onslaught of all these new unknown options to unfamiliar programs, it settles down to being not so dramatic, other than having to deal with the plethora aspect... but that would be so in any case. BTW, the "they" you refer to is notionally you and I... and bear in mind that the history of many of the staple programs goes back many years when things grew somewhat more organically than might be preferred today. Significantly, that legacy needs to be backwardly compatible... There are moves afoot to improve it, but its not easy to contain flowing water. –  Peter.O Mar 16 '12 at 8:23
    
@Peter.O- You do have a point. Backwards compatibility sure is a double-edged sword. However more often than not, I find myself tripping on it. That's probably why I have such a detached tone in my earlier comment when I used "they", but who like you pointed out are people like you and I. Thanks for you comment! :) –  sandman Mar 16 '12 at 14:24

I would expect it to say

wget [options] URL...
wget [-i|--input-file] file [options] [URL...]

The single synopsis line is somewhat common for GNU man pages, where the authoritative documentation is the info documentation, and the man page is a very short summary, often describing only the most common options.

Compare this to BSD tools such as tar and the independent tool rsync.

On the other hand, POSIX Utility Conventions say that multiple synopsis lines should be used for mutually exclusive options, and the -i option is actually not mutually exclusive.

share|improve this answer

Isn't that all a specific implementation of http://en.wikipedia.org/wiki/Backus-Naur_form ?

share|improve this answer

man 7 man-pages (from the Linux man-pages package) explains some conventions that you should be aware of, even if there are some man pages that fail to follow the conventions.

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

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