Chris Pickett wrote: > On 7/25/09, Garrett D'Amore <gdamore at sun.com> wrote: > >> Chris Pickett wrote: >> >> >>> On 7/25/09, Garrett D'Amore <gdamore at sun.com> wrote: >>> >>> >>> >>>> My main concern here is the integration of manual page functionality >>>> >> into >> >>>> the commands themselves. I see both benefits and costs. The benefit is >>>> that the documentation is more likely to match the actual command. But >>>> >> part >> >>>> of the cost is a much higher cost to perform localization for these, and >>>> (depending on implementation) a potentially larger minimum size of the >>>> binaries. (I'm assuming for the moment that the documentation is stored >>>> >> in >> >>>> the binary, and the command is doing more than just executing some >>>> >> pipeline >> >>>> to access the manual content from /usr/share/man or whatever.) >>>> >>>> Personally, I think --man, --html and --nroff and such is a dangerous >>>> precedent to set. >>>> >>>> >>>> >>> What about --help and --version? Do you object to those options, too? >>> Would you drop your concerns if Roland would rename --man to >>> --extended-help? >>> >>> >>> >> When the --man output really is a manual page, I still object. It doesn't >> matter what you call it -- the problem is that we have two copies of the >> same information, the on-line manual page and the bits in the binary. >> >> Actually, if --man were to generate an actual man page by reading the man >> text from the on-disk file that is formatted by man(1) itself, then I would >> probably answer all (or very nearly so) of my concerns about this. >> > > If you would've ever researched the implementation you would come to > the conclusion that this is not possible. The same string used for > argument parsing is the same string used to generate the help, > version, man, nroff and html output. There is no space wasted > *anywhere*. >
That's unfortunate... there is a lot of text in the output from some of this man output... its pretty obvious to me that the "SEE ALSO", "IMPLEMENTATION", and "DESCRIPTION" sections of the --man output are not actually *required* for option parsing. It may be that the text is embedded in a way that makes it difficult or impossible to remove. At some level that's an implementation detail, but it is one that the committee will have to consider when the vote is taken. But I also think you might well be wrong. For example, consider the following in builtins.c (for sleep): *const* *char* sh_optsleep <http://src.opensolaris.org/source/s?refs=sh_optsleep&project=/onnv>[] = 1478 "[-1c?\n@(#)$Id: sleep (AT&T Research) 1999-04-07 $\n]" 1479 USAGE_LICENSE <http://src.opensolaris.org/source/s?defs=USAGE_LICENSE&project=/onnv> 1480 "[+NAME?sleep - suspend execution for an interval]" 1481 "[+DESCRIPTION?\bsleep\b suspends execution for at least the time specified " 1482 "by \aseconds\a or until a \bSIGALRM\b signal is received. " 1483 "\aseconds\a can be specified as a floating point number but the " 1484 "actual granularity depends on the underlying system, normally " 1485 "around 1 millisecond.]" 1486 "\n" 1487 "\nseconds\n" 1488 "\n" 1489 "[+EXIT STATUS?]{" 1490 "[+0?The execution was successfully suspended for at least \atime\a " 1491 "seconds, or a \bSIGALRM\b signal was received.]" 1492 "[+>0?An error occurred.]" 1493 "}" 1494 "[+SEE ALSO?\btime\b(1), \bwait\b(1)]" 1495 ; Why couldn't I have simply #ifdef'd out lines 1479-1488, and 1489-1494? None of that text looks (at least to me) to be intrinsically necessary as part of the options parser. > >> If you read my architectural concerns about this, then you'd understand why >> I have problems with it. (Right now it looks like I'm very much in the >> minority >> > > Yes, you are. > Well, we'll see. I'll be satisfied if the the committee takes a vote, no matter how the vote turns out. At least then I'll know that the concerns I've raised were properly considered. It may be that the concerns are no longer relevant, in which case I'll happily stand aside. So my requesting a vote on the issue (and pointing out the concerns) should not be a problem for folks convinced that none of my concerns matter anymore and that the other PSARC members will see the foolishness of my thinking. > >> -- maybe a minority of one on this -- but if so then a vote on the >> issue will be easy for the project team to achieve, and costs nobody >> anything except me -- and the cost to me is that I'll have to write the >> resulting opinion.) >> > > Where and when is such a vote done? Where can I vote? > On Wednesday at the PSARC meeting. Only regular PSARC members can vote. - Garrett
