jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. -- mark Rick Matthews wrote: I agree in principle with Jim's points. In particular, 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. If ARCs are going to require this information, it should be documented somewhere that a user can find it a normal operating environment. Currently, I'd have to agree this is man pages. I think a further point of this discussion is a need for ARCs to adopt a consistent means of doing so, and stick to it. In several of the cited cases with man pages, the man pages were produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned why we would have man pages for jar/java release vehicles. That is inconsistent, which is why I believe Jim raised the issue. Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem to be a checklist of items needed for a FOSS jar project (and of course, many checklists are incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s: 1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues) 2) Man pages for stability and taxonomy 3) What portions need to have declared stability, etc. (like package name) 4) What JDK version(s)? 5) Versioning of jar files Mark Martin brought up number 5 quite awhile ago. There was no further action taken. The jar files really seem to parallel C libraries, and should have a best practice for versioning similar to (or maybe expanded) Library and Shared Object Requirements. IMHO, man page declaration of stability and taxonomy works. Let's keep that until there is a suitable better way. Lloyd's method of documenting is a good start, but we can't hope to force external communities to use such a method, except by general acceptance. We could make it a best practice for non-FOSS jar deliverables that are being ARCed. This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion. I think the ARCs need to look into these issues (as is being done), and reasonable methods/ practices be established, and then those be consistently applied. -- Rick On 05/13/09 13:30, Jim Walker wrote: For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but not standard practice for Java developers to look for man pages alone, doesn't seem enough reason to stop man pages being delivered with jar file packages.
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Mark A. Carlson wrote: Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? - Garrett -- mark Rick Matthews wrote: I agree in principle with Jim's points. In particular, 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. If ARCs are going to require this information, it should be documented somewhere that a user can find it a normal operating environment. Currently, I'd have to agree this is man pages. I think a further point of this discussion is a need for ARCs to adopt a consistent means of doing so, and stick to it. In several of the cited cases with man pages, the man pages were produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned why we would have man pages for jar/java release vehicles. That is inconsistent, which is why I believe Jim raised the issue. Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem to be a checklist of items needed for a FOSS jar project (and of course, many checklists are incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s: 1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues) 2) Man pages for stability and taxonomy 3) What portions need to have declared stability, etc. (like package name) 4) What JDK version(s)? 5) Versioning of jar files Mark Martin brought up number 5 quite awhile ago. There was no further action taken. The jar files really seem to parallel C libraries, and should have a best practice for versioning similar to (or maybe expanded) Library and Shared Object Requirements. IMHO, man page declaration of stability and taxonomy works. Let's keep that until there is a suitable better way. Lloyd's method of documenting is a good start, but we can't hope to force external communities to use such a method, except by general acceptance. We could make it a best practice for non-FOSS jar deliverables that are being ARCed. This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion. I think the ARCs need to look into these issues (as is being done), and reasonable methods/ practices be established, and then those be consistently applied. -- Rick On 05/13/09 13:30, Jim Walker wrote: For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Garrett D'Amore wrote: Mark A. Carlson wrote: Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? I think the only real review that is relevant is where it is installed and how it is packaged. If it provides a service how that service is started. This is not really any different to what we allow for code written in other languages. For example the real documentation (including stability levels) for libcurl is html docs under /usr/share/ That is what came from upstream. Personally I find even the addition of some of the ATTRIBUTES section information more than is really necessary in some cases - like when it is blindinly obvious this isn't OpenSolaris/Sun developed components. However given there is a good working system for adding it and it does provide value I'm happy to see it continue. If there is no man page for something and its docs come in a different format then IMO we should leave those docs alone. -- Darren J Moffat
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Garrett D'Amore writes: Mark A. Carlson wrote: Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? It's not another layer of review. It's architectural review as required by the process. No matter how important a project team may be, we simply do not defer to project teams to do all architectural review on our behalf. There's only one ARC, and the system is designed that way on purpose. So, JCP may do whatever reviews it desires in its own way (as may other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be shipped as a Sun product -- including but not limited to being part of the OpenSolaris distribution -- it's necessary that the engineering work goes through architectural review. In this case, I think we *are* concerned about advertising the right stability level for these interfaces, because that's an inherent part of software design, and not just some artifice that comes out of the ARC. If there's some local definition of stability levels and reference documentation, and these are well understood by users, then that's great. It doesn't matter to me much that it's not identical to our taxonomy or to man pages. We may as well use what's natural (and in fact require its use in all reviewed projects) so that users will understand it better. However, I do not agree that this means that we take a pass on it. If that's what we're planning to do (or if it's what you're suggesting here), then either (a) Java needs to create a SAC-sponsored process to play nice with the rest of us or (b) we need a much bigger rule (from the CTO's office) giving Java a get-out-of-ARC-free card. I don't think we can or should do that on our own. -- James Carlson, Solaris Networking james.d.carlson at sun.com Sun Microsystems / 35 Network Drive71.232W Vox +1 781 442 2084 MS UBUR02-212 / Burlington MA 01803-2757 42.496N Fax +1 781 442 1677
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
James Carlson wrote: Garrett D'Amore writes: Mark A. Carlson wrote: Let's keep in mind that we are trying to document (in an easily accessible place) the interface classification of the OpenSolaris instance (not the Java interface across platforms). Given that we need to do this without massive patches to the upstream code, and that Java projects should use whatever native mechanism exists to document the classification across platforms, the OpenSolaris man page seems to be the best place. I remain unconvinced that we (OpenSolaris) should even be concerned about stability of Java APIs upon OpenSolaris. (With the possible exception of APIs that are designed specifically to *support* OpenSolaris itself.) Do other members see value in having another layer of commitment and review beyond whatever is already done as part of the Java community? It's not another layer of review. It's architectural review as required by the process. No matter how important a project team may be, we simply do not defer to project teams to do all architectural review on our behalf. There's only one ARC, and the system is designed that way on purpose. This sounds like a self-serving statement to me. I've always believed (and maybe I've misunderstood) that ARC review is designed to ensure that the bits that we deliver are properly reviewed -- to prevent total anarchy, and to ensure that the right people are looking at the project. What I'm failing to understand is how PSARC (or LSARC) review of Java APIs is at all meaningful. The right parties to involve in those conversations are *not* (at least today) the members of the ARCs. In fact, I propose that the current ARCs are woefully inadequate to understanding the delivery concerns for software that it is intended to be used in environments that are not Unix-ish. Furthermore, what sense does it make to deny a Java API, or even issue TCRs against such an API, when the API comes from upstream (and the upstream might well be Sun itself!), and is concerned with portability and such. I'm opposed to the idea of process for its own sake -- the process needs to add something or its just a waste everyone's time. I think reviewing of Java APIs (and assigning stability levels to such) on any kind of fine grained scale qualifies as such a waste. What *does* make sense for review, IMO, is: 1) delivery of major new revisions or features, such as Java 1.6 or whatever. 2) location of deliverables (what directory are libraries and commands located in) 3) stability of *major* components. (I.e. Java 1.6 is assigned a Committed binding on Solaris or somesuch) Anything more than that, including trying to provide man pages for individual APIs, is utter nonsense, IMO. So, JCP may do whatever reviews it desires in its own way (as may other quasi-ARC-like bodies, such as CLARC and Sun Ray ARC), but to be shipped as a Sun product -- including but not limited to being part of the OpenSolaris distribution -- it's necessary that the engineering work goes through architectural review. I view Java as a bit special, because it has an entire runtime environment that is totally disconnected from the rest of the platform. Trying to review a whole different platform in that context makes little or no sense, except in the broadest terms of Java is available, and the version number is X with Commitment Level Y. Here are the directories...') In this case, I think we *are* concerned about advertising the right stability level for these interfaces, because that's an inherent part of software design, and not just some artifice that comes out of the ARC. But its totally redundant, except that in this case the folks reviewing the API are probably completely inadequate to the task of performing the review. For example, how many ARC members are familiar with the issues faced by software intended to be deployed on cell phones. Or Win32? Or even Linux, for that matter? What about the considerations for software deployed in the browser? Or the sandbox restrictions of Java? Like it or not, our specialty is Solaris. The further afield we get from that, the more inadequate our ability to meaningfully review it. At some point we either have to degenerate into a pointless rubber stamp, or (worse) a potentially harmful (because we lack adequate context) barrier to progress. If there's some local definition of stability levels and reference documentation, and these are well understood by users, then that's great. It doesn't matter to me much that it's not identical to our taxonomy or to man pages. We may as well use what's natural (and in fact require its use in all reviewed projects) so that users will understand it better. However, I do not agree that this means that we take a pass on it. If that's what we're planning to do (or if it's what you're suggesting here), then
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
I agree in principle with Jim's points. In particular, 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. If ARCs are going to require this information, it should be documented somewhere that a user can find it a normal operating environment. Currently, I'd have to agree this is man pages. I think a further point of this discussion is a need for ARCs to adopt a consistent means of doing so, and stick to it. In several of the cited cases with man pages, the man pages were produced as part of the Fast Track process. In the case of LSARC/2009/262, it was questioned why we would have man pages for jar/java release vehicles. That is inconsistent, which is why I believe Jim raised the issue. Toward that end, issues continue to be raised with jar/java FOSS projects. There doesn't seem to be a checklist of items needed for a FOSS jar project (and of course, many checklists are incomplete). As I recall, the following issues resulted from FOSS cases delivering jar s: 1) How to deliver javadocs to OpenSolaris (mostly due to web site volume issues) 2) Man pages for stability and taxonomy 3) What portions need to have declared stability, etc. (like package name) 4) What JDK version(s)? 5) Versioning of jar files Mark Martin brought up number 5 quite awhile ago. There was no further action taken. The jar files really seem to parallel C libraries, and should have a best practice for versioning similar to (or maybe expanded) Library and Shared Object Requirements. IMHO, man page declaration of stability and taxonomy works. Let's keep that until there is a suitable better way. Lloyd's method of documenting is a good start, but we can't hope to force external communities to use such a method, except by general acceptance. We could make it a best practice for non-FOSS jar deliverables that are being ARCed. This assumes Lloyd's proposal is sound, which I don't feel qualified to have opinion. I think the ARCs need to look into these issues (as is being done), and reasonable methods/ practices be established, and then those be consistently applied. -- Rick On 05/13/09 13:30, Jim Walker wrote: For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but not standard practice for Java developers to look for man pages alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. Cheers, Jim -- - Rick Matthews email: Rick.Matthews at sun.com Sun Microsystems, Inc. phone:+1(651) 554-1518 1270 Eagan Industrial Road
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Could we not add something like a stability file to the META-INF directory in a JAR file then provide something (like extension in IDE, or CLI) to extract it? I was going to suggest adding it to the manifest, but it would seem to be more strict about the format of the file - while the directory META-INF would be more flexible. Just my 2?, Darren. On 19/05/2009 16:53, Michael Kearney wrote: I wouldn't want to see the Sun jar files have the @Taxonomy annotation and a completely different (or non-existent) method, such as a man page for FOSS jar files. I'd like to see a single, consistent method and I think that's a short and simple man page. -Michael Norm Jacobs wrote: Jim Walker wrote: For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? NO, NO, NO. We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects. Largely, the projects are not going to be interested in this type of change. This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command. I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? Simply put, If we can leave the upstream bits alone, we should. If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community. For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream. This doesn't mean that you can't include support for SMF, RBAC, ... It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred. So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate. I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? They won't. 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but not standard practice for Java developers to look for man pages alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. The requirement has really been to provide documentation. We have not forced folks to deliver man pages when the software they were delivering had it's own documentation. If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything. If software was lacking documentation, we have asked for documentation that describes it, usually a man page. The intent is to provide the documentation that is expected by the users of the software. -Norm -- http://www.sun.com * Michael Kearney * Staff Software Engineer *Sun Microsystems, Inc.* MS UBRM05-390, 500 Eldorado Blvd Broomfield, CO
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
Jim Walker wrote: For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? NO, NO, NO. We don't want to be in the business of patching this bit of Sun lore into source and or documentation delivered by existing open source projects. Largely, the projects are not going to be interested in this type of change. This should be handled by a separate mechanism that falls outside of that arena, perhap by the taxonomy(1) command. I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? Simply put, If we can leave the upstream bits alone, we should. If we have to make changes to make it build, install, or function properly then coordinate those changes with the upstream community. For SFW, it's ok to deliver them as a patch initially, but the expectation is that the next update will obsolete the patch unless there is a really compelling reason to deviate from the upstream. This doesn't mean that you can't include support for SMF, RBAC, ... It just means that we want something that doesn't require new patches at each update and ultimately, no patching at all would be preferred. So again, leave the open source bits (docs in this case) alone unless there is a really compelling reason to deviate. I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? They won't. 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but not standard practice for Java developers to look for man pages alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. The requirement has really been to provide documentation. We have not forced folks to deliver man pages when the software they were delivering had it's own documentation. If it comes with texinfo, javadoc, html, ... then we have let them deliver that documentation and not required a man page for everything. If software was lacking documentation, we have asked for documentation that describes it, usually a man page. The intent is to provide the documentation that is expected by the users of the software. -Norm
jar file man pages - was Re: trove-2.0.4 [LSARC/2009/262 FastTrack timeout 05/05/2009]
For LSARC, PSARC and the opinion writer(s) to consider Michael Kearney wrote: 1. Lloyd, I like the idea of your annotation but have a couple of concerns. - Would teams be expected to update third party, open source jar files with the annotation? - Would the ARC provide the common @Taxonomy annotation Java code? I have concerns too. In general, we will not be able to change FOSS code upstream like this. We normally try to do as little modification as possible (ie. just enough to get it to run well on Solaris/OpenSolaris). This is another reason why short man pages are being tacked on. Is it possible to tack on a page to the javadoc? I don't want to see big javadoc patches in the SFW consolidation that document detailed taxonomy information that we have to carry forever because they will never be accepted into the upstream community. Why would a FOSS project creating jar files even care about our taxonomy rules? 2. What if the man page simple documented the stability at the granularity of the jar file and nothing else. Perhaps the man page could generically reference the Javadoc? Not every jar file in /usr/share/lib/java has a man page, but that is the current practice, for the ones that do: $ man asm $ man mvel $ man janino $ man jettison $ man joda-time $ man jaxen-core $ man junit $ man ant (needs a more direct reference to javadoc) ... As I see it, having jar file man pages... 1. Provides users stability and availability (taxonomy) information about jar file packages on Solaris/OpenSolaris not available anywhere else. 2. Is pretty painless for project teams to produce and support. 3. Man pages do no harm, and I think users are already getting use to having them. Some information is better than no information. 4. Until there is a better way, man pages should be required for any new jar file submissions into Solaris/OpenSolaris. I thought this was already true. 5. Man pages are used by most Solaris/OpenSolaris packages. 6. I appreciate where Java developers are coming from, but not standard practice for Java developers to look for man pages alone, doesn't seem enough reason to stop man pages being delivered with jar file packages. We can't control how jar files are delivered or documented on windows or other environments, but we can on Solaris/OpenSolaris. BTW. ccing Norm (sfw c-team lead) since one of the requirements to integrate into sfw is a man page. Cheers, Jim
