[Combining responses to multiple subthreads to try to reduce mail load.] Garrett D'Amore wrote: >>> 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?
We've always had to manage the risk of getting out of sync between the implementation, the built-in help, the man pages, docs.sun.com, and other forms of documentation. --man is just another way of formatting the built-in help, so doesn't add any more risk there. If this option had been called "--verbose-help" or "--help-me-more", would you be objecting as much as you are? Is it just the confusion of the "built-in help formatted like man" vs. an actual man page that worries you? > 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. That's certainly reasonable for operating systems which have accepted that limit. The one we're discussing here though, has not, so that doesn't apply. The current documented minimum RAM for OpenSolaris (and thus likely Solaris.Next) are 512mb. The current documented minimum RAM for Solaris 10 is 384mb for UFS root, 768mb for ZFS root. [1] [1] http://docs.sun.com/app/docs/doc/820-7273/installbugs-113?a=view >> 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? Since gettext() and catgets() were invented. In practice, this happens every time someone adds a string to a localized application, as that string is not translated instantly, but in the next update of translated strings. As a whole, Solaris has always been only partially localized, and never claimed to be, attempted to be, or aspired to be fully localized. Some portions were fairly fully localized in the past, but that is an ever smaller portion of the OS in recent years, due to the combination of budget shrinking while the content included continues to grow. >> Will your opinion text also recommend to the PAC that they delete all >> the admin guides, user guides, and all other docs other than the man >> pages from the Solaris documentation and docs.sun.com because they are >> multiple copies of the same information? >> > > No, because of two reasons: > > 1) the "man pages" are sourced by the same process and originate from > the same text No, the other documents are very different text, with different processes for creating and updating them. For an example from the small part of the OS you're most familiar with, there is a huge difference between the text in the "Writing Device Drivers" guide and the section 7 man pages - as there should be since they are different sorts of documents - tutorial vs. reference. When you update the DDI, you need to make sure both are updated - just filing a man page bug won't change the device drivers guide unless the human who processes your bug notices for you that you forgot to request updates to both. > 2) those bits are not delivered to the end-users on the media We have delivered documentation CD's in the past with those bits on, and once upon a time, even printed copies of them in the boxes with the media. We do deliver some documentation on the media other than man pages - built in help in GUI applications, the "Getting Started" guide, the GNU info docs, all the files in /usr/share/doc/, and so on. > Of course, if you want to add some text to the potential opinion (which > may or may not be a minority opinion), feel free to send me draft text > after the vote. "The majority feels that the minority belief that there should be exactly one canonical source of documentation for any portion of the system, and that all others be removed, is contrary to both the long standing Solaris implementation history and recognized industry best practice, and a dangerous reduction of Solaris usability, with little measurable benefit." -- -Alan Coopersmith- alan.coopersmith at sun.com Sun Microsystems, Inc. - X Window System Engineering
