Re: RFC: Part 1 of new GObject tutorial

[Ryan McDougall <NQG24419 nifty com>]

On Fri, 2004-16-07 at 19:56 +0100, Roger Leigh wrote:
> Ryan McDougall <NQG24419 nifty com> writes:
> 
> > As promised I finished the the first part of a tutorial I started
> > writing for the fun of it. It only includes making a pretty lame
> > fundamental class with no inheritance, but its is (hopefully) very
> > comprehensive and clear. There are code examples included.
> >
> > Therefore I'm asking everyone with some experience to give it a read
> > over for technical mistakes, or unclear language.
> 
> OK.  These are all the things I could see:

Thanks for the advice, I appreciate the feedback!
> 
> 1. main() in gobject-tutorial-example1.c should be in a separate
>    file--it's not part of the class implementation.

True. It adds another file, but if I beef up the example then it would
be more worth it.
> 
> 2. The class finaliser does nothing, so personally I would not include
>    it.

Throughout I tried to be as complete as possible so anyone using it as a
template wouldn't miss something.
> 
> 3. Should people really be encouraged to use fundamental types, rather
>    than deriving from GObject?

No, thats why I will developer it further to use GObject and the new
macros introduced in 2.4.
> 
> 4. While the example works, I personally find examples easier to
>    follow when they have a useful purpose.  Currently I can see what
>    your example is showing, but I can't see a /point/ to it.  Compare
>    it with this example:
> 
>       http://people.debian.org/~rleigh/gtk/ogcalc/ogcalc-1.0.4.tar.gz
>       (this was even simpler than your tutorial nine months ago!)
> 
>    I would suggest keeping the class the same, but give the class name
>    and fields some names and purpose that the reader can relate to.

You have a point, but I don't think I'll have time to do so until I've
finished the prose part, which for me is the most important.

If you can make one simple class do something interesting without adding
superfluous code, you are more than welcome to help me out with a patch!

> 
> 5. The tutorial text could use some line wrapping.  If you use Emacs,
>    try "M-x text-mode" and then press "M-q" while point is in each
>    paragraph, which will nicely flow the text.  It's not too readable
>    on a text terminal :(

I will consider my formatting further. Actually I wouldn't mind some
XML/HTML guru showing me how to make it presentable in that form.
> 
> 6. You might find a typesetting system such as LaTeX makes writing
>    much easier :)  Feel free to copy stuff out of my tutorial,
>    providing your licence is GPL-compatible.
> 
> 7. "objects' livetimes".  I think you mean "lifetimes".

Yeah, there are a couple type-os. ;)
> 
> 8. The unfinished part 2 needs to be vary careful in describing
>    base/class/instance init/finalise functions, in order to clearly
>    differentiate their role, execution order, required usage and
>    examples of each.

I think I have finally understood that myself, but you are welcome to
submit anything you think I've missed.
> 
> 
> > Next section will tackle inheriting from GObject, and the one after will
> > be about inheriting from our custom class.
> 
> Sounds great!  I am finding GObject very nice, but will really
> appreciate some more documentation on the subject.  I look forward to
> reading it.
> 
> 
> Regards,
> Roger
> 

Once again, thanks for the comments.

Cheers,
Ryan