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
_______________________________________________
freebsd-ports@freebsd.org mailing list
http://lists.freebsd.org/mailman/listinfo/freebsd-ports
To unsubscribe, send any mail to "freebsd-ports-unsubscr...@freebsd.org"
