there seems to be a reasonable understanding of issues on both sides I don't believe I have been misrepresented/misinterpreted
to show that the ast side is not being bone-headed about not wanting to change, there is more to the ast upstream than is (or proposed to be) in solaris I don't expect this to weigh much either way for the ARC decision, but I think its important to understand motivation on the upstream side, which is basically a 3 person organization (the code authors) I just grep'd ~400 instances of ast optget self documentation which includes .c optget / .sh getopts usage strings, self-documenting library discipline/method routines (http://citeseerx.ist.psu.edu/search?q="The+discipline+and+method+architecture+for+reusable+libraries), and self-documenting plugins (runtime shared library discipline/method routines) if you can't tell by now the ast setup is, among other things, geared to minimize the work required by coders to maintain a working system by keeping code/documentation/configuration fairly localized e.g., when a new method or plugin (e.g., sum method, archive format, sort method) is added to ast it is self-contained and rarely requires a change to the corresponding utility wrapper there is no way that we could commit to a *vaporware* proposal of reworking the self-documentation which would impact the { source, build, packaging, installation, testing, l10n } steps in our software configuration to consider switching we would need: - a portable xml-whatever-to-whatever implementation - a way to automatically convert existing code to the proposed form - a way to handle both static and dynamic (runtime) documentation sources - a way to ensure that changes to the master source(s) make their way to build targets and all of this working in a posix conforming sandbox configuration but even then I don't know if its worth the effort on the ast side because it pretty much guarantess a disconnect between the command a user executes and the documentation shown by man on systems that provide multiple implementations of the same command (e.g., vendor vs xpg* vs gnu vs ast) here are two proposals (1) something similar already mentioned on the list(s) modify "man foo" to check for self-documenting foo this could be done by checking for e.g. some-dir/foo.sd and if found run foo --man 2>&1 nroff-magic some-dir/foo.sd where some-dir/foo.sd could contain solaris-specific sections not supplied by ast this would satisfy the upstream because man documentation would always be up to date (and it requires no source mods:), and the dowstream because it could append its own documentation requirements independent of the upstream (2) there is one #ifdef SOLARIS the upstream can consider the upstream will add and maintain code in libast that will intercept generic libast::optget() options objectionable to solaris and first fork/exec man <command-name> and if that fails then emit the ast self-documentation; it will be up to the downstream to provide the man input and maintain consistency between that and the implementation; the man input could be generated by a mechanism similar to the man mods in (1) (hmm, just checked "man does-not-exist" on solaris 5.10 and it exits 0! failure detection would have to check man stdout for "No manual entry for ...") I don't care for (2) because it forks ast behavior between solaris vs non-solaris, but I also don't want to impede the progress roland has made -- Glenn Fowler -- at&t Research, Florham Park NJ -- On Sun, 26 Jul 2009 21:21:04 -0700 Garrett D'Amore wrote: > Glenn Fowler wrote: > > On Sun, 26 Jul 2009 16:00:57 -0700 Garrett D'Amore wrote: > >> Roland Mainz wrote: > >>> Alan Coopersmith wrote: > >>>> I'm sponsoring this fast-track request on behalf of the > >>>> ksh93-integration and busybox projects. The timeout is > >>>> set for Friday, July 31, 2009. > >>> [snip] > >>> Just to clarify (since both points have IMHO been either ignored or > >>> misinterpreted several times): > >>> 1. We do _not_ intent to remove or discontinue normal documentation, > >>> including manual pages (in fact I've been a long-term advocate of > >>> getting Solaris moved to DocBook/XML-based manual pages (including > >>> _shipping_ them as part of the installation instead of the nroff > >>> versions (that's why I even worked on a /usr/bin/man replacement > >>> codebase))). > >> I heard you. However, the upstream sources have *not* agreed with this > >> approach. > > you want upstream to agree to an approach that even solaris hasn't settled > > on yet? > Well that much is true (we've not settled yet) -- the decision *would* > have been good to have (either way), which is why I derailed it... I > felt that such a decision deserved explicit consideration rather than > coming in as an implementation detail. > That said... I received the following text in an e-mail message from you > (also delivered to the list): > in almost all other cases the optget() usage string *is* the man > page src, > and we have no intention of ever maintaining separate .1 man pages, > save the traditional exceptions for the long ones like sh(1) > if there are concerns about maintaining separate optget() usage strings > and .1 text files for ast commands on solaris, then I recommend > generating the man page from the --nroff output; > So while the question of a separate XML file wasn't specifically raised > and answered, I had taken the above text to indicate that you > (collectively as the ksh93 upstream) were also rejecting other schemes > to move this kind of documentation out of the cooked binary. > I'm sorry if I've misunderstood either you or Roland on this, or if I've > misapplied what you said. > - Garrett
