[busybox-dev] AST versions of fold, mktemp, pathchk,& tty [PSARC/2009/414 FastTrack timeout 07/31/2009]

[John Sonnenschein]

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