[prev in list] [next in list] [prev in thread] [next in thread] 

List:       php-gtk-doc
Subject:    Re: [PHP-GTK-DOC] php-gtk2 docs
From:       Andrei Zmievski <andrei () gravitonic ! com>
Date:       2005-03-17 5:42:16
Message-ID: 52059D48-96A7-11D9-B980-000D93B4252E () gravitonic ! com
[Download RAW message or body]

On Mar 16, 2005, at 2:28 PM, Christian Weiske wrote:

> - the compiled manual should use directories. I hate it that some
> programs (konqueror or opera) have to load 1800+ files in the view just
> that I can select the index.html

Sure, as long as the rest of our tools are changed to accomodate this. 
I am talking about manual search, docs updates generator, etc.

> - we need an object hierarchy. This is easy as the current stylesheet
> contains a function I wrote a year ago which exaclty does this

Definitely - this is a very good idea.

> - more tutorials. The basic hello world is ok, but many people want at
> least this ones:
>   - widget packing (multiple in one window)
>   - opening other windows from within the original ones (modal/non
> modal, what to do with multiple gtk::main loops, passing parameters
> between windows)
>   - object oriented programming. Current sample scripts are all
> spaghetti code with absolutely no objects. This is a practice which
> isn't suitable for middle and large or even nearly every project.
>   - explain what gtk, gdk, pango, glade and so is and how they are
> connected

All sounds good.

> - all the files in utf-8. The good old iso-8859-1 is nice, but not
> suitable for many languages. This would also mean that the utf-8
> conversion before compiling isn't necessary any more. I had a
> conversation with Steph about this for the php-gtk1 manual many months
> before, and she meant that mixing is bad - as current editors don't
> automatically recognize the encoding. So if everything is in utf-8, 
> it's
> really easy to switch between translations and the original files.

This will help a lot, but we need to think about how this will affect 
documentation contributors, since this is yet another step on the 
learning curve. We will have to help them find an use an editor that 
supports UTF-8.

> - All classes should have a mini-howto section which explains the most
> frequently needed solutions with examples

Linked from the main class page, I hope, not included in it.

> - I would recommend the following structure, which is near to the 
> curent
> one:
> ====================
> -Introduction
> -Tutorials
>  -Installation
>  -Gtk, Pango & Co
>  -Hello World
>  -Packing
>  -Building apps with glade
>  -Object oriented scripts
>  -Localization with gettext
> -Reference
>  -Gtk
>   -Object Hierarchy
>   -GtkA
>    -Constructor
>    -FunctionA
>    -FunctionB
>    -PropertyA
>    -PropertyB
>    -SignalA
>    -SignalB
>    -MiniHowTo
>   -GtkB
>   -GtkC
>  -Gdk
>  -Pango
>  -Glade
>  -Atk???
> -FAQ
> ====================

Where do static functions go? Under Gtk:: and Gdk:: and such? What 
about enums and flags?

Overall, it looks very good.

-Andrei

-- 
PHP-GTK Documentation Mailing List (http://gtk.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php

[prev in list] [next in list] [prev in thread] [next in thread]