While you talk about implementation issues and details below, I'm
unconvinced that my architectural considerations are addressed. It may
be that I chose poor examples, but rest assured I chose them at random.
Some examination of the code makes me think there are are others that
have a lot of content in them.
Other replies:
* From a end-user's view point, it looks like a man page, it is access
with an option called "--man", so how saying that this is not a
"replacement" for man pages feels a bit dishonest to me. Indeed, there
could be important information in the regular man page, but a user
wouldn't think to read that because they'll just --man. How is the end
user to know that this isn't the "real" man page. (Or for that matter,
which one is the "real" man page?)
* On l10n sparse catalogs. I'm sure that it is possible to build sparse
catalogs. I'm unsure that this is an accepted practice however, and in
markets where l10n is required, having some of the messaging be excluded
might require extraordinary measures to have such a waiver. (Then again
they might now... I don't know enough about the processes that go into
deciding when l10n is needed or not.) Note that these are *business*
issues which may face anyone that wants to deliver any commercial
product based on OpenSolaris. Of course, if you're only interested in
giving your stuff away for free, then such concerns are not likely to be
important to you.
Thanks. Mostly at this point I'll just wait and see how this pans out
during the meeting on Wednesday. Actually, that does bring up one
order of business: will you be available for the meeting on Wednesday at
10am PDT? If not, do you want us to take the vote, or would you prefer
to reschedule for a week when you can be available?
- Garrett
Roland Mainz wrote:
> Garrett D'Amore wrote:
>
>> Roland Mainz wrote:
>>
>>> Garrett D'Amore wrote:
>>>
>>>> Alan Coopersmith wrote:
>>>>
>>>>> Garrett D'Amore wrote:
>>>>>
> [snip]
>
>>>> 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.)
>>
>
> Right... but it cannot be easily stripped either because there are
> callbacks tied into the getopts code. Most of this specific getopts
> stuff (which is an exception (AFAIK the only one beyond "ulimit")) is
> actually _dynamically_ generated based on the capabilities of the
> underlying crypto libraries. IMO you hit the worst example of all... ;-(
>
> [snip]
>
>>> 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.
>>
>
> Right... but I also remind you that we try to _avoid_ the history of
> Solaris's ksh88 which was gradually fork'ed over time with the "best
> intentions" which later rendered the code incompatible to other ksh88
> versions on other Unices and pretty much unmaintainable, too. The
> ksh93-integration project was then created with the _strong_ intention
> to _prevent_ this kind of problems to happen _ever_ again, which
> resulted in several major and unbreakable rules for this project which
> includes:
> - WE DO NOT FORK THE CODE
> - WE DO NOT BREAK THE KSH93 TEST SUITE
> - THE KSH93 TEST SUITE IS COMPLETELY OFF-LIMITS FOR CHANGES
> (I am using uppercase here to make it very clear that this project was
> founded to prevent the history from repeating. Sun unfortunately has a
> long tradition of shooting itself into it's many feet and when this
> project was founded we really hoped to prevent these mistakes at least
> for this project).
>
> That's why I am very unhappy about the suggestion to "litter" the code
> with lots of (IMHO) unneccesary |#ifdef SOLARIS|. It would mean we fork
> the code, create a huge additional maintaince and testing burden (and
> testing is already a _pain_, we're now working on the ksh93-integration
> update2 for more than six month and more than four of them are spend in
> testing) and make the code (slightly) incompatible. It's only "slightly"
> for _now_ but I know poeple love precedents and once this is established
> there is no way to stop the flood anymore.
>
> [snip]
>
>>> 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.
>>
>
> Erm... why ? l10n catalogs are always allowed to be sparse.
>
>
>>> 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.
>>
>
> Actually this is not much "wasted space" since the same string is used
> for getopts parsing and the "--help" output which you (AFAIK) wish to
> keep around.
>
>
>> 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.)
>>
>
> Right... the recent layoffs hit April Chin who was doing the
> coordination work and her disappearance from Sun wreaked lots of havoc.
> Even security-related bugs and their patches went "missing" ... the
> manual page stuff comes at the bottom of that list of mayhem.
>
>
>> 4) Furthermore, the --man output doesn't reflect standards required for
>> Sun man pages. For example, there is no
>> ATTRIBUTES table.
>>
>
> Again, the output is not intended to be a full manual page. I said that
> several times (and I am starting to feel ignored).
>
>
>> 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.
>>
>
> Again, the getopts string is used to create the "--man"+"--help" output.
> There isn't much wasted space. And the little bit of "extra space"
> you're describing is more or less "hidden" by the detail that
>
>
>> 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.
>>
>
> Again, please read what I wrote. We use the getopts string for this.
>
>
>> 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.)
>>
>
> Please see above. It is _not_ mandatory to do the localisation for every
> string. The code explicitly allows sparse catalogs.
>
>
>> 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.
>>
>
> See above...
>
>
>> 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.
>>
>
> See above.
>
> ----
>
> Bye,
> Roland
>
>
