To answer the OP's question:
I don't like asking n00b questions
This may a newbies question, but it's a good one,
'cause as I pointed out in my former post, manpages are the most important documentation,
and it actually needs a bit warm up with that system, since sometimes it is too brief to get all out of it one needs to come to a satifying solution - and often enough you need to read several manpages to get something done, because some tasks are not done by understanding one manpage alone (I pointed out the problem of how to write a documentation on something complex and huge like an operating system, and what all comes with, not only a mass of packages.)
The certain example you put with portmaster needs to be discriminated:
How to read manpages in general is one point.
How the shell handles it - reading/understanding (error) messages is something different (
astyle already covered that.)
And how a certain program/filter/app uses or names its options is something completely else again.
This depends on the certain piece of software (And you may already know un1x is case sensitive; means -d -D are not the same.)
How to read manpages:
Manpages are manuals.
Like the manual for a oven it just covers how to use the oven. It
may come with some example recipes, but if simply to better understand the usage of the oven, to tell you it can be used to make stews, cookies, pizza, and pies, not to cover a certain dish. You may comprehend an oven's manual trying to cover every possible recipe would be endless.
So it's up to you to combine the recipe of apple tard with the manual's information, and gain experience on it to get your perfect apple tard in this oven.
As far as I know (please correct me, if I'm wrong) there are no rules how options have to be named (Some things are defined in POSIX, but that's no guarentee it covers everything, nor everybody always sticks to it strictly in any case.)
As
scottro already pointed out, FreeBSD's manpages are (almost always) exemplary.
They (almost always) have the same structure.
So most programs/filters try to stick to a conform system of how to use options, like -x for single character options, --xxx for multicharacter (wordlike) options, and the file(s) to be handled are placed last.
Many (most) programs at least try to stick to a conformity as far as possible, and use e.g. -h for help, -v for verbose, -r for recursive, -h human readable.
But it's easy to understand it makes no sense to reserve -r for recursive if the programm has no use for recursive, but something else -r is better used for.
So like anywhere else, if there rules (written/not written) there always are exceptions.
That's why you may look it up any time in the manpage.
On the
webpage you already linked,
or by using
man portmaster to view it in your shell
(the manpages are on your machine, too. So you don't need no internet to access them.
And if you tell your shell to use
most instead of the default
less
(
pkg install most then
setenv PAGER most in ~/.cshrc (if you use [t]csh)) you get the manpages be shown colorfully structured.)
According to what already has been said here my advice is:
1. Very first look always should be the official HB.
2. If that what you're looking for is not covered there, second view is manpages.
Even if you realize after reading the first lines of a manpage's head it's not what you're looking for,
my advice is to at least skim once completely through it; just simply scroll it down, if only to get the idea how long the manpage is, and if there are examples; you'd be amazed after a while what knowledge you gather that way just by flying by, only. Of course, you will not learn its content that way. But another time if you actually need it (and for many manpages the day will come) you've already seen it.
As
scottro pointed out:
Many good things are at the bottom of a manpage.
Mostly examples which not seldom cover the exact solution you're just looking for, give you an idea, or at least point you in the right direction.
Also at the bottom of a manpage almost always you'll find a list of files,
and other manpages on the same topic, with additional, according, similar, or alternative information.
I solved many of my tasks - gained some knowledge/understanding by just follow, skimming through, and reading those.
3. If this - HB & manpagess - ain't no help, it's always worth a shot to look into
/usr/local/share/doc/
You'll find a lot of elaborated documenation on the userland things you have installed.
To end with a - *cough* - 'philosophical' truism:
Learning un1x mostly means learn to read the documentation.
Tipp:
Try to look for manpages also on other topics, not only the certain command you're currently like to use.
You'll be amazed what you will find.
e.g.
man hier
man.freebsd.org
