Alan Coopersmith wrote:
> Garrett D'Amore wrote:
>
>> 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.
>>
>
> The minimum memory requirement for the release this is integrating into
> is 512Mb. A few k of memory, in a shared library that can be shared amongst
> all processes using it, is far down in the noise.
>
This attitude, spread across dozens, or hundreds of projects, is part of
the reason why software still struggles even in the face of Moore's
law. Nobody cares about a few kB, but those kB add up in aggregate.
>
>> 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.
>>
>
> We also install commands users never use, drivers for hardware they don't
> have (and could possibly never have), sample audio files they'll never
> listen to, etc. Text that helps them use a command is far more useful
> than any of those.
>
Yes, but *two* copies of the text? And in many cases those drivers
*can* be easily removed, as can the audio files. They are
uninstallable. (In fact, I recently pushed a change to delete a 300k
audio file that nobody listens to anymore. The remaining audio files
are much smaller, and *may* be used by various applications or user
configs.)
>
>> 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.)
>>
>
> This documentation is less likely to be out of sync with the implementation
> than the traditional man page. That's an improvement to the architecture,
> making sure the user always has at least a correct, if less detailed, source
> of documentation of the options. It will also always document the version
> the user is using - I've seen far too many questions on OpenSolaris e-mail
> and IRC from users confused because their PATH & MANPATH don't match and
> they're seeing /usr/gnu man pages but running /usr/bin commands, or vice
> versa.
>
I agree that this is likely to be an improvement (although it turns out
that the documentation in the command still has to be maintained.) Does
that mean we abandon traditional man pages?
>
>> 4) Furthermore, the --man output doesn't reflect standards required for
>> Sun man pages. For example, there is no
>> ATTRIBUTES table.
>>
>
> That's a good reason why there should also be a traditional man page, and
> --man shouldn't replace it, just supplement it.
>
Your response here conflicts with your response to point #3 above.
Either we have one canonical copy of the documentation that should
always be correct and maintained, or we risk having the two copies get
out of sync or become inaccurate. Which should it be?
>
>> 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.
>>
>
> That choice was added when we shipped workstations with 105Mb hard disks.
> That choice makes no sense on today's computers and decreases system
> usability. Many of the install options added for 105Mb hard disks will
> be gone in the installer for the Solaris release this integrates to, since
> they make no sense in the day of 1Tb hard disks costing $100, and even
> embedded systems, like the cell phone in my pocket, having many times the
> disk space of that 105Mb SPARCstation 1.
>
I seem to recall we are also struggling to find room on the LiveCD.
Space constraints are *not* a thing of the past.
This attitude -- memory is cheap so it doesn't matter -- is why systems
that should be fully capable of performing the same basic tasks we did 5
years ago, are now no longer able to boot an operating system even
though the end user is really just interested in doing the same basic task.
Yes, I believe in tight code. Yes I believe memory should still be
treated as a precious resource. No, I don't think it is unreasonable to
ask to be able to use an operating system with 128 MB of RAM.
As far as I'm concerned, this "fight" is the "good fight", and I'll
stand my ground on it. I may well be overruled, but I refused to just
take the easy and lazy path of considering system resources an
infinitely wasteable resource.
>
>> 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.
>>
>
> That's a good reason why there should also be a traditional man page, and
> --man shouldn't replace it, just supplement it.
>
>
>> 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.)
>>
>
> Translators don't have to translate every string in the application.
>
Since when? I thought that pretty much every human interaction had to
be l10n'd in order to be qualified as localized. This is the first time
I've heard of "partially" localizing an application. Are there any
other precedents for this?
>
>> 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.
>>
>
> That argument, like the above, are Sun business decisions. If Sun wants
> to save money, it can make decisions about what it pays to translate, but
> that should not affect the architecture of the shared OpenSolaris code base.
> Please separate business considerations of one distro maker from the shared
> architecture of all distros.
>
Separating things like basic costs from architecture is IMO foolish. We
don't live in an abstract world were funding is unlimited and memory is
free. In the real world, getting work done costs money. And, I'm not
even talking about what this might cost Sun -- the same costs apply to
*anyone* who might perform this work.
>
>> 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...
>>
>
> *THIS* case does not set precedent because this precedent was set in the
> previous cases shipping commands with --man/--html/--nroff options. This
> project team should not be penalized because you failed to raise objections
> to this architecture when those precedents were set.
>
The precedent set was not made explicitly -- in my opinion it slid by
without due consideration. I'm not saying we have to go back and rip
out the support from existing commands -- but I *am* saying that if this
is going to be the new way of doing things, then we ought to at least
properly consider it.
So yes, I do get to ask that we reconsider the direction. ARC has done
this to numerous projects in the past as well.
>
>> 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.
>>
>
> This is the OpenSolaris ARC, not Sun business review.
>
But it is relevant to *SOLARIS*. (Or if you prefer *OpenSolaris*.)
-- Garrett
