Hi Roland, I'm not against having multiple ways of accessing the man page data as long as the output is consistent. The solution you mentioned below I think is reasonable and something that can be maintained. Having the docbook/xml master source would solve a lot of issues and could be the single source for Solaris/OpenSolaris binaries, manpages, and docs.sun.com entries. I would like to recommend that this path be taken and brought before the ARC to make it the standard generation and maintenance interface for man pages. It may be appropriate for such a project to be sponsored by the Documentation community.
*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* Octave J. Orgeron Solaris Virtualization Architect and Consultant Web: http://unixconsole.blogspot.com E-Mail: unixconsole at yahoo.com *-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-*-* ----- Original Message ---- From: Roland Mainz <roland.ma...@nrubsig.org> To: John Sonnenschein <johnsonnenschein at gmail.com> Cc: Alan Coopersmith <Alan.Coopersmith at sun.com>; Busybox development <busybox-dev at opensolaris.org>; Garrett D'Amore <gdamore at sun.com>; ksh93-integration-discuss at opensolaris.org; PSARC-ext at sun.com Sent: Saturday, July 25, 2009 11:52:23 PM Subject: Re: [busybox-dev] AST versions of fold, mktemp,pathchk,& tty [PSARC/2009/414 FastTrack timeout 07/31/2009] 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. > 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]). [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)) ---- Bye, Roland -- __ . . __ (o.\ \/ /.o) roland.mainz at nrubsig.org \__\/\/__/ MPEG specialist, C&&JAVA&&Sun&&Unix programmer /O /==\ O\ TEL +49 641 3992797 (;O/ \/ \O;) _______________________________________________ opensolaris-arc mailing list opensolaris-arc at opensolaris.org
