[portmaster] navigation in the man page

[Doug Barton]

On 08/16/2010 20:42, Anonymous wrote:
> Doug Barton<dougb at FreeBSD.org>  writes:
>
>>> - inconsistent in using terms (flags vs. options)
>>
>> Again, snarky; but I will take a look at making this usage more
>> consistent. Personally I have always used these terms interchangeably,
>> but I could have been wrong about it all this time. :)
>
> "The average user" may not be familiar `flag' and `option' describe same
> things in the context of running programs from command line.

Fair enough.

>>> - being too verbose about port-related terms[2]
>>>
>>> [2] Like the one below
>>>
>>>          [-R] -r name/glob of port directory in /var/db/pkg
>>>
>>>       Why not use `origin' or `pkg-name' term from pkg_info(1)? WTF is
>>>       `port directory in /var/db/pkg' ? Only *package* directories lie
>>>       there.
>>
>> Well origin is obviously wrong, however my attempt here is to convey
>> the information necessary to users who are not at all familiar with
>> the port system internals. While it may not be the proper shorthand
>> term, anyone who isn't clear about what I mean can easily look in
>> /var/db/pkg, see the names of the directories there, and come to the
>> right conclusion about what they need to specify on the command line.
>
> You can define the meaning of a term in an option description and common
> terms can be put into DESCRIPTION section. Such terms can be described
> more verbosely in order to not confuse new users as well as experienced
> ones. No need to clutter usage line of an option.

Thanks, you have neatly defined my dilemma. You want some things in the 
man page to be less verbose, but you also want some things to be more 
verbose. Since I can't win, I take my best shot. :)

> Besides, without any kind of brackets it's a bit confusing whether those
> words separated by spaces are treated as several arguments or as one.

I'll consider this as well.

>>> On the side, I still can't find how to shut up portmaster from asking me
>>> about +IGNOREME ports.
>>
>> The design is that if portmaster encounters a port with an +IGNOREME
>> file it will ask you, once and only once, under certain circumstances,
>> if you want to update it. My theory is that "the average user" is
>> rather likely to put an +IGNOREME file in a port, err, package, errr,
>> directory in /var/db/pkg and subsequently forget that it's there. If
>> portmaster is asking you more than once during the same run about a
>> port with an +IGNOREME file then please report that as a bug (here on
>> the list is fine), with specific instructions on how to reproduce it.
>
> Why not add smth like --no-confirm? I'm one of those "average users"

No you're not, not even close. You're way ahead of the "average user" 
curve, you're not fooling me. :)

>> If you really really want portmaster to never prompt you about a port
>> you can create a pattern for it based on what portmaster does with the
>> -x option and put that in your portmaster rc file.
>
> PM_EXCL? It's not documented in portmaster(8) nor in sample config.

That's because it's not _intended_ for use in the manner I'm suggesting, 
but that doesn't mean that it can't be used that way. (In fact, I know 
of users that already do.)


Doug

-- 

	Improve the effectiveness of your Internet presence with
	a domain name makeover!    http://SupersetSolutions.com/

	Computers are useless. They can only give you answers.
			-- Pablo Picasso