Re: for the GNOME hater in all of us...

["Stephen J. Turnbull" <turnbull@example.com>]

>>>>> "Simon" == Simon Cozens <simon@example.com> writes:

    Simon> Stephen J. Turnbull (lists.tlug):
    >> read GTK code, and I've attempted to read the docs.[1] [1]I'm
    >> pretty fast reader, but not so fast I can read stuff that ain't
    >> written yet.

    Simon> Stephen, I appreciate fully the fact that you're trolling,
    Simon> but the art of trolling is to do so with information that
    Simon> is not easily contradictable; here, you're just way too
    Simon> easy to defeat.

    Simon> Game over:
    Simon> http://developer.gnome.org/doc/API/gtk/index.html

Simon, I wasn't trolling with contradictable information, not to my
knowledge.  The last time I looked, in late June, only about 1/2 that
manual was available from www.gtk.org.[1]  The Qt documentation was far
better.  So I took what (even in hindsight) seemed a small risk with
that provocative statement.

This is definitely an improvement over the Qt docs I saw, and what was
on www.gtk.org then hardly qualifies as a draft for what is there now.
Then, about half of it was just place holders.  Especially distressing
was the the state of the description of resource files, saying how
wonderful they were without describing how to use them.  (None of the
narcissism is left, thank heaven.)  The rest was in varying states of
completeness and correctness.

It's a pity it wasn't in current shape, because the book I was
researching for went to press a few days ago.

And yes, I did check carefully.  The last thing that I set in stone
for the draft was the remarks on I18N in GTK+ and Qt, because I was
hoping against hope that the docs would improve.  Neither did (Qt
showed some movement over the 6 months I worked on the project).  And
the state of the GTK+ docs didn't seem all that much different from
the first time I'd looked maybe two years ago.

No, I didn't ask on the mailing list.  Of course they would have told
me "we'll have docs RSN."  In my place, would _you_ believe that?  In
a pig's eye, you would.  (Remember, I don't know any of those
developers personally, even though you evidently do.)

Nor is the game over, actually, not if you play in _my_ gym.

I probably could not have given GTK+ better reviews anyway, since it
is still extremely hard to find out anything about the I18N features
(which is what my chapter was about, and which is all I complained
about lack of documentation for).

As far as I can tell, the Gtk+ manual doesn't mention it.  It is
_completely_ absent from the description of the GtkText widget, for
sure.  Not acceptable.  Oops, it does mention locale-specific resource
files (although not why you might want to use them).  The
GtkFontSelectionDialog and GtkFontSelection pages both ignore I18N
(pretty hard, considering they mention charsets).

The GTK+ 1.2 Online tutorial's TOC doesn't mention it, and it doesn't
have an index.

There is a section on IMs in the GDK manual, really skimpy.
Especially considering how well XIM is documented in Xlib ("see the
Xlib documentation" sez GDK :-P ).

    >> Evidently you do _not_ build GNOME from scratch.  (I don't
    >> either, but I've never heard a good word for it from those who
    >> have done so.)

    Simon> If that was a specific you, then of course I have done
    Simon> so. If it was a general "you", then, no, I wouldn't
    Simon> encourage it. This is why we have good people like Helix
    Simon> doing all that for us. I've built an entire Linux distro
    Simon> from scratch before too. That wasn't fun either.

So you agree with me.  :-)

I don't care whether the vendor is Microsoft or Helix; I don't like
running things I _can't_ build.[2]  dpkg is a convenience; when it
becomes a necessity, I get worried.

I've built pretty much everything that matters on my (i386, sparc was
another kettle of fish) system _without_ Debian's .diff.gz, including
many versions of the kernel, glibc a couple of times, and X11R6 once
or thrice.  Smail far too many times.  All (except glibc) mostly built
the first time after careful configuration (they often didn't work
right, most unfortunately, Smail ;-).  After looking at the several MB
of gnome*.diff.gz (a long time ago, 6 months, I'll admit, and
including the gtk diffs), I just said "no".  I couldn't understand the
diff, let alone the source!

    >> Dividing things into multiple libraries just makes it worse;
    >> you can change your APIs _without_ breaking your own builds.
    >> Unless the APIs are documented.  Sorry, Luke, the source is
    >> _not_ acceptable documentation for an API[3][4].  It will
    >> change tomorrow---"that's called development", eh, Simon?

    Simon> Underdocumented it ain't.

Now.  It's always been above average for OSS not from GNU or legacy
Unix (oh, but it is from GNU, isn't it---I take that back ;-), but
until now it has certainly would not have been possible to write a
nontrivial program correctly without looking at the Gtk source or
trying the code, or both.

In I18N, it probably still isn't.

The point is, the documentation has lagged the development.  Even in
GNOME.  In GTK+ much of the docs are lagging the code by _years_.

And evidently the people who wrote the GTK+ documentation agree with
you about holism q.v.); there is nothing like an overview in the
"reference manual."  As good as it is, that is something of a
misnomer: it's really a collection of function man pages, not a
reference manual.  It's not close to an API definition.  (This lack of
a comprehensive view probably helps explain the complete lack of I18N
discussion.  The APIs are hidden in the toolkit, so didn't get picked
up by documenters focussed on the components.)

Granted, all that will probably come.  But it should have come much
earlier!  Like, first!

    >> Taken completely out of context from a different message:

    Simon> isolating and compartmentalising code is extremely useful
    Simon> to avoid requiring a holistic understanding of [...]

    >> ... anything at all.  Especially not the users' requirements!

    Simon> Taken completely out of logic as well, it seems.

Simon, c'mon.  _Somebody_ has to have a holistic[3] understanding of
the system.  Since there are basically no bosses and no paid testers
in OSS development, and the architects often have to go on whether the
source builds and runs without crashing and the statement of the
contributor that the feature works, the _programmers_ _need_ to have a
holistic understanding.  Otherwise you _do_ get bloat, as contributors
add little features that they want piecemeal, and the whole structure
gets excessively large and fragmented.  (Not to mention promising
documentation RSN---but does the code get backed out for lack of docs?
No way!)

The I18N features of GTK+ remain a good example of undocumented
features which may or may not work well with the rest of the system.  I
have my strong doubts about the charsets feature of the font selection
widgets, for example.

    >> Simon, I'm really surprised to see you advocating the MDPPDM
    >> (Modular Debian Project Perl Debasement Methodology).  That's
    >> precisely how they do it, as you very well know.

    Simon> Yes, but they do it exceptionally badly.

Not exceptional at all, in my experience with OSS.  Just larger scale
than anything except Mozilla, and of course the GNU Project itself.
Both of which have always been Wiener processes, API-wise.

If GNOME is really going to do better, cool.  But I'll believe it when
I see it.  The vast improvement in the docs in just a few weeks is
pretty impressive, I'll admit.  Enough that I'll try it again when I
have a day to clean up the expected breakage.  But not Enlightenment!

But I've seen that happen before, and then they go back to their bad
old habits.  Maybe it's different this time---there is some commercial
muscle behind tedious things like docs now.  But commercial vendors
haven't always been the best examples!

*****

Break from troll.  I'll watch GNOME, and judge the project on what it
does.  It's interesting enough that I already want to know how they're
doing it ... the docs they've produced recently go against much that I
thought I knew about open source development.  Enough so that I'm not
convinced yet.

But there is still a lot that they need to do, as I'm sure you'll
admit.  The component pages smell strongly of automatic generation.  A
sweet smell---they are individually complete, comprehensive as a
suite, and formatted consistently---but it indicates that not as much
work has gone into them as you might think.  Neither the tutorials nor
the function man pages constitute a true reference manual, and that's
going to be a _lot_ more work than the others, requiring more expertise.


Footnotes: 
[1]  I don't remember if I looked carefully at www.GNOME.org at that
point; I did visit, but mainly to check for GTK docs.  The book didn't
cover GNOME, so I didn't look carefully.  The last time I did it was
pretty unintelligible, but that may have been 9 months ago now.

[2]  I'm not as much a purist as Chris or Austin.  I'm willing to risk
getting hacked, and _then_ fix from source.

[3]  If you meant "detailed", why didn't you write that?

-- 
University of Tsukuba                Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Institute of Policy and Planning Sciences       Tel/fax: +81 (298) 53-5091
_________________  _________________  _________________  _________________
What are those straight lines for?  "XEmacs rules."