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.
> 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.
> 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.
> 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.
> 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.
> 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.
> 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.
> 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.
> 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.
--
-Alan Coopersmith- alan.coopersmith at sun.com
Sun Microsystems, Inc. - X Window System Engineering
