[portmaster] navigation in the man page

[Doug Barton]

It's customary to cc the maintainer of a port when you're commenting on 
it. Even more so when the maintainer is also the software author. I 
usually keep up on the lists, but there are times when it falls lower on 
the priority list so copying me on the message will ensure I can see it 
in a timely manner.


On 08/16/2010 15:31, Anonymous wrote:
> Am I the only one who finds it hard to navigate in portmaster(8)?

Nope. :) You've got great company. I'm in sort of a no-win situation 
here. Most of what's in the man page now is there as a result of users 
being confused about something, however now I'm getting complaints that 
the man page is too long, too hard to read, etc.

Since I can't win either way, and since there are an unmanageably large 
number of options (which makes being succinct almost impossible) I have 
chosen to more fully document things. That way at least the information 
is there if the user chooses to search for it.

You seem pretty convinced and/or upset about what you wrote below, so 
consider my response as simply an opportunity for me to present my side 
of the story, rather than an attempt to change your mind. :)

> - options are neither sorted alphabetically nor grouped in blocks[1]

In the SYNOPSIS section the options are organized in terms of the flags 
that can be used for regular port operations (Common Flags), then the 
various ways to specify what port to work on, then the various other 
options that are also relevant to individual ports, then the package 
and index options, then the "other" options that are not related to 
installs/updates.

In the OPTIONS section they are grouped roughly the same way (and 
roughly in the same order), alphabetically, but with mutually exclusive 
options grouped together.

> - too little space between an option and its description

Aside from the fact that this just plain sounds snarky, you'll have to 
take up your concerns with -mdoc. My intention (which I believe I've 
successfully accomplished) is to use standard markup wherever possible.

> - 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. :)

> - 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.

> - SYNOPSYS makes a spaghetti with one-letter options, long options and comments[3]
 >
 > [3] Smth like `portmaster [options] [args...]' is probably enough.
 >      There is already EXAMPLES section, no need to duplicate it.

We'll have to agree to disagree on this one. The descriptions in that 
section are already as terse as I feel comfortable making them.

> - DESCRIPTION is too verbose,
 >
 > [4] I for one read DESCRIPTION only once, when first run the tool and
 >      never again. Most of the time I'm more concerned how certain
 >      option changes behavior and not interested in general prose.

Again, I'd love to have it shorter, but this isn't cat we're talking 
about here. And of course, you're always free to just not read it (you'd 
be in good company there too). :)

OTOH, there have recently been a non-trivial number of users asking me 
about "Can portmaster do $foo?" where the answer to their question is 
already documented in the man page, often in the DESCRIPTION section. Of 
course, the values of $foo are all different, making it that much harder 
for me to decide what ought to be cut.

I'd also like to point out that IME most people use the search feature 
of their $PAGER to find specific information about options.

> - `-i' option is misleading, portmaster is already quite interactive

  -i  interactive update mode -- ask whether to rebuild ports

To me that's pretty descriptive. Of course I could make the description 
more verbose if you like. :)

You might have noticed that I re-edited your post a bit to make my 
replies more meaningful. Feel free to conclude from that that you and I 
have vastly different communication styles, and therefore we are not 
likely to reach agreement on what my man page should look like.

> 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.

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.


hth,

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