On 7/26/09, Josh Hurst <joshhurst at gmail.com> wrote:
> On 7/26/09, Jennifer Pioch <piochjennifer at googlemail.com> wrote:
> > On 7/26/09, Garrett D'Amore <gdamore at sun.com> wrote:
> > > 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
> >
> >
> > Didn't you read what Roland wrote about the project rules?
> >
> > > in several major and unbreakable rules for this project which
> > > includes:
> > > - WE DO NOT FORK THE CODE
> > > - WE DO NOT BREAK THE KSH93 TEST SUITE
> > > - THE KSH93 TEST SUITE IS COMPLETELY OFF-LIMITS FOR CHANGES
> >
> >
> > If you are forking the code with such unnecessary changes I will NO
> > LONGER CONTRIBUTE to this or any other Opensolaris.org project.
>
>
> I will not contribute either if Sun decides to fork with silly
> justifications. Taking away --man is an incompatible change and must
> not be tolerated.
I agree with Josh. Neither I will contribute to Opensolaris if Sun
forks the AST code just to enforce their silly politics.
--
^---^
(@)v(@) Chris Pickett
| / IT consultant
===m==m=== pkchris at users.sourceforge.net
