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
