On Fri, 24 Jul 2009 23:01:51 -0700 Garrett D'Amore wrote: > Now let me break down the architectural problems I have with --man (and > also with --nroff and --troff), as they pertain to Solaris:
> 1) The commands increase the size of the text segment. Not only does > it add new parsing requirements (you have to at least have enough code > to handle --man, for example), but you also have the text of the man > pages themselves. While you might like to maintain the fiction that > this comes for free, it *is* a fiction. Run sum --man or some of the > other commands and you'll see content that was not automatically generated. a point, a question, some background, and a comment point for any ast command --??? lists the man page for options available to all ast commands via libast::optget(), so the "new parsing requirements" are provided in one place, most likely a shared library function, not in each command question "you'll see content that was not automatically generated" ? well part of sum --man *is* automatically generated specifically the methods listed for --method (try sum --?method) each method provides its own documentation that is combined at runtime for --man etc. via an optget() callback function that scans a method table although ast sum does not use plugins (methods in runtime shared libs / dlls) other ast commands do (e.g., pax, sort, vczip (not part of this case)) and plugins provide documentation using the same mechanism; plugins added to the command specific plugin path will show up in the next self-documenting (--man) output the ksh93 ulimit resource related options are generated on the fly from a separate resource table there are a few other instances where ksh93 generates option and self-documentation at runtime -- (script) user defined types is one example -- I'll let dgk elaborate on that background motivations behind --man in optget() - avoid duplication that may result in documentation that does not reflect implementation (if its not in the optget() usage then its not implemented) - avoid the man command providing legitimate documentation for the wrong command (PATH points to a different foo than man foo) - installing a command a.out also installs its documentation the static ksh93 sh.1 man page is an exception to the ast rule: the man pages for almost all other ast commands (ARC'd or not) are derived from --man, and there are no plans to provide static .1 man pages for them if solaris requires a .1 for each command then for the ast commands I imagine that being done via --nroff with a bit of automated filtering comment this is the first time I can remember someone complaining about (me) *providing* documentation -- Glenn Fowler -- at&t Research, Florham Park NJ --
