[portmaster] navigation in the man page
Am I the only one who finds it hard to navigate in portmaster(8)? - options are neither sorted alphabetically nor grouped in blocks[1] - too little space between an option and its description - inconsistent in using terms (flags vs. options) - being too verbose about port-related terms[2] - SYNOPSYS makes a spaghetti with one-letter options, long options and comments[3] - DESCRIPTION is too verbose, it should go either to EXAMPLES or to a specific option description[4] in OPTIONS - `-i' option is misleading, portmaster is already quite interactive On the side, I still can't find how to shut up portmaster from asking me about +IGNOREME ports. [1] look at how grouping is done in grep(1) from textproc/gnugrep [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. [3] Smth like `portmaster [options] [args...]' is probably enough. There is already EXAMPLES section, no need to duplicate it. [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. ___ 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
Re: [portmaster] navigation in the man page
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
Re: [portmaster] navigation in the man page
Doug Barton do...@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. - 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. 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. 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 that expects tools to have non-interactive mode, do its best with defaults and fail otherwise. 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. Way to promote reading the code. ;) ___ 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
Re: [portmaster] navigation in the man page
On 08/16/2010 20:42, Anonymous wrote: Doug Bartondo...@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 ___ 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
