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. Jenny -- Jennifer Pioch, Uni Frankfurt
