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
