James: I think the complication with libraries such as libnotify is that they are free software projects, so while Sun can say "anything we ship that uses this will come from the JDS team so it is project private", this doesn't mean that 3rd parties or others in the free software community might not write stuff that uses it. It isn't really private since the source code is freely available, as are ABI docs, websites, mail list archive discussions, etc.
So this sort of interface falls in the fuzzy ground between Uncommitted, External, and Private. From Sun's perspective, we can consider it Private. From a realistic perspective, it is Uncommitted. That's my take. The advantage of providing a manpage is that it provides help to developers wanting to work with the library in the free software community. Such a manpage should probably explain that the library isn't too stable, and perhaps encourage people to engage with the community to make it more stable if this is desired. Isn't OpenSolaris trying to encourage developers to adopt it's platform? Quality manpages and good documentation are probably the sort of thing that attracts developers, no? The feeling that your distro cares, you know. Though perhaps Sun doesn't want to invest too much time/effort into supporting free software desktop developers, specifically. Also, some argue that people don't read manpages for desktop applications since most user's interact with the desktop only via the UI. I don't know. I like manpages, and I think they have value. So, over the years, I've worked quite a bit on them. Many of the GNOME manpages we ship have my name on them, but I don't want to write them all myself. Brian > Brian Cameron writes: >> My understanding of Sun manpage policy is that all libraries >> should have manpages, if only to describe that they are Uncommitted >> in the ATTRIBUTES section and not to be used. > > No, if it's intended as "Private," as this one seems to be, then *by > definition* it must not have man pages. > > In that case, it should be shipped as libdaemon.so.1 (not > libdaemon.so, as the case materials seem to have), and it should omit > any compilation symlink and associated header files. > > If it's meant to be used by multiple projects, and not just this one, > then it may well need a much closer look and higher commitment, which > would require a man page. >
