The case hasn't been denied; it's been derailed so an opinion can be written and it will be clear if precedence has been set or not with this case.
From the LSARC meeting today, it seemed like the majority of the committee thought it was fine for the project team and other teams to ship a man page. I don't think that is the right way to go, in that some jar files will have man pages, some won't and Java developers probably won't look for a man page anyway. I think Jim identified correctly a real problem - how do we communicate the interface classification of a jar file to the end user. I think we need a comprehensive and consistent solution. And the javadocs proposal has a lot of merit to it. We are voting on whether the project team should be allowed to ship the man page. (I thought the majority wanted that but need to take an explicit vote) So if after the vote, I am in the minority, than the case is approved and I write a section stating the minority opinion. If after the vote, I am in the majority, then the case is approved, the team doesn't ship a man page, and the minority can write their section of the opinion if they chose. Margot Mark Martin wrote: > > I'm presuming you're voting against this case as spec'd, with the > offered opinion, correct? The project team hasn't been given a chance > to make any advised or required modifications, so it seems a bit > imprudent to deny a case in that manner. > The intent here is that the man page inclusion precedent will be set > here and now, right? If the vote sustains for approval with a man > page, then there's no need to bring another case forth, right? Seems > like Jim's gap would be addressed in that case. Or should the > "optionally" token in the opinion text be taken as a failure to cover > the gap? > > On the topic, though, I think Jim brings a very good point -- how does > the project team communicate the expected stability? Lloyd brings an > interesting solution with the use of Java Attributes as documentation > decoration, although I have a few issues with it on technical > grounds. For those not on the call, I see the problem as this: > > At some point, Sun must have established the precedent and the > _expectation_ that stability levels of most types of interfaces were > to be expressed to consumers of those interfaces in the man pages. > I'm sorry I can't quote chapter and verse. This is, as far as I'm > aware, a communication norm that I don't see in other systems, Sun > originated or otherwise. Java certainly does not have it as part of > any standard, nor does Linux, as we discussed in the bsh vs. beanshell > debate in PSARC. > > As we're ramping up integration of java components, we're creating new > gaps from old practice. One of these is the nomenclature surrounding > the naming of the jar files themselves (jars as "libraries"), which I > won't go into here. The other is the point which Jim raised -- > there's currently no expected way to communicate stability level other > than man pages. Adding man pages to java jar projects (projects which > deliver only .jars) _feels_ wrong, since the consumers of these jars > aren't going to expect to find a man page -- they're on a very > different usage model than most other consumers of C libraries and > command line interfaces. Consumers in this case typically use > JavaDocs as their source of API information, and that _feels_ like a > better place to put that information. > > If the man pages are explicitly NOT to be delivered with "jar" > projects, then where is the stability level expressed? If in > JavaDocs, then what does that look like, assuming we need precision > for that nomenclature? > > Does the very same taxonomy even apply to jars? The current taxonomy > is, as a core component of its definition, dependent on release > versions of Solaris. Obviously, java jar's are more tightly coupled > to Java versions than on OS release versions, no? > >> >> Thanks, >> Margot >> >> >> _______________________________________________ >> opensolaris-arc mailing list >> opensolaris-arc at opensolaris.org >
