Re: gtkmm capabilities

[Roel Vanhout <roel riks nl>]

Murray Cumming wrote:
> > I cannot point to exact locations and say 'this or that function isn't 
> > documented'.
> But that's what you mention later, so please do remember to file bugs
> when that's what you find.

I do not find any place where I wrote 'gtkmm function x is missing 
documentation'. If I do find bugs in documentation, I will reports a 
bug; however I did never file bug reports when something wasn't 
explained fully or ambiguously in the documentation. That's just too 
much overhead for me, sorry. I _would_ use a php-style annotation system 
as suggested by Bart Hakvoort.

However, you seem to insist on 'real' examples. Let's take these two 
from Gtk::ComboBox:

-http://www.gtkmm.org/docs/gtkmm-2.4/docs/reference/html/classGtk_1_1ComboBox.html#a11
"""
  bool Gtk::ComboBox::get_add_tearoffs() const
    Gets the current value of the :add-tearoffs property.
  Returns:
    The current value of the :add-tearoffs property.
"""

But what is the :add-tearoffs property? A description of what that 
property does, or at least a link to such a description, would be nice. 
Otherwise I don't even have an idea where to go look for it.

-http://www.gtkmm.org/docs/gtkmm-2.4/docs/reference/html/classGtk_1_1ComboBox.html#a19
"""
void Gtk::ComboBox::set_active (const TreeModel::iterator& iter )
  Sets the current active item to be the one referenced by iter .
    iter must correspond to a path of depth one.
  Since: 2.4
  Parameters:
    iter The Gtk::TreeIter.
"""

This function sets the active item, but what is the active item? Is it 
the currently selected item? But wait, there is a 
Gtk::ComboBox::unset_active() function, because that function "causes no 
item to be active". Would that mean that an empty string is selected in 
the combobox? But there are comboboxes where I don't want to allow that. 
That's related to the sematics of this function, so it should be linked.

These are silly little examples and I don't have hours to sift through 
all documentation, although these are the _sort_ of things I run into 
with the gtkmm documentation.

> > It's more about the whole 'experience' (lame word). Now, 
> > MSDN isn't all that, but take for example the documentation for a call I 
> > just needed 10 minutes ago: CWinApp::GetProfileInt(). Apart from the 
> > fact that MSDN has a nice application that I can use to search through 
> > documentation and bookmark etc,
> I use google for the gtkmm documentation. devhelp is also very good.

Google just isn't practical, imo: no hierachical structures, too slow, 
no type-ahead find. Devhelp is ok (after I wrote a 
gtkmm-to-devhelp-index xsl stylesheet ;) ), but missing features. Ie 
last time I used it it couldn't even do case-insensitive search.

> > have a look at the webpage:
> > http://msdn.microsoft.com/library/default.asp?url=/library/en-us/vclib/html/_mfc_cwinapp.3a3a.getprofileint.asp
> > It has a full explanation of all parameters, the return value,
> Most gtkmm methods have the same documentation.

Yes, that's true. But see my remark above about the property. Saying 
'true if ok, false if not' is not helpful with a function named 
'SetFooProperty(bool arg)' if there is no indication of what 'Foo' is or 
does in this context.

> > pitfalls to watch out for,
> There are not so many pitfalls with gtkmm compared to MFC. Sorry about
> that.

I'll file a bug report on this ;)

> > > If anybody wants to pay $3000 for a few days of training, I and many
> > > others would be happy to help.
> >
> > Again, this is the difference between hobby and commercial projects.
> Companies often pay for training with proprietary software (and are
> often forced to because the documentation of proprietary software is
> usually so bad.)
> I don't understand what the difference is. Training happens for both
> proprietary and non-proprietary softare.

It's not about proprietary vs non-proprietary software, but about who 
has the money to buy that training. Companies who make money from 
software can afford training, hobbyists can't.

> > If 
> > I were to write commercial software with gtkmm I would convince my 
> > company to pony up for training. But I won't pay for it from my own 
> > money for hobby software.
> > BTW, I do think there would be a market for a (small) company that would 
> > provide commercial support and training for gtkmm (but only if the 
> > Windows version would be up to par with the X version).
> Again, what bugs exactly (in a separate email thread please)? I don't
> doubt that there are some, but you must call attention to them if you
> want them to be fixed.

For Windows you mean? Well, how about 
http://bugzilla.gnome.org/show_bug.cgi?id=158040? I know, 'compiler 
bug', but that doesn't stop it from being an obstacle for people to use 
it on Windows (please don't say 'just use gcc', I don't want to get into 
that discussion).
What I meant was that I feel there is a need for an LGPL cross-platform 
toolkit. Windows is, IMO, an afterthought throughout in the whole of gtk 
and, by consequence, gtkmm. Again, this is just a random remark, I don't 
feel like going into discussion about it. Feel free to disagree with me.


cheers,

roel