Garrett D'Amore wrote:
> 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?
Sorry, I mistakenly used the wrong numbers... I meant to say 1479-1485.
I *suspect* that the parser needs lines 1486 thru 1488. (Although I've
not read the parser code to be certain.)
- Garrett
>
> 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
>
