Roland Mainz wrote:
> John Sonnenschein wrote:
>
>> On 25-Jul-09, at 4:59 PM, James Carlson wrote:
>>
>>> John Sonnenschein wrote:
>>>
>>>> I've got a question about this...
>>>> Whose responsibility is it to update the man pages and --man
>>>> command then? The people whose jobs it is to update man pages, or
>>>> the people whose jobs it is to update the command line utility?
>>>> Basically if a new flag is added in the future for some reason, how
>>>> will one synchronize the man pages?
>>>>
>>> Usually, that's done by filing a bug against the man pages.
>>>
>>> The advantage of keeping the documentation separate is that it's in
>>> the hands of professional documentation writers, who are able to
>>> keep a consistent style across all of the system man pages.
>>>
>>> I'm with Garrett about the inadvisability of baking man page
>>> documentation into executables, but for ksh93-related things, I
>>> think that ship has unfortunately sailed.
>>>
>> Sure but for the sake of argument if we have some tools that have --
>> man and also man pages, does that mean that the docs people will be
>> putting back to ON,
>>
>
> Erm... why should the documentation people do putback into OS/Net ? The
> strings used by getopts are used for argument parsing and are - as "nice
> side-effect" - reused to generate the output for --help, --version,
> --man etc.
>
I have no objections to --version, --help. My concerns relate to --man,
--nroff, and --html.
>
>> or will there be a desynchronization between the
>> man pages and the --man pages ?
>>
>
> They _may_ be out-of-sync shortly after code putback if we add new
> options to the |getopts()| string until the documentation folks caught
> up with the code changes. But as I am trying to say over and over again
> (and I am starting to feel _ignored_) that the output for --help, --man
> etc. is generated from the getopts string template used for argument
> parsing. This string is there to "drive" the argument parsing and is
> absolutely the wrong place for Solaris-specific edits. We have a real,
> seperate and maintained manual page for that purpose ([1]).
>
Apparently the upstream disagrees with you. They (well Glenn) in fact
*recommend* that the man page generated automatically from the --nroff
output.
> [1]=(And as said _several_ times that we could use a DocBook/XML manual
> page as master source file shared between documentation and code folks
> in the future from which both the Solaris manpage and the getopts string
> can be generated from (this would eliminate all the "manpages
> out-of-sync" concerns described in this thread))
>
That helps address some, but not all, of the concerns. You still wind
up with the situation of two physical copies of the documentation on the
media.
This approach also seems not to match what the upstream suppliers seem
to be saying...
I rather strongly suspect that in the end we will be faced with one of
two choices:
1) fork the code base and do what we feel is right for Solaris, or
2) accept the upstream's view of how documentation should be produced
and delivered to end-users, even though it doesn't match historical
precedent for Solaris, or what (at least some of us) we believe is the
right way to do this for Solaris
Neither of those decisions are wonderful ones, but the fact is that this
is a situation where we can't achieve all of our desires. So it will be
up to us (and the ARC) to decide which ones are more important. Which
is why a vote is necessary.
- Garrett
> ----
>
> Bye,
> Roland
>
>
