Update accordingly, please reivew Chris
Brian Cameron ??: > Chris: > > >>>> These four libs are delivered with SUNWgtkmm, they are missing manpage >>>> originally. Attached are the manpage for them. >>>> >>>> >>> We have a separate manpage for libgiomm, but we lump all the >>> other "mm" interfaces into a single manpage. This seems a bit >>> odd. Shouldn't we either have separate manpages for them all >>> or a single manpage with shadow manpages? >>> >>> >> These four libs are delivered in SUNWgtkmm package (pangomm will be >> moved out), and all >> belong to gtkmm project. >> > > This seems a bit confusing to me since we deliver separate section 3 > manpages for each of the atk, gdk, and gtk libraries. > > >>> The NAME says: C++ interface for GTK+ >>> However, this manpage seems to be intended to be a shadow manpage >>> for libatkmm, libgdkmm, etc. also? So just saying "for GTK+" >>> doesn't seem right. >>> >>> >> What I mean GTK+ here is the GTK+ project, I think they all listed under >> gtk.org. I can make it >> clear if needed. >> > > I think "C++ interfaces for ATK, GDK, and GTK+" would be more clear. > > >>> The DESCRIPTION section only explains gtkmm, and not the other >>> libraries that you plan to shadow manpage to this one. >>> >>> >> gtkmm is a name of the project, it includes these four libs, just like >> the manpage for libpango, it >> inclues libpango, libpangox etc. but in the Description, we only use the >> statement Pango. >> > > Right, but with the libpango manpage the various libraries (aside from > libpango itself) are just backend libraries. The end user would likely > only ever use the libpango interfaces from their application. This is > probably why the libpango manpage focuses on the one library more. > > This manpage is different since the end user is likely to want to > write directly to each library separately. > > Also, even though ATK may be shipped with gtkmm, it really isn't a > part of GTK+. The ATK is an interface that is also, for example, > shared by Java (and perhaps KDE in the future). So it is a bit > misleading to make it sound like libatkmm is a GTK+ specific feature. > This is just an artifact of it being included in the gtkmm module. > > I think that it would be good to provide a separate paragraph for > each library in the DESCRIPTION section to explain each one > separately. > > For that matter, it wouldn't be a bad idea for the Pango manpage > to also be updated to provide more docs for each library. > This would just make the manpage a bit more clear. > > >>> There seems to be a /usr/share/doc/gtkmm-2.4 directory, but this >>> doesn't seem referenced in the FILE section as a documentation >>> reference. Why don't the other interfaces have docs installed >>> to /usr/share/doc? Even if we don't install docs, we probably >>> should provide online doc links for each interface. >>> >> /usr/share/doc/gtkmm-2.4 directory contains the demo sourcecode in >> /usr/demo/jds/bin/gtkmm, I will add >> it to the FILE section >> > > Yes, I would also add links to any online docs for the other > interfaces if we don't ship installed docs on the filesystem. > > Brian > -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.opensolaris.org/pipermail/jds-review/attachments/20080804/050cc8fa/attachment.html>
