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? -JohnS On 24-Jul-09, at 11:01 PM, Garrett D'Amore wrote: > Roland Mainz wrote: >> Garrett D'Amore wrote: >> >>> Alan Coopersmith wrote: >>> >>>> Garrett D'Amore wrote: >>>> >>>>> Personally, I think --man, --html and --nroff and such is a >>>>> dangerous >>>>> precedent to set. I'd rather not have them, and instead rely on >>>>> the >>>>> "man" command to provide this functionality. >>>>> >>>> Isn't it a bit late to raise such a concern, since the precedent >>>> was set >>>> in the long list of previous cases that used AST/ksh93 >>>> implementations? >>>> >>> It might be. I certainly should have raised the issue back then. >>> I'm >>> still not happy about this. >>> >> >> Why ? >> > > I'll explain why further down. > >> >>> There's yet another concern, which is that I've found that man >>> <command> >>> and command --man do not generate the same document. So we know >>> introduce a problem were documentation delivered on the system can >>> be >>> inconsistent. >>> >> >> Erm... no. As said in my other email the "--man" output is >> basically a >> short/terse format and more or less exactly what the "getopts" parser >> sees (it may even be usefull if main documentation and actual code >> are >> out-of-sync (which is currently the case for many commands)). >> > > No, it isn't. (Well, you might have "extra" text in the getopts > parser, but for an example look at the output from sum --help. Its > quite a rich manual page, far beyond the normal getopts kind of > messaging.) > >> >>> I feel really strongly that this was a bad idea. >>> >> >> IMO it was a nice idea - see my other email where this feature >> originated from. >> > > I understand the notion. And for projects that don't have the same > considerations we do, the idea is elegant. But I'll elaborate > further below why I think this idea is *not* a good idea for our > project. >> >>> Strongly enough that >>> I'm contemplating derailing the case. >>> >> >> And what should we do then ? The only thing we can do is to remove it >> from the case materials - removing it from the code can only be done >> globally (e.g. libast) and that really will break existing&&ARC'ed >> parts. >> > > #ifdef SOLARIS ? Seriously, if you want Solaris to adopt these > commands in favor of our current native implementations, then there > has to be some willingness to address architectural issues found on, > or even specific to, Solaris. > > >> [snip] >> >>>> No matter what you multiply $0 by, it's still $0. (We don't >>>> localize man >>>> pages in Solaris. A subset of man pages used to be translated >>>> to Japanese, >>>> but I believe even that is no longer done.) >>>> >>> Really? That comes as a surprise. But we *do* localize commands. >>> >> >> Actually the situation is AFAIK currently that there is not really >> much >> funding for this left and the basic system commands are very low >> priority. That's why I am currently working on getting a rag-tag team >> set-up to get l10n catalogs for the AST commands (e.g. covering ksh93 >> itself and all commands which go through the busybox-like "alias" >> wrapper (including those commands covered by this ARC case)) >> integrated >> (first covering Japanese, Chinese, French and later German, Spanish, >> Russian, Urkainian locales). >> > > That may be the case. However, the your misunderstanding my > argument, at the bottom of this message I'll elaborate further. > >> >>> So >>> does putting --man content in the command suddenly mean that in >>> order to >>> be I18N compliant they have to be localized? That would certainly >>> add >>> to the cost. >>> >> >> I don't understand the connection here: >> 1. "i18n" is "internationalisation", e.g. the support for non-ASCII >> characters&co. and this is fully covered by the new commands (and I >> am >> _very_ picky about this detail). >> > > The point is that it must be possible for the commands to be > localized. While there is no *technical* difference imposed by the > length of the string, the string itself must be localizable. That > means you can't elide handling of this when you localize the rest of > the command, I think. > >> 2. "l10n" means "localistion" and mainly rotates around error >> strings/messages/etc. being provided in non-english languages. > > Yes. > > 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. > > 2) We also have traditional manual pages. On a normal system, the > default installation will include now *two* copies of the manual > page. This is wasted space. > > 3) Worse, the pages can be out of synch with each other. (The sum > man pages are again a good example of this.) Which is correct? > (*Probably* the --man command output.) > > 4) Furthermore, the --man output doesn't reflect standards required > for Sun man pages. For example, there is no > ATTRIBUTES table. > > 5) Some users elect to *remove* manual pages (or not install them) > to save space. We've long offered this choice. However, putting > the man pages in the binary effectively removes this choice from the > user. > > 6) There has historically been different processes for man page > content generation than for software engineering. By putting the > man page content into the binary, you basically wind up skipping the > editorial review (and in many cases creation) of those man pages by > our professional documentation writers and editors. > > 7) The rules for localization of documentation and commands have > historically often been different (based on funding levels, rules > for selling to different locales, and business priorities.) By > putting manual page content hard coded into the documentation, you > wind up creating a locked relationship where the two have to be > localized together, or not at all. This ultimately increases the > cost of localizing a command should such a localization be desired. > (Translators often charge by the word.) > > 8) The teams involved with localization of manual pages vs. commands > have historically been different, and have different costs. I > strongly suspect it costs more to localize a command than it does to > localize documentation. (You have to test the command, and the > translators also need to know more about technical details such as > handling message catalogs.) So if we do decide we need to localize > this stuff in the future, its probably going to cost us more to do > in a binary than it would as an actual document. > > 9) Worse, if we keep *both* the man page and the command text, we > might wind up paying *double* the cost, by translating *both* > versions. > > 10) Whether we want to admit it or not, when many of our core > utilities start doing this, the request is going to be that the rest > of our utilities (e.g. dladm, ifconfig, maybe even the man command > itself!) support --man as well. (I admit at first blush its a nifty > feature, and many users are going to like it, without understanding > or caring about the the ramifications I've listed above.) So saying > that this doesn't set precedent is IMO akin to putting ones fingers > in ones ears and saying LALALALA... If we're going down this road, > then it needs to be an explicit decision rather than something that > happened as an implementation accident. > > Now, all that said I do understand why the AST/ksh93 team has gone > down this road. Indeed, if I was going to deliver an unbundled > project, I might make the same decisions. Many of the above > concerns won't be relevant to David Korn or Glenn Fowler, and this > approach probably *does* solve problems that the upstream cares > about (no need to write actual separate man pages for example). > But they *are* relevant to Sun and the Solaris project. > > Many of the above issues could be handled more cleanly by simply > having --man execute the man command and feed the generated result. > But then, this begs the question, why not just run "man command" > instead of "command --man" ? (Indeed, the first form is more > familiar and requires less typing than the introduced --man content.) > > So with all that said, I believe that its *important* that the > decision to inline man pages into libraries and manual pages be made > *explicitly* by the ARC. I believe (going back and reading over the > previous ARC materials) that this detail was largely unconsidered > during previous ARC cases, and I would like the ARC membership the > change to think on the above points I've made, and make a decision > explicitly. > > With that in mind, I'm derailing this case for a vote, and I'll > write the opinion. Unless you want to provide more answers or > responses to my above points, I don't think any further work is > required from the project team -- we have enough information (I > think) to proceed with a vote on this. > > I will say just one more thing. Where it not for the --man, -- > nroff, and --html options, I think I would unhesitatingly give this > case a +1. I think the rest of the case has a great deal of > technical merit, and I actually would like to see the changes > integrated -- just without manual pages integrated into the binaries. > > -- Garrett > > _______________________________________________ > opensolaris-arc mailing list > opensolaris-arc at opensolaris.org
